.Dt CDECL99 \&1 "Cdecl99 User's Manual"
.Sh NAME
.Nm cdecl99
-.Nd Make sense of C declaratiosns
+.Nd Make sense of C declarations
.Sh SYNOPSIS
.Nm
.Op Fl q
Run in batch (non-interactive) mode. Execute the commands provided on standard
input as usual, but do not print any prompts. Exit with status 0 if and only
if all commands complete successfully.
-
+.Pp
This option implies
.Fl -quiet .
.It Fl i , -interactive
as if it were entered at the prompt, then exit. This option can be specified
multiple times; all commands are run in the same order as specified on the
command line.
-
+.Pp
This option implies
.Fl -batch .
.It Fl f , -file Ar file
are specified, any
.Fl -file
option is ignored.
-
+.Pp
This option implies
.Fl -batch .
.It Fl V , -version
Translates a given C declaration or type name into something resembling
English.
.It simplify Ar declaration
-Simplifies a given C decalaration or type name by eliminating redundant
+Simplifies a given C declaration or type name by eliminating redundant
components.
.It declare Ar identifier No as Ar english-decl
Translates an English declaration into C code.
.Xr cdecl 1 ,
and is described by the following context-free grammar. This grammar is for
illustrative purposes only: it is ambiguous and doesn't capture all the nuances
-of the C language. In this grammar,
-.Fa underlined words
-are nonterminals, \[*e] represents the empty string, and both
+of the C language. In this grammar, nonterminals are represented
+.Va [ thusly ] ,
+\[*e] represents the empty string, and both
.Li |
and successive \[->] under the same nonterminal indicate alternation. All
other symbols are terminals. The nonterminals
-.Fa identifier , type-specifier , type-qualifier , storage-class-specifier
+.Va [ identifier ] , [ type-specifier ] ,
+.Va [ type-qualifier ] , [ storage-class-specifier ]
and
-.Fa function-specifier
+.Va [ function-specifier ]
are defined as in C.
-.Bl -column -offset indent ".Fa english-decl" ""
-.It Fa english Ta \[->] Ta Li declare Fa identifier Li as Fa english-decl
-.It Ta \[->] Ta Li type Fa english-decl
-.It Fa english-decl Ta \[->] Ta Fa sf-specs declarator
-.It Fa declarator Ta \[->] Ta Fa qualifiers Li pointer to Fa declarator
-.It Ta \[->] Ta Li array Fa size Li of Fa declarator
-.It Ta \[->] Ta Li function Fa parameters Li returning Fa declarator
-.It Ta \[->] Ta Fa tq-specs
-.It Fa qualifiers Ta \[->] Ta Fa type-qualifier qualifiers | No \[*e]
-.It Fa tq-specs Ta \[->] Ta Fa type-qualifier tq-specs
-.It Ta \[->] Ta Fa type-specifier tq-specs
+.Bl -column -offset indent ".Va english-decl" ""
+.It Va english Ta \[->] Ta Li declare Va [ identifier ] Li as Va [ english-decl ]
+.It Ta \[->] Ta Li type Va [ english-decl ]
+.It Va english-decl Ta \[->] Ta Va [ sf-specs ] [ declarator ]
+.It Va declarator Ta \[->] Ta Va [ qualifiers ] Li pointer to Va [ declarator ]
+.It Ta \[->] Ta Li array Va [ size ] Li of Va [ declarator ]
+.It Ta \[->] Ta Li function Va [ parameters ] Li returning Va [ declarator ]
+.It Ta \[->] Ta Va [ tq-specs ]
+.It Va qualifiers Ta \[->] Ta Va [ type-qualifier ] [ qualifiers ] | No \[*e]
+.It Va tq-specs Ta \[->] Ta Va [ type-qualifier ] [ tq-specs ]
+.It Ta \[->] Ta Va [ type-specifier ] [ tq-specs ]
.It Ta \[->] Ta \[*e]
-.It Fa sf-specs Ta \[->] Ta Fa storage-class-specifier sf-specs
-.It Ta \[->] Ta Fa function-specifier sf-specs
+.It Va sf-specs Ta \[->] Ta Va [ storage-class-specifier ] [ sf-specs ]
+.It Ta \[->] Ta Va [ function-specifier ] [ sf-specs ]
.It Ta \[->] Ta \[*e]
-.It Fa size Ta \[->] Ta Fa integer | Fa identifier | Li * | No \[*e]
-.It Fa parameters Ta \[->] Ta Po Fa param-list Pc
-.It Ta \[->] Ta Po Fa param-list Li , ... Pc
+.It Va size Ta \[->] Ta Va [ integer ] | Va [ identifier ] | Li * | No \[*e]
+.It Va parameters Ta \[->] Ta Po Va [ param-list ] Pc
+.It Ta \[->] Ta Po Va [ param-list ] Li , ... Pc
.It Ta \[->] Ta \[*e]
-.It Fa param-list Ta \[->] Ta Fa parameter | Fa parameter Li , Fa param-list
-.It Fa parameter Ta \[->] Ta Fa identifier Li as Fa english-decl
-.It Ta \[->] Ta Fa english-decl
+.It Va param-list Ta \[->] Ta Va [ parameter ] | Va [ parameter ] Li , Va [ param-list ]
+.It Va parameter Ta \[->] Ta Va [ identifier ] Li as Va [ english-decl ]
+.It Ta \[->] Ta Va [ english-decl ]
.El
.Sh RESOLVING AMBIGUITIES
The C context-free grammar has many ambiguities regarding declarations.
Ordinarily, these ambiguities are resolved by the context in which the
declaration appears, such as which typedef names are currently in scope.
-
+.Pp
For example, the meaning of the declaration
.Ic int f(int (foo))
depends on whether or not a typedef named
-.Fa foo
+.Va foo
is in scope. If such a typedef is in scope, this declares
-.Fa f
+.Va f
as a function that takes (after adjustment) a pointer to a function that takes
a
-.Fa foo
+.Va foo
and returns an int, returning an int. If there is no such typedef, then this
declares
-.Fa f
+.Va f
as a function that takes an int and returns an int.
-
+.Pp
Since
.Nm
isn't a C compiler, on several occasions it has to arbitrarily pick one of two
.Nm
will choose the alternative with the simplest explanation. Thus, f is
interpreted as a function which takes an int and returns an int.
+.Sh EXAMPLES
+.Bl -tag -width Output:
+.It Input:
+.Li explain int x;
+.It Output:
+.Li declare x as int
+.It Input:
+.Li explain static int* x, y;
+.It Output:
+.Li declare x as static pointer to int
+.sp 0
+.Li declare y as static int
+.It Input:
+.Li explain extern int printf(const char *fmt, ...);
+.It Output:
+.Li declare printf as extern function (fmt as pointer to const char, ...) returning int
+.It Input:
+.Li explain size_t volatile * const (* restrict)[1][2][3]
+.It Output:
+.Li type restrict pointer to array 1 of array 2 of array 3 of const pointer to volatile int
+.It Input:
+.Li declare x as int
+.It Output:
+.Li int x
+.It Input:
+.Li type function (pointer to const char) returning size_t
+.It Output:
+.Li size_t (const char *)
+.It Input:
+.Li declare f as inline function (g as pointer to array 6 of pointer to const char) returning pointer to function (int, ...) returning int
+.It Output:
+.Li inline int (*f(const char *(*g)[6]))(int, ...)
+.It Input:
+.Li simplify const int const ((*restrict x))
+.It Output:
+.Li const int * restrict x
+.El
.Sh AUTHORS
Nick Bowler <nbowler@draconx.ca>
.Sh COPYRIGHT
Copyright \(co 2011 Nick Bowler
-
+.Pp
Permission is granted to copy, distribute and/or modify this manual under the
terms of the Do What The Fuck You Want To Public License, version 2.
.Sh SEE ALSO
projects / cdecl99.git / blobdiff