doc/bison.1

   1 .TH BISON 1 local
   2 .SH NAME
   3 bison \- GNU Project parser generator (yacc replacement)
   4 .SH SYNOPSIS
   5 .B bison
   6 [
   7 .BI \-b  " file-prefix"
   8 ] [
   9 .BI \-\-file-prefix= file-prefix
  10 ] [
  11 .B \-d
  12 ] [
  13 .BI \-\-defines= defines-file
  14 ] [
  15 .B \-g
  16 ] [
  17 .BI \-\-graph= graph-file
  18 ] [
  19 .B \-k
  20 ] [
  21 .B \-\-token-table
  22 ] [
  23 .B \-l
  24 ] [
  25 .B \-\-no-lines
  26 ] [
  27 .B \-n
  28 ] [
  29 .B \-\-no-parser
  30 ] [
  31 .BI \-o " outfile"
  32 ] [
  33 .BI \-\-output-file= outfile
  34 ] [
  35 .BI \-p " prefix"
  36 ] [
  37 .BI \-\-name-prefix= prefix
  38 ] [
  39 .B \-t
  40 ] [
  41 .B \-\-debug
  42 ] [
  43 .B \-v
  44 ] [
  45 .B \-\-verbose
  46 ] [
  47 .B \-V
  48 ] [
  49 .B \-\-version
  50 ] [
  51 .B \-y
  52 ] [
  53 .B \-\-yacc
  54 ] [
  55 .B \-h
  56 ] [
  57 .B \-\-help
  58 ] [
  59 .B \-\-fixed-output-files
  60 ]
  61 file
  62 .SH DESCRIPTION
  63 .I Bison
  64 is a parser generator in the style of
  65 .IR yacc (1).
  66 It should be upwardly compatible with input files designed
  67 for
  68 .IR yacc .
  69 .PP
  70 Input files should follow the
  71 .I yacc
  72 convention of ending in
  73 .BR .y .
  74 Unlike
  75 .IR yacc ,
  76 the generated files do not have fixed names, but instead use the prefix
  77 of the input file.
  78 Moreover, if you need to put
  79 .IR C++
  80 code in the input file, you can end his name by a C++-like extension
  81 (.ypp or .y++), then bison will follow your extension to name the
  82 output file (.cpp or .c++).
  83 For instance, a grammar description file named
  84 .B parse.yxx
  85 would produce the generated parser in a file named
  86 .BR parse.tab.cxx ,
  87 instead of
  88 .IR yacc 's
  89 .BR y.tab.c
  90 or old
  91 .IR Bison
  92 versions
  93 .BR parse.tab.c .
  94 .PP
  95 This description of the options that can be given to
  96 .I bison
  97 is adapted from the node
  98 .B Invocation
  99 in the
 100 .B bison.texinfo
 101 manual, which should be taken as authoritative.
 102 .PP
 103 .I Bison
 104 supports both traditional single-letter options and mnemonic long
 105 option names.  Long option names are indicated with
 106 .B \-\-
 107 instead of
 108 .BR \- .
 109 Abbreviations for option names are allowed as long as they
 110 are unique.  When a long option takes an argument, like
 111 .BR \-\-file-prefix ,
 112 connect the option name and the argument with
 113 .BR = .
 114 .SS OPTIONS
 115 .TP
 116 .BI \-b " file-prefix"
 117 .br
 118 .ns
 119 .TP
 120 .BI \-\-file-prefix= file-prefix
 121 Specify a prefix to use for all
 122 .I bison
 123 output file names.  The names are
 124 chosen as if the input file were named
 125 \fIfile-prefix\fB.c\fR.
 126 .TP
 127 .B \-d
 128 .br
 129 .ns
 130 Write an extra output file containing macro definitions for the token
 131 type names defined in the grammar and the semantic value type
 132 .BR YYSTYPE ,
 133 as well as a few
 134 .B extern
 135 variable declarations.
 136 .sp
 137 If the parser output file is named
 138 \fIname\fB.c\fR
 139 then this file
 140 is named
 141 \fIname\fB.h\fR.
 142 .sp
 143 This output file is essential if you wish to put the definition of
 144 .B yylex
 145 in a separate source file, because
 146 .B yylex
 147 needs to be able to refer to token type codes and the variable
 148 .BR yylval .
 149 .TP
 150 .BI \-\-defines= defines-file
 151 The behaviour of
 152 .BI \-\-defines
 153 is the same than
 154 .BI \-d
 155 option.
 156 The only difference is that it has an optionnal argument which is
 157 the name of the output filename.
 158 .TP
 159 .BI \-g
 160 .br
 161 .ns
 162 Output a VCG definition of the LALR(1) grammar automaton computed by
 163 Bison. If the grammar file is
 164 .BR foo.y
 165 , the VCG output file will be
 166 .BR foo.vcg .
 167 .TP
 168 .BI \-\-graph= graph-file
 169 The behaviour of
 170 .BI \-\-graph
 171 is the same than
 172 .BI \-g
 173 option. The only difference is that it has an optionnal argument which
 174 is the name of the output graph filename.
 175 .TP
 176 .B \-k
 177 .br
 178 .ns
 179 .TP
 180 .B \-\-token-table
 181 This switch causes the \fIname\fB.tab.c\fR output to include a list of
 182 token names in order by their token numbers;  this is defined in the array
 183 .IR yytname .
 184 Also generated
 185 are #defines for
 186 .IR YYNTOKENS ,
 187 .IR YYNNTS ,
 188 .IR YYNRULES ,
 189 and
 190 .IR YYNSTATES .
 191 .TP
 192 .B \-l
 193 .br
 194 .ns
 195 .TP
 196 .B \-\-no-lines
 197 Don't put any
 198 .B #line
 199 preprocessor commands in the parser file.
 200 Ordinarily
 201 .I bison
 202 puts them in the parser file so that the C compiler
 203 and debuggers will associate errors with your source file, the
 204 grammar file.  This option causes them to associate errors with the
 205 parser file, treating it an independent source file in its own right.
 206 .TP
 207 .B \-n
 208 .br
 209 .ns
 210 .TP
 211 .B \-\-no-parser
 212 Do not generate the parser code into the output;  generate only
 213 declarations.  The generated \fIname\fB.tab.c\fR file will have only
 214 constant declarations.  In addition, a \fIname\fB.act\fR file is
 215 generated containing a switch statement body containing all the
 216 translated actions.
 217 .TP
 218 .BI \-o " outfile"
 219 .br
 220 .ns
 221 .TP
 222 .BI \-\-output-file= outfile
 223 Specify the name
 224 .I outfile
 225 for the parser file.
 226 .sp
 227 The other output files' names are constructed from
 228 .I outfile
 229 as described under the
 230 .B \-v
 231 and
 232 .B \-d
 233 switches.
 234 .TP
 235 .BI \-p " prefix"
 236 .br
 237 .ns
 238 .TP
 239 .BI \-\-name-prefix= prefix
 240 Rename the external symbols used in the parser so that they start with
 241 .I prefix
 242 instead of
 243 .BR yy .
 244 The precise list of symbols renamed is
 245 .BR yyparse ,
 246 .BR yylex ,
 247 .BR yyerror ,
 248 .BR yylval ,
 249 .BR yychar ,
 250 and
 251 .BR yydebug .
 252 .sp
 253 For example, if you use
 254 .BR "\-p c" ,
 255 the names become
 256 .BR cparse ,
 257 .BR clex ,
 258 and so on.
 259 .TP
 260 .B \-t
 261 .br
 262 .ns
 263 .TP
 264 .B \-\-debug
 265 In the parser file, define the macro
 266 .B YYDEBUG
 267 to 1 if it is not already defined,
 268 so that the debugging facilities are compiled.
 269 .TP
 270 .B \-v
 271 .br
 272 .ns
 273 .TP
 274 .B \-\-verbose
 275 Write an extra output file containing verbose descriptions of the
 276 parser states and what is done for each type of look-ahead token in
 277 that state.
 278 .sp
 279 This file also describes all the conflicts, both those resolved by
 280 operator precedence and the unresolved ones.
 281 .sp
 282 The file's name is made by removing
 283 .B .tab.c
 284 or
 285 .B .c
 286 from the parser output file name, and adding
 287 .B .output
 288 instead.
 289 .sp
 290 Therefore, if the input file is
 291 .BR foo.y ,
 292 then the parser file is called
 293 .B foo.tab.c
 294 by default.  As a consequence, the verbose
 295 output file is called
 296 .BR foo.output .
 297 .TP
 298 .B \-V
 299 .br
 300 .ns
 301 .TP
 302 .B \-\-version
 303 Print the version number of
 304 .I bison
 305 and exit.
 306 .TP
 307 .B \-h
 308 .br
 309 .ns
 310 .TP
 311 .B \-\-help
 312 Print a summary of the options to
 313 .I bison
 314 and exit.
 315 .TP
 316 .B \-y
 317 .br
 318 .ns
 319 .TP
 320 .B \-\-yacc
 321 .br
 322 .ns
 323 .TP
 324 .B \-\-fixed-output-files
 325 Equivalent to
 326 .BR "\-o y.tab.c" ;
 327 the parser output file is called
 328 .BR y.tab.c ,
 329 and the other outputs are called
 330 .B y.output
 331 and
 332 .BR y.tab.h .
 333 The purpose of this switch is to imitate
 334 .IR yacc 's
 335 output file name conventions.
 336 Thus, the following shell script can substitute for
 337 .IR yacc :
 338 .sp
 339 .RS
 340 .ft B
 341 bison \-y $*
 342 .ft R
 343 .sp
 344 .RE
 345 .SH FILES
 346 /usr/local/share/bison/bison.simple     simple parser
 347 .br
 348 /usr/local/share/bison/bison.hairy      complicated parser
 349 .SH "ENVIRONMENT VARIABLES"
 350 .TP
 351 .SM BISON_SIMPLE
 352 If this is set, it specifies the location in which the
 353 .B bison.simple
 354 parser can be found.
 355 .TP
 356 .SM BISON_HAIRY
 357 If this is set, it specifies the location in which the
 358 .B bison.hairy
 359 parser can be found.
 360 .SH SEE ALSO
 361 .IR yacc (1)
 362 .br
 363 The
 364 .IR "Bison Reference Manual" ,
 365 included as the file
 366 .B bison.texinfo
 367 in the
 368 .I bison
 369 source distribution.
 370 .SH DIAGNOSTICS
 371 Self explanatory.