+++ /dev/null
-.Dd July 18, 2011
-.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 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 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
-.Xr libcdecl 3 ,
-.Xr cdecl 1 ,
-.Xr c++decl 1
projects / cdecl99.git / blobdiff