home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / program / cdecl / cdecl.man < prev    next >
Text File  |  1993-10-23  |  12KB  |  396 lines
  1.  
  2.  
  3.  
  4.                                                                      CDECL(1)
  5.  
  6.  
  7.  
  8.    NAME
  9.      cdecl, c++decl - Compose C and C++ type declarations
  10.  
  11.    SYNOPSIS
  12.      cdecl [-a | -+ | -p | -r] [-cidDV]
  13.           [[_✓f_✓i_✓l_✓e_✓s ...] | explain ... | declare ... | cast ... | set ... |
  14.           help ... | ? ... ]
  15.      c++decl [-a | -+ | -p | -r] [-cidDV]
  16.           [[_✓f_✓i_✓l_✓e_✓s ...] | explain ... | declare ... | cast ... | set ... |
  17.           help ... | ? ... ]
  18.      explain ...
  19.      declare ...
  20.      cast ...
  21.  
  22.    DESCRIPTION
  23.      _✓C_✓d_✓e_✓c_✓l (and _✓c++_✓d_✓e_✓c_✓l ) is a program for encoding and decoding C (C++)
  24.      type-declarations.  The C language (the default for _✓c_✓d_✓e_✓c_✓l , or with the
  25.      -a option) is based on the (draft proposed) X3J11 ANSI Standard; option-
  26.      ally, the C language may be based on the pre-ANSI definition defined by
  27.      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
  28.      used), or the C language defined by the Ritchie PDP-11 C compiler (the
  29.      -r option is used).  The C++ language (the default for _✓c++_✓d_✓e_✓c_✓l , or with
  30.      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,
  31.      plus the version 2.0 additions to the language.
  32.  
  33.      _✓C_✓d_✓e_✓c_✓l reads the named files for statements in the language described
  34.      below.  A transformation is made from that language to C (C++) or
  35.      pseudo-English.  The results of this transformation are written on stan-
  36.      dard output.  If no files are named, or a filename of ``-'' is encoun-
  37.      tered, standard input will be read.  If standard input is coming from a
  38.      terminal, (or the -i option is used), a prompt will be written to the
  39.      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
  40.      _✓c_✓a_✓s_✓t, or the first argument is one of the commands discussed below, the
  41.      argument list will be interpreted according to the grammar shown below
  42.      instead of as file names.
  43.  
  44.      You can use _✓c_✓d_✓e_✓c_✓l as you create a C program with an editor like vi(1) or
  45.      emacs(1).  You simply type in the pseudo-English version of the declara-
  46.      tion and apply _✓c_✓d_✓e_✓c_✓l as a filter to the line.  (In vi(1), type
  47.      ``!!cdecl<cr>''.)
  48.  
  49.      If the _✓c_✓r_✓e_✓a_✓t_✓e _✓p_✓r_✓o_✓g_✓r_✓a_✓m option -c is used, the output will include semi-
  50.      colons after variable declarations and curly brace pairs after function
  51.      declarations.
  52.  
  53.      The -V option will print out the version numbers of the files used to
  54.      create the process.  If the source is compiled with debugging informa-
  55.      tion turned on, the -d option will enable it to be output.  If the
  56.      source is compiled with YACC debugging information turned on, the -D
  57.      option will enable it to be output.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.    CDECL(1)
  71.  
  72.  
  73.    COMMAND LANGUAGE
  74.      There are six statements in the language.  The _✓d_✓e_✓c_✓l_✓a_✓r_✓e statement com-
  75.      poses a C type-declaration from a verbose description.  The _✓c_✓a_✓s_✓t state-
  76.      ment composes a C type-cast as might appear in an expression.  The
  77.      _✓e_✓x_✓p_✓l_✓a_✓i_✓n statement decodes a C type-declaration or cast, producing a ver-
  78.      bose description.  The _✓h_✓e_✓l_✓p (or ?) statement provides a help message.
  79.      The _✓q_✓u_✓i_✓t (or _✓e_✓x_✓i_✓t) statement (or the end of file) exits the program.
  80.      The _✓s_✓e_✓t statement allows the command line options to be set interac-
  81.      tively.  Each statement is separated by a semi-colon or a newline.
  82.  
  83.      The following grammar describes the language.  In the grammar, words in
  84.      "<>" are non-terminals, bare lower-case words are terminals that stand
  85.      for themselves.  Bare upper-case words are other lexical tokens: NOTHING
  86.      means the empty string; NAME means a C identifier; NUMBER means a string
  87.      of decimal digits; and NL means the new-line or semi-colon characters.
  88.  
  89.      Some synonyms are permitted during a declaration: character -> char,
  90.      constant -> const, enumeration -> enum, func -> function, integer ->
  91.      int, ptr -> pointer, ref -> reference, ret -> returning, structure ->
  92.      struct, and vector -> array.
  93.  
  94.           <program> ::= NOTHING
  95.                     | <program> <stmt> NL
  96.           <stmt>    ::= NOTHING
  97.                     | declare NAME as <adecl>
  98.                     | declare <adecl>
  99.                     | cast NAME into <adecl>
  100.                     | cast <adecl>
  101.                     | explain <optstorage> <ptrmodlist> <type> <cdecl>
  102.                     | explain <storage> <ptrmodlist> <cdecl>
  103.                     | explain ( <ptrmodlist> <type> <cast> ) optional-NAME
  104.                     | set <options>
  105.                     | help | ?
  106.                     | quit
  107.                     | exit
  108.           <adecl>   ::= array of <adecl>
  109.                     | array NUMBER of <adecl>
  110.                     | function returning <adecl>
  111.                     | function ( <adecl-list> ) returning <adecl>
  112.                     | <ptrmodlist> pointer to <adecl>
  113.                     | <ptrmodlist> pointer to member of class NAME <adecl>
  114.                     | <ptrmodlist> reference to <adecl>
  115.                     | <ptrmodlist> <type>
  116.           <cdecl>   ::= <cdecl1>
  117.                     | * <ptrmodlist> <cdecl>
  118.                     | NAME :: * <cdecl>
  119.                     | & <ptrmodlist> <cdecl>
  120.           <cdecl1>  ::= <cdecl1> ( )
  121.                     | <cdecl1> ( <castlist> )
  122.                     | <cdecl1> [ ]
  123.                     | <cdecl1> [ NUMBER ]
  124.                     | ( <cdecl> )
  125.                     | NAME
  126.           <cast>    ::= NOTHING
  127.  
  128.  
  129.    2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                                                                      CDECL(1)
  137.  
  138.  
  139.                     | ( )
  140.                     | ( <cast> ) ( )
  141.                     | ( <cast> ) ( <castlist> )
  142.                     | ( <cast> )
  143.                     | NAME :: * <cast>
  144.                     | * <cast>
  145.                     | & <cast>
  146.                     | <cast> [ ]
  147.                     | <cast> [ NUMBER ]
  148.           <type>    ::= <typename> | <modlist>
  149.                     | <modlist> <typename>
  150.                     | struct NAME | union NAME | enum NAME | class NAME
  151.           <castlist>::= <castlist> , <castlist>
  152.                     | <ptrmodlist> <type> <cast>
  153.                     | <name>
  154.           <adecllist>::= <adecllist> , <adecllist>
  155.                     | NOTHING
  156.                     | <name>
  157.                     | <adecl>
  158.                     | <name> as <adecl>
  159.           <typename>::= int | char | double | float | void
  160.           <modlist> ::= <modifier> | <modlist> <modifier>
  161.           <modifier>::= short | long | unsigned | signed | <ptrmod>
  162.           <ptrmodlist>::= <ptrmod> <ptrmodlist> | NOTHING
  163.           <ptrmod>  ::= const | volatile | noalias
  164.           <storage> ::= auto | extern | register | auto
  165.           <optstorage>::= NOTHING | <storage>
  166.           <options> ::= NOTHING | <options>
  167.                     | create | nocreate
  168.                     | interactive | nointeractive
  169.                     | ritchie | preansi | ansi | cplusplus
  170.                     | debug | nodebug | yydebug | noyydebug
  171.  
  172.    EXAMPLES
  173.      To declare an array of pointers to functions like malloc(3), do
  174.  
  175.           declare fptab as array of pointer to function returning pointer to
  176.           char
  177.  
  178.      The result of this command is
  179.  
  180.           char *(*fptab[])()
  181.  
  182.      When you see this declaration in someone else's code, you can make sense
  183.      out of it by doing
  184.  
  185.           explain char *(*fptab[])()
  186.  
  187.      The proper declaration for signal(2), ignoring function prototypes, is
  188.      easily described in _✓c_✓d_✓e_✓c_✓l's language:
  189.  
  190.           declare signal as function returning pointer to function returning
  191.           void
  192.  
  193.  
  194.  
  195.                                                                             3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.    CDECL(1)
  203.  
  204.  
  205.      which produces
  206.  
  207.           void (*signal())()
  208.  
  209.      The function declaration that results has two sets of empty parentheses.
  210.      The author of such a function might wonder where to put the parameters:
  211.  
  212.           declare signal as function (arg1,arg2) returning pointer to func-
  213.           tion returning void
  214.  
  215.      provides the following solution (when run with the -_✓c option):
  216.  
  217.           void (*signal(arg1,arg2))() { }
  218.  
  219.      If we want to add in the function prototypes, the function prototype for
  220.      a function such as _exit(2) would be declared with:
  221.  
  222.           declare _exit as function (retvalue as int) returning void
  223.  
  224.      giving
  225.  
  226.           void _exit(int retvalue) { }
  227.  
  228.      As a more complex example using function prototypes, signal(2) could be
  229.      fully defined as:
  230.  
  231.           declare signal as function(x as int, y as pointer to function(int)
  232.           returning void) returning pointer to function(int) returning void
  233.  
  234.      giving (with -c)
  235.  
  236.           void (*signal(int x, void (*y)(int )))(int ) { }
  237.  
  238.      _✓C_✓d_✓e_✓c_✓l can help figure out the where to put the "const" and "volatile"
  239.      modifiers in declarations, thus
  240.  
  241.           declare foo as pointer to const int
  242.  
  243.      gives
  244.  
  245.           const int *foo
  246.  
  247.      while
  248.  
  249.           declare foo as const pointer to int
  250.  
  251.      gives
  252.  
  253.           int * const foo
  254.  
  255.      _✓C++_✓d_✓e_✓c_✓l can help with declaring references, thus
  256.  
  257.           declare x as reference to pointer to character
  258.  
  259.  
  260.  
  261.    4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                                                                      CDECL(1)
  269.  
  270.  
  271.      gives
  272.  
  273.           char *&x
  274.  
  275.      _✓C++_✓d_✓e_✓c_✓l can help with pointers to member of classes, thus declaring a
  276.      pointer to an integer member of a class X with
  277.  
  278.           declare foo as pointer to member of class X int
  279.  
  280.      gives
  281.  
  282.           int X::*foo
  283.  
  284.      and
  285.  
  286.           declare foo as pointer to member of class X function (arg1, arg2)
  287.           returning pointer to class Y
  288.  
  289.      gives
  290.  
  291.           class Y *(X::*foo)(arg1, arg2)
  292.  
  293.    DIAGNOSTICS
  294.      The declare, cast and explain statements try to point out constructions
  295.      that are not supported in C.  In some cases, a guess is made as to what
  296.      was really intended.  In these cases, the C result is a toy declaration
  297.      whose semantics will work only in Algol-68.  The list of unsupported C
  298.      constructs is dependent on which version of the C language is being used
  299.      (see the ANSI, pre-ANSI, and Ritchie options).  The set of supported C++
  300.      constructs is a superset of the ANSI set, with the exception of the
  301.      noalias keyword.
  302.  
  303.    SEE ALSO
  304.      (draft proposed) ANSI National Standard X3J11
  305.  
  306.      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.
  307.      Kernighan & D. Ritchie.
  308.  
  309.      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.
  310.      Stroustrup.
  311.  
  312.    CAVEATS
  313.      The pseudo-English syntax is excessively verbose.
  314.  
  315.      There is a wealth of semantic checking that isn't being done.
  316.  
  317.      _✓C_✓d_✓e_✓c_✓l'_✓s scope is intentionally small.  It doesn't help you figure out
  318.      initializations.  It expects storage classes to be at the beginning of a
  319.      declaration, followed by the the const, volatile and noalias modifiers,
  320.      followed by the type of the variable.  _✓C_✓d_✓e_✓c_✓l doesn't know anything about
  321.      variable length argument lists.  (This includes the ``,...'' _✓s_✓y_✓n_✓t_✓a_✓x.)
  322.  
  323.      _✓C_✓d_✓e_✓c_✓l thinks all the declarations you utter are going to be used as
  324.      external definitions.  Some declaration contexts in C allow more
  325.  
  326.  
  327.                                                                             5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.    CDECL(1)
  335.  
  336.  
  337.      flexibility than this.  An example of this is:
  338.  
  339.           declare argv as array of array of char
  340.  
  341.      where _✓c_✓d_✓e_✓c_✓l responds with
  342.  
  343.           Warning: Unsupported in C -- 'Inner array of unspecified size'
  344.                   (maybe you mean "array of pointer")
  345.           char argv[][]
  346.  
  347.      Tentative support for the _✓n_✓o_✓a_✓l_✓i_✓a_✓s keyword has been put in because it is
  348.      in the current ANSI specifications.
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.    6
  394.  
  395.