Cdecl reads the named files for statements in the language described below. A transformation is made from that language to C (C++) or pseudo-English. The results of this transformation are written on standard output. If no files are named, or a filename of ``-'' is encountered, standard input will be read. If standard input is coming from a terminal, (or the -i option is used), a prompt will be written to the terminal before each line. If cdecl is invoked as explain, declare or cast, or the first argument is one of the commands discussed below, the argument list will be interpreted according to the grammar shown below instead of as file names.
You can use cdecl as you create a C program with an editor like vi(1) or emacs(1). You simply type in the pseudo-English version of the declaration and apply cdecl as a filter to the line. (In vi(1), type ``!!cdecl<cr>''.)
If the create program option -c is used, the output will include semi-colons after variable declarations and curly brace pairs after function declarations.
The -V option will print out the version numbers of the files used to create the process. If the source is compiled with debugging information turned on, the -d option will enable it to be output. If the source is compiled with YACC debugging information turned on, the -D option will enable it to be output.
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 or semi-colon characters.
Some synonyms are permitted during a declaration: character -> char, constant -> const, enumeration -> enum, func -> function, integer -> int, ptr -> pointer, ref -> reference, ret -> returning, structure -> struct, and vector -> array.
<program> ::= NOTHING
| <program> <stmt> NL
<stmt> ::= NOTHING
| declare NAME as <adecl>
| declare <adecl>
| cast NAME into <adecl>
| cast <adecl>
| explain <optstorage> <ptrmodlist> <type> <cdecl>
| explain <storage> <ptrmodlist> <cdecl>
| explain ( <ptrmodlist> <type> <cast> ) optional-NAME
| set <options>
| help | ?
| quit
| exit
<adecl> ::= array of <adecl>
| array NUMBER of <adecl>
| function returning <adecl>
| function ( <adecl-list> ) returning <adecl>
| <ptrmodlist> pointer to <adecl>
| <ptrmodlist> pointer to member of class NAME <adecl>
| <ptrmodlist> reference to <adecl>
| <ptrmodlist> <type>
<cdecl> ::= <cdecl1>
| * <ptrmodlist> <cdecl>
| NAME :: * <cdecl>
| & <ptrmodlist> <cdecl>
<cdecl1> ::= <cdecl1> ( )
| <cdecl1> ( <castlist> )
| <cdecl1> [ ]
| <cdecl1> [ NUMBER ]
| ( <cdecl> )
| NAME
<cast> ::= NOTHING
| ( )
| ( <cast> ) ( )
| ( <cast> ) ( <castlist> )
| ( <cast> )
| NAME :: * <cast>
| * <cast>
| & <cast>
| <cast> [ ]
| <cast> [ NUMBER ]
<type> ::= <typename> | <modlist>
| <modlist> <typename>
| struct NAME | union NAME | enum NAME | class NAME
<castlist>::= <castlist> , <castlist>
| <ptrmodlist> <type> <cast>
| <name>
<adecllist>::= <adecllist> , <adecllist>
| NOTHING
| <name>
| <adecl>
| <name> as <adecl>
<typename>::= int | char | double | float | void
<modlist> ::= <modifier> | <modlist> <modifier>
<modifier>::= short | long | unsigned | signed | <ptrmod>
<ptrmodlist>::= <ptrmod> <ptrmodlist> | NOTHING
<ptrmod> ::= const | volatile | noalias
<storage> ::= auto | extern | register | auto
<optstorage>::= NOTHING | <storage>
<options> ::= NOTHING | <options>
| create | nocreate
| interactive | nointeractive
| ritchie | preansi | ansi | cplusplus
| debug | nodebug | yydebug | noyydebug
The result of this command is
When you see this declaration in someone else's code, you can make sense out of it by doing
The proper declaration for signal(2), ignoring function prototypes, is easily described in cdecl's language:
which produces
The function declaration that results has two sets of empty parentheses. The author of such a function might wonder where to put the parameters:
provides the following solution (when run with the -c option):
If we want to add in the function prototypes, the function prototype for a function such as _exit(2) would be declared with:
giving
As a more complex example using function prototypes, signal(2) could be fully defined as:
giving (with -c)
Cdecl can help figure out the where to put the "const" and "volatile" modifiers in declarations, thus
gives
while
gives
C++decl can help with declaring references, thus
gives
C++decl can help with pointers to member of classes, thus declaring a pointer to an integer member of a class X with
gives
and
gives
§8.4 of the C Reference Manual within The C Programming Language by B. Kernighan & D. Ritchie.
§8 of the C++ Reference Manual within The C++ Programming Language by B. Stroustrup.
There is a wealth of semantic checking that isn't being done.
Cdecl's scope is intentionally small. It doesn't help you figure out initializations. It expects storage classes to be at the beginning of a declaration, followed by the the const, volatile and noalias modifiers, followed by the type of the variable. Cdecl doesn't know anything about variable length argument lists. (This includes the ``,...'' syntax.)
Cdecl thinks all the declarations you utter are going to be used as external definitions. Some declaration contexts in C allow more flexibility than this. An example of this is:
where cdecl responds with
Warning: Unsupported in C -- 'Inner array of unspecified size'
(maybe you mean "array of pointer")
char argv[][]
Tentative support for the noalias keyword has been put in because it is in the current ANSI specifications.