doc/q2c.texi

   1 @node q2c Input Format, GNU Free Documentation License, Data File Format, Top
   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, q2c Input Structure, q2c Input Format, q2c Input Format
  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, Grammar Rules, Invoking q2c, q2c Input Format
  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,  , q2c Input Structure, q2c Input Format
  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 ::= ID : subcommands .
 116 subcommands ::= subcommand
 117             ::= subcommands ; subcommand
 118 @end example
 119
 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
 123 (@samp{.}).
 124
 125 @example
 126 subcommand ::= default-opt arity-opt ID sbc-defn
 127 default-opt ::=
 128             ::= *
 129 arity-opt ::=
 130           ::= +
 131           ::= ^
 132 sbc-defn ::= opt-prefix = specifiers
 133          ::= [ ID ] = array-sbc
 134          ::= opt-prefix = sbc-special-form
 135 opt-prefix ::=
 136            ::= ( ID )
 137 @end example
 138
 139 A subcommand that begins with an asterisk (@samp{*}) is the default
 140 subcommand.  The keyword used for the default subcommand can be omitted
 141 in the PSPP syntax file.
 142
 143 A plus sign (@samp{+}) indicates that a subcommand can appear more than
 144 once.  A caret (@samp{^}) indicate that a subcommand must appear exactly
 145 once.  A subcommand marked with neither character may appear once or not
 146 at all, but not more than once.
 147
 148 The subcommand name appears after the leading option characters.
 149
 150 There are three forms of subcommands.  The first and most common form
 151 simply gives an equals sign (@samp{=}) and a list of specifiers, which
 152 can each be set to a single setting.  The second form declares an array,
 153 which is a set of flags that can be individually turned on by the user.
 154 There are also several special forms that do not take a list of
 155 specifiers.
 156
 157 Arrays require an additional @code{ID} argument.  This is used as a
 158 prefix, prepended to the variable names constructed from the
 159 specifiers.  The other forms also allow an optional prefix to be
 160 specified.
 161
 162 @example
 163 array-sbc ::= alternatives
 164           ::= array-sbc , alternatives
 165 alternatives ::= ID
 166              ::= alternatives | ID
 167 @end example
 168
 169 An array subcommand is a set of Boolean values that can independently be
 170 turned on by the user, listed separated by commas (@samp{,}).  If an value has more
 171 than one name then these names are separated by pipes (@samp{|}).
 172
 173 @example
 174 specifiers ::= specifier
 175            ::= specifiers , specifier
 176 specifier ::= opt-id : settings
 177 opt-id ::=
 178        ::= ID
 179 @end example
 180
 181 Ordinary subcommands (other than arrays and special forms) require a
 182 list of specifiers.  Each specifier has an optional name and a list of
 183 settings.  If the name is given then a correspondingly named variable
 184 will be used to store the user's choice of setting.  If no name is given
 185 then there is no way to tell which setting the user picked; in this case
 186 the settings should probably have values attached.
 187
 188 @example
 189 settings ::= setting
 190          ::= settings / setting
 191 setting ::= setting-options ID setting-value
 192 setting-options ::=
 193                 ::= *
 194                 ::= !
 195                 ::= * !
 196 @end example
 197
 198 Individual settings are separated by forward slashes (@samp{/}).  Each
 199 setting can be as little as an @code{ID} token, but options and values
 200 can optionally be included.  The @samp{*} option means that, for this
 201 setting, the @code{ID} can be omitted.  The @samp{!} option means that
 202 this option is the default for its specifier.
 203
 204 @example
 205 setting-value ::=
 206               ::= ( setting-value-2 )
 207               ::= setting-value-2
 208 setting-value-2 ::= setting-value-options setting-value-type : ID
 209                     setting-value-restriction
 210 setting-value-options ::=
 211                       ::= *
 212 setting-value-type ::= N
 213                    ::= D
 214 setting-value-restriction ::=
 215                           ::= , STRING
 216 @end example
 217
 218 Settings may have values.  If the value must be enclosed in parentheses,
 219 then enclose the value declaration in parentheses.  Declare the setting
 220 type as @samp{n} or @samp{d} for integer or floating point type,
 221 respectively.  The given @code{ID} is used to construct a variable name.
 222 If option @samp{*} is given, then the value is optional; otherwise it
 223 must be specified whenever the corresponding setting is specified.  A
 224 ``restriction'' can also be specified which is a string giving a C
 225 expression limiting the valid range of the value.  The special escape
 226 @code{%s} should be used within the restriction to refer to the
 227 setting's value variable.
 228
 229 @example
 230 sbc-special-form ::= VAR
 231                  ::= VARLIST varlist-options
 232                  ::= INTEGER opt-list
 233                  ::= DOUBLE opt-list
 234                  ::= PINT
 235                  ::= STRING @r{(the literal word STRING)} string-options
 236                  ::= CUSTOM
 237 varlist-options ::=
 238                 ::= ( STRING )
 239 opt-list ::=
 240          ::= LIST
 241 string-options ::=
 242                ::= ( STRING STRING )
 243 @end example
 244
 245 The special forms are of the following types:
 246
 247 @table @code
 248 @item VAR
 249
 250 A single variable name.
 251
 252 @item VARLIST
 253
 254 A list of variables.  If given, the string can be used to provide
 255 @code{PV_@var{*}} options to the call to @code{parse_variables}.
 256
 257 @item INTEGER
 258
 259 A single integer value.
 260
 261 @item INTEGER LIST
 262
 263 A list of integers separated by spaces or commas.
 264
 265 @item DOUBLE
 266
 267 A single floating-point value.
 268
 269 @item DOUBLE LIST
 270
 271 A list of floating-point values.
 272
 273 @item PINT
 274
 275 A single positive integer value.
 276
 277 @item STRING
 278
 279 A string value.  If the options are given then the first string is an
 280 expression giving a restriction on the value of the string; the second
 281 string is an error message to display when the restriction is violated.
 282
 283 @item CUSTOM
 284
 285 A custom function is used to parse this subcommand.  The function must
 286 have prototype @code{int custom_@var{name} (void)}.  It should return 0
 287 on failure (when it has already issued an appropriate diagnostic), 1 on
 288 success, or 2 if it fails and the calling function should issue a syntax
 289 error on behalf of the custom handler.
 290
 291 @end table
 292 @setfilename ignored