Utility to Interpret C Declarations
(c) David Pilling

Clicking on the menu item opens up a directory containing a utility 'cdecl'. This utility must be run from the command line, either by directly referencing it or by copying it into your library directory and entering '*cdecl'. It can also be used from within an Edit Task Window.

When the application is running, pressing Escape or entering 'Quit' exits.

The instructions provided with the utility by David Pilling now follow.


Name: cdecl

Purpose: Cdecl is a program for encoding and decoding C type-declarations. It reads standard input for statements in the language described below. The results are written on standard output.

Usage: cdecl


Description
===========

Cdecl, will explain in english complex C variable definitions and turn english descriptions into C. To start cdecl, type *cdecl and then enter help followed by RETURN. You can then try out the examples given later or type quit to leave cdecl.

Cdecl's scope is intentionally small. It doesn't help you figure out storage classes or initializations.


Command Language
================

There are four statements in the language.
The "declare" statement composes a C type-declaration from a verbose description.
The "cast" statement composes a C type-cast as might appear in an expression.
The "explain" statement decodes a C type-declaration, producing a verbose description.
The "help" statement describes the others.

The following grammar describes the language.
In the grammar, words in "<>" are non-terminals, bare lower-case words are terminals that stand for themselves.
Bare upper-case words are other lexical tokens:
NOTHING means the empty string;
NAME means a C identifier;
NUMBER means a string of decimal digits; and
NL means the new-line character.

<program>    ::= NOTHING
               | <program> <stat> NL
<stat>       ::= NOTHING
               | declare NAME as <decl>
               | cast NAME into <decl>
               | explain <cdecl>
               | help
<decl>       ::= array of <decl>
               | array NUMBER of <decl>
               | function returning <decl>
               | function ( NAME ) returning <decl>
               | pointer to <decl>
               | <type>
<cdecl>      ::= <cdecl1>
               | * <cdecl>
<cdecl1>     ::= <cdecl1> ( )
               | <cdecl1> [ ]
               | <cdecl1> [ NUMBER ]
               | ( <cdecl> )
               | NAME
<type>       ::= <typename> | <modlist>
               | <modlist> <typename>
               | struct NAME | union NAME | enum NAME
<typename>   ::= int | char | double | float
<modlist>    ::= <modifier> | <modlist> <modifier>
<modifier>   ::= short | long | unsigned


Examples
========

To declare an array of pointers to functions like malloc(3), do

   declare fptab as array of pointer to function returning pointer to char

The result of this command is

   char *(*fptab[])()

When you see this declaration in someone else's code, you can make sense out of it by doing

   explain char *(*fptab[])()

The proper declaration for signal(2) cannot be described in cdecl 's language (it can't be described in C either). An adequate declaration for most purposes is given by:

   declare signal as function returning pointer to function returning int

The function declaration that results has two sets of empty parentheses. The author of such a function might wonder where the parameters go.

   declare signal as function (args) returning pointer to function returning int
provides the solution:

   int (*signal(args))()


Diagnostics
===========
The declare statement tries to point out constructions that are not supported in C.
Also, certain non-portable constructs are flagged.
Syntax errors cause the parser to play dead until a newline is read.


See Also
========
Section 8.4 of the C Reference Manual.


Bugs
====
The pseudo-English syntax is excessively verbose.


Notes
Release 1.00
Archimedes implementation (c) David Pilling 1988.
