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