external/bsd/byacc/dist/yacc.1

   1 .\"     $NetBSD: yacc.1,v 1.4 2011/09/10 21:29:04 christos Exp $
   2 .\"
   3 .\" Id: yacc.1,v 1.12 2011/09/08 00:40:44 tom Exp
   4 .\"
   5 .\" .TH YACC 1 "July\ 15,\ 1990"
   6 .\" .UC 6
   7 .TH YACC 1 "September 7, 2011" "Berkeley Yacc" "User Commands"
   8 .SH NAME
   9 Yacc \- an LALR(1) parser generator
  10 .SH SYNOPSIS
  11 .B yacc [ -dgilrtv ] [ \-b
  12 .I file_prefix
  13 .B ] [ \-p
  14 .I symbol_prefix
  15 .B ]
  16 .I filename
  17 .SH DESCRIPTION
  18 .B Yacc
  19 reads the grammar specification in the file
  20 .I filename
  21 and generates an LALR(1) parser for it.
  22 The parsers consist of a set of LALR(1) parsing tables and a driver routine
  23 written in the C programming language.
  24 .B Yacc
  25 normally writes the parse tables and the driver routine to the file
  26 .IR y.tab.c.
  27 .PP
  28 The following options are available:
  29 .TP
  30 \fB\-b \fP\fIfile_prefix\fR
  31 The
  32 .B \-b
  33 option changes the prefix prepended to the output file names to
  34 the string denoted by
  35 .IR file_prefix.
  36 The default prefix is the character
  37 .IR y.
  38 .TP
  39 .B \-d
  40 The \fB-d\fR option causes the header file
  41 .BR y.tab.h
  42 to be written.
  43 It contains #define's for the token identifiers.
  44 .TP
  45 .B \-g
  46 The
  47 .B \-g
  48 option causes a graphical description of the generated LALR(1) parser to
  49 be written to the file
  50 .BR y.dot
  51 in graphviz format, ready to be processed by dot(1).
  52 .TP
  53 .B \-i
  54 The \fB-i\fR option causes a supplementary header file
  55 .BR y.tab.i
  56 to be written.
  57 It contains extern declarations
  58 and supplementary #define's as needed to map the conventional \fIyacc\fP
  59 \fByy\fP-prefixed names to whatever the \fB-p\fP option may specify.
  60 The code file, e.g., \fBy.tab.c\fP is modified to #include this file
  61 as well as the \fBy.tab.h\fP file, enforcing consistent usage of the
  62 symbols defined in those files.
  63 .IP
  64 The supplementary header file makes it simpler to separate compilation
  65 of lex- and yacc-files.
  66 .TP
  67 .B \-l
  68 If the
  69 .B \-l
  70 option is not specified,
  71 .B yacc
  72 will insert \fI#line\fP directives in the generated code.
  73 The \fI#line\fP directives let the C compiler relate errors in the
  74 generated code to the user's original code.
  75 If the \fB-l\fR option is specified,
  76 .B yacc
  77 will not insert the \fI#line\fP directives.
  78 \&\fI#line\fP directives specified by the user will be retained.
  79 .TP
  80 \fB\-o \fP\fIoutput_file\fR
  81 specify the filename for the parser file.
  82 If this option is not given, the output filename is
  83 the file prefix concatenated with the file suffix, e.g., \fBy.tab.c\fP.
  84 This overrides the \fB-p\fP option.
  85 .TP
  86 \fB\-p \fP\fIsymbol_prefix\fR
  87 The
  88 .B \-p
  89 option changes the prefix prepended to yacc-generated symbols to
  90 the string denoted by
  91 .IR symbol_prefix.
  92 The default prefix is the string
  93 .BR yy.
  94 .TP
  95 .B \-P
  96 create a reentrant parser, e.g., "%pure-parser".
  97 .TP
  98 .B \-r
  99 The
 100 .B \-r
 101 option causes
 102 .B yacc
 103 to produce separate files for code and tables.  The code file
 104 is named
 105 .IR y.code.c,
 106 and the tables file is named
 107 .IR y.tab.c.
 108 The prefix "\fIy.\fP" can be overridden using the \fB\-b\fP option.
 109 .TP
 110 .B \-t
 111 The
 112 .B \-t
 113 option changes the preprocessor directives generated by
 114 .B yacc
 115 so that debugging statements will be incorporated in the compiled code.
 116 .TP
 117 .B \-v
 118 The
 119 .B \-v
 120 option causes a human-readable description of the generated parser to
 121 be written to the file
 122 .IR y.output.
 123 .TP
 124 .B \-V
 125 print the version number to the standard output.
 126 .SH EXTENSIONS
 127 .B yacc
 128 provides some extensions for compatibility with bison and other implementations
 129 of yacc:
 130 .TP
 131 \fB %expect\fP \fInumber\fP
 132 tell \fByacc\fP the expected number of shift/reduce conflicts.
 133 That makes it only report the number if it differs.
 134 .TP
 135 \fB %expect-rr\fP \fInumber\fP
 136 tell \fByacc\fP the expected number of reduce/reduce conflicts.
 137 That makes it only report the number if it differs.
 138 This is (unlike bison) allowable in LALR parsers.
 139 .TP
 140 \fB %lex-param\fP { \fIargument-declaration\fP }
 141 By default, the lexer accepts no parameters, e.g., \fByylex()\fP.
 142 Use this directive to add parameter declarations for your customized lexer.
 143 .TP
 144 \fB %parse-param\fP { \fIargument-declaration\fP }
 145 By default, the parser accepts no parameters, e.g., \fByyparse()\fP.
 146 Use this directive to add parameter declarations for your customized parser.
 147 .TP
 148 \fB %pure-parser\fP
 149 Most variables (other than \fByydebug\fP and \fByynerrs\fP) are
 150 allocated on the stack within \fByyparse\fP, making the parser reasonably
 151 reentrant.
 152 .
 153 .SH DIAGNOSTICS
 154 If there are rules that are never reduced, the number of such rules is
 155 reported on standard error.
 156 If there are any LALR(1) conflicts, the number of conflicts is reported
 157 on standard error.