OS/2 Professional/OS2PRO194.ISO/os2/prgramer/cdecl/cdecl.1

Text File | 1990-07-21 | 10.0 KB | 293 lines

@(#)cdecl.1 2.4 3/30/88

NAME

cdecl - Compose C and C++ type declarations

SYNOPSIS

cdecl [-a | -+ | -p | -r] [-cidDV]
      [[ files ...] |
      explain ... |
      declare ... |
      cast ... |
      set ... |
      help ... |
      ? ... ]

DESCRIPTION

Cdecl is a program for encoding and decoding C (C++) type-declarations.
The C language (the default for cdecl, or with the -a option) is based on
the (draft proposed) X3J11 ANSI Standard; optionally, the C language may
be based on the pre-ANSI definition defined by Kernighan & Ritchie's
"The C Programming Language" book (the -p option is used), or the C language
defined by the Ritchie PDP-11 C compiler (the .B -r option is used).
The C++ language (with the -+ option) is based on Stroustrup's "The C++
Programming Language", plus the version 2.0 additions to the language.

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 or
emacs. You simply type in the pseudo-English version of the declaration and
apply cdecl as a filter to the line. (In vi, 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.

"COMMAND LANGUAGE"
There are six 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 or cast, producing a verbose description. The "help" (or
?) statement provides a help message. The "quit" (or "exit" ) statement (or the
end of file) exits the program. The "set" statement allows the command line
options to be set interactively. Each statement is separated by a semi-colon or
a newline.

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

EXAMPLES

To declare an array of pointers to functions like malloc, 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, ignoring function prototypes, is easily
described in cdecl 's language:

    declare signal as function returning pointer to function returning void

which produces

    void (*signal())()

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

    declare signal as function (arg1,arg2) returning pointer to function returning void

provides the following solution (when run with the -c option):

    void (*signal(arg1,arg2))()
    {
    }

If we want to add in the function prototypes, the function prototype for a
function such as _exit would be declared with:

    declare _exit as function (retvalue as int) returning void

giving

    void _exit(int retvalue)
    {
    }

As a more complex example using function prototypes, signal could be fully
defined as:

    declare signal as function(x as int, y as pointer to function(int) returning void) returning pointer to function(int) returning void

giving (with -c)

    void (*signal(int x, void (*y)(int )))(int )
    {
    }

Cdecl can help figure out the where to put the "const" and "volatile" modifiers
in declarations, thus

    declare foo as pointer to const int

gives

    const int *foo

while

    declare foo as const pointer to int

gives

    int * const foo

The C++ option (-+) can help with declaring references, thus

    declare x as reference to pointer to character

gives

    char *&x

The C++ option can help with pointers to member of classes, thus
declaring a pointer to an integer member of a class X with

    declare foo as pointer to member of class X int

gives

    int X::*foo

and

    declare foo as pointer to member of class X function (arg1, arg2) returning pointer to class Y

gives

    class Y *(X::*foo)(arg1, arg2)

DIAGNOSTICS

The declare, cast and explain statements try to point out constructions that
are not supported in C. In some cases, a guess is made as to what was really
intended. In these cases, the C result is a toy declaration whose semantics
will work only in Algol-68. The list of unsupported C constructs is dependent
on which version of the C language is being used (see the ANSI, pre-ANSI, and
Ritchie options). The set of supported C++ constructs is a superset of the
ANSI set, with the exception of the noalias keyword.

"SEE ALSO"

(draft proposed) ANSI National Standard X3J11
(sc8.4 of the C Reference Manual within "The C Programming Language"
by B. Kernighan & D. Ritchie.

(sc8 of the C++ Reference Manual within "The C++ Programming Language"
by B. Stroustrup.

CAVEATS

The pseudo-English syntax is excessively verbose.

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 ``f(CW,...'' 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:

    declare argv as array of array of char

where cdecl responds with

Warning: Unsupported in C -- 'Inner array of unspecified size'
        (maybe you mean "array of pointer")
char argv[][]

ANSI has removed noalias from the language specification, cdecl still supports
it.