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 \-k
  16 ] [
  17 .B \-\-token-table
  18 ] [
  19 .B \-l
  20 ] [
  21 .B \-\-no-lines
  22 ] [
  23 .B \-n
  24 ] [
  25 .B \-\-no-parser
  26 ] [
  27 .BI \-o " outfile"
  28 ] [
  29 .BI \-\-output-file= outfile
  30 ] [
  31 .BI \-p " prefix"
  32 ] [
  33 .BI \-\-name-prefix= prefix
  34 ] [
  35 .B \-r
  36 ] [
  37 .B \-\-raw
  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 For instance, a grammar description file named
  79 .B parse.y
  80 would produce the generated parser in a file named
  81 .BR parse.tab.c ,
  82 instead of
  83 .IR yacc 's
  84 .BR y.tab.c .
  85 .PP
  86 This description of the options that can be given to
  87 .I bison
  88 is adapted from the node
  89 .B Invocation
  90 in the
  91 .B bison.texinfo
  92 manual, which should be taken as authoritative.
  93 .PP
  94 .I Bison
  95 supports both traditional single-letter options and mnemonic long
  96 option names.  Long option names are indicated with
  97 .B \-\-
  98 instead of
  99 .BR \- .
 100 Abbreviations for option names are allowed as long as they
 101 are unique.  When a long option takes an argument, like
 102 .BR \-\-file-prefix ,
 103 connect the option name and the argument with
 104 .BR = .
 105 .SS OPTIONS
 106 .TP
 107 .BI \-b " file-prefix"
 108 .br
 109 .ns
 110 .TP
 111 .BI \-\-file-prefix= file-prefix
 112 Specify a prefix to use for all
 113 .I bison
 114 output file names.  The names are
 115 chosen as if the input file were named
 116 \fIfile-prefix\fB.c\fR.
 117 .TP
 118 .B \-d
 119 .br
 120 .ns
 121 .TP
 122 .B \-\-defines
 123 Write an extra output file containing macro definitions for the token
 124 type names defined in the grammar and the semantic value type
 125 .BR YYSTYPE ,
 126 as well as a few
 127 .B extern
 128 variable declarations.
 129 .sp
 130 If the parser output file is named
 131 \fIname\fB.c\fR
 132 then this file
 133 is named
 134 \fIname\fB.h\fR.
 135 .sp
 136 This output file is essential if you wish to put the definition of
 137 .B yylex
 138 in a separate source file, because
 139 .B yylex
 140 needs to be able to refer to token type codes and the variable
 141 .BR yylval .
 142 .TP
 143 .B \-r
 144 .br
 145 .ns
 146 .TP
 147 .B \-\-raw
 148 The token numbers in the \fIname\fB.h\fR file are usually the Yacc compatible
 149 translations.  If this switch is specified, Bison token numbers
 150 are output instead.  (Yacc numbers start at 257 except for single character
 151 tokens;  Bison assigns token numbers sequentially for all tokens
 152 starting at 3.)
 153 .TP
 154 .B \-k
 155 .br
 156 .ns
 157 .TP
 158 .B \-\-token-table
 159 This switch causes the \fIname\fB.tab.c\fR output to include a list of
 160 token names in order by their token numbers;  this is defined in the array
 161 .IR yytname .
 162 Also generated
 163 are #defines for
 164 .IR YYNTOKENS ,
 165 .IR YYNNTS ,
 166 .IR YYNRULES ,
 167 and
 168 .IR YYNSTATES .
 169 .TP
 170 .B \-l
 171 .br
 172 .ns
 173 .TP
 174 .B \-\-no-lines
 175 Don't put any
 176 .B #line
 177 preprocessor commands in the parser file.
 178 Ordinarily
 179 .I bison
 180 puts them in the parser file so that the C compiler
 181 and debuggers will associate errors with your source file, the
 182 grammar file.  This option causes them to associate errors with the
 183 parser file, treating it an independent source file in its own right.
 184 .TP
 185 .B \-n
 186 .br
 187 .ns
 188 .TP
 189 .B \-\-no-parser
 190 Do not generate the parser code into the output;  generate only
 191 declarations.  The generated \fIname\fB.tab.c\fR file will have only
 192 constant declarations.  In addition, a \fIname\fB.act\fR file is
 193 generated containing a switch statement body containing all the
 194 translated actions.
 195 .TP
 196 .BI \-o " outfile"
 197 .br
 198 .ns
 199 .TP
 200 .BI \-\-output-file= outfile
 201 Specify the name
 202 .I outfile
 203 for the parser file.
 204 .sp
 205 The other output files' names are constructed from
 206 .I outfile
 207 as described under the
 208 .B \-v
 209 and
 210 .B \-d
 211 switches.
 212 .TP
 213 .BI \-p " prefix"
 214 .br
 215 .ns
 216 .TP
 217 .BI \-\-name-prefix= prefix
 218 Rename the external symbols used in the parser so that they start with
 219 .I prefix
 220 instead of
 221 .BR yy .
 222 The precise list of symbols renamed is
 223 .BR yyparse ,
 224 .BR yylex ,
 225 .BR yyerror ,
 226 .BR yylval ,
 227 .BR yychar ,
 228 and
 229 .BR yydebug .
 230 .sp
 231 For example, if you use
 232 .BR "\-p c" ,
 233 the names become
 234 .BR cparse ,
 235 .BR clex ,
 236 and so on.
 237 .TP
 238 .B \-t
 239 .br
 240 .ns
 241 .TP
 242 .B \-\-debug
 243 Output a definition of the macro
 244 .B YYDEBUG
 245 into the parser file,
 246 so that the debugging facilities are compiled.
 247 .TP
 248 .B \-v
 249 .br
 250 .ns
 251 .TP
 252 .B \-\-verbose
 253 Write an extra output file containing verbose descriptions of the
 254 parser states and what is done for each type of look-ahead token in
 255 that state.
 256 .sp
 257 This file also describes all the conflicts, both those resolved by
 258 operator precedence and the unresolved ones.
 259 .sp
 260 The file's name is made by removing
 261 .B .tab.c
 262 or
 263 .B .c
 264 from the parser output file name, and adding
 265 .B .output
 266 instead.
 267 .sp
 268 Therefore, if the input file is
 269 .BR foo.y ,
 270 then the parser file is called
 271 .B foo.tab.c
 272 by default.  As a consequence, the verbose
 273 output file is called
 274 .BR foo.output .
 275 .TP
 276 .B \-V
 277 .br
 278 .ns
 279 .TP
 280 .B \-\-version
 281 Print the version number of
 282 .I bison
 283 and exit.
 284 .TP
 285 .B \-h
 286 .br
 287 .ns
 288 .TP
 289 .B \-\-help
 290 Print a summary of the options to
 291 .I bison
 292 and exit.
 293 .TP
 294 .B \-y
 295 .br
 296 .ns
 297 .TP
 298 .B \-\-yacc
 299 .br
 300 .ns
 301 .TP
 302 .B \-\-fixed-output-files
 303 Equivalent to
 304 .BR "\-o y.tab.c" ;
 305 the parser output file is called
 306 .BR y.tab.c ,
 307 and the other outputs are called
 308 .B y.output
 309 and
 310 .BR y.tab.h .
 311 The purpose of this switch is to imitate
 312 .IR yacc 's
 313 output file name conventions.
 314 Thus, the following shell script can substitute for
 315 .IR yacc :
 316 .sp
 317 .RS
 318 .ft B
 319 bison \-y $*
 320 .ft R
 321 .sp
 322 .RE
 323 .PP
 324 The long-named options can be introduced with `+' as well as `\-\-',
 325 for compatibility with previous releases.  Eventually support for `+'
 326 will be removed, because it is incompatible with the POSIX.2 standard.
 327 .SH FILES
 328 /usr/local/lib/bison.simple     simple parser
 329 .br
 330 /usr/local/lib/bison.hairy      complicated parser
 331 .SH SEE ALSO
 332 .IR yacc (1)
 333 .br
 334 The
 335 .IR "Bison Reference Manual" ,
 336 included as the file
 337 .B bison.texinfo
 338 in the
 339 .I bison
 340 source distribution.
 341 .SH DIAGNOSTICS
 342 Self explanatory.