(parse_rank_function) Fix msg() bug found by -Wformat.

[pspp] / doc / q2c.texi

@node q2c Input Format, GNU Free Documentation License, Data File Format, Top
@appendix @code{q2c} Input Format

PSPP statistical procedures have a bizarre and somewhat irregular
syntax.  Despite this, a parser generator has been written that
adequately addresses many of the possibilities and tries to provide
hooks for the exceptional cases.  This parser generator is named
@code{q2c}.

@menu
* Invoking q2c::                q2c command-line syntax.
* q2c Input Structure::         High-level layout of the input file.
* Grammar Rules::               Syntax of the grammar rules.
@end menu

@node Invoking q2c, q2c Input Structure, q2c Input Format, q2c Input Format
@section Invoking q2c

@example
q2c @var{input.q} @var{output.c}
@end example

@code{q2c} translates a @samp{.q} file into a @samp{.c} file.  It takes
exactly two command-line arguments, which are the input file name and
output file name, respectively.  @code{q2c} does not accept any
command-line options.

@node q2c Input Structure, Grammar Rules, Invoking q2c, q2c Input Format
@section @code{q2c} Input Structure

@code{q2c} input files are divided into two sections: the grammar rules
and the supporting code.  The @dfn{grammar rules}, which make up the
first part of the input, are used to define the syntax of the
statistical procedure to be parsed.  The @dfn{supporting code},
following the grammar rules, are copied largely unchanged to the output
file, except for certain escapes.

The most important lines in the grammar rules are used for defining
procedure syntax.  These lines can be prefixed with a dollar sign
(@samp{$}), which prevents Emacs' CC-mode from munging them.  Besides
this, a bang (@samp{!}) at the beginning of a line causes the line,
minus the bang, to be written verbatim to the output file (useful for
comments).  As a third special case, any line that begins with the exact
characters @code{/* *INDENT} is ignored and not written to the output.
This allows @code{.q} files to be processed through @code{indent}
without being munged.

The syntax of the grammar rules themselves is given in the following
sections.

The supporting code is passed into the output file largely unchanged.
However, the following escapes are supported.  Each escape must appear
on a line by itself.

@table @code
@item /* (header) */

Expands to a series of C @code{#include} directives which include the
headers that are required for the parser generated by @code{q2c}.

@item /* (decls @var{scope}) */

Expands to C variable and data type declarations for the variables and
@code{enum}s input and output by the @code{q2c} parser.  @var{scope}
must be either @code{local} or @code{global}.  @code{local} causes the
declarations to be output as function locals.  @code{global} causes them
to be declared as @code{static} module variables; thus, @code{global} is
a bit of a misnomer.

@item /* (parser) */

Expands to the entire parser.  Must be enclosed within a C function.

@item /* (free) */

Expands to a set of calls to the @code{free} function for variables
declared by the parser.  Only needs to be invoked if subcommands of type
@code{string} are used in the grammar rules.
@end table

@node Grammar Rules,  , q2c Input Structure, q2c Input Format
@section Grammar Rules

The grammar rules describe the format of the syntax that the parser
generated by @code{q2c} will understand.  The way that the grammar rules
are included in @code{q2c} input file are described above.

The grammar rules are divided into tokens of the following types:

@table @asis
@item Identifier (@code{ID})

An identifier token is a sequence of letters, digits, and underscores
(@samp{_}).  Identifiers are @emph{not} case-sensitive.

@item String (@code{STRING})

String tokens are initiated by a double-quote character (@samp{"}) and
consist of all the characters between that double quote and the next
double quote, which must be on the same line as the first.  Within a
string, a backslash can be used as a ``literal escape''.  The only
reasons to use a literal escape are to include a double quote or a
backslash within a string.

@item Special character

Other characters, other than white space, constitute tokens in
themselves.

@end table

The syntax of the grammar rules is as follows:

@example
grammar-rules ::= ID : subcommands .
subcommands ::= subcommand
            ::= subcommands ; subcommand
@end example

The syntax begins with an ID or STRING token that gives the name of the
procedure to be parsed.  The rest of the syntax consists of subcommands
separated by semicolons (@samp{;}) and terminated with a full stop
(@samp{.}).

@example
subcommand ::= sbc-options ID sbc-defn
sbc-options ::= 
            ::= sbc-option
            ::= sbc-options sbc-options
sbc-option ::= *
           ::= +
           ::= ^
sbc-defn ::= opt-prefix = specifiers
         ::= [ ID ] = array-sbc
         ::= opt-prefix = sbc-special-form
opt-prefix ::=
           ::= ( ID )
@end example

Each subcommand can be prefixed with one or more option characters.  An
asterisk (@samp{*}) is used to indicate the default subcommand; the
keyword used for the default subcommand can be omitted in the PSPP
syntax file.  A plus sign (@samp{+}) is used to indicate that a
subcommand can appear more than once; if it is not present then that
subcommand can appear no more than once.
A carat sign (@samp{^}) is used to indicate that a subcommand must appear
at least once.

The subcommand name appears after the option characters.

There are three forms of subcommands.  The first and most common form
simply gives an equals sign (@samp{=}) and a list of specifiers, which
can each be set to a single setting.  The second form declares an array,
which is a set of flags that can be individually turned on by the user.
There are also several special forms that do not take a list of
specifiers.

Arrays require an additional @code{ID} argument.  This is used as a
prefix, prepended to the variable names constructed from the
specifiers.  The other forms also allow an optional prefix to be
specified.

@example
array-sbc ::= alternatives
          ::= array-sbc , alternatives
alternatives ::= ID
             ::= alternatives | ID
@end example

An array subcommand is a set of Boolean values that can independently be
turned on by the user, listed separated by commas (@samp{,}).  If an value has more
than one name then these names are separated by pipes (@samp{|}).

@example
specifiers ::= specifier
           ::= specifiers , specifier
specifier ::= opt-id : settings
opt-id ::=
       ::= ID
@end example

Ordinary subcommands (other than arrays and special forms) require a
list of specifiers.  Each specifier has an optional name and a list of
settings.  If the name is given then a correspondingly named variable
will be used to store the user's choice of setting.  If no name is given
then there is no way to tell which setting the user picked; in this case
the settings should probably have values attached.

@example
settings ::= setting
         ::= settings / setting
setting ::= setting-options ID setting-value
setting-options ::=
                ::= *
                ::= !
                ::= * !
@end example

Individual settings are separated by forward slashes (@samp{/}).  Each
setting can be as little as an @code{ID} token, but options and values
can optionally be included.  The @samp{*} option means that, for this
setting, the @code{ID} can be omitted.  The @samp{!} option means that
this option is the default for its specifier.

@example
setting-value ::=
              ::= ( setting-value-2 )
              ::= setting-value-2
setting-value-2 ::= setting-value-options setting-value-type : ID 
                    setting-value-restriction
setting-value-options ::=
                      ::= *
setting-value-type ::= N
                   ::= D
setting-value-restriction ::= 
                          ::= , STRING
@end example

Settings may have values.  If the value must be enclosed in parentheses,
then enclose the value declaration in parentheses.  Declare the setting
type as @samp{n} or @samp{d} for integer or floating point type,
respectively.  The given @code{ID} is used to construct a variable name.
If option @samp{*} is given, then the value is optional; otherwise it
must be specified whenever the corresponding setting is specified.  A
``restriction'' can also be specified which is a string giving a C
expression limiting the valid range of the value.  The special escape
@code{%s} should be used within the restriction to refer to the
setting's value variable.

@example
sbc-special-form ::= VAR
                 ::= VARLIST varlist-options
                 ::= INTEGER opt-list
                 ::= DOUBLE opt-list
                 ::= PINT
                 ::= STRING @r{(the literal word STRING)} string-options
                 ::= CUSTOM
varlist-options ::= 
                ::= ( STRING )
opt-list ::=
         ::= LIST
string-options ::= 
               ::= ( STRING STRING )
@end example

The special forms are of the following types:

@table @code
@item VAR

A single variable name.

@item VARLIST

A list of variables.  If given, the string can be used to provide
@code{PV_@var{*}} options to the call to @code{parse_variables}. 

@item INTEGER

A single integer value.

@item INTEGER LIST

A list of integers separated by spaces or commas.

@item DOUBLE

A single floating-point value.

@item DOUBLE LIST

A list of floating-point values.

@item PINT

A single positive integer value.

@item STRING

A string value.  If the options are given then the first string is an
expression giving a restriction on the value of the string; the second
string is an error message to display when the restriction is violated.

@item CUSTOM

A custom function is used to parse this subcommand.  The function must
have prototype @code{int custom_@var{name} (void)}.  It should return 0
on failure (when it has already issued an appropriate diagnostic), 1 on
success, or 2 if it fails and the calling function should issue a syntax
error on behalf of the custom handler.

@end table
@setfilename ignored