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