doc/cdecl99.1

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