--- /dev/null
+.Dd March 6, 2021
+.Os cdecl99
+.Dt CDECL99 \&1 "Cdecl99 User's Manual"
+.Sh NAME
+.Nm cdecl99
+.Nd Make sense of C declarations
+.Sh SYNOPSIS
+.Nm
+.Op Fl q
+.Op Fl b Ns | Ns Fl i
+.Op Fl f Ar file Ns | Ns Fl e Ar command Op Fl e Ar command ...
+.Sh DESCRIPTION
+.Nm
+is the command-line interface to libcdecl, enabling you to make heads and tails
+of complicated C declarations.
+It supports parsing almost any syntactically valid C99 declaration, producing
+output similar to that of
+.Xr cdecl 1 .
+Unlike
+.Xr cdecl 1 ,
+.Nm
+fully supports all relevant C99 keywords, has no undue restrictions on
+identifiers, groks features such as complex types, variadic functions and
+named parameters, and can also understand plain type names.
+On the other hand,
+.Nm
+does not support any older versions of C, nor does it support C++ other than
+the common subset of those other languages and C99.
+.Nm
+is also much stricter than
+.Xr cdecl 1 ,
+and will reject many invalid declarations that
+.Xr cdecl 1
+would accept.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl q , -quiet
+Suppress the welcome message when starting
+.Nm .
+.It Fl b , -batch
+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
+Run in interactive mode. This is the default.
+.It Fl e , -execute Ar command
+Execute
+.Ar command
+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
+Read commands from
+.Ar file
+instead of standard input. If both
+.Fl -execute
+and
+.Fl -file
+are specified, any
+.Fl -file
+option is ignored.
+.Pp
+This option implies
+.Fl -batch .
+.It Fl V , -version
+Print a version message and exit.
+.It Fl H , -help
+Print a help message and exit.
+.El
+.Sh COMMANDS
+All interactive
+.Nm
+commands consist of a single word followed by one or more spaces, followed by
+the argument.
+Whitespace preceding the command name is ignored.
+.Bl -tag -width indent
+.It explain Ar declaration
+Translates a given C declaration or type name into something resembling
+English.
+.It simplify Ar declaration
+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.
+.It type Ar english-decl
+Translates an English type name into C code.
+.It help
+Displays an overview of all available commands.
+.It quit
+Exits the program.
+.El
+.Sh ENGLISH DECLARATIONS
+.Nm
+uses a language similar to English to explain or construct C declarations.
+The format is based on the one used in
+.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, 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
+.Va [ identifier ] , [ type-specifier ] ,
+.Va [ type-qualifier ] , [ storage-class-specifier ]
+and
+.Va [ function-specifier ]
+are defined as in C.
+.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 Va sf-specs Ta \[->] Ta Va [ storage-class-specifier ] [ sf-specs ]
+.It Ta \[->] Ta Va [ function-specifier ] [ sf-specs ]
+.It Ta \[->] Ta \[*e]
+.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 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
+.Va foo
+is in scope.
+If such a typedef is in scope, this declares
+.Va f
+as a function that takes (after adjustment) a pointer to a function that takes
+a
+.Va foo
+and returns an int, returning an int.
+If there is no such typedef, then this declares
+.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
+possibilities.
+The rule that is generally applied is that
+.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, 2021 Nick Bowler
+.Pp
+Permission is granted to copy, distribute and/or modify this manual under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+.Sh SEE ALSO
+.Xr libcdecl 3 ,
+.Xr cdecl 1 ,
+.Xr c++decl 1
projects / cdecl99.git / blobdiff