doc/man/cdecl99.1

   1 .Dd July 18, 2011
   2 .Os cdecl99
   3 .Dt CDECL99 \&1 "Cdecl99 User's Manual"
   4 .Sh NAME
   5 .Nm cdecl99
   6 .Nd Make sense of C declarations
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Op Fl q
  10 .Op Fl b Ns | Ns Fl i
  11 .Op Fl f file Ns | Ns Fl e Ar command Op Fl e Ar command ...
  12 .Sh DESCRIPTION
  13 .Nm
  14 is the command-line interface to libcdecl, enabling you to make heads and tails
  15 of complicated C declarations.  It supports parsing almost any syntactically
  16 valid C99 declaration, producing output similar to that of
  17 .Xr cdecl 1 .
  18 Unlike
  19 .Xr cdecl 1 ,
  20 .Nm
  21 fully supports all relevant C99 keywords, has no undue restrictions on
  22 identifiers, groks features such as complex types, variadic functions and named
  23 parameters, and can also understand plain type names.  On the other hand,
  24 .Nm
  25 does not support any older versions of C, nor does it support C++ other than
  26 the common subset of those other languages and C99.
  27 .Nm
  28 is also much stricter than
  29 .Xr cdecl 1 ,
  30 and will reject many invalid declarations that
  31 .Xr cdecl 1
  32 would accept.
  33 .Sh OPTIONS
  34 .Bl -tag -width indent
  35 .It Fl q , -quiet
  36 Suppress the welcome message when starting
  37 .Nm .
  38 .It Fl b , -batch
  39 Run in batch (non-interactive) mode.  Execute the commands provided on standard
  40 input as usual, but do not print any prompts.  Exit with status 0 if and only
  41 if all commands complete successfully.
  42 .Pp
  43 This option implies
  44 .Fl -quiet .
  45 .It Fl i , -interactive
  46 Run in interactive mode.  This is the default.
  47 .It Fl e , -execute Ar command
  48 Execute
  49 .Ar command
  50 as if it were entered at the prompt, then exit.  This option can be specified
  51 multiple times; all commands are run in the same order as specified on the
  52 command line.
  53 .Pp
  54 This option implies
  55 .Fl -batch .
  56 .It Fl f , -file Ar file
  57 Read commands from
  58 .Ar file
  59 instead of standard input.  If both
  60 .Fl -execute
  61 and
  62 .Fl -file
  63 are specified, any
  64 .Fl -file
  65 option is ignored.
  66 .Pp
  67 This option implies
  68 .Fl -batch .
  69 .It Fl V , -version
  70 Print a version message and exit.
  71 .It Fl H , -help
  72 Print a help message and exit.
  73 .El
  74 .Sh COMMANDS
  75 All interactive
  76 .Nm
  77 commands consist of a single word followed by one or more spaces, followed by
  78 the argument.  Whitespace preceding the command name is ignored.
  79 .Bl -tag -width indent
  80 .It explain Ar declaration
  81 Translates a given C declaration or type name into something resembling
  82 English.
  83 .It simplify Ar declaration
  84 Simplifies a given C declaration or type name by eliminating redundant
  85 components.
  86 .It declare Ar identifier No as Ar english-decl
  87 Translates an English declaration into C code.
  88 .It type Ar english-decl
  89 Translates an English type name into C code.
  90 .It help
  91 Displays an overview of all available commands.
  92 .It quit
  93 Exits the program.
  94 .El
  95 .Sh ENGLISH DECLARATIONS
  96 .Nm
  97 uses a language similar to English to explain or construct C declarations.  The
  98 format is based on the one used in
  99 .Xr cdecl 1 ,
 100 and is described by the following context-free grammar.  This grammar is for
 101 illustrative purposes only: it is ambiguous and doesn't capture all the nuances
 102 of the C language.  In this grammar, nonterminals are represented
 103 .Va [ thusly ] ,
 104 \[*e] represents the empty string, and both
 105 .Li |
 106 and successive \[->] under the same nonterminal indicate alternation.  All
 107 other symbols are terminals.  The nonterminals
 108 .Va [ identifier ] , [ type-specifier ] ,
 109 .Va [ type-qualifier ] , [ storage-class-specifier ]
 110 and
 111 .Va [ function-specifier ]
 112 are defined as in C.
 113 .Bl -column -offset indent ".Va english-decl" ""
 114 .It Va english      Ta \[->] Ta Li declare Va [ identifier ] Li as Va [ english-decl ]
 115 .It                 Ta \[->] Ta Li type Va [ english-decl ]
 116 .It Va english-decl Ta \[->] Ta Va [ sf-specs ] [ declarator ]
 117 .It Va declarator   Ta \[->] Ta Va [ qualifiers ] Li pointer to Va [ declarator ]
 118 .It                 Ta \[->] Ta Li array Va [ size ] Li of Va [ declarator ]
 119 .It                 Ta \[->] Ta Li function Va [ parameters ] Li returning Va [ declarator ]
 120 .It                 Ta \[->] Ta Va [ tq-specs ]
 121 .It Va qualifiers   Ta \[->] Ta Va [ type-qualifier ] [ qualifiers ] | No \[*e]
 122 .It Va tq-specs     Ta \[->] Ta Va [ type-qualifier ] [ tq-specs ]
 123 .It                 Ta \[->] Ta Va [ type-specifier ] [ tq-specs ]
 124 .It                 Ta \[->] Ta \[*e]
 125 .It Va sf-specs     Ta \[->] Ta Va [ storage-class-specifier ] [ sf-specs ]
 126 .It                 Ta \[->] Ta Va [ function-specifier ] [ sf-specs ]
 127 .It                 Ta \[->] Ta \[*e]
 128 .It Va size         Ta \[->] Ta Va [ integer ] | Va [ identifier ] | Li * | No \[*e]
 129 .It Va parameters   Ta \[->] Ta Po Va [ param-list ] Pc
 130 .It                 Ta \[->] Ta Po Va [ param-list ] Li , ... Pc
 131 .It                 Ta \[->] Ta \[*e]
 132 .It Va param-list   Ta \[->] Ta Va [ parameter ] | Va [ parameter ] Li , Va [ param-list ]
 133 .It Va parameter    Ta \[->] Ta Va [ identifier ] Li as Va [ english-decl ]
 134 .It                 Ta \[->] Ta Va [ english-decl ]
 135 .El
 136 .Sh RESOLVING AMBIGUITIES
 137 The C context-free grammar has many ambiguities regarding declarations.
 138 Ordinarily, these ambiguities are resolved by the context in which the
 139 declaration appears, such as which typedef names are currently in scope.
 140 .Pp
 141 For example, the meaning of the declaration
 142 .Ic int f(int (foo))
 143 depends on whether or not a typedef named
 144 .Va foo
 145 is in scope.  If such a typedef is in scope, this declares
 146 .Va f
 147 as a function that takes (after adjustment) a pointer to a function that takes
 148 a
 149 .Va foo
 150 and returns an int, returning an int.  If there is no such typedef, then this
 151 declares
 152 .Va f
 153 as a function that takes an int and returns an int.
 154 .Pp
 155 Since
 156 .Nm
 157 isn't a C compiler, on several occasions it has to arbitrarily pick one of two
 158 possibilities.  The rule that is generally applied is that
 159 .Nm
 160 will choose the alternative with the simplest explanation.  Thus, f is
 161 interpreted as a function which takes an int and returns an int.
 162 .Sh AUTHORS
 163 Nick Bowler <nbowler@draconx.ca>
 164 .Sh COPYRIGHT
 165 Copyright \(co 2011 Nick Bowler
 166 .Pp
 167 Permission is granted to copy, distribute and/or modify this manual under the
 168 terms of the Do What The Fuck You Want To Public License, version 2.
 169 .Sh SEE ALSO
 170 .Xr libcdecl 3 ,
 171 .Xr cdecl 1 ,
 172 .Xr c++decl 1