GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/files/program/cdecl/cdecl.man

Text File | 1993-10-23 | 11.9 KB | 396 lines

                                                                     CDECL(1)



   NAME
     cdecl, c++decl - Compose C and C++ type declarations

   SYNOPSIS
     cdecl [-a | -+ | -p | -r] [-cidDV]
          [[_✓f_✓i_✓l_✓e_✓s ...] | explain ... | declare ... | cast ... | set ... |
          help ... | ? ... ]
     c++decl [-a | -+ | -p | -r] [-cidDV]
          [[_✓f_✓i_✓l_✓e_✓s ...] | explain ... | declare ... | cast ... | set ... |
          help ... | ? ... ]
     explain ...
     declare ...
     cast ...

   DESCRIPTION
     _✓C_✓d_✓e_✓c_✓l (and _✓c++_✓d_✓e_✓c_✓l ) is a program for encoding and decoding C (C++)
     type-declarations.  The C language (the default for _✓c_✓d_✓e_✓c_✓l , or with the
     -a option) is based on the (draft proposed) X3J11 ANSI Standard; option-
     ally, the C language may be based on the pre-ANSI definition defined by
     Kernighan & Ritchie's _✓T_✓h_✓e _✓C _✓P_✓r_✓o_✓g_✓r_✓a_✓m_✓m_✓i_✓n_✓g _✓L_✓a_✓n_✓g_✓u_✓a_✓g_✓e book (the -p option is
     used), or the C language defined by the Ritchie PDP-11 C compiler (the
     -r option is used).  The C++ language (the default for _✓c++_✓d_✓e_✓c_✓l , or with
     the -+ option) is based on Stroustrup's _✓T_✓h_✓e _✓C++ _✓P_✓r_✓o_✓g_✓r_✓a_✓m_✓m_✓i_✓n_✓g _✓L_✓a_✓n_✓g_✓u_✓a_✓g_✓e,
     plus the version 2.0 additions to the language.

     _✓C_✓d_✓e_✓c_✓l 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 stan-
     dard output.  If no files are named, or a filename of ``-'' is encoun-
     tered, 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 _✓c_✓d_✓e_✓c_✓l is invoked as _✓e_✓x_✓p_✓l_✓a_✓i_✓n, _✓d_✓e_✓c_✓l_✓a_✓r_✓e or
     _✓c_✓a_✓s_✓t, 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 _✓c_✓d_✓e_✓c_✓l 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 declara-
     tion and apply _✓c_✓d_✓e_✓c_✓l as a filter to the line.  (In vi(1), type
     ``!!cdecl<cr>''.)

     If the _✓c_✓r_✓e_✓a_✓t_✓e _✓p_✓r_✓o_✓g_✓r_✓a_✓m 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 informa-
     tion 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.





                                                                            1






   CDECL(1)


   COMMAND LANGUAGE
     There are six statements in the language.  The _✓d_✓e_✓c_✓l_✓a_✓r_✓e statement com-
     poses a C type-declaration from a verbose description.  The _✓c_✓a_✓s_✓t state-
     ment composes a C type-cast as might appear in an expression.  The
     _✓e_✓x_✓p_✓l_✓a_✓i_✓n statement decodes a C type-declaration or cast, producing a ver-
     bose description.  The _✓h_✓e_✓l_✓p (or ?) statement provides a help message.
     The _✓q_✓u_✓i_✓t (or _✓e_✓x_✓i_✓t) statement (or the end of file) exits the program.
     The _✓s_✓e_✓t statement allows the command line options to be set interac-
     tively.  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


   2






                                                                     CDECL(1)


                    | ( )
                    | ( <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(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), ignoring function prototypes, is
     easily described in _✓c_✓d_✓e_✓c_✓l's language:

          declare signal as function returning pointer to function returning
          void



                                                                            3






   CDECL(1)


     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 func-
          tion 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(2) 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(2) 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 ) { }

     _✓C_✓d_✓e_✓c_✓l 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

     _✓C++_✓d_✓e_✓c_✓l can help with declaring references, thus

          declare x as reference to pointer to character



   4






                                                                     CDECL(1)


     gives

          char *&x

     _✓C++_✓d_✓e_✓c_✓l 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

     8.4 of the C Reference Manual within _✓T_✓h_✓e _✓C _✓P_✓r_✓o_✓g_✓r_✓a_✓m_✓m_✓i_✓n_✓g _✓L_✓a_✓n_✓g_✓u_✓a_✓g_✓e by B.
     Kernighan & D. Ritchie.

     8 of the C++ Reference Manual within _✓T_✓h_✓e _✓C++ _✓P_✓r_✓o_✓g_✓r_✓a_✓m_✓m_✓i_✓n_✓g _✓L_✓a_✓n_✓g_✓u_✓a_✓g_✓e by B.
     Stroustrup.

   CAVEATS
     The pseudo-English syntax is excessively verbose.

     There is a wealth of semantic checking that isn't being done.

     _✓C_✓d_✓e_✓c_✓l'_✓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.  _✓C_✓d_✓e_✓c_✓l doesn't know anything about
     variable length argument lists.  (This includes the ``,...'' _✓s_✓y_✓n_✓t_✓a_✓x.)

     _✓C_✓d_✓e_✓c_✓l thinks all the declarations you utter are going to be used as
     external definitions.  Some declaration contexts in C allow more


                                                                            5






   CDECL(1)


     flexibility than this.  An example of this is:

          declare argv as array of array of char

     where _✓c_✓d_✓e_✓c_✓l responds with

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

     Tentative support for the _✓n_✓o_✓a_✓l_✓i_✓a_✓s keyword has been put in because it is
     in the current ANSI specifications.












































   6