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