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 \-l
  16 ] [
  17 .B \-\-no-lines
  18 ] [
  19 .BI \-o " outfile"
  20 ] [
  21 .BI \-\-output-file= outfile
  22 ] [
  23 .BI \-p " prefix"
  24 ] [
  25 .BI \-\-name-prefix= prefix
  26 ] [
  27 .B \-t
  28 ] [
  29 .B \-\-debug
  30 ] [
  31 .B \-v
  32 ] [
  33 .B \-\-verbose
  34 ] [
  35 .B \-V
  36 ] [
  37 .B \-\-version
  38 ] [
  39 .B \-y
  40 ] [
  41 .B \-\-yacc
  42 ] [
  43 .B \-h
  44 ] [
  45 .B \-\-help
  46 ] [
  47 .B \-\-fixed-output-files
  48 ]
  49 file
  50 .SH DESCRIPTION
  51 .I Bison
  52 is a parser generator in the style of
  53 .IR yacc (1).
  54 It should be upwardly compatible with input files designed
  55 for
  56 .IR yacc .
  57 .PP
  58 Input files should follow the
  59 .I yacc
  60 convention of ending in
  61 .BR .y .
  62 Unlike
  63 .IR yacc ,
  64 the generated files do not have fixed names, but instead use the prefix
  65 of the input file.
  66 For instance, a grammar description file named
  67 .B parse.y
  68 would produce the generated parser in a file named
  69 .BR parse.tab.c ,
  70 instead of
  71 .IR yacc 's
  72 .BR y.tab.c .
  73 .PP
  74 This description of the options that can be given to
  75 .I bison
  76 is adapted from the node
  77 .B Invocation
  78 in the
  79 .B bison.texinfo
  80 manual, which should be taken as authoritative.
  81 .PP
  82 .I Bison
  83 supports both traditional single-letter options and mnemonic long
  84 option names.  Long option names are indicated with
  85 .B \-\-
  86 instead of
  87 .BR \- .
  88 Abbreviations for option names are allowed as long as they
  89 are unique.  When a long option takes an argument, like
  90 .BR \-\-file-prefix ,
  91 connect the option name and the argument with
  92 .BR = .
  93 .SS OPTIONS
  94 .TP
  95 .BI \-b " file-prefix"
  96 .br
  97 .ns
  98 .TP
  99 .BI \-\-file-prefix= file-prefix
 100 Specify a prefix to use for all
 101 .I bison
 102 output file names.  The names are
 103 chosen as if the input file were named
 104 \fIfile-prefix\fB.c\fR.
 105 .TP
 106 .B \-d
 107 .br
 108 .ns
 109 .TP
 110 .B \-\-defines
 111 Write an extra output file containing macro definitions for the token
 112 type names defined in the grammar and the semantic value type
 113 .BR YYSTYPE ,
 114 as well as a few
 115 .B extern
 116 variable declarations.
 117 .sp
 118 If the parser output file is named
 119 \fIname\fB.c\fR
 120 then this file
 121 is named
 122 \fIname\fB.h\fR.
 123 .sp
 124 This output file is essential if you wish to put the definition of
 125 .B yylex
 126 in a separate source file, because
 127 .B yylex
 128 needs to be able to refer to token type codes and the variable
 129 .BR yylval .
 130 .TP
 131 .B \-l
 132 .br
 133 .ns
 134 .TP
 135 .B \-\-no-lines
 136 Don't put any
 137 .B #line
 138 preprocessor commands in the parser file.
 139 Ordinarily
 140 .I bison
 141 puts them in the parser file so that the C compiler
 142 and debuggers will associate errors with your source file, the
 143 grammar file.  This option causes them to associate errors with the
 144 parser file, treating it an independent source file in its own right.
 145 .TP
 146 .BI \-o " outfile"
 147 .br
 148 .ns
 149 .TP
 150 .BI \-\-output-file= outfile
 151 Specify the name
 152 .I outfile
 153 for the parser file.
 154 .sp
 155 The other output files' names are constructed from
 156 .I outfile
 157 as described under the
 158 .B \-v
 159 and
 160 .B \-d
 161 switches.
 162 .TP
 163 .BI \-p " prefix"
 164 .br
 165 .ns
 166 .TP
 167 .BI \-\-name-prefix= prefix
 168 Rename the external symbols used in the parser so that they start with
 169 .I prefix
 170 instead of
 171 .BR yy .
 172 The precise list of symbols renamed is
 173 .BR yyparse ,
 174 .BR yylex ,
 175 .BR yyerror ,
 176 .BR yylval ,
 177 .BR yychar ,
 178 and
 179 .BR yydebug .
 180 .sp
 181 For example, if you use
 182 .BR "\-p c" ,
 183 the names become
 184 .BR cparse ,
 185 .BR clex ,
 186 and so on.
 187 .TP
 188 .B \-t
 189 .br
 190 .ns
 191 .TP
 192 .B \-\-debug
 193 Output a definition of the macro
 194 .B YYDEBUG
 195 into the parser file,
 196 so that the debugging facilities are compiled.
 197 .TP
 198 .B \-v
 199 .br
 200 .ns
 201 .TP
 202 .B \-\-verbose
 203 Write an extra output file containing verbose descriptions of the
 204 parser states and what is done for each type of look-ahead token in
 205 that state.
 206 .sp
 207 This file also describes all the conflicts, both those resolved by
 208 operator precedence and the unresolved ones.
 209 .sp
 210 The file's name is made by removing
 211 .B .tab.c
 212 or
 213 .B .c
 214 from the parser output file name, and adding
 215 .B .output
 216 instead.
 217 .sp
 218 Therefore, if the input file is
 219 .BR foo.y ,
 220 then the parser file is called
 221 .B foo.tab.c
 222 by default.  As a consequence, the verbose
 223 output file is called
 224 .BR foo.output .
 225 .TP
 226 .B \-V
 227 .br
 228 .ns
 229 .TP
 230 .B \-\-version
 231 Print the version number of
 232 .I bison
 233 and exit.
 234 .TP
 235 .B \-h
 236 .br
 237 .ns
 238 .TP
 239 .B \-\-help
 240 Print a summary of the options to
 241 .I bison
 242 and exit.
 243 .TP
 244 .B \-y
 245 .br
 246 .ns
 247 .TP
 248 .B \-\-yacc
 249 .br
 250 .ns
 251 .TP
 252 .B \-\-fixed-output-files
 253 Equivalent to
 254 .BR "\-o y.tab.c" ;
 255 the parser output file is called
 256 .BR y.tab.c ,
 257 and the other outputs are called
 258 .B y.output
 259 and
 260 .BR y.tab.h .
 261 The purpose of this switch is to imitate
 262 .IR yacc 's
 263 output file name conventions.
 264 Thus, the following shell script can substitute for
 265 .IR yacc :
 266 .sp
 267 .RS
 268 .ft B
 269 bison \-y $*
 270 .ft R
 271 .sp
 272 .RE
 273 .PP
 274 The long-named options can be introduced with `+' as well as `\-\-',
 275 for compatibility with previous releases.  Eventually support for `+'
 276 will be removed, because it is incompatible with the POSIX.2 standard.
 277 .SH FILES
 278 /usr/local/lib/bison.simple     simple parser
 279 .br
 280 /usr/local/lib/bison.hairy      complicated parser
 281 .SH SEE ALSO
 282 .IR yacc (1)
 283 .br
 284 The
 285 .IR "Bison Reference Manual" ,
 286 included as the file
 287 .B bison.texinfo
 288 in the
 289 .I bison
 290 source distribution.
 291 .SH DIAGNOSTICS
 292 Self explanatory.
 293