Rewrite PSPP output engine.
[pspp-builds.git] / doc / dev / q2c.texi
1 @node q2c Input Format
2 @appendix @code{q2c} Input Format
3
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
8 @code{q2c}.
9
10 @menu
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.
14 @end menu
15
16 @node Invoking q2c
17 @section Invoking q2c
18
19 @example
20 q2c @var{input.q} @var{output.c}
21 @end example
22
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
26 command-line options.
27
28 @node q2c Input Structure
29 @section @code{q2c} Input Structure
30
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.
37
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}
46 without being munged.
47
48 The syntax of the grammar rules themselves is given in the following
49 sections.
50
51 The supporting code is passed into the output file largely unchanged.
52 However, the following escapes are supported.  Each escape must appear
53 on a line by itself.
54
55 @table @code
56 @item /* (header) */
57
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}.
60
61 @item /* (decls @var{scope}) */
62
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
68 a bit of a misnomer.
69
70 @item /* (parser) */
71
72 Expands to the entire parser.  Must be enclosed within a C function.
73
74 @item /* (free) */
75
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.
79 @end table
80
81 @node Grammar Rules
82 @section Grammar Rules
83
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.
87
88 The grammar rules are divided into tokens of the following types:
89
90 @table @asis
91 @item Identifier (@code{ID})
92
93 An identifier token is a sequence of letters, digits, and underscores
94 (@samp{_}).  Identifiers are @emph{not} case-sensitive.
95
96 @item String (@code{STRING})
97
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.
104
105 @item Special character
106
107 Other characters, other than white space, constitute tokens in
108 themselves.
109
110 @end table
111
112 The syntax of the grammar rules is as follows:
113
114 @example
115 grammar-rules ::= command-name opt-prefix : subcommands .
116 command-name ::= ID
117              ::= STRING
118 opt-prefix ::=
119            ::= ( ID )
120 subcommands ::= subcommand
121             ::= subcommands ; subcommand
122 @end example
123
124 The syntax begins with an ID token that gives the name of the
125 procedure to be parsed.  For command names that contain multiple
126 words, a STRING token may be used instead, e.g.@: @samp{"FILE
127 HANDLE"}.  Optionally, an ID in parentheses specifies a prefix used
128 for all file-scope identifiers declared by the emitted code.
129
130 The rest of the syntax consists of subcommands separated by semicolons
131 (@samp{;}) and terminated with a full stop (@samp{.}).
132
133 @example
134 subcommand ::= default-opt arity-opt ID sbc-defn
135 default-opt ::=
136             ::= *
137 arity-opt ::=
138           ::= +
139           ::= ^
140 sbc-defn ::= opt-prefix = specifiers
141          ::= [ ID ] = array-sbc
142          ::= opt-prefix = sbc-special-form
143 @end example
144
145 A subcommand that begins with an asterisk (@samp{*}) is the default
146 subcommand.  The keyword used for the default subcommand can be omitted
147 in the PSPP syntax file.
148
149 A plus sign (@samp{+}) indicates that a subcommand can appear more than
150 once.  A caret (@samp{^}) indicate that a subcommand must appear exactly
151 once.  A subcommand marked with neither character may appear once or not
152 at all, but not more than once.
153
154 The subcommand name appears after the leading option characters.
155
156 There are three forms of subcommands.  The first and most common form
157 simply gives an equals sign (@samp{=}) and a list of specifiers, which
158 can each be set to a single setting.  The second form declares an array,
159 which is a set of flags that can be individually turned on by the user.
160 There are also several special forms that do not take a list of
161 specifiers.
162
163 Arrays require an additional @code{ID} argument.  This is used as a
164 prefix, prepended to the variable names constructed from the
165 specifiers.  The other forms also allow an optional prefix to be
166 specified.
167
168 @example
169 array-sbc ::= alternatives
170           ::= array-sbc , alternatives
171 alternatives ::= ID
172              ::= alternatives | ID
173 @end example
174
175 An array subcommand is a set of Boolean values that can independently be
176 turned on by the user, listed separated by commas (@samp{,}).  If an value has more
177 than one name then these names are separated by pipes (@samp{|}).
178
179 @example
180 specifiers ::= specifier
181            ::= specifiers , specifier
182 specifier ::= opt-id : settings
183 opt-id ::=
184        ::= ID
185 @end example
186
187 Ordinary subcommands (other than arrays and special forms) require a
188 list of specifiers.  Each specifier has an optional name and a list of
189 settings.  If the name is given then a correspondingly named variable
190 will be used to store the user's choice of setting.  If no name is given
191 then there is no way to tell which setting the user picked; in this case
192 the settings should probably have values attached.
193
194 @example
195 settings ::= setting
196          ::= settings / setting
197 setting ::= setting-options ID setting-value
198 setting-options ::=
199                 ::= *
200                 ::= !
201                 ::= * !
202 @end example
203
204 Individual settings are separated by forward slashes (@samp{/}).  Each
205 setting can be as little as an @code{ID} token, but options and values
206 can optionally be included.  The @samp{*} option means that, for this
207 setting, the @code{ID} can be omitted.  The @samp{!} option means that
208 this option is the default for its specifier.
209
210 @example
211 setting-value ::=
212               ::= ( setting-value-2 )
213               ::= setting-value-2
214 setting-value-2 ::= setting-value-options setting-value-type : ID
215                     setting-value-restriction
216 setting-value-options ::=
217                       ::= *
218 setting-value-type ::= N
219                    ::= D
220                    ::= S
221 setting-value-restriction ::=
222                           ::= , STRING
223 @end example
224
225 Settings may have values.  If the value must be enclosed in parentheses,
226 then enclose the value declaration in parentheses.  Declare the setting
227 type as @samp{n}, @samp{d}, or @samp{s} for integer, floating-point,
228 or string type, respectively.  The given @code{ID} is used to
229 construct a variable name.
230 If option @samp{*} is given, then the value is optional; otherwise it
231 must be specified whenever the corresponding setting is specified.  A
232 ``restriction'' can also be specified which is a string giving a C
233 expression limiting the valid range of the value.  The special escape
234 @code{%s} should be used within the restriction to refer to the
235 setting's value variable.
236
237 @example
238 sbc-special-form ::= VAR
239                  ::= VARLIST varlist-options
240                  ::= INTEGER opt-list
241                  ::= DOUBLE opt-list
242                  ::= PINT
243                  ::= STRING @r{(the literal word STRING)} string-options
244                  ::= CUSTOM
245 varlist-options ::=
246                 ::= ( STRING )
247 opt-list ::=
248          ::= LIST
249 string-options ::=
250                ::= ( STRING STRING )
251 @end example
252
253 The special forms are of the following types:
254
255 @table @code
256 @item VAR
257
258 A single variable name.
259
260 @item VARLIST
261
262 A list of variables.  If given, the string can be used to provide
263 @code{PV_@var{*}} options to the call to @code{parse_variables}.
264
265 @item INTEGER
266
267 A single integer value.
268
269 @item INTEGER LIST
270
271 A list of integers separated by spaces or commas.
272
273 @item DOUBLE
274
275 A single floating-point value.
276
277 @item DOUBLE LIST
278
279 A list of floating-point values.
280
281 @item PINT
282
283 A single positive integer value.
284
285 @item STRING
286
287 A string value.  If the options are given then the first string is an
288 expression giving a restriction on the value of the string; the second
289 string is an error message to display when the restriction is violated.
290
291 @item CUSTOM
292
293 A custom function is used to parse this subcommand.  The function must
294 have prototype @code{int custom_@var{name} (void)}.  It should return 0
295 on failure (when it has already issued an appropriate diagnostic), 1 on
296 success, or 2 if it fails and the calling function should issue a syntax
297 error on behalf of the custom handler.
298
299 @end table
300 @setfilename ignored