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