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