3 .Dt CDECL99 \&1 "Cdecl99 User's Manual"
6 .Nd Make sense of C declarations
11 .Op Fl f file Ns | Ns Fl e Ar command Op Fl e Ar command ...
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
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,
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.
28 is also much stricter than
30 and will reject many invalid declarations that
34 .Bl -tag -width indent
36 Suppress the welcome message when starting
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.
45 .It Fl i , -interactive
46 Run in interactive mode. This is the default.
47 .It Fl e , -execute 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
56 .It Fl f , -file Ar file
59 instead of standard input. If both
70 Print a version message and exit.
72 Print a help message and exit.
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
83 .It simplify Ar declaration
84 Simplifies a given C declaration or type name by eliminating redundant
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.
91 Displays an overview of all available commands.
95 .Sh ENGLISH DECLARATIONS
97 uses a language similar to English to explain or construct C declarations. The
98 format is based on the one used in
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
104 \[*e] represents the empty string, and both
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 ]
111 .Va [ function-specifier ]
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 ]
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.
141 For example, the meaning of the declaration
143 depends on whether or not a typedef named
145 is in scope. If such a typedef is in scope, this declares
147 as a function that takes (after adjustment) a pointer to a function that takes
150 and returns an int, returning an int. If there is no such typedef, then this
153 as a function that takes an int and returns an int.
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
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.
163 .Bl -tag -width Output:
169 .Li explain static int* x, y;
171 .Li declare x as static pointer to int
173 .Li declare y as static int
175 .Li explain extern int printf(const char *fmt, ...);
177 .Li declare printf as extern function (fmt as pointer to const char, ...) returning int
179 .Li explain size_t volatile * const (* restrict)[1][2][3]
181 .Li type restrict pointer to array 1 of array 2 of array 3 of const pointer to volatile int
187 .Li type function (pointer to const char) returning size_t
189 .Li size_t (const char *)
191 .Li declare f as inline function (g as pointer to array 6 of pointer to const char) returning pointer to function (int, ...) returning int
193 .Li inline int (*f(const char *(*g)[6]))(int, ...)
195 .Li simplify const int const ((*restrict x))
197 .Li const int * restrict x
200 Nick Bowler <nbowler@draconx.ca>
202 Copyright \(co 2011 Nick Bowler
204 Permission is granted to copy, distribute and/or modify this manual under the
205 terms of the Do What The Fuck You Want To Public License, version 2.