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 .I 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 .B y.tab.c
  90 or old
  91 .I Bison
  92 version's
  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\fP\fB.c\fP.
 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 .IB name .c
 139 then this file
 140 is named
 141 \fIname\fP\fB.h\fP.
 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 behavior of
 152 .B \-\-defines
 153 is the same than
 154 .B \-d
 155 option.
 156 The only difference is that it has an optional 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 behavior of
 170 .BI \-\-graph
 171 is the same than
 172 .BI \-g
 173 option.  The only difference is that it has an optional 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
 182 .IB name .tab.c
 183 output to include a list of
 184 token names in order by their token numbers; this is defined in the array
 185 .IR yytname .
 186 Also generated
 187 are #defines for
 188 .IR YYNTOKENS ,
 189 .IR YYNNTS ,
 190 .IR YYNRULES ,
 191 and
 192 .IR YYNSTATES .
 193 .TP
 194 .B \-l
 195 .br
 196 .ns
 197 .TP
 198 .B \-\-no-lines
 199 Don't put any
 200 .B #line
 201 preprocessor commands in the parser file.
 202 Ordinarily
 203 .I bison
 204 puts them in the parser file so that the C compiler
 205 and debuggers will associate errors with your source file, the
 206 grammar file.  This option causes them to associate errors with the
 207 parser file, treating it an independent source file in its own right.
 208 .TP
 209 .B \-n
 210 .br
 211 .ns
 212 .TP
 213 .B \-\-no-parser
 214 Do not generate the parser code into the output; generate only
 215 declarations.  The generated
 216 .IB name .tab.c
 217 file will have only
 218 constant declarations.  In addition, a
 219 .IB name .act
 220 file is
 221 generated containing a switch statement body containing all the
 222 translated actions.
 223 .TP
 224 .BI \-o " outfile"
 225 .br
 226 .ns
 227 .TP
 228 .BI \-\-output-file= outfile
 229 Specify the name
 230 .I outfile
 231 for the parser file.
 232 .sp
 233 The other output files' names are constructed from
 234 .I outfile
 235 as described under the
 236 .B \-v
 237 and
 238 .B \-d
 239 switches.
 240 .TP
 241 .BI \-p " prefix"
 242 .br
 243 .ns
 244 .TP
 245 .BI \-\-name-prefix= prefix
 246 Rename the external symbols used in the parser so that they start with
 247 .I prefix
 248 instead of
 249 .BR yy .
 250 The precise list of symbols renamed is
 251 .BR yyparse ,
 252 .BR yylex ,
 253 .BR yyerror ,
 254 .BR yylval ,
 255 .BR yychar ,
 256 and
 257 .BR yydebug .
 258 .sp
 259 For example, if you use
 260 .BR "\-p c" ,
 261 the names become
 262 .BR cparse ,
 263 .BR clex ,
 264 and so on.
 265 .TP
 266 .B \-t
 267 .br
 268 .ns
 269 .TP
 270 .B \-\-debug
 271 In the parser file, define the macro
 272 .B YYDEBUG
 273 to 1 if it is not already defined,
 274 so that the debugging facilities are compiled.
 275 .TP
 276 .B \-v
 277 .br
 278 .ns
 279 .TP
 280 .B \-\-verbose
 281 Write an extra output file containing verbose descriptions of the
 282 parser states and what is done for each type of look-ahead token in
 283 that state.
 284 .sp
 285 This file also describes all the conflicts, both those resolved by
 286 operator precedence and the unresolved ones.
 287 .sp
 288 The file's name is made by removing
 289 .B .tab.c
 290 or
 291 .B .c
 292 from the parser output file name, and adding
 293 .B .output
 294 instead.
 295 .sp
 296 Therefore, if the input file is
 297 .BR foo.y ,
 298 then the parser file is called
 299 .B foo.tab.c
 300 by default.  As a consequence, the verbose
 301 output file is called
 302 .BR foo.output .
 303 .TP
 304 .B \-V
 305 .br
 306 .ns
 307 .TP
 308 .B \-\-version
 309 Print the version number of
 310 .I bison
 311 and exit.
 312 .TP
 313 .B \-h
 314 .br
 315 .ns
 316 .TP
 317 .B \-\-help
 318 Print a summary of the options to
 319 .I bison
 320 and exit.
 321 .TP
 322 .B \-y
 323 .br
 324 .ns
 325 .TP
 326 .B \-\-yacc
 327 .br
 328 .ns
 329 .TP
 330 .B \-\-fixed-output-files
 331 Equivalent to
 332 .BR "\-o y.tab.c" ;
 333 the parser output file is called
 334 .BR y.tab.c ,
 335 and the other outputs are called
 336 .B y.output
 337 and
 338 .BR y.tab.h .
 339 The purpose of this switch is to imitate
 340 .IR yacc 's
 341 output file name conventions.
 342 Thus, the following shell script can substitute for
 343 .IR yacc :
 344 .sp
 345 .RS
 346 .ft B
 347 bison \-y $*
 348 .ft R
 349 .sp
 350 .RE
 351 .SH FILES
 352 /usr/local/share/bison/bison.simple     simple parser
 353 .br
 354 /usr/local/share/bison/bison.hairy      complicated parser
 355 .SH "ENVIRONMENT VARIABLES"
 356 .TP
 357 .SM BISON_SIMPLE
 358 If this is set, it specifies the location in which the
 359 .B bison.simple
 360 parser can be found.
 361 .TP
 362 .SM BISON_HAIRY
 363 If this is set, it specifies the location in which the
 364 .B bison.hairy
 365 parser can be found.
 366 .SH SEE ALSO
 367 .IR yacc (1)
 368 .br
 369 The
 370 .IR "Bison Reference Manual" ,
 371 included as the file
 372 .B bison.texinfo
 373 in the
 374 .I bison
 375 source distribution.
 376 .SH DIAGNOSTICS
 377 Self explanatory.