1 @node q2c Input Format, , Data File Format, Top
2 @appendix @code{q2c} Input Format
4 PSPP statistical procedures have a bizarre and somewhat irregular
5 syntax. Despite this, a parser generator has been written that
6 adequately addresses many of the possibilities and tries to provide
7 hooks for the exceptional cases. This parser generator is named
11 * Invoking q2c:: q2c command-line syntax.
12 * q2c Input Structure:: High-level layout of the input file.
13 * Grammar Rules:: Syntax of the grammar rules.
16 @node Invoking q2c, q2c Input Structure, q2c Input Format, q2c Input Format
20 q2c @var{input.q} @var{output.c}
23 @code{q2c} translates a @samp{.q} file into a @samp{.c} file. It takes
24 exactly two command-line arguments, which are the input file name and
25 output file name, respectively. @code{q2c} does not accept any
28 @node q2c Input Structure, Grammar Rules, Invoking q2c, q2c Input Format
29 @section @code{q2c} Input Structure
31 @code{q2c} input files are divided into two sections: the grammar rules
32 and the supporting code. The @dfn{grammar rules}, which make up the
33 first part of the input, are used to define the syntax of the
34 statistical procedure to be parsed. The @dfn{supporting code},
35 following the grammar rules, are copied largely unchanged to the output
36 file, except for certain escapes.
38 The most important lines in the grammar rules are used for defining
39 procedure syntax. These lines can be prefixed with a dollar sign
40 (@samp{$}), which prevents Emacs' CC-mode from munging them. Besides
41 this, a bang (@samp{!}) at the beginning of a line causes the line,
42 minus the bang, to be written verbatim to the output file (useful for
43 comments). As a third special case, any line that begins with the exact
44 characters @code{/* *INDENT} is ignored and not written to the output.
45 This allows @code{.q} files to be processed through @code{indent}
48 The syntax of the grammar rules themselves is given in the following
51 The supporting code is passed into the output file largely unchanged.
52 However, the following escapes are supported. Each escape must appear
58 Expands to a series of C @code{#include} directives which include the
59 headers that are required for the parser generated by @code{q2c}.
61 @item /* (decls @var{scope}) */
63 Expands to C variable and data type declarations for the variables and
64 @code{enum}s input and output by the @code{q2c} parser. @var{scope}
65 must be either @code{local} or @code{global}. @code{local} causes the
66 declarations to be output as function locals. @code{global} causes them
67 to be declared as @code{static} module variables; thus, @code{global} is
72 Expands to the entire parser. Must be enclosed within a C function.
76 Expands to a set of calls to the @code{free} function for variables
77 declared by the parser. Only needs to be invoked if subcommands of type
78 @code{string} are used in the grammar rules.
81 @node Grammar Rules, , q2c Input Structure, q2c Input Format
82 @section Grammar Rules
84 The grammar rules describe the format of the syntax that the parser
85 generated by @code{q2c} will understand. The way that the grammar rules
86 are included in @code{q2c} input file are described above.
88 The grammar rules are divided into tokens of the following types:
91 @item Identifier (@code{ID})
93 An identifier token is a sequence of letters, digits, and underscores
94 (@samp{_}). Identifiers are @emph{not} case-sensitive.
96 @item String (@code{STRING})
98 String tokens are initiated by a double-quote character (@samp{"}) and
99 consist of all the characters between that double quote and the next
100 double quote, which must be on the same line as the first. Within a
101 string, a backslash can be used as a ``literal escape''. The only
102 reasons to use a literal escape are to include a double quote or a
103 backslash within a string.
105 @item Special character
107 Other characters, other than whitespace, constitute tokens in
112 The syntax of the grammar rules is as follows:
115 grammar-rules ::= ID : subcommands .
116 subcommands ::= subcommand
117 ::= subcommands ; subcommand
120 The syntax begins with an ID or STRING token that gives the name of the
121 procedure to be parsed. The rest of the syntax consists of subcommands
122 separated by semicolons (@samp{;}) and terminated with a full stop
126 subcommand ::= sbc-options ID sbc-defn
129 ::= sbc-options sbc-options
132 sbc-defn ::= opt-prefix = specifiers
133 ::= [ ID ] = array-sbc
134 ::= opt-prefix = sbc-special-form
139 Each subcommand can be prefixed with one or more option characters. An
140 asterisk (@samp{*}) is used to indicate the default subcommand; the
141 keyword used for the default subcommand can be omitted in the PSPP
142 syntax file. A plus sign (@samp{+}) is used to indicate that a
143 subcommand can appear more than once; if it is not present then that
144 subcommand can appear no more than once.
146 The subcommand name appears after the option characters.
148 There are three forms of subcommands. The first and most common form
149 simply gives an equals sign (@samp{=}) and a list of specifiers, which
150 can each be set to a single setting. The second form declares an array,
151 which is a set of flags that can be individually turned on by the user.
152 There are also several special forms that do not take a list of
155 Arrays require an additional @code{ID} argument. This is used as a
156 prefix, prepended to the variable names constructed from the
157 specifiers. The other forms also allow an optional prefix to be
161 array-sbc ::= alternatives
162 ::= array-sbc , alternatives
164 ::= alternatives | ID
167 An array subcommand is a set of Boolean values that can independently be
168 turned on by the user, listed separated by commas (@samp{,}). If an value has more
169 than one name then these names are separated by pipes (@samp{|}).
172 specifiers ::= specifier
173 ::= specifiers , specifier
174 specifier ::= opt-id : settings
179 Ordinary subcommands (other than arrays and special forms) require a
180 list of specifiers. Each specifier has an optional name and a list of
181 settings. If the name is given then a correspondingly named variable
182 will be used to store the user's choice of setting. If no name is given
183 then there is no way to tell which setting the user picked; in this case
184 the settings should probably have values attached.
188 ::= settings / setting
189 setting ::= setting-options ID setting-value
196 Individual settings are separated by forward slashes (@samp{/}). Each
197 setting can be as little as an @code{ID} token, but options and values
198 can optionally be included. The @samp{*} option means that, for this
199 setting, the @code{ID} can be omitted. The @samp{!} option means that
200 this option is the default for its specifier.
204 ::= ( setting-value-2 )
206 setting-value-2 ::= setting-value-options setting-value-type : ID
207 setting-value-restriction
208 setting-value-options ::=
210 setting-value-type ::= N
212 setting-value-restriction ::=
216 Settings may have values. If the value must be enclosed in parentheses,
217 then enclose the value declaration in parentheses. Declare the setting
218 type as @samp{n} or @samp{d} for integer or floating point type,
219 respectively. The given @code{ID} is used to construct a variable name.
220 If option @samp{*} is given, then the value is optional; otherwise it
221 must be specified whenever the corresponding setting is specified. A
222 ``restriction'' can also be specified which is a string giving a C
223 expression limiting the valid range of the value. The special escape
224 @code{%s} should be used within the restriction to refer to the
225 setting's value variable.
228 sbc-special-form ::= VAR
229 ::= VARLIST varlist-options
233 ::= STRING @r{(the literal word STRING)} string-options
240 ::= ( STRING STRING )
243 The special forms are of the following types:
248 A single variable name.
252 A list of variables. If given, the string can be used to provide
253 @code{PV_@var{*}} options to the call to @code{parse_variables}.
257 A single integer value.
261 A list of integers separated by spaces or commas.
265 A single floating-point value.
269 A list of floating-point values.
273 A single positive integer value.
277 A string value. If the options are given then the first string is an
278 expression giving a restriction on the value of the string; the second
279 string is an error message to display when the restriction is violated.
283 A custom function is used to parse this subcommand. The function must
284 have prototype @code{int custom_@var{name} (void)}. It should return 0
285 on failure (when it has already issued an appropriate diagnostic), 1 on
286 success, or 2 if it fails and the calling function should issue a syntax
287 error on behalf of the custom handler.