doc/refcard.tex

   1 % Bison Quick Reference
   2
   3 %**start of header
   4 \newcount\columnsperpage
   5
   6 % This file can be printed with 1 or 2 columns per page (see below).
   7 % Specify how many you want here.  Nothing else needs to be changed
   8 % unless you are maintaining the documentation.
   9 % For printing reference cards to use in books, specify one column
  10 % per page and reduce to 80%.
  11 % Note that if columnsperpage is set to 2, there will be a few overfull
  12 % boxes, but they are not serious. Just uncomment \finalout.
  13
  14 \columnsperpage=1
  15
  16 % comment out this line if you want page numbers to appear.
  17 \nopagenumbers
  18
  19 \def\finalout{\overfullrule=0pt}
  20 %\finalout
  21
  22 % Copyright (c) 1998, 2001, 2009--2015, 2018--2021 Free Software
  23 % Foundation, Inc.
  24 %
  25 % This file is part of Bison.
  26 %
  27 % This program is free software: you can redistribute it and/or modify
  28 % it under the terms of the GNU General Public License as published by
  29 % the Free Software Foundation, either version 3 of the License, or
  30 % (at your option) any later version.
  31 %
  32 % This program is distributed in the hope that it will be useful,
  33 % but WITHOUT ANY WARRANTY; without even the implied warranty of
  34 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  35 % GNU General Public License for more details.
  36 %
  37 % You should have received a copy of the GNU General Public License
  38 % along with this program.  If not, see <https://www.gnu.org/licenses/>.
  39 %
  40 % This file is intended to be processed by plain TeX (TeX82).
  41 %
  42 % The final reference card has two columns:
  43 % This file can be used to produce it in any of three ways:
  44 % 1 column per page
  45 %    produces two separate pages, each of which needs to be reduced to 80%.
  46 %    This gives the best resolution.
  47 % 2 columns per page
  48 %    produces a single page.
  49 %    You will still need to cut and paste.
  50 % Which mode to use is controlled by setting \columnsperpage above.
  51 %
  52 % Authors:
  53 %  Brendan Kehoe
  54 %  UUCP: widener!brendan
  55 %  Internet: brendan@cs.widener.edu
  56 %
  57 %  Gavin Nicol
  58 %  Internet: nick@nsis.cl.co.jp
  59 %
  60 % This refcard format was created by Steve Gildea.
  61 %
  62 % Thanks to Paul Rubin, Bob Chassell, Len Tower, and Richard Mlynarik
  63 % for their many good ideas.
  64
  65 % We only change the following to change the version numbers and
  66 % such.
  67
  68 \def\bisonversion{1.31}                    % the bison version
  69
  70 \def\refcardversion{0.5}                   % reference card version
  71 \def\month{November}                       % month
  72 \def\year{2001}                            % year
  73 \def\version{\month\ \year, Bison Refcard Version \refcardversion}
  74
  75 % for copyright notices
  76 \def\small{\smallfont\textfont2=\smallsy\baselineskip=.8\baselineskip}
  77 \def\medium{\mediumfont\textfont2=\mediumsy\baselineskip=.8\baselineskip}
  78
  79 \def\copyrightnotice{
  80 \vskip .15ex plus .25 fill
  81 \begingroup\medium
  82 \centerline{Copyright \copyright\ \year\ Free Software Foundation, Inc.}
  83 \vskip .2\baselineskip
  84 \centerline{\version}
  85 \vskip .2\baselineskip
  86 \centerline{designed by Brendan Kehoe and Gavin Nicol}
  87 \vskip .2\baselineskip
  88 \centerline{for Bison \bisonversion}
  89
  90 Permission is granted to make and distribute copies of this card
  91 provided the copyright notice and this permission notice
  92 are preserved on all copies.
  93 \vskip .2\baselineskip
  94 For information, write to the:
  95 \vskip .2\baselineskip
  96 \centerline{Free Software Foundation, Inc.}
  97 \vskip .2\baselineskip
  98 \centerline{51 Franklin Street, Fifth Floor}
  99 \vskip .2\baselineskip
 100 \centerline{Boston, MA 02110-1301 USA}
 101 \endgroup}
 102
 103 %%%% smallcopyrightnotice for two column printing on one page.
 104 \def\smallcopyrightnotice{
 105 \vskip .15ex plus .25 fill
 106 \begingroup\small
 107 \centerline{Copyright \copyright\ \year\ Free Software Foundation, Inc.}
 108 \vskip .2\baselineskip
 109 \centerline{\version}
 110 \vskip .2\baselineskip
 111 \centerline{designed by Brendan Kehoe and Gavin Nicol}
 112 \vskip .2\baselineskip
 113 \centerline{for Bison \bisonversion}
 114
 115 Permission is granted to make and distribute copies of this card
 116 provided the copyright notice and this permission notice
 117 are preserved on all copies.
 118 \vskip .2\baselineskip
 119 For information, write to the:
 120 \vskip .2\baselineskip
 121 \centerline{Free Software Foundation, Inc.}
 122 \vskip .2\baselineskip
 123 \centerline{51 Franklin Street, Fifth Floor}
 124 \vskip .2\baselineskip
 125 \centerline{Boston, MA 02110-1301 USA}
 126 \endgroup}
 127
 128 % make \bye not \outer so that the \def\bye in the \else clause below
 129 % can be scanned without complaint.
 130 \def\bye{\par\vfill\supereject\end}
 131
 132 \newdimen\intercolumnskip
 133 \newbox\columna
 134 \newbox\columnb
 135
 136 \def\ncolumns{\the\columnsperpage}
 137
 138 \message{[\ncolumns\space
 139   column\if 1\ncolumns\else s\fi\space per page]}
 140
 141 \def\scaledmag#1{ scaled \magstep #1}
 142
 143 % This multi-way format was designed by Stephen Gildea
 144 % October 1986.
 145 \if 1\ncolumns
 146   \hsize 4in
 147   \vsize 10in
 148 % We want output .3 inch *from top of paper edge*; i.e. -.7in from TeX default
 149   \voffset -.7in % Comment out for xdvi viewing; include for printing.
 150   \font\titlefont=\fontname\tenbf \scaledmag3
 151   \font\headingfont=\fontname\tenbf \scaledmag2
 152   \font\smallfont=cmr6
 153   \font\smallsy=cmsy6
 154   \font\mediumfont=cmr10
 155   \font\mediumsy=cmsy10
 156
 157
 158 % two lines below commented out in Yet Another Attempt to eliminate
 159 % page numbers from the output.
 160   \footline{\hss}
 161 % \footline{\hss\folio}
 162   \def\makefootline{\baselineskip10pt\hsize6.5in\line{\the\footline}}
 163 \else
 164   \hsize 3.2in
 165   \vsize 7.95in
 166   \hoffset -.75in
 167   \voffset -.745in
 168   \font\titlefont=cmbx10 \scaledmag2
 169   \font\headingfont=cmbx10 \scaledmag1
 170   \font\smallfont=cmr6
 171   \font\smallsy=cmsy6
 172   \font\eightrm=cmr8
 173   \font\eightbf=cmbx8
 174   \font\eightit=cmti8
 175   \font\eighttt=cmtt8
 176   \font\eightsy=cmsy8
 177   \textfont0=\eightrm
 178   \textfont2=\eightsy
 179   \def\rm{\eightrm}
 180   \def\bf{\eightbf}
 181   \def\it{\eightit}
 182   \def\tt{\eighttt}
 183 %%%% Reduce skip from .8 to .75 to permit printing on two pages.
 184   \normalbaselineskip=.75\normalbaselineskip
 185   \normallineskip=.75\normallineskip
 186   \normallineskiplimit=.75\normallineskiplimit
 187   \normalbaselines\rm           %make definitions take effect
 188
 189   \if 2\ncolumns
 190     \let\maxcolumn=b
 191     \footline{\hss\rm\folio\hss}
 192     \def\makefootline{\vskip 2in \hsize=6.86in\line{\the\footline}}
 193   \font\mediumfont=cmr10
 194   \font\mediumsy=cmsy10
 195
 196 % Leave 3 column code here in case size increases.
 197   \else \if 3\ncolumns
 198     \let\maxcolumn=c
 199     \nopagenumbers
 200   \font\mediumfont=cmr10
 201   \font\mediumsy=cmsy10
 202
 203   \else
 204     \errhelp{You must set \columnsperpage equal to 1, 2, or 3.}
 205     \errmessage{Illegal number of columns per page}
 206   \fi\fi
 207
 208   \intercolumnskip=.46in
 209   \def\abc{a}
 210   \output={%
 211       % This next line is useful when designing the layout.
 212       %\immediate\write16{Column \folio\abc\space starts with \firstmark}
 213       \if \maxcolumn\abc \multicolumnformat \global\def\abc{a}
 214       \else\if a\abc
 215         \global\setbox\columna\columnbox \global\def\abc{b}
 216         %% in case we never use \columnb (two-column mode)
 217         \global\setbox\columnb\hbox to -\intercolumnskip{}
 218       \else
 219         \global\setbox\columnb\columnbox \global\def\abc{c}\fi\fi}
 220   \def\multicolumnformat{\shipout\vbox{\makeheadline
 221       \hbox{\box\columna\hskip\intercolumnskip
 222         \box\columnb\hskip\intercolumnskip\columnbox}
 223       \makefootline}\advancepageno}
 224   \def\columnbox{\leftline{\pagebody}}
 225
 226   \def\bye{\par\vfill\supereject
 227     \if a\abc \else\null\vfill\eject\fi
 228     \if a\abc \else\null\vfill\eject\fi
 229     \end}
 230 \fi
 231
 232 % we won't be using math mode much, so redefine some of the characters
 233 % we might want to talk about
 234 \catcode`\^=12
 235 \catcode`\_=12
 236
 237 \chardef\\=`\\
 238 \chardef\{=`\{
 239 \chardef\}=`\}
 240
 241 \hyphenation{mini-buf-fer}
 242
 243 \parindent 0pt
 244 % \parskip 1ex plus .5ex minus .5ex
 245 \parskip 0.5ex plus .25ex minus .25ex
 246
 247 \outer\def\newcolumn{\vfill\eject}
 248
 249 \outer\def\title#1{{\titlefont\centerline{#1}}\vskip 1ex plus .5ex}
 250
 251 \outer\def\section#1{\par\filbreak
 252   \vskip 1.5ex plus 1ex minus 1ex {\headingfont #1}\mark{#1}%
 253   \vskip 1ex plus .5ex minus 0.75ex}
 254
 255 \newdimen\keyindent
 256
 257 \def\beginindentedkeys{\keyindent=1em}
 258 \def\endindentedkeys{\keyindent=0em}
 259 \endindentedkeys
 260
 261 \def\paralign{\vskip\parskip\halign}
 262
 263 \def\<#1>{$\langle${\rm #1}$\rangle$}
 264
 265 \def\kbd#1{{\tt#1}\null}        %\null so not an abbrev even if period follows
 266
 267 \def\beginexample{\par\leavevmode\begingroup
 268   \obeylines\obeyspaces\parskip0pt\tt}
 269 {\obeyspaces\global\let =\ }
 270 \def\endexample{\endgroup}
 271 \def\begincexample{%
 272   \par\leavevmode\begingroup%
 273   \obeylines\obeyspaces%
 274   % bpk--added indentation
 275   \advance\leftskip.25truein
 276 %  \parskip0pt%
 277   \tt}
 278 {\obeyspaces\global\let =\ }
 279 \def\endcexample{\endgroup}
 280
 281 %%%%% Prime definition of key; redefined below to prevent overful hboxes
 282
 283 \def\key#1#2{\leavevmode\hbox to \hsize
 284   {\vtop {\hsize=.67\hsize \rightskip=1em #1}
 285   \kbd{#2}\hfil}}
 286
 287 \newbox\metaxbox
 288 \setbox\metaxbox\hbox{\kbd{M-x }}
 289 \newdimen\metaxwidth
 290 \metaxwidth=\wd\metaxbox
 291
 292 \def\metax#1#2{\leavevmode\hbox to \hsize{\hbox to .75\hsize
 293   {\hskip\keyindent\relax#1\hfil}%
 294   \hskip -\metaxwidth minus 1fil
 295   \kbd{#2}\hfil}}
 296
 297 \def\threecol#1#2#3{\hskip\keyindent\relax#1\hfil&\kbd{#2}\quad
 298   &\kbd{#3}\quad\cr}
 299
 300 %**end of header
 301 \f
 302 %     ************
 303 %     **  BISON **
 304 %     ************
 305
 306 \title{Bison Quick Reference}
 307
 308 \section{Starting Bison}
 309 %***********************
 310
 311 To use Bison, type: \kbd{bison {\it filename}}
 312
 313 Options can be used as: \kbd{bison {\it options} {\it filename}}
 314
 315 \section{Command Line Options}
 316 %*****************************
 317
 318 \key{Display usage information.}                         {-h}
 319 \key{Display version information.}                       {-V}
 320 \key{Generate token and {\tt YYSTYPE} definitions.}      {-d}
 321 \key{Prepend a prefix to external symbols.}              {-p {\it prefix}}
 322 \key{Don't put {\tt \#line} directives in the parser.}   {-l}
 323 \key{Specify the output file.}                           {-o {\it filename}}
 324 \key{Debug or {\it trace} mode.}                      {-t}
 325 \key{Verbose description of the parser.}                 {-v}
 326 \key{Emulate {\tt yacc} (generate {\tt y.tab.*} files).} {-y}
 327
 328 \vskip .10truein
 329 {\bf Note:} The token and {\tt YYSTYPE} definitions are generated
 330 to a file called {\tt y.tab.h} if the {\tt -y} option is used,
 331 otherwise it will have the format {\tt {\it name}.tab.h}, where
 332 {\it name} is the leading part of the parser definition filename.
 333
 334 \section{Definitions}
 335 %********************
 336
 337 \key{Declare a terminal symbol.}{\%token <{\it t\/}>
 338       {\it n}}
 339
 340 \key{Declare a terminal symbol, and define its association.}
 341       {{\it association} <{\it t\/}> {\it n}}
 342
 343 \vskip .2\baselineskip
 344 \key{Generate a reentrant (pure) parser.}
 345       {\%pure_parser}
 346
 347 \key{Define the union of all data types used in the parser.}
 348       {\%union\{{\it field list}\} }
 349
 350 \vskip .2\baselineskip
 351 \key{Tell {\tt bison} where to start parsing.}
 352       {\%start {\it m}}
 353
 354 \key{Tell {\tt bison} the data type of symbols.}
 355       {\%type <{\it t\/}> {\it s1}\dots{\it sn}}
 356
 357 \vskip .10truein
 358
 359 In the above, {\it t} is a {\it type} defined in the {\tt \%union}
 360 definition,  {\it n} is a {\it terminal} symbol name, {\it m} is a
 361 {\it nonterminal} symbol name, and {\it association} can be one of
 362 {\tt \%left}, {\tt \%right}, or {\tt \%nonassoc}.
 363
 364 \vskip .10truein
 365
 366 The {\tt <{\it t\/}>} after {\tt \%token, \%left, \%right} and {\tt
 367   \%nonassoc} is optional. Additionally, precedence may be overridden
 368 in the rules with {\tt \%prec} commands.
 369
 370 \section{Parser Definition Files}
 371 %*********************************
 372
 373 The general form for a parser definition is:
 374
 375 \begincexample
 376 \{\%
 377    /* Initial C code.  */
 378 \%\}
 379
 380  {\it Token and type definitions}
 381
 382 \%\%
 383
 384    Rule definition 1
 385           \vdots
 386    Rule definition {\it n}
 387
 388 \%\%
 389
 390   /* Other C code.  */
 391 \endcexample
 392
 393
 394 % Decrease standard baselineskip for the second page
 395  \baselineskip = .9\baselineskip
 396
 397 \section {Rule definitions}
 398 %**************************
 399
 400 Rules take the form:
 401
 402 \vskip -\baselineskip
 403 \beginexample
 404      nonterminal : {\it statement} 1
 405                  | {\it statement} 2
 406                      \vdots
 407                  | {\it statement n}
 408                  ;
 409 \endexample
 410
 411 Where {\it statements} can be either empty, or contain
 412 a mixture of C code (enclosed in {\tt \{...\}}), and the
 413 symbols that make up the nonterminal. For example:
 414
 415 \vskip -\baselineskip
 416 \beginexample
 417      expression : number '$+$' number \{ \$\$ $=$ \$1 $+$ \$3 \}
 418                 | number '$-$' number \{ \$\$ $=$ \$1 $-$ \$3 \}
 419                 | number '$/$' number \{ \$\$ $=$ \$1 $/$ \$3 \}
 420                 | number '$*$' number \{ \$\$ $=$ \$1 $*$ \$3 \}
 421                 ;
 422 \endexample
 423
 424 For altering the precedence of a symbol use:
 425 \vskip -\baselineskip
 426
 427 \beginexample
 428      \%prec name
 429 \endexample
 430
 431 For example:
 432 \vskip -\baselineskip
 433 \beginexample
 434      foo : gnu bar gnu      \%prec bar
 435          ;
 436 \endexample
 437
 438 \section{Grammar Variables and Symbols}
 439 %**************************************
 440
 441 \key{Recognize an error \& continue parsing.}{error}
 442 \key{Access data associated with a symbol.}  {\$\$, \$0\dots\${\it n}}
 443 \key{Access a field of the  data union.}    {\$\$.{\it t},
 444                                      \$0.{\it t}\dots\${\it n}.{\it t}}
 445 \key{Access symbol's location.}             {@\$, @0\dots@{\it n}}
 446 \key{Access data's line location.}          {@{\it x}.{\it line\_spec}}
 447 \key{Access data's column location.}        {@{\it x}.{\it column\_spec}}
 448
 449
 450 \vskip .10truein
 451 %
 452 Where {\it t} is a type defined in the {\tt \%union}, {\it n} is a
 453 number, {\it x} is a number or \$, {\it line\_spec} one of {\tt
 454   first_line} and {\tt last_line}, and {\it column\_spec} is specified
 455 as either {\tt first_column} or {\tt last_column}.
 456
 457 \section {Variables and Types}
 458 %*****************************
 459
 460 \key{Current lookahead token.}                 {yychar}
 461 \key{Debug mode flag.}                         {yydebug}
 462 \key{Data associated with the current token.}  {yylval}
 463 \key{Source position of current token.}        {yylloc}
 464 \key{Number of errors encountered.}            {yynerrs}
 465 \key{Position information type.}               {YYLTYPE}
 466 \key{Data type associated with symbols.}       {YYSTYPE}
 467
 468 \section {Functions}
 469 %*******************
 470
 471 % Redefine to prevent overfull hboxes
 472 \def\key#1#2{\leavevmode\hbox to \hsize
 473   {\vtop {\hsize=.625\hsize \rightskip=1em #1}
 474   \kbd{#2}\hfil}}
 475
 476 \key{User defined error handler.}         {int yyerror(char *)}
 477 \key{User defined lexical analyzer.}      {int yylex()}
 478 \key{The grammar parser.}                 {int yyparse()}
 479
 480 % Return to previous size
 481 \def\key#1#2{\leavevmode\hbox to \hsize
 482   {\vtop {\hsize=.67\hsize \rightskip=1em #1}
 483   \kbd{#2}\hfil}}
 484
 485 \section{Macros}
 486 %***************
 487
 488 \key{Quit parsing immediately. Return 1.}           {YYABORT}
 489 \key{Quit parsing immediately. Return 0.}           {YYACCEPT}
 490 \key{Pretend a syntax error occurred.}              {YYERROR}
 491 \key{Value in {\tt yychar} if no lookahead token.}  {YYEMPTY}
 492 \key{Clear previous lookahead token.}               {yyclearin}
 493 \key{Recover normally from an error.}               {yyerrok}
 494
 495 % **************
 496 % ** The end  **
 497 % **************
 498
 499 \vskip \baselineskip
 500 \if 1\ncolumns
 501 \copyrightnotice
 502 \else
 503 \smallcopyrightnotice
 504 \fi
 505
 506 \bye
 507
 508 \f
 509 % Local variables:
 510 % compile-command: "tex refcard"
 511 % End: