CDECLSection: Linux Programmer's Manual (1)
Updated: 15 January 1996
CDECLSection: Linux Programmer's Manual (1)
Updated: 15 January 1996
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. The prompt can be turned off by the -q option (or the set noprompt command). 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.
When it is run interactively, cdecl uses the GNU readline library to provide keyword completion and command line history, very much like bash(1) (q.v.). Pressing TAB will complete the partial keyword before the cursor, unless there is more than one possible completion, in which case a second TAB will show the list of possible completions and redisplay the command line. The left and right arrow keys and backspace can be used for editing in a natural way, and the up and down arrow keys retrieve previous command lines from the history. Most other familiar keys, such as Ctrl-U to delete all text from the cursor back to the beginning of the line, work as expected. There is an ambiguity between the int and into keywords, but cdecl will guess which one you meant, and it always guesses correctly.
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.
character is a synonym for char constant is a synonym for const enumeration is a synonym for enum func is a synonym for function integer is a synonym for int ptr is a synonym for pointer ref is a synonym for reference ret is a synonym for returning structure is a synonym for struct vector is a synonym for array
The TAB completion feature only knows about the keywords in the right column of the structure, not the ones in the left column. TAB completion is a lot less useful when the leading characters of different keywords are the same (the keywords confict with one another), and putting both columns in would cause quite a few conflicts.
<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 | prompt | noprompt | ritchie | preansi | ansi | cplusplus | debug | nodebug | yydebug | noyydebug
Note: debugging information and YACC debugging information are only available if they have been compiled into cdecl. The last two options correspond to the -d and -D command line options, respectively. Debugging information is normally used in program development, and is not generally compiled into distributed executables.
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:
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:
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
C++decl can help with declaring references, thus
C++decl can help with pointers to member of classes, thus declaring a pointer to an integer member of a class X with
ISO/IEC 9899:1990 (the ISO standard)
The comp.lang.c FAQ
Section 8.4 of the C Reference Manual within The C Programming Language by B. Kernighan & D. Ritchie.
There is a wealth of semantic checking that isn't being done.
Cdecl was written before the ANSI C standard was completed, and no attempt has been made to bring it up-to-date. Nevertheless, it is very close to the standard, with the obvious exception of noalias.
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
GNU readline support and Linux port by David R. Conrad, <email@example.com>