home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / CDECL.ZIP / CDECL.1 next >
Text File  |  1990-07-21  |  10KB  |  293 lines
  1. @(#)cdecl.1 2.4 3/30/88
  2.  
  3. NAME
  4.  
  5. cdecl - Compose C and C++ type declarations
  6.  
  7. SYNOPSIS
  8.  
  9. cdecl [-a | -+ | -p | -r] [-cidDV]
  10.       [[ files ...] |
  11.       explain ... |
  12.       declare ... |
  13.       cast ... |
  14.       set ... |
  15.       help ... |
  16.       ? ... ]
  17.  
  18. DESCRIPTION
  19.  
  20. Cdecl is a program for encoding and decoding C (C++) type-declarations.
  21. The C language (the default for cdecl, or with the -a option) is based on
  22. the (draft proposed) X3J11 ANSI Standard; optionally, the C language may
  23. be based on the pre-ANSI definition defined by Kernighan & Ritchie's 
  24. "The C Programming Language" book (the -p option is used), or the C language
  25. defined by the Ritchie PDP-11 C compiler (the .B -r option is used).
  26. The C++ language (with the -+ option) is based on Stroustrup's "The C++
  27. Programming Language", plus the version 2.0 additions to the language.
  28.  
  29. Cdecl reads the named files for statements in the language described below.
  30. A transformation is made from that language to C (C++) or pseudo-English.
  31. The results of this transformation are written on standard output.
  32. If no files are named, or a filename of ``-'' is encountered, standard input
  33. will be read. If standard input is coming from a terminal, (or the -i
  34. option is used), a prompt will be written to the terminal before each line.
  35.  
  36. If cdecl is invoked as explain, declare or cast, or the first argument is
  37. one of the commands discussed below, the argument list will be interpreted
  38. according to the grammar shown below instead of as file names.
  39.  
  40. You can use cdecl as you create a C program with an editor like vi or
  41. emacs. You simply type in the pseudo-English version of the declaration and
  42. apply cdecl as a filter to the line. (In vi, type ``!!cdecl<cr>''.)
  43.  
  44. If the "create program" option -c is used, the output will include semi-colons
  45. after variable declarations and curly brace pairs after function declarations.
  46.  
  47. The -V option will print out the version numbers of the files used to create
  48. the process. If the source is compiled with debugging information turned on,
  49. the -d option will enable it to be output. If the source is compiled with YACC
  50. debugging information turned on, the -D option will enable it to be output.
  51.  
  52. "COMMAND LANGUAGE"
  53. There are six statements in the language. The "declare" statement composes a C
  54. type-declaration from a verbose description. The "cast" statement composes a C
  55. type-cast as might appear in an expression. The "explain" statement decodes a
  56. C type-declaration or cast, producing a verbose description. The "help" (or
  57. ?) statement provides a help message. The "quit" (or "exit" ) statement (or the
  58. end of file) exits the program. The "set" statement allows the command line
  59. options to be set interactively. Each statement is separated by a semi-colon or
  60. a newline.
  61.  
  62. The following grammar describes the language. In the grammar, words in "<>" are
  63. non-terminals, bare lower-case words are terminals that stand for themselves.
  64. Bare upper-case words are other lexical tokens:
  65. NOTHING means the empty string;
  66. NAME means a C identifier;
  67. NUMBER means a string of decimal digits; and
  68. NL means the new-line or semi-colon characters.
  69.  
  70. Some synonyms are permitted during a declaration:
  71. character -> char,
  72. constant -> const,
  73. enumeration -> enum,
  74. func -> function,
  75. integer -> int,
  76. ptr -> pointer,
  77. ref -> reference,
  78. ret -> returning,
  79. structure -> struct,
  80. and
  81. vector -> array.
  82.  
  83.         <program>       ::= NOTHING
  84.                 | <program> <stmt> NL
  85.         <stmt>  ::= NOTHING
  86.                 | declare NAME as <adecl>
  87.                 | declare <adecl>
  88.                 | cast NAME into <adecl>
  89.                 | cast <adecl>
  90.                 | explain <optstorage> <ptrmodlist> <type> <cdecl>
  91.                 | explain <storage> <ptrmodlist> <cdecl>
  92.                 | explain ( <ptrmodlist> <type> <cast> ) optional-NAME
  93.                 | set <options>
  94.                 | help | ?
  95.                 | quit
  96.                 | exit
  97.         <adecl> ::= array of <adecl>
  98.                 | array NUMBER of <adecl>
  99.                 | function returning <adecl>
  100.                 | function ( <adecl-list> ) returning <adecl>
  101.                 | <ptrmodlist> pointer to <adecl>
  102.                 | <ptrmodlist> pointer to member of class NAME <adecl>
  103.                 | <ptrmodlist> reference to <adecl>
  104.                 | <ptrmodlist> <type>
  105.         <cdecl> ::= <cdecl1>
  106.                 | * <ptrmodlist> <cdecl>
  107.                 | NAME :: * <cdecl>
  108.                 | & <ptrmodlist> <cdecl>
  109.         <cdecl1>        ::= <cdecl1> ( )
  110.                 | <cdecl1> ( <castlist> )
  111.                 | <cdecl1> [ ]
  112.                 | <cdecl1> [ NUMBER ]
  113.                 | ( <cdecl> )
  114.                 | NAME
  115.         <cast>  ::= NOTHING
  116.                 | ( )
  117.                 | ( <cast> ) ( )
  118.                 | ( <cast> ) ( <castlist> )
  119.                 | ( <cast> )
  120.                 | NAME :: * <cast>
  121.                 | * <cast>
  122.                 | & <cast>
  123.                 | <cast> [ ]
  124.                 | <cast> [ NUMBER ]
  125.         <type>  ::= <typename> | <modlist>
  126.                 | <modlist> <typename>
  127.                 | struct NAME | union NAME | enum NAME | class NAME
  128.         <castlist>      ::= <castlist> , <castlist>
  129.                 | <ptrmodlist> <type> <cast>
  130.                 | <name>
  131.         <adecllist>     ::= <adecllist> , <adecllist>
  132.                 | NOTHING
  133.                 | <name>
  134.                 | <adecl>
  135.                 | <name> as <adecl>
  136.         <typename>      ::= int | char | double | float | void
  137.         <modlist>       ::= <modifier> | <modlist> <modifier>
  138.         <modifier>      ::= short | long | unsigned | signed | <ptrmod>
  139.         <ptrmodlist>    ::= <ptrmod> <ptrmodlist> | NOTHING
  140.         <ptrmod>        ::= const | volatile | noalias
  141.         <storage>       ::= auto | extern | register | auto
  142.         <optstorage>    ::= NOTHING | <storage>
  143.         <options>       ::= NOTHING | <options>
  144.                 | create | nocreate
  145.                 | interactive | nointeractive
  146.                 | ritchie | preansi | ansi | cplusplus
  147.                 | debug | nodebug | yydebug | noyydebug
  148.  
  149. EXAMPLES
  150.  
  151. To declare an array of pointers to functions like malloc, do
  152.  
  153.     declare fptab as array of pointer to function returning pointer to char
  154.  
  155. The result of this command is
  156.  
  157.     char *(*fptab[])()
  158.  
  159. When you see this declaration in someone else's code, you can make sense out
  160. of it by doing
  161.  
  162.     explain char *(*fptab[])()
  163.  
  164. The proper declaration for signal, ignoring function prototypes, is easily
  165. described in cdecl 's language:
  166.  
  167.     declare signal as function returning pointer to function returning void
  168.  
  169. which produces
  170.  
  171.     void (*signal())()
  172.  
  173. The function declaration that results has two sets of empty parentheses.
  174. The author of such a function might wonder where to put the parameters:
  175.  
  176.     declare signal as function (arg1,arg2) returning pointer to function returning void
  177.  
  178. provides the following solution (when run with the -c option):
  179.  
  180.     void (*signal(arg1,arg2))()
  181.     {
  182.     }
  183.  
  184. If we want to add in the function prototypes, the function prototype for a
  185. function such as _exit would be declared with:
  186.  
  187.     declare _exit as function (retvalue as int) returning void
  188.  
  189. giving
  190.  
  191.     void _exit(int retvalue)
  192.     {
  193.     }
  194.  
  195. As a more complex example using function prototypes, signal could be fully
  196. defined as:
  197.  
  198.     declare signal as function(x as int, y as pointer to function(int) returning void) returning pointer to function(int) returning void
  199.  
  200. giving (with -c)
  201.  
  202.     void (*signal(int x, void (*y)(int )))(int )
  203.     {
  204.     }
  205.  
  206. Cdecl can help figure out the where to put the "const" and "volatile" modifiers
  207. in declarations, thus
  208.  
  209.     declare foo as pointer to const int
  210.  
  211. gives
  212.  
  213.     const int *foo
  214.  
  215. while
  216.  
  217.     declare foo as const pointer to int
  218.  
  219. gives
  220.  
  221.     int * const foo
  222.  
  223. The C++ option (-+) can help with declaring references, thus
  224.  
  225.     declare x as reference to pointer to character
  226.  
  227. gives
  228.  
  229.     char *&x
  230.  
  231. The C++ option can help with pointers to member of classes, thus
  232. declaring a pointer to an integer member of a class X with
  233.  
  234.     declare foo as pointer to member of class X int
  235.  
  236. gives
  237.  
  238.     int X::*foo
  239.  
  240. and
  241.  
  242.     declare foo as pointer to member of class X function (arg1, arg2) returning pointer to class Y
  243.  
  244. gives
  245.  
  246.     class Y *(X::*foo)(arg1, arg2)
  247.  
  248. DIAGNOSTICS
  249.  
  250. The declare, cast and explain statements try to point out constructions that
  251. are not supported in C. In some cases, a guess is made as to what was really
  252. intended. In these cases, the C result is a toy declaration whose semantics
  253. will work only in Algol-68. The list of unsupported C constructs is dependent
  254. on which version of the C language is being used (see the ANSI, pre-ANSI, and
  255. Ritchie options). The set of supported C++ constructs is a superset of the
  256. ANSI set, with the exception of the noalias keyword.
  257.  
  258. "SEE ALSO"
  259.  
  260. (draft proposed) ANSI National Standard X3J11
  261. (sc8.4 of the C Reference Manual within "The C Programming Language"
  262. by B. Kernighan & D. Ritchie.
  263.  
  264. (sc8 of the C++ Reference Manual within "The C++ Programming Language"
  265. by B. Stroustrup.
  266.  
  267. CAVEATS
  268.  
  269. The pseudo-English syntax is excessively verbose.
  270.  
  271. There is a wealth of semantic checking that isn't being done.
  272.  
  273. Cdecl's scope is intentionally small. It doesn't help you figure out
  274. initializations. It expects storage classes to be at the beginning of a
  275. declaration, followed by the the const, volatile and noalias modifiers,
  276. followed by the type of the variable. Cdecl doesn't know anything about
  277. variable length argument lists. (This includes the ``f(CW,...'' syntax.)
  278.  
  279. Cdecl thinks all the declarations you utter are going to be used as external
  280. definitions. Some declaration contexts in C allow more flexibility than this.
  281. An example of this is:
  282.  
  283.     declare argv as array of array of char
  284.  
  285. where cdecl responds with
  286.  
  287. Warning: Unsupported in C -- 'Inner array of unspecified size'
  288.         (maybe you mean "array of pointer")
  289. char argv[][]
  290.  
  291. ANSI has removed noalias from the language specification, cdecl still supports
  292. it.
  293.