Debian Codegraph @

documentation/manual/invoking/options.yo

raw
1 Where available, single letter options are listed between parentheses
2 beyond their associated long-option variants. Single letter options require
3 arguments if their associated long options also require arguments. Options
4 affecting the class- or implementation header files are ignored if these
5 files already exist. Options accepting a `filename' do not accept path names,
6 i.e., they cannot contain directory separators (tt(/)); options accepting a
7 'pathname' may contain directory separators.
8
9 Some options may cause errors. This happens when they conflict with the
10 contents of a file which bic() cannot modify (e.g., a parser class header file
11 exists, but doesn't define a namespace, but a tt(--namespace) option was
12 specified).
13
14 To solve the error the offending option could be omitted; the existing file
15 could be removed; or the existing file could be hand-edited according to the
16 option's specification.
17
18 Note that bic() currently does not handle the opposite error condition: if a
19 previously used option is omitted, then bic() does not report an
20 inconsistency. In those cases compilation errors may be observed.
21
22 itemization(
23 it() loption(analyze-only) (soption(A))nl()
24 Only analyze the grammar. No files are (re)written. This option can
25 be used to test the grammatic correctness of modification `in
26 situ', without overwriting previously generated files. If the
27 grammar contains syntactic errors only syntax analysis is
28 performed.
29
30 it() lsoption(baseclass-header)(b)(filename)nl()
31 tt(Filename) defines the name of the file to contain the parser's
32 base class. This class defines, e.g., the parser's symbolic
33 tokens. Defaults to the name of the parser class plus the suffix
34 tt(base.h). It is generated, unless otherwise indicated (see
35 tt(--no-baseclass-header) and tt(--dont-rewrite-baseclass-header)
36 below).
37
38 It is an error if this option is used and an already
39 existing parser class header file does not contain tt(#include
40 "filename").
41
42 it() label(PREINCLUDE) lsoption(baseclass-preinclude)(H)(pathname)nl()
43 tt(Pathname) defines the path to the file preincluded in the
44 parser's base-class header. This option is needed in situations
45 where the base class header file refers to types which might not
46 yet be known. E.g., with polymorphic semantic values a
47 tt(std::string) value type might be used. Since the tt(string)
48 header file is not by default included in tt(parserbase.h) we
49 somehow need to inform the compiler about this and possibly other
50 headers. The suggested procedure is to use a pre-include header
51 file declaring the required types. By default `tt(header)' is
52 surrounded by double quotes: tt(#include "header") is used when
53 the option tt(-H header) is specified. When the argument is
54 surrounded by pointed brackets tt(#include <header>) is
55 included. In the latter case, quotes might be required to escape
56 interpretation by the shell (e.g., using tt(-H '<header>')).
57
58 it() lsoption(baseclass-skeleton)(B)(pathname)nl()
59 tt(Pathname) defines the path name to the file containing the
60 skeleton of the parser's base class. It defaults to the
61 installation-defined default path name (e.g.,
62 tt(/usr/share/bisonc++/) plus tt(bisonc++base.h)).
63
64 it() lsoption(class-header)(c)(filename)nl()
65 tt(Filename) defines the name of the file to contain the parser
66 class. Defaults to the name of the parser class plus the suffix
67 tt(.h)
68
69 It is an error if this option is used and an already
70 existing implementation header file does not contain tt(#include
71 "filename").
72
73 it() loption(class-name) tt(className) nl()
74 Defines the name of the bf(C++) class that is generated. If
75 neither this option, nor the tt(%class-name) directory is
76 specified, then the default class name (tt(Parser)) is used.
77
78 It is an error if this option is used and tt(className) differs
79 from the name of the class that is defined in an already existing
80 parser-class header file and/or if an already existing
81 implementation header file does not define members of the class
82 tt(`className').
83
84 it() lsoption(class-skeleton)(C)(pathname)nl()
85 tt(Pathname) defines the path name to the file containing the
86 skeleton of the parser class. It defaults to the
87 installation-defined default path name (e.g.,
88 tt(/usr/share/bisonc++/) plus tt(bisonc++.h)).
89
90 it() loption(construction)nl()
91 Details about the construction of the parsing tables are written to
92 the same file as written by the tt(--verbose) option (i.e.,
93 tt(<grammar>.output), where tt(<grammar>) is the input file read
94 by bic()). This information is primarily useful for developers. It
95 augments the information written to the verbose grammar output
96 file, generated by the tt(--verbose) option.
97
98 it() loption(debug)nl()
99 Provide the generated tt(parse) and its support functions with
100 debugging code, optionally showing the actual parsing process on
101 the standard output stream. When included, the debugging output is
102 active by default, but its activity may be controlled using the
103 tt(setDebug(bool on-off)) member. Bic() does not use tt(#ifdef
104 DEBUG) macros. Rerun bic() without the tt(--debug) option to
105 remove the debugging code.
106
107 Note that this option does em(not) show the actions of bic()'s own
108 parser, its own lexical scanner or merely the numbers of the
109 case-entries executed by the parser's tt(parse) function. If that
110 is what you want, use the tt(--own-debug, --action-cases,
111 --scanner-debug) and/or tt(--own-tokens) options.
112
113 When polymorphic semantic values
114 are used (see section
115 IFDEF(manpagetext)(\
116 bf(POLYMORPHIC SEMANTIC VALUES)\
117 )(\
118 ref(POLYMORPHIC)\
119 ))
120 then the generated parser might attempt to retrieve an incorrect
121 polymorphic value. In that case a fatal error is generated, ending
122 bic()'s run. The error message itself cannot refer to the action
123 block where the error occurred. If this situation is encountered,
124 rerun bic(), specifying tt(--debug) and call
125 tt(parser.setDebug(Parser::ACTIONCASES)): as a debugging aid the
126 generated parser then shows the executeAction switch's case entry
127 numbers just before their execution.
128
129 it() lsoption(default-actions)(d)(off|quiet|warn)nl()
130 When tt(warn) is specified (which is the default) an action block
131 executing tt($$ = $1) (or tt($$ = STYPE_{}) for empty production
132 rules) is added to production rules that do not explicitly define
133 their own final action blocks, while issuing a warning. When
134 tt(quiet) is specified these action blocks are silently added. It
135 is an error when the types of $$ and $1 differ (but it is OK if
136 neither $$ nor $1 is associated with a specific type). When
137 tt(off) is specified no action blocks are added (issuing a warning
138 unless the option/directive tt(tag-mismatches off) has been
139 specified).
140
141 it() label(ERRORVERBOSE)loption(error-verbose)nl()
142 When a syntactic error is reported, the generated parse function
143 dumps the parser's state stack to the standard output
144 stream. The stack dump shows on separate lines a stack index
145 followed by the state stored at the indicated stack element. The
146 first stack element is the stack's top element.
147
148 it() lsoption(filenames)(f)(filename)nl()
149 tt(Filename) is a generic file name that is used for all header
150 files generated by bic(). Options defining specific file names are
151 also available (which then, in turn, overrule the name specified
152 by this option).
153
154 it() loption(flex)nl()
155 Bic() generates code calling tt(d_scanner.yylex()) to obtain the
156 next lexical token, and calling tt(d_scanner.YYText()) for the
157 matched text, unless overruled by options or directives explicitly
158 defining these functions. By default, the interface defined by
159 bf(flexc++)(1) is used. This option is only interpreted if the
160 tt(--scanner) option or tt(%scanner) directive is also used.
161
162 it() loption(help) (soption(h))nl()
163 Write basic usage information to the standard output stream and
164 terminate.
165
166 it() lsoption(implementation-header)(i)(filename)nl()
167 tt(Filename) defines the name of the file to contain the
168 implementation header. It defaults to the name of the generated
169 parser class plus the suffix tt(.ih).
170
171 The implementation header should contain all directives and
172 declarations em(only) used by the implementations of the parser's
173 member functions. It is the only header file that is included by
174 the source file containing tt(parse)'s implementation. User
175 defined implementation of other class members may use the same
176 convention, thus concentrating all directives and declarations
177 that are required for the compilation of other source files
178 belonging to the parser class in one header file.
179
180 it() lsoption(implementation-skeleton)(I)(pathname)nl()
181 tt(Pathname) defines the path name to the file containing the
182 skeleton of the implementation header. t defaults to the
183 installation-defined default path name (e.g.,
184 tt(/usr/share/bisonc++/) plus tt(bisonc++.ih)).
185
186 it() loption(insert-stype)nl()
187 This option is only effective if the tt(debug) option (or
188 tt(%debug) directive) has been specified. When tt(insert-stype)
189 has been specified the parsing function's debug output also shows
190 selected semantic values. It should only be used if objects or
191 variables of the semantic value type tt(STYPE_) can be inserted
192 into tt(ostreams).
193
194 it() label(MAXDEPTH) laoption(max-inclusion-depth)(value)nl()
195 Set the maximum number of nested grammar files. Defaults to 10.
196
197 it() loption(namespace) tt(identifier) nl()
198 Define all of the code generated by bic() in the namespace
199 tt(identifier). By default no namespace is defined. If this
200 options is used the implementation header is provided with a
201 commented out tt(using namespace) declaration for the specified
202 namespace. In addition, the parser and parser base class
203 header files also use the specified namespace to define their
204 include guard directives.
205
206 It is an error if this option is used and an already existing
207 parser-class header file and/or implementation header file does
208 not define tt(namespace identifier).
209
210 it() loption(no-baseclass-header)nl()
211 Do not write the file containing the parser class' base class, even
212 if that file doesn't yet exist. By default the file containing the
213 parser's base class is (re)written each time bic() is called. Note
214 that this option should normally be avoided, as the base class
215 defines the symbolic terminal tokens that are returned by the
216 lexical scanner. When the construction of this file is suppressed,
217 modifications of these terminal tokens are not communicated to the
218 lexical scanner.
219
220 it() loption(no-decoration) (soption(D))nl()
221 Do not include user-defined or default actions when generating the
222 parser's tt(parse) member. This effectively generates a parser
223 which merely performs syntax checks, without performing the
224 actions which are normally executed when rules have been
225 matched. This may be useful in situations where a (partially or
226 completely) decorated grammar is reorganized, and the syntactic
227 correctness of the modified grammar must be verified, or in
228 situations where the grammar has already been decorated, but
229 functions which are called from the rules's actions have not yet
230 been impleemented.
231
232 it() loption(no-lines)nl()
233 Do not put tt(#line) preprocessor directives in the file containing
234 the parser's tt(parse) function. By default the file containing
235 the parser's tt(parse) function also contains tt(#line)
236 preprocessor directives. This option allows the compiler and
237 debuggers to associate errors with lines in your grammar
238 specification file, rather than with the source file containing
239 the tt(parse) function itself.
240
241 it() loption(no-parse-member)nl()
242 Do not write the file containing the parser's predefined parser
243 member functions, even if that file doesn't yet exist. By default
244 the file containing the parser's tt(parse) member function is
245 (re)written each time bic() is called. Note that this option
246 should normally be avoided, as this file contains parsing
247 tables which are altered whenever the grammar definition is
248 modified.
249
250 it() loption(own-debug)nl()
251 Displays the actions performed by bic()'s parser when it processes
252 the grammar specification file(s) (lots of output!). This implies
253 the tt(--verbose) option.
254
255 it() loption(own-tokens) (soption(T))nl()
256 The tokens returned as well as the text matched by bic()'s lexcial
257 scanner are shown when this option is used.
258
259 This option does em(not) result in the em(generated) parsing
260 function displaying returned tokens and matched text. If that is
261 what you want, use the tt(--print-tokens) option.
262
263 it() lsoption(parsefun-skeleton)(P)(pathname)nl()
264 tt(Pathname) defines the path name of the file containing the
265 parsing member function's skeleton. It defaults to the
266 installation-defined default path name (e.g.,
267 tt(/usr/share/bisonc++/) plus tt(bisonc++.cc)).
268
269 it() lsoption(parsefun-source)(p)(filename)nl()
270 tt(Filename) defines the name of the source file to contain the
271 parser member function tt(parse). Defaults to tt(parse.cc).
272
273 it() lsoption(polymorphic-code-skeleton)(L)(pathname)nl()
274 tt(Pathname) defines the path name of the file containing the
275 non-template members of the polymorphic Base class. It defaults
276 to the installation-defined default path name (e.g.,
277 tt(/usr/share/bisonc++/) plus tt(bisonc++polymorphic.code)).
278
279 it() lsoption(polymorphic-skeleton)(M)(pathame)nl()
280 tt(Pathname) defines the path name of the file containing the
281 skeleton of the polymorphic template classes. It defaults to the
282 installation-defined default path name (e.g.,
283 tt(/usr/share/bisonc++/) plus tt(bisonc++polymorphic)).
284
285 it() loption(print-tokens) (soption(t))nl()
286 The generated parsing function implements a function tt(print_)
287 displaying (on the standard output stream) the tokens returned by
288 the parser's scanner as well as the corresponding matched
289 text. This implementation is suppressed when the parsing function
290 is generated without using this option. The member tt(print_) is
291 called from tt(Parser::print), which is defined in-line in the the
292 parser's class header. Calling tt(Parser::print_) can thus easily
293 be controlled from tt(print), using, e.g., a variable that set by
294 the program using the parser generated by bic().
295
296 This option does em(not) show the tokens returned and text matched
297 by bic() itself when it is reading its input file(s). If
298 that is what you want, use the tt(--own-tokens) option.
299
300 it() loption(prompt)nl()
301 When adding debugging code (using the tt(debug) option or
302 directive) the debug information is displayed continuously while
303 the parser processes its input. When using the tt(prompt) option
304 (or directive) the generated parser displays a prompt (a question
305 mark) at each step of the parsing process. Caveat: when using this
306 option the parser's input cannot be provided at the parser's
307 standard input stream.
308
309 it() label(REQUIRED) laoption(required-tokens)(number)nl()
310 Following a syntactic error, require at least tt(number)
311 successfully processed tokens before another syntactic error can
312 be reported. By default tt(number) is zero.
313
314 it() label(SCANOPT) lsoption(scanner)(s)(pathname)nl()
315 tt(Pathname) defines the path name to the file defining the
316 scanner's class interface (e.g., tt("../scanner/scanner.h")). When
317 this option is used the parser's member tt(int lex()) is
318 predefined as
319 verb(
320 int Parser::lex()
321 {
322 return d_scanner.lex();
323 }
324 )
325 and an object tt(Scanner d_scanner) is composed into the parser
326 (but see also option tt(scanner-class-name)). The example shows
327 the function that's called by default. When the tt(--flex) option
328 (or tt(%flex) directive) is specified the function
329 tt(d_scanner.yylex()) is called. Any other function to call can be
330 specified using the tt(--scanner-token-function) option (or
331 tt(%scanner-token-function) directive).
332
333 By default bic() surrounds tt(pathname) by double quotes (using,
334 e.g., tt(#include "pathname")). When tt(pathname) is surrounded
335 by pointed brackets tt(#include <pathname>) is included.
336
337 It is an error if this option is used and an already existing
338 parser class header file does not include tt(`pathname').
339
340 it() loption(scanner-class-name) tt(scannerClassName) nl()
341 Defines the name of the scanner class, declared by the tt(pathname)
342 header file that is specified at the tt(scanner) option or
343 directive. By default the class name tt(Scanner) is used.
344
345 It is an error if this option is used and either the
346 tt(scanner) option was not provided, or the parser class interface
347 in an already existing parser class header file does not declare a
348 scanner class tt(d_scanner) object.
349
350 it() loption(scanner-debug)nl()
351 Show de scanner's matched rules and returned tokens. This
352 extensively displays the rules and tokens matched and returned by
353 bic()'s scanner, instead of just showing the tokens and matched
354 text which are received by bic(). If you want the latter, use the
355 option tt(--own-tokens).
356
357 it() laoption(scanner-matched-text-function)(function-call)nl()
358 The scanner function returning the text that was matched at the
359 last call of the scanner's token function. A complete function
360 call expression should be provided (including a scanner object, if
361 used). This option overrules the tt(d_scanner.matched()) call used
362 by default when the tt(%scanner) directive is specified, and it
363 overrules the tt(d_scanner.YYText()) call used when the tt(%flex)
364 directive is provided. Example:
365 verb(
366 --scanner-matched-text-function "myScanner.matchedText()"
367 )
368
369 it() laoption(scanner-token-function)(function-call)nl()
370 The scanner function returning the next token, called from the
371 parser's tt(lex) function. A complete function
372 call expression should be provided (including a scanner object, if
373 used). This option overrules the tt(d_scanner.lex()) call used
374 by default when the tt(%scanner) directive is specified, and it
375 overrules the tt(d_scanner.yylex()) call used when the tt(%flex)
376 directive is provided. Example:
377 verb(
378 --scanner-token-function "myScanner.nextToken()"
379 )
380
381 It is an error if this option is used and the scanner token
382 function is not called from the code in an already
383 existing implementation header.
384
385 it() loption(show-filenames)nl()
386 Writes the names of the generated files to the standard error
387 stream.
388
389 it() lsoption(skeleton-directory)(S)(directory)nl()
390 Specifies the directory containing the skeleton files. In addition
391 to specifying a common names for the skeleton files the locations
392 of individual skeleton files can be specified using the options
393 (tt(-B -C, -H, -I, -L) and tt(-M)).
394
395 it() loption(stack-expansion)(size)nl()
396 Defines the number of elements to be added to the generated
397 parser's semantic value stack when it must be enlarged. By default
398 10 elements are added to the stack. This option/directive is
399 interpreted only once, and only if tt(size) at least equals the
400 default stack expansion size of 10.
401
402 it() loption(tag-mismatches) tt(off|on)nl()
403 When tt(on) is specified (which is the default), a warning is
404 issued if no $$ assignment was detected in an action block, or if
405 adding a default $$ = ... action was suppressed (cf. the
406 tt(default-actions off) option or directive).
407
408 it() laoption(target-directory)(pathname) nl()
409 tt(Pathname) defines the directory where generated files should be
410 written. By default this is the directory where bic() is
411 called.
412
413 it() loption(thread-safe)nl()
414 Only used with polymorphic semantic values, and then only required
415 when the parser is used in multiple threads: it ensures that each
416 thread's polymorphic code only accesses its own parser's error
417 counting variable.
418
419 it() lsoption(token-class)(K)(classname)nl()
420 tt(Classname) defines the name of the tt(Tokens) class that is
421 defined when tt(token-path) (see below) is specified. If
422 tt(token-path) isn't specified then this option is ignored. By
423 default the class name tt(Tokens) is used.
424
425 it() lsoption(token-namespace)(N)(namespace)nl()
426 If tt(token-path) is specified (see below) then tt(namespace)
427 defines the namespace of the tt(Tokens) class. By default no
428 namespace is used.
429
430 it() lsoption(token-path)(F)(pathname)nl()
431 tt(Pathname) defines the path name of the file to contain the
432 tt(struct Tokens) defining the enumeration tt(Tokens_) containing
433 the symbolic tokens of the generated grammar. If this option is
434 specified the tt(ParserBase) class is derived from it, thus making
435 the tokens available to the generated parser class. The name of
436 the tt(struct Tokens) can be altered using the tt(token-class)
437 directive or option.
438 By default (i.e., if tt(token_path) is not specified) the tokens
439 are defined as the tt(enum Tokens_) in the tt(ParserBase) class.
440 If tt(pathname) doesn't exist it is created by bic(). If the
441 tt(pathname) file already exists it is rewritten at each new run
442 of bic().
443
444 it() loption(usage)nl()
445 Writes basic usage information to the standard output stream and
446 terminates.
447
448 it() loption(verbose) (soption(V))nl()
449 Writes a file containing verbose descriptions of the parser states
450 and what is done for each type of look-ahead token in that state.
451 This file also describes all conflicts detected in the grammar,
452 both those resolved by operator precedence and those that remain
453 unresolved. It is not created by default, but if requested the
454 information is written on tt(<grammar>.output), where
455 tt(<grammar>) is the grammar specification file passed to bic().
456
457 it() loption(version) (soption(v))nl()
458 Displays bic()'s version number and terminates.
459
460 )