Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
yacc.html (67068B)
1 <!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved -->
2 <!DOCTYPE HTML>
3 <html lang="en">
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0">
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 -->
8 <!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved -->
9 <title>yacc</title>
10 </head>
11 <body bgcolor="white">
12 <div class="NAVHEADER">
13 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
14 <tr class="nav">
15 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/xgettext.html" accesskey="P"><<<
16 Previous</a></td>
17 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
18 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/zcat.html" accesskey="N">Next >>></a></td>
19 </tr>
20 </table>
21 <hr align="left" width="100%"></div>
22 <script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3">
23 <center><font size="2">The Open Group Base Specifications Issue 8<br>
24 IEEE Std 1003.1-2024<br>
25 Copyright © 2001-2024 The IEEE and The Open Group</font></center>
26 <hr size="2" noshade>
27 <a name="top" id="top"></a> <a name="yacc" id="yacc"></a> <a name="tag_20_154" id="tag_20_154"></a><!-- yacc -->
28 <h4 class="mansect"><a name="tag_20_154_01" id="tag_20_154_01"></a>NAME</h4>
29 <blockquote>yacc — yet another compiler compiler (<b>DEVELOPMENT</b>)</blockquote>
30 <h4 class="mansect"><a name="tag_20_154_02" id="tag_20_154_02"></a>SYNOPSIS</h4>
31 <blockquote class="synopsis">
32 <div class="box"><code><tt><sup>[<a href="javascript:open_code('CD')">CD</a>]</sup> <img src="../images/opt-start.gif" alt=
33 "[Option Start]" border="0"> yacc</tt> <b>[</b><tt>-dltv</tt><b>] [</b><tt>-b</tt> <i>file_prefix</i><b>] [</b><tt>-p</tt>
34 <i>sym_prefix</i><b>]</b> <i>grammar</i> <tt><img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
35 </blockquote>
36 <h4 class="mansect"><a name="tag_20_154_03" id="tag_20_154_03"></a>DESCRIPTION</h4>
37 <blockquote>
38 <p>The <i>yacc</i> utility shall read a description of a context-free grammar in <i>grammar</i> and write C source code, conforming
39 to the ISO C standard, to a code file, and optionally header information into a header file, in the current directory. The
40 generated source code shall not depend on any undefined, unspecified, or implementation-defined behavior, except in cases where it
41 is copied directly from the supplied grammar, or in cases that are documented by the implementation. The C code shall define a
42 function and related routines and macros for an automaton that executes a parsing algorithm meeting the requirements in <a href=
43 "#tag_20_154_13_13">Algorithms</a> .</p>
44 <p>The form and meaning of the grammar are described in the EXTENDED DESCRIPTION section.</p>
45 <p>The C source code and header file shall be produced in a form suitable as input for the C compiler (see <a href=
46 "../utilities/c17.html#"><i>c17</i></a> ).</p>
47 </blockquote>
48 <h4 class="mansect"><a name="tag_20_154_04" id="tag_20_154_04"></a>OPTIONS</h4>
49 <blockquote>
50 <p>The <i>yacc</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
51 Guidelines</i></a> , except for Guideline 9.</p>
52 <p>The following options shall be supported:</p>
53 <dl compact>
54 <dd></dd>
55 <dt><b>-b </b><i>file_prefix</i></dt>
56 <dd>Use <i>file_prefix</i> instead of <b>y</b> as the prefix for all output filenames. The code file <b>y.tab.c</b>, the header
57 file <b>y.tab.h</b> (created when <b>-d</b> is specified), and the description file <b>y.output</b> (created when <b>-v</b> is
58 specified), shall be changed to <i>file_prefix</i><b>.tab.c</b>, <i>file_prefix</i><b>.tab.h</b>, and
59 <i>file_prefix</i><b>.output</b>, respectively.</dd>
60 <dt><b>-d</b></dt>
61 <dd>Write the header file; by default only the code file is written. See the OUTPUT FILES section.</dd>
62 <dt><b>-l</b></dt>
63 <dd>Produce a code file that does not contain any <b>#line</b> constructs. If this option is not present, it is unspecified whether
64 the code file or header file contains <b>#line</b> directives. This should only be used after the grammar and the associated
65 actions are fully debugged.</dd>
66 <dt><b>-p </b><i>sym_prefix</i></dt>
67 <dd><br>
68 Use <i>sym_prefix</i> instead of <b>yy</b> as the prefix for all external names produced by <i>yacc</i>. The names affected shall
69 include the functions <i>yyparse</i>(), <i>yylex</i>(), and <i>yyerror</i>(), and the variables <i>yylval</i>, <i>yychar</i>, and
70 <i>yydebug</i>. (In the remainder of this section, the six symbols cited are referenced using their default names only as a
71 notational convenience.) Local names may also be affected by the <b>-p</b> option; however, the <b>-p</b> option shall not affect
72 <b>#define</b> symbols generated by <i>yacc</i>.</dd>
73 <dt><b>-t</b></dt>
74 <dd>Modify conditional compilation directives to permit compilation of debugging code in the code file. Runtime debugging
75 statements shall always be contained in the code file, but by default conditional compilation directives prevent their
76 compilation.</dd>
77 <dt><b>-v</b></dt>
78 <dd>Write a file containing a description of the parser and a report of conflicts generated by ambiguities in the grammar.</dd>
79 </dl>
80 <br></blockquote>
81 <h4 class="mansect"><a name="tag_20_154_05" id="tag_20_154_05"></a>OPERANDS</h4>
82 <blockquote>
83 <p>The following operand is required:</p>
84 <dl compact>
85 <dd></dd>
86 <dt><i>grammar</i></dt>
87 <dd>A pathname of a file containing instructions, hereafter called <i>grammar</i>, for which a parser is to be created. The format
88 for the grammar is described in the EXTENDED DESCRIPTION section.</dd>
89 </dl>
90 </blockquote>
91 <h4 class="mansect"><a name="tag_20_154_06" id="tag_20_154_06"></a>STDIN</h4>
92 <blockquote>
93 <p>Not used.</p>
94 </blockquote>
95 <h4 class="mansect"><a name="tag_20_154_07" id="tag_20_154_07"></a>INPUT FILES</h4>
96 <blockquote>
97 <p>The file <i>grammar</i> shall be a text file formatted as specified in the EXTENDED DESCRIPTION section.</p>
98 </blockquote>
99 <h4 class="mansect"><a name="tag_20_154_08" id="tag_20_154_08"></a>ENVIRONMENT VARIABLES</h4>
100 <blockquote>
101 <p>The following environment variables shall affect the execution of <i>yacc</i>:</p>
102 <dl compact>
103 <dd></dd>
104 <dt><i>LANG</i></dt>
105 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
106 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
107 variables used to determine the values of locale categories.)</dd>
108 <dt><i>LC_ALL</i></dt>
109 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
110 <dt><i>LC_CTYPE</i></dt>
111 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
112 opposed to multi-byte characters in arguments and input files).</dd>
113 <dt><i>LC_MESSAGES</i></dt>
114 <dd><br>
115 Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd>
116 <dt><i>NLSPATH</i></dt>
117 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
118 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
119 "0"></dd>
120 </dl>
121 <p>The <i>LANG</i> and <i>LC_*</i> variables affect the execution of the <i>yacc</i> utility as stated. The <i>main</i>() function
122 defined in <a href="#tag_20_154_13_11">Yacc Library</a> shall call:</p>
123 <pre>
124 <tt>setlocale(LC_ALL, "")
125 </tt></pre>
126 <p>and thus the program generated by <i>yacc</i> shall also be affected by the contents of these variables at runtime.</p>
127 </blockquote>
128 <h4 class="mansect"><a name="tag_20_154_09" id="tag_20_154_09"></a>ASYNCHRONOUS EVENTS</h4>
129 <blockquote>
130 <p>Default.</p>
131 </blockquote>
132 <h4 class="mansect"><a name="tag_20_154_10" id="tag_20_154_10"></a>STDOUT</h4>
133 <blockquote>
134 <p>Not used.</p>
135 </blockquote>
136 <h4 class="mansect"><a name="tag_20_154_11" id="tag_20_154_11"></a>STDERR</h4>
137 <blockquote>
138 <p>If shift/reduce or reduce/reduce conflicts are detected in <i>grammar</i>, <i>yacc</i> shall write a report of those conflicts
139 to the standard error in an unspecified format.</p>
140 <p>Standard error shall also be used for diagnostic messages.</p>
141 </blockquote>
142 <h4 class="mansect"><a name="tag_20_154_12" id="tag_20_154_12"></a>OUTPUT FILES</h4>
143 <blockquote>
144 <p>The code file, the header file, and the description file shall be text files. All are described in the following sections.</p>
145 <h5><a name="tag_20_154_12_01" id="tag_20_154_12_01"></a>Code File</h5>
146 <p>This file shall contain the C source code for the <i>yyparse</i>() function. It shall contain code for the various semantic
147 actions with macro substitution performed on them as described in the EXTENDED DESCRIPTION section. Preceding this code it shall
148 contain an <tt>extern int yychar</tt> declaration or <tt>int yychar</tt> definition, and <b>#define</b> statements for the
149 following macros:</p>
150 <dl compact>
151 <dd></dd>
152 <dt>YYEMPTY</dt>
153 <dd>Token number indicating there is no lookahead token. This macro shall expand to an integer constant with a value less than
154 zero, protected by parentheses.</dd>
155 <dt>YYEOF</dt>
156 <dd>Token number indicating the end of input. This macro shall expand to the value 0.</dd>
157 </dl>
158 <p>It also shall contain a copy of the <b>#define</b> statements in the header file, prior to any code copied from semantic actions
159 in <i>grammar</i>, and the following function prototypes for the <i>yyerror</i>(), <i>yylex</i>(), and <i>yyparse</i>() functions,
160 after any code copied from within <b>%{</b> and <b>%}</b> in the declarations section in <i>grammar</i> and before any code copied
161 from semantic actions in <i>grammar</i>:</p>
162 <pre>
163 <tt>void yyerror(const char *);
164 int yylex(void);
165 int yyparse(void);
166 </tt></pre>
167 <p>The declarations of <i>yyerror</i>() and <i>yylex</i>() shall be protected by <b>#ifndef</b> or <b>#if</b> preprocessor
168 statements such that each is only visible if a preprocessor macro with the name yyerror or yylex, respectively, is not already
169 defined, where the yy in the macro names is replaced by <i>sym_prefix</i> if the <b>-p</b> <i>sym_prefix</i> option is used.</p>
170 <p>If a <b>%union</b> declaration is used, the declaration for YYSTYPE and an <tt>extern YYSTYPE yylval</tt> declaration or
171 <tt>YYSTYPE yylval</tt> definition shall also be included in this file.</p>
172 <p>The code file shall not contain a declaration of the <i>main</i>() function, unless one is present within <b>%{</b> and
173 <b>%}</b> in the declarations section in <i>grammar</i>.</p>
174 <h5><a name="tag_20_154_12_02" id="tag_20_154_12_02"></a>Header File</h5>
175 <p>The header file shall contain <b>#define</b> statements that associate the token numbers with the token names. This allows
176 source files other than the code file to access the token codes. If a <b>%union</b> declaration is used, the declaration for
177 YYSTYPE and an <tt>extern YYSTYPE yylval</tt> declaration shall also be included in this file. The header file may also declare the
178 <i>yyparse</i>() function, using a function prototype. It shall not declare the <i>yyerror</i>() and <i>yylex</i>() functions.</p>
179 <h5><a name="tag_20_154_12_03" id="tag_20_154_12_03"></a>Description File</h5>
180 <p>The description file shall be a text file containing a description of the state machine corresponding to the parser, using an
181 unspecified format. Limits for internal tables (see <a href="#tag_20_154_13_14">Limits</a> ) shall also be reported, in an
182 implementation-defined manner. (Some implementations may use dynamic allocation techniques and have no specific limit values to
183 report.)</p>
184 </blockquote>
185 <h4 class="mansect"><a name="tag_20_154_13" id="tag_20_154_13"></a>EXTENDED DESCRIPTION</h4>
186 <blockquote>
187 <p>The <i>yacc</i> command accepts a language that is used to define a grammar for a target language to be parsed by the tables and
188 code generated by <i>yacc</i>. The language accepted by <i>yacc</i> as a grammar for the target language is described below using
189 the <i>yacc</i> input language itself.</p>
190 <p>The input <i>grammar</i> includes rules describing the input structure of the target language and code to be invoked when these
191 rules are recognized to provide the associated semantic action. The code to be executed shall appear as bodies of text that are
192 intended to be C-language code. These bodies of text shall not contain C-language trigraphs. The C-language inclusions are presumed
193 to form a correct function when processed by <i>yacc</i> into its output files. The code included in this way shall be executed
194 during the recognition of the target language.</p>
195 <p>Given a grammar, the <i>yacc</i> utility generates the files described in the OUTPUT FILES section. The code file can be
196 compiled and linked using <a href="../utilities/c17.html"><i>c17</i></a>. If the declaration and programs sections of the grammar
197 file did not include definitions of <i>main</i>(), <i>yylex</i>(), and <i>yyerror</i>(), the compiled output requires linking with
198 externally supplied versions of those functions. Default versions of <i>main</i>() and <i>yyerror</i>() are supplied in the
199 <i>yacc</i> library and can be linked in by using the <b>-l y</b> operand to <a href="../utilities/c17.html"><i>c17</i></a>.
200 The <i>yacc</i> library interfaces need not support interfaces with other than the default <b>yy</b> symbol prefix. The application
201 provides the lexical analyzer function, <i>yylex</i>(); the <a href="../utilities/lex.html"><i>lex</i></a> utility is specifically
202 designed to generate such a routine.</p>
203 <h5><a name="tag_20_154_13_01" id="tag_20_154_13_01"></a>Input Language</h5>
204 <p>The application shall ensure that every specification file consists of three sections in order: <i>declarations</i>, <i>grammar
205 rules</i>, and <i>programs</i>, separated by double <percent-sign> characters (<tt>"%%"</tt>). The declarations and programs
206 sections can be empty. If the latter is empty, the preceding <tt>"%%"</tt> mark separating it from the rules section can be
207 omitted.</p>
208 <p>The input is free form text following the structure of the grammar defined below.</p>
209 <h5><a name="tag_20_154_13_02" id="tag_20_154_13_02"></a>Lexical Structure of the Grammar</h5>
210 <p>The <blank>, <newline>, and <form-feed> character shall be ignored, except that the application shall ensure
211 that they do not appear in names or multi-character reserved symbols. Comments shall be enclosed in <tt>"/* ... */"</tt>,
212 and can appear wherever a name is valid.</p>
213 <p>Names are of arbitrary length, made up of letters, periods (<tt>'.'</tt>), underscores (<tt>'_'</tt>), and non-initial digits.
214 Uppercase and lowercase letters are distinct. Conforming applications shall not use names beginning in <b>yy</b> or <b>YY</b> since
215 the <i>yacc</i> parser uses such names. Many of the names appear in the final output of <i>yacc</i>, and thus they should be chosen
216 to conform with any additional rules created by the C compiler to be used. In particular they appear in <b>#define</b>
217 statements.</p>
218 <p>A literal shall consist of a single character enclosed in single-quote characters. All of the escape sequences supported for
219 character constants by the ISO C standard shall be supported by <i>yacc</i>.</p>
220 <p>The relationship with the lexical analyzer is discussed in detail below.</p>
221 <p>The application shall ensure that the NUL character is not used in grammar rules or literals.</p>
222 <h5><a name="tag_20_154_13_03" id="tag_20_154_13_03"></a>Declarations Section</h5>
223 <p>The declarations section is used to define the symbols used to define the target language and their relationship with each
224 other. In particular, much of the additional information required to resolve ambiguities in the context-free grammar for the target
225 language is provided here.</p>
226 <p>Usually <i>yacc</i> assigns the relationship between the symbolic names it generates and their underlying numeric value. The
227 declarations section makes it possible to control the assignment of these values.</p>
228 <p>It is also possible to keep semantic information associated with the tokens currently on the parse stack in a user-defined
229 C-language <b>union</b>, if the members of the union are associated with the various names in the grammar. The declarations section
230 provides for this as well.</p>
231 <p>The first group of declarators below all take a list of names as arguments. That list can optionally be preceded by the name of
232 a C union member (called a <i>tag</i> below) appearing within <tt>'<'</tt> and <tt>'>'</tt>. (As an exception to the
233 typographical conventions of the rest of this volume of POSIX.1-2024, in this case <<i>tag</i>> does not represent a
234 metavariable, but the literal angle bracket characters surrounding a symbol.) The use of <i>tag</i> specifies that the tokens named
235 on this line shall be of the same C type as the union member referenced by <i>tag</i>. This is discussed in more detail below.</p>
236 <p>For lists used to define tokens, the first appearance of a given token can be followed by a positive integer (as a string of
237 decimal digits). If this is done, the underlying value assigned to it for lexical purposes shall be taken to be that number.</p>
238 <p>The following declares <i>name</i> to be a token:</p>
239 <pre>
240 <tt>%token </tt><b>[</b><tt><</tt><i>tag</i><tt>></tt><b>] </b><i>name </i><b>[</b><i>number</i><b>] [</b><i>name </i><b>[</b><i>number</i><b>]]</b><tt>...
241 </tt></pre>
242 <p>If <i>tag</i> is present, the C type for all tokens on this line shall be declared to be the type referenced by <i>tag</i>. If a
243 positive integer, <i>number</i>, follows a <i>name</i>, that value shall be assigned to the token.</p>
244 <p>The following declares <i>name</i> to be a token, and assigns precedence to it:</p>
245 <pre>
246 <tt>%left </tt><b>[</b><tt><</tt><i>tag</i><tt>></tt><b>] </b><i>name </i><b>[</b><i>number</i><b>] [</b><i>name </i><b>[</b><i>number</i><b>]]</b><tt>...
247 %right </tt><b>[</b><tt><</tt><i>tag</i><tt>></tt><b>] </b><i>name </i><b>[</b><i>number</i><b>] [</b><i>name </i><b>[</b><i>number</i><b>]]</b><tt>...
248 </tt></pre>
249 <p>One or more lines, each beginning with one of these symbols, can appear in this section. All tokens on the same line have the
250 same precedence level and associativity; the lines are in order of increasing precedence or binding strength. <b>%left</b> denotes
251 that the operators on that line are left associative, and <b>%right</b> similarly denotes right associative operators. If
252 <i>tag</i> is present, it shall declare a C type for <i>name</i>s as described for <b>%token</b>.</p>
253 <p>The following declares <i>name</i> to be a token, and indicates that this cannot be used associatively:</p>
254 <pre>
255 <tt>%nonassoc </tt><b>[</b><tt><</tt><i>tag</i><tt>></tt><b>] </b><i>name </i><b>[</b><i>number</i><b>] [</b><i>name </i><b>[</b><i>number</i><b>]]</b><tt>...
256 </tt></pre>
257 <p>If the parser encounters associative use of this token it reports an error. If <i>tag</i> is present, it shall declare a C type
258 for <i>name</i>s as described for <b>%token</b>.</p>
259 <p>The following declares that union member <i>name</i>s are non-terminals, and thus it is required to have a <i>tag</i> field at
260 its beginning:</p>
261 <pre>
262 <tt>%type <</tt><i>tag</i><tt>> </tt><i>name</i><tt>...
263 </tt></pre>
264 <p>Because it deals with non-terminals only, assigning a token number or using a literal is also prohibited. If this construct is
265 present, <i>yacc</i> shall perform type checking; if this construct is not present, the parse stack shall hold only the <b>int</b>
266 type.</p>
267 <p>Every name used in <i>grammar</i> not defined by a <b>%token</b>, <b>%left</b>, <b>%right</b>, or <b>%nonassoc</b> declaration
268 is assumed to represent a non-terminal symbol. The <i>yacc</i> utility shall report an error for any non-terminal symbol that does
269 not appear on the left side of at least one grammar rule.</p>
270 <p>Once the type, precedence, or token number of a name is specified, it shall not be changed. If the first declaration of a token
271 does not assign a token number, <i>yacc</i> shall assign a token number. Once this assignment is made, the token number shall not
272 be changed by explicit assignment.</p>
273 <p>The following declarators do not follow the previous pattern.</p>
274 <p>The following declares the non-terminal <i>name</i> to be the <i>start symbol</i>, which represents the largest, most general
275 structure described by the grammar rules:</p>
276 <pre>
277 <tt>%start </tt><i>name</i><tt>
278 </tt></pre>
279 <p>By default, it is the left-hand side of the first grammar rule; this default can be overridden with this declaration.</p>
280 <p>The following declares the <i>yacc</i> value stack to be a union of the various types of values desired.</p>
281 <pre>
282 <tt>%union { </tt><i>body of union</i><tt> (</tt><i>in C</i><tt>) }
283 </tt></pre>
284 <p>The body of the union shall not contain unbalanced curly brace preprocessing tokens.</p>
285 <p>By default, the values returned by actions (see below) and the lexical analyzer shall be of type <b>int</b>. The <i>yacc</i>
286 utility keeps track of types, and it shall insert corresponding union member names in order to perform strict type checking of the
287 resulting parser.</p>
288 <p>Alternatively, given that at least one <<i>tag</i>> construct is used, the union can be declared in a header file (which
289 shall be included in the declarations section by using a <b>#include</b> construct within <b>%{</b> and <b>%}</b>), and a
290 <b>typedef</b> used to define the symbol YYSTYPE to represent this union. The effect of <b>%union</b> is to provide the declaration
291 of YYSTYPE directly from the <i>yacc</i> input.</p>
292 <p>C-language declarations and definitions can appear in the declarations section, enclosed by the following marks:</p>
293 <pre>
294 <tt>%{ ... %}
295 </tt></pre>
296 <p>These statements shall be copied into the code file, and have global scope within it so that they can be used in the rules and
297 program sections. The statements shall not contain <tt>"%}"</tt> outside a comment, string literal, or multi-character
298 constant.</p>
299 <p>The application shall ensure that the declarations section is terminated by the token <b>%%</b>.</p>
300 <h5><a name="tag_20_154_13_04" id="tag_20_154_13_04"></a>Grammar Rules in yacc</h5>
301 <p>The rules section defines the context-free grammar to be accepted by the function <i>yacc</i> generates, and associates with
302 those rules C-language actions and additional precedence information. The grammar is described below, and a formal definition
303 follows.</p>
304 <p>The rules section is comprised of one or more grammar rules. A grammar rule has the form:</p>
305 <pre>
306 <tt>A : BODY ;
307 </tt></pre>
308 <p>The symbol <b>A</b> represents a non-terminal name, and <b>BODY</b> represents a sequence of zero or more <i>name</i>s,
309 <i>literal</i>s, and <i>semantic action</i>s that can then be followed by optional <i>precedence rule</i>s. Only the names and
310 literals participate in the formation of the grammar; the semantic actions and precedence rules are used in other ways. The
311 <colon> and the <semicolon> are <i>yacc</i> punctuation. If there are several successive grammar rules with the same
312 left-hand side, the <vertical-line> (<tt>'|'</tt>) can be used to avoid rewriting the left-hand side; in this case the
313 <semicolon> appears only after the last rule. The BODY part can be empty (or empty of names and literals) to indicate that
314 the non-terminal symbol matches the empty string.</p>
315 <p>The <i>yacc</i> utility assigns a unique number to each rule. Rules using the vertical bar notation are distinct rules. The
316 number assigned to the rule appears in the description file.</p>
317 <p>The elements comprising a BODY are:</p>
318 <dl compact>
319 <dd></dd>
320 <dt><i>name</i>, <i>literal</i></dt>
321 <dd>These form the rules of the grammar: <i>name</i> is either a <i>token</i> or a <i>non-terminal</i>; <i>literal</i> stands for
322 itself (less the lexically required quotation marks).</dd>
323 <dt><i>semantic action</i></dt>
324 <dd><br>
325 With each grammar rule, the user can associate actions to be performed each time the rule is recognized in the input process. (Note
326 that the word "action" can also refer to the actions of the parser—shift, reduce, and so on.)
327 <p>These actions can return values and can obtain the values returned by previous actions. These values are kept in objects of type
328 YYSTYPE (see <b>%union</b>). The result value of the action shall be kept on the parse stack with the left-hand side of the rule,
329 to be accessed by other reductions as part of their right-hand side. By using the <<i>tag</i>> information provided in the
330 declarations section, the code generated by <i>yacc</i> can be strictly type checked and contain arbitrary information. In
331 addition, the lexical analyzer can provide the same kinds of values for tokens, if desired.</p>
332 <p>An action is an arbitrary C statement and as such can do input or output, call subprograms, and alter external variables. An
333 action is one or more C statements enclosed in curly braces <tt>'{'</tt> and <tt>'}'</tt>. The statements shall not contain
334 unbalanced curly brace preprocessing tokens.</p>
335 <p>Certain pseudo-variables can be used in the action. These are macros for access to data structures known internally to
336 <i>yacc</i>.</p>
337 <dl compact>
338 <dd></dd>
339 <dt>$$</dt>
340 <dd>The value of the action can be set by assigning it to $$. If type checking is enabled and the type of the value to be assigned
341 cannot be determined, a diagnostic message may be generated.</dd>
342 <dt>$<i>number</i></dt>
343 <dd>This refers to the value returned by the component specified by the token <i>number</i> in the right side of a rule, reading
344 from left to right; <i>number</i> can be zero or negative. If <i>number</i> is zero or negative, it refers to the data associated
345 with the name on the parser's stack preceding the leftmost symbol of the current rule. (That is, <tt>"$0"</tt> refers to the name
346 immediately preceding the leftmost name in the current rule to be found on the parser's stack and <tt>"$-1"</tt> refers to the
347 symbol to <i>its</i> left.) If <i>number</i> refers to an element past the current point in the rule, or beyond the bottom of the
348 stack, the result is undefined. If type checking is enabled and the type of the value to be assigned cannot be determined, a
349 diagnostic message may be generated.</dd>
350 <dt>$<<i>tag</i>><i>number</i></dt>
351 <dd><br>
352 These correspond exactly to the corresponding symbols without the <i>tag</i> inclusion, but allow for strict type checking (and
353 preclude unwanted type conversions). The effect is that the macro is expanded to use <i>tag</i> to select an element from the
354 YYSTYPE union (using <i>dataname.tag</i>). This is particularly useful if <i>number</i> is not positive.</dd>
355 <dt>$<<i>tag</i>>$</dt>
356 <dd>This imposes on the reference the type of the union member referenced by <i>tag</i>. This construction is applicable when a
357 reference to a left context value occurs in the grammar, and provides <i>yacc</i> with a means for selecting a type.</dd>
358 </dl>
359 <p>Actions can occur anywhere in a rule (not just at the end); an action can access values returned by actions to its left, and in
360 turn the value it returns can be accessed by actions to its right. An action appearing in the middle of a rule shall be equivalent
361 to replacing the action with a new non-terminal symbol and adding an empty rule with that non-terminal symbol on the left-hand
362 side. The semantic action associated with the new rule shall be equivalent to the original action. The use of actions within rules
363 might introduce conflicts that would not otherwise exist.</p>
364 <p>By default, the value of a rule shall be the value of the first element in it. If the first element does not have a type
365 (particularly in the case of a literal) and type checking is turned on by <b>%type</b>, an error message shall result.</p>
366 </dd>
367 <dt><i>precedence</i></dt>
368 <dd>The keyword <b>%prec</b> can be used to change the precedence level associated with a particular grammar rule. Examples of this
369 are in cases where a unary and binary operator have the same symbolic representation, but need to be given different precedences,
370 or where the handling of an ambiguous if-else construction is necessary. The reserved symbol <b>%prec</b> can appear immediately
371 after the body of the grammar rule and can be followed by a token name or a literal. It shall cause the precedence of the grammar
372 rule to become that of the following token name or literal. The action for the rule as a whole can follow <b>%prec</b>.</dd>
373 </dl>
374 <p>If a program section follows, the application shall ensure that the grammar rules are terminated by <b>%%</b>.</p>
375 <h5><a name="tag_20_154_13_05" id="tag_20_154_13_05"></a>Programs Section</h5>
376 <p>The <i>programs</i> section can include the definition of the lexical analyzer <i>yylex</i>(), and any other functions; for
377 example, those used in the actions specified in the grammar rules. It is unspecified whether the programs section precedes or
378 follows the semantic actions in the output file; therefore, if the application contains any macro definitions and declarations
379 intended to apply to the code in the semantic actions, it shall place them within <tt>"%{ ... %}"</tt> in the
380 declarations section.</p>
381 <h5><a name="tag_20_154_13_06" id="tag_20_154_13_06"></a>Input Grammar</h5>
382 <p>The following input to <i>yacc</i> yields a parser for the input to <i>yacc</i>. This formal syntax takes precedence over the
383 preceding text syntax description.</p>
384 <p>The lexical structure is defined less precisely; <a href="#tag_20_154_13_02">Lexical Structure of the Grammar</a> defines most
385 terms. The correspondence between the previous terms and the tokens below is as follows.</p>
386 <dl compact>
387 <dd></dd>
388 <dt><b>IDENTIFIER</b></dt>
389 <dd>This corresponds to the concept of <i>name</i>, given previously. It also includes literals as defined previously.</dd>
390 <dt><b>C_IDENTIFIER</b></dt>
391 <dd>This is a name, and additionally it is known to be followed by a <colon>. A literal cannot yield this token.</dd>
392 <dt><b>NUMBER</b></dt>
393 <dd>A string of digits (a non-negative decimal integer).</dd>
394 <dt><b>TYPE</b>, <b>LEFT</b>, <b>MARK</b>, <b>LCURL</b>, <b>RCURL</b></dt>
395 <dd><br>
396 These correspond directly to <b>%type</b>, <b>%left</b>, <b>%%</b>, <b>%{</b>, and <b>%}</b>.</dd>
397 <dt><b>{ ... }</b></dt>
398 <dd>This indicates C-language source code, with the possible inclusion of <tt>'$'</tt> macros as discussed previously.</dd>
399 </dl>
400 <pre>
401 <tt>/* Grammar for the input to yacc. */
402 /* Basic entries. */
403 /* The following are recognized by the lexical analyzer. */
404 <br>
405 %token IDENTIFIER /* Includes identifiers and literals */
406 %token C_IDENTIFIER /* identifier (but not literal)
407 followed by a :. */
408 %token NUMBER /* [0-9][0-9]* */
409 <br>
410 /* Reserved words : %type=>TYPE %left=>LEFT, and so on */
411 <br>
412 %token LEFT RIGHT NONASSOC TOKEN PREC TYPE START UNION
413 <br>
414 %token MARK /* The %% mark. */
415 %token LCURL /* The %{ mark. */
416 %token RCURL /* The %} mark. */
417 <br>
418 /* 8-bit character literals stand for themselves; */
419 /* tokens have to be defined for multi-byte characters. */
420 <br>
421 %start spec
422 <br>
423 %%
424 <br>
425 spec : defs MARK rules tail
426 ;
427 tail : MARK
428 {
429 /* In this action, set up the rest of the file. */
430 }
431 | /* Empty; the second MARK is optional. */
432 ;
433 defs : /* Empty. */
434 | defs def
435 ;
436 def : START IDENTIFIER
437 | UNION
438 {
439 /* Copy union definition to output. */
440 }
441 | LCURL
442 {
443 /* Copy C code to output file. */
444 }
445 RCURL
446 | rword tag nlist
447 ;
448 rword : TOKEN
449 | LEFT
450 | RIGHT
451 | NONASSOC
452 | TYPE
453 ;
454 tag : /* Empty: union tag ID optional. */
455 | '<' IDENTIFIER '>'
456 ;
457 nlist : nmno
458 | nlist nmno
459 ;
460 nmno : IDENTIFIER /* Note: literal invalid with % type. */
461 | IDENTIFIER NUMBER /* Note: invalid with % type. */
462 ;
463 <br>
464 /* Rule section */
465 <br>
466 rules : C_IDENTIFIER rbody prec
467 | rules rule
468 ;
469 rule : C_IDENTIFIER rbody prec
470 | '|' rbody prec
471 ;
472 rbody : /* empty */
473 | rbody IDENTIFIER
474 | rbody act
475 ;
476 act : '{'
477 {
478 /* Copy action, translate $$, and so on. */
479 }
480 '}'
481 ;
482 prec : /* Empty */
483 | PREC IDENTIFIER
484 | PREC IDENTIFIER act
485 | prec ';'
486 ;
487 </tt></pre>
488 <h5><a name="tag_20_154_13_07" id="tag_20_154_13_07"></a>Conflicts</h5>
489 <p>The parser produced for an input grammar may contain states in which conflicts occur. The conflicts occur because the grammar is
490 not LALR(1). An ambiguous grammar always contains at least one LALR(1) conflict. The <i>yacc</i> utility shall resolve all
491 conflicts, using either default rules or user-specified precedence rules.</p>
492 <p>Conflicts are either shift/reduce conflicts or reduce/reduce conflicts. A shift/reduce conflict is where, for a given state and
493 lookahead symbol, both a shift action and a reduce action are possible. A reduce/reduce conflict is where, for a given state and
494 lookahead symbol, reductions by two different rules are possible.</p>
495 <p>The rules below describe how to specify what actions to take when a conflict occurs. Not all shift/reduce conflicts can be
496 successfully resolved this way because the conflict may be due to something other than ambiguity, so incautious use of these
497 facilities can cause the language accepted by the parser to be much different from that which was intended. The description file
498 shall contain sufficient information to understand the cause of the conflict. Where ambiguity is the reason either the default or
499 explicit rules should be adequate to produce a working parser.</p>
500 <p>The declared precedences and associativities (see <a href="#tag_20_154_13_03">Declarations Section</a> ) are used to resolve
501 parsing conflicts as follows:</p>
502 <ol>
503 <li>
504 <p>A precedence and associativity is associated with each grammar rule; it is the precedence and associativity of the last token or
505 literal in the body of the rule. If the <b>%prec</b> keyword is used, it overrides this default. Some grammar rules might not have
506 both precedence and associativity.</p>
507 </li>
508 <li>
509 <p>If there is a shift/reduce conflict, and both the grammar rule and the input symbol have precedence and associativity associated
510 with them, then the conflict is resolved in favor of the action (shift or reduce) associated with the higher precedence. If the
511 precedences are the same, then the associativity is used; left associative implies reduce, right associative implies shift, and
512 non-associative implies an error in the string being parsed.</p>
513 </li>
514 <li>
515 <p>When there is a shift/reduce conflict that cannot be resolved by rule 2, the shift is done. Conflicts resolved this way are
516 counted in the diagnostic output described in <a href="#tag_20_154_13_08">Error Handling</a> .</p>
517 </li>
518 <li>
519 <p>When there is a reduce/reduce conflict, a reduction is done by the grammar rule that occurs earlier in the input sequence.
520 Conflicts resolved this way are counted in the diagnostic output described in <a href="#tag_20_154_13_08">Error Handling</a> .</p>
521 </li>
522 </ol>
523 <p>Conflicts resolved by precedence or associativity shall not be counted in the shift/reduce and reduce/reduce conflicts reported
524 by <i>yacc</i> on either standard error or in the description file.</p>
525 <h5><a name="tag_20_154_13_08" id="tag_20_154_13_08"></a>Error Handling</h5>
526 <p>The token <b>error</b> shall be reserved for error handling. The name <b>error</b> can be used in grammar rules. It indicates
527 places where the parser can recover from a syntax error. The default value of <b>error</b> shall be 256. Its value can be changed
528 using a <b>%token</b> declaration. The lexical analyzer should not return the value of <b>error</b>.</p>
529 <p>The parser shall detect a syntax error when it is in a state where the action associated with the lookahead symbol is
530 <b>error</b>. A semantic action can cause the parser to initiate error handling by executing the macro YYERROR. When YYERROR is
531 executed, the semantic action passes control back to the parser. YYERROR cannot be used outside of semantic actions.</p>
532 <p>When the parser detects a syntax error, it normally calls <i>yyerror</i>() with the character string
533 <tt>"syntax error"</tt> as its argument. The call shall not be made if the parser is still recovering from a previous error
534 when the error is detected. The parser is considered to be recovering from a previous error until the parser has shifted over at
535 least three normal input symbols since the last error was detected or a semantic action has executed the macro <i>yyerrok</i>. The
536 parser shall not call <i>yyerror</i>() when YYERROR is executed.</p>
537 <p>The macro function YYRECOVERING shall return 1 if a syntax error has been detected and the parser has not yet fully recovered
538 from it. Otherwise, zero shall be returned.</p>
539 <p>When a syntax error is detected by the parser, the parser shall check if a previous syntax error has been detected. If a
540 previous error was detected, and if no normal input symbols have been shifted since the preceding error was detected, the parser
541 checks if the lookahead symbol is an endmarker (see <a href="#tag_20_154_13_09">Interface to the Lexical Analyzer</a> ). If it is,
542 the parser shall return with a non-zero value. Otherwise, the lookahead symbol shall be discarded and normal parsing shall
543 resume.</p>
544 <p>When YYERROR is executed or when the parser detects a syntax error and no previous error has been detected, or at least one
545 normal input symbol has been shifted since the previous error was detected, the parser shall pop back one state at a time until the
546 parse stack is empty or the current state allows a shift over <b>error</b>. If the parser empties the parse stack, it shall return
547 with a non-zero value. Otherwise, it shall shift over <b>error</b> and then resume normal parsing. If the parser reads a lookahead
548 symbol before the error was detected, that symbol shall still be the lookahead symbol when parsing is resumed.</p>
549 <p>The macro <i>yyerrok</i> in a semantic action shall cause the parser to act as if it has fully recovered from any previous
550 errors. The macro <i>yyclearin</i> shall cause the parser to discard the current lookahead token. If the current lookahead token
551 has not yet been read, <i>yyclearin</i> shall have no effect.</p>
552 <p>The macro YYACCEPT shall cause the parser to return with the value zero. The macro YYABORT shall cause the parser to return with
553 a non-zero value.</p>
554 <h5><a name="tag_20_154_13_09" id="tag_20_154_13_09"></a>Interface to the Lexical Analyzer</h5>
555 <p>The application shall ensure that the <i>yylex</i>() function is an integer-valued function that returns a <i>token number</i>
556 greater than zero representing the kind of token read, or a value less than or equal to zero when the end of input is reached. When
557 the parser generated by <i>yacc</i> calls <i>yylex</i>(), it shall assign the returned value, if greater than zero, to the external
558 variable <i>yychar</i>. If there is a value associated with the returned token (see the discussion of <i>tag</i> above), it shall
559 be assigned to the external variable <i>yylval</i>. If the return value from <i>yylex</i>() is less than or equal to zero, the
560 parser shall assign the value YYEOF to <i>yychar</i>.</p>
561 <p>If the parser and <i>yylex</i>() do not agree on these token numbers, reliable communication between them cannot occur. For
562 (single-byte character) literals, the token is simply the numeric value of the character in the current character set. The numbers
563 for other tokens can either be chosen by <i>yacc</i>, or chosen by the user. In either case, the <b>#define</b> construct of C is
564 used to allow <i>yylex</i>() to return these numbers symbolically. The <b>#define</b> statements are put into the code file, and
565 the header file if that file is requested. The set of characters permitted by <i>yacc</i> in an identifier is larger than that
566 permitted by C. Token names found to contain such characters shall not be included in the <b>#define</b> declarations.</p>
567 <p>If the token numbers are chosen by <i>yacc</i>, the tokens other than literals shall be assigned numbers greater than 256,
568 although no order is implied. A token can be explicitly assigned a number by following its first appearance in the declarations
569 section with a number. Names and literals not defined this way retain their default definition. All token numbers assigned by
570 <i>yacc</i> shall be unique and distinct from the token numbers used for literals and user-assigned tokens. If duplicate token
571 numbers cause conflicts in parser generation, <i>yacc</i> shall report an error; otherwise, it is unspecified whether the token
572 assignment is accepted or an error is reported.</p>
573 <p>When a parser action is executed, <i>yychar</i> shall hold either the token number of the lookahead token, or YYEMPTY indicating
574 that there is no lookahead token, or YYEOF indicating the end of input. If <i>yychar</i> holds the token number of the lookahead
575 token, <i>yylval</i> shall hold the value associated with that token, if any.</p>
576 <p>The application shall ensure that when the end of input is reached, the <i>yylex</i>() function returns a value that is zero or
577 negative. The parser shall treat this as the token number YYEOF for a special token called the <i>endmarker</i>. If the tokens up
578 to, but excluding, the endmarker form a structure that matches the start symbol, the parser shall accept the input. If the
579 endmarker is seen in any other context, it shall be considered an error.</p>
580 <h5><a name="tag_20_154_13_10" id="tag_20_154_13_10"></a>Completing the Program</h5>
581 <p>In addition to <i>yyparse</i>() and <i>yylex</i>(), the functions <i>yyerror</i>() and <i>main</i>() are required to make a
582 complete program. The application can supply <i>main</i>() and <i>yyerror</i>(), or those routines can be obtained from the
583 <i>yacc</i> library.</p>
584 <h5><a name="tag_20_154_13_11" id="tag_20_154_13_11"></a>Yacc Library</h5>
585 <p>The following functions shall appear only in the <i>yacc</i> library accessible through the <b>-l y</b> operand to <a href=
586 "../utilities/c17.html"><i>c17</i></a>; they can therefore be redefined by a conforming application:</p>
587 <dl compact>
588 <dd></dd>
589 <dt><b>int </b><i>main</i>(<b>void</b>)</dt>
590 <dd><br>
591 This function shall call <i>yyparse</i>() and exit with an unspecified value. Other actions within this function are
592 unspecified.</dd>
593 <dt><b>void </b><i>yyerror</i>(<b>const char</b> *<i>s</i>)</dt>
594 <dd><br>
595 This function shall write the NUL-terminated argument to standard error, followed by a <newline>.</dd>
596 </dl>
597 <p>The order of the <b>-l y</b> and <b>-l l</b> operands given to <a href="../utilities/c17.html"><i>c17</i></a> is
598 significant; the application shall either provide its own <i>main</i>() function or ensure that <b>-l y</b> precedes
599 <b>-l l</b>.</p>
600 <h5><a name="tag_20_154_13_12" id="tag_20_154_13_12"></a>Debugging the Parser</h5>
601 <p>The parser generated by <i>yacc</i> shall have diagnostic facilities in it that can be optionally enabled at either compile time
602 or at runtime (if enabled at compile time). The compilation of the runtime debugging code is under the control of YYDEBUG, a
603 preprocessor symbol. If YYDEBUG has a non-zero value, the debugging code shall be included. If its value is zero, the code shall
604 not be included.</p>
605 <p>In parsers where the debugging code has been included, the external <b>int</b> <i>yydebug</i> can be used to turn debugging on
606 (with a non-zero value) and off (zero value) at runtime. The initial value of <i>yydebug</i> shall be zero.</p>
607 <p>When <b>-t</b> is specified, the code file shall be built such that, if YYDEBUG is not already defined at compilation time
608 (using the <a href="../utilities/c17.html"><i>c17</i></a> <b>-D</b> YYDEBUG option, for example), YYDEBUG shall be set explicitly
609 to 1. When <b>-t</b> is not specified, the code file shall be built such that, if YYDEBUG is not already defined, it shall be set
610 explicitly to zero.</p>
611 <p>The format of the debugging output is unspecified but includes at least enough information to determine the shift and reduce
612 actions, and the input symbols. It also provides information about error recovery.</p>
613 <h5><a name="tag_20_154_13_13" id="tag_20_154_13_13"></a>Algorithms</h5>
614 <p>The parser constructed by <i>yacc</i> implements an LALR(1) parsing algorithm as documented in the literature. It is unspecified
615 whether the parser is table-driven or direct-coded.</p>
616 <p>A parser generated by <i>yacc</i> shall never request an input symbol from <i>yylex</i>() while in a state where the only
617 actions other than the error action are reductions by a single rule.</p>
618 <p>The literature of parsing theory defines these concepts.</p>
619 <h5><a name="tag_20_154_13_14" id="tag_20_154_13_14"></a>Limits</h5>
620 <p>The <i>yacc</i> utility may have several internal tables. The minimum maximums for these tables are shown in the following
621 table. The exact meaning of these values is implementation-defined. The implementation shall define the relationship between these
622 values and between them and any error messages that the implementation may generate should it run out of space for any internal
623 structure. An implementation may combine groups of these resources into a single pool as long as the total available to the user
624 does not fall below the sum of the sizes specified by this section.<br></p>
625 <p class="caption">Table: Internal Limits in <i>yacc</i></p>
626 <center>
627 <table border="1" cellpadding="3" align="center">
628 <tr valign="top">
629 <th align="center">
630 <p class="tent"><b>Limit</b></p>
631 </th>
632 <th align="center">
633 <p class="tent"><b>Minimum Maximum</b></p>
634 </th>
635 <th align="center">
636 <p class="tent"><b>Description</b></p>
637 </th>
638 </tr>
639 <tr valign="top">
640 <td align="left">
641 <p class="tent">{NTERMS}</p>
642 </td>
643 <td align="left">
644 <p class="tent">126</p>
645 </td>
646 <td align="left">
647 <p class="tent">Number of tokens.</p>
648 </td>
649 </tr>
650 <tr valign="top">
651 <td align="left">
652 <p class="tent">{NNONTERM}</p>
653 </td>
654 <td align="left">
655 <p class="tent">200</p>
656 </td>
657 <td align="left">
658 <p class="tent">Number of non-terminals.</p>
659 </td>
660 </tr>
661 <tr valign="top">
662 <td align="left">
663 <p class="tent">{NPROD}</p>
664 </td>
665 <td align="left">
666 <p class="tent">300</p>
667 </td>
668 <td align="left">
669 <p class="tent">Number of rules.</p>
670 </td>
671 </tr>
672 <tr valign="top">
673 <td align="left">
674 <p class="tent">{NSTATES}</p>
675 </td>
676 <td align="left">
677 <p class="tent">600</p>
678 </td>
679 <td align="left">
680 <p class="tent">Number of states.</p>
681 </td>
682 </tr>
683 <tr valign="top">
684 <td align="left">
685 <p class="tent">{MEMSIZE}</p>
686 </td>
687 <td align="left">
688 <p class="tent">5200</p>
689 </td>
690 <td align="left">
691 <p class="tent">Length of rules. The total length, in names (tokens and non-terminals), of all the rules of the grammar. The
692 left-hand side is counted for each rule, even if it is not explicitly repeated, as specified in <a href="#tag_20_154_13_04">Grammar
693 Rules in yacc</a> .</p>
694 </td>
695 </tr>
696 <tr valign="top">
697 <td align="left">
698 <p class="tent">{ACTSIZE}</p>
699 </td>
700 <td align="left">
701 <p class="tent">4000</p>
702 </td>
703 <td align="left">
704 <p class="tent">Number of actions. "Actions" here (and in the description file) refer to parser actions (shift, reduce, and so
705 on) not to semantic actions defined in <a href="#tag_20_154_13_04">Grammar Rules in yacc</a> .</p>
706 </td>
707 </tr>
708 </table>
709 </center>
710 </blockquote>
711 <h4 class="mansect"><a name="tag_20_154_14" id="tag_20_154_14"></a>EXIT STATUS</h4>
712 <blockquote>
713 <p>The following exit values shall be returned:</p>
714 <dl compact>
715 <dd></dd>
716 <dt> 0</dt>
717 <dd>Successful completion.</dd>
718 <dt>>0</dt>
719 <dd>An error occurred.</dd>
720 </dl>
721 </blockquote>
722 <h4 class="mansect"><a name="tag_20_154_15" id="tag_20_154_15"></a>CONSEQUENCES OF ERRORS</h4>
723 <blockquote>
724 <p>If any errors are encountered, the run is aborted and <i>yacc</i> exits with a non-zero status. Partial code files and header
725 files may be produced. The summary information in the description file shall always be produced if the <b>-v</b> flag is
726 present.</p>
727 </blockquote>
728 <hr>
729 <div class="box"><em>The following sections are informative.</em></div>
730 <h4 class="mansect"><a name="tag_20_154_16" id="tag_20_154_16"></a>APPLICATION USAGE</h4>
731 <blockquote>
732 <p>Historical implementations experience name conflicts on the names <b>yacc.tmp</b>, <b>yacc.acts</b>, <b>yacc.debug</b>,
733 <b>y.tab.c</b>, <b>y.tab.h</b>, and <b>y.output</b> if more than one copy of <i>yacc</i> is running in a single directory at one
734 time. The <b>-b</b> option was added to overcome this problem. The related problem of allowing multiple <i>yacc</i> parsers to be
735 placed in the same file was addressed by adding a <b>-p</b> option to override the previously hard-coded <b>yy</b> variable
736 prefix.</p>
737 <p class="tent">The description of the <b>-p</b> option specifies the minimal set of function and variable names that cause
738 conflict when multiple parsers are linked together. YYSTYPE does not need to be changed. Instead, the programmer can use <b>-b</b>
739 to give the header files for different parsers different names, and then the file with the <i>yylex</i>() for a given parser can
740 include the header for that parser. Names such as <i>yyclearerr</i> do not need to be changed because they are used only in the
741 actions; they do not have linkage. It is possible that an implementation has other names, either internal ones for implementing
742 things such as <i>yyclearerr</i>, or providing non-standard features that it wants to change with <b>-p</b>.</p>
743 <p class="tent">Unary operators that are the same token as a binary operator in general need their precedence adjusted. This is
744 handled by the <b>%prec</b> advisory symbol associated with the particular grammar rule defining that unary operator. (See <a href=
745 "#tag_20_154_13_04">Grammar Rules in yacc</a> .) Applications are not required to use this operator for unary operators, but the
746 grammars that do not require it are rare.</p>
747 <p class="tent">If <i>yyerror</i>() and <i>yylex</i>() are not defined within <b>%{</b> and <b>%}</b> in the declarations section
748 as functions or macros, nor in the programs section as functions, recommended practice is to declare them as functions in a
749 separate header file and include that file in the declarations section, followed by <tt>#define yyerror yyerror</tt> and
750 <tt>#define yylex yylex</tt>. This lets the separate header file be the definitive API for all code defining or using these
751 functions.</p>
752 </blockquote>
753 <h4 class="mansect"><a name="tag_20_154_17" id="tag_20_154_17"></a>EXAMPLES</h4>
754 <blockquote>
755 <p>Access to the <i>yacc</i> library is obtained with library search operands to <a href="../utilities/c17.html"><i>c17</i></a>. To
756 use the <i>yacc</i> library <i>main</i>():</p>
757 <pre>
758 <tt>c17 y.tab.c -l y
759 </tt></pre>
760 <p class="tent">Both the <a href="../utilities/lex.html"><i>lex</i></a> library and the <i>yacc</i> library contain <i>main</i>().
761 To access the <i>yacc</i> <i>main</i>():</p>
762 <pre>
763 <tt>c17 y.tab.c lex.yy.c -l y -l l
764 </tt></pre>
765 <p class="tent">This ensures that the <i>yacc</i> library is searched first, so that its <i>main</i>() is used.</p>
766 <p class="tent">The historical <i>yacc</i> libraries have contained two simple functions that are normally coded by the application
767 programmer. These functions are similar to the following code:</p>
768 <pre>
769 <tt>#include <locale.h>
770 int main(void)
771 {
772 extern int yyparse();
773 <br class="tent">
774 setlocale(LC_ALL, "");
775 <br class="tent">
776 /* If the following parser is one created by lex, the
777 application must be careful to ensure that LC_CTYPE
778 and LC_COLLATE are set to the POSIX locale. */
779 (void) yyparse();
780 return (0);
781 }
782 <br class="tent">
783 #include <stdio.h>
784 <br class="tent">
785 void yyerror(const char *msg)
786 {
787 (void) fprintf(stderr, "%s\n", msg);
788 return (0);
789 }
790 </tt></pre></blockquote>
791 <h4 class="mansect"><a name="tag_20_154_18" id="tag_20_154_18"></a>RATIONALE</h4>
792 <blockquote>
793 <p>The references in <b>Referenced Documents</b> may be helpful in constructing the parser generator. The referenced DeRemer and
794 Pennello article (along with the works it references) describes a technique to generate parsers that conform to this volume of
795 POSIX.1-2024. Work in this area continues to be done, so implementors should consult current literature before doing any new
796 implementations. The original Knuth article is the theoretical basis for this kind of parser, but the tables it generates are
797 impractically large for reasonable grammars and should not be used. The "equivalent to" wording is intentional to assure that the
798 best tables that are LALR(1) can be generated.</p>
799 <p class="tent">There has been confusion between the class of grammars, the algorithms needed to generate parsers, and the
800 algorithms needed to parse the languages. They are all reasonably orthogonal. In particular, a parser generator that accepts the
801 full range of LR(1) grammars need not generate a table any more complex than one that accepts SLR(1) (a relatively weak class of LR
802 grammars) for a grammar that happens to be SLR(1). Such an implementation need not recognize the case, either; table compression
803 can yield the SLR(1) table (or one even smaller than that) without recognizing that the grammar is SLR(1). The speed of an LR(1)
804 parser for any class is dependent more upon the table representation and compression (or the code generation if a direct parser is
805 generated) than upon the class of grammar that the table generator handles.</p>
806 <p class="tent">The speed of the parser generator is somewhat dependent upon the class of grammar it handles. However, the original
807 Knuth article algorithms for constructing LR parsers were judged by its author to be impractically slow at that time. Although full
808 LR is more complex than LALR(1), as computer speeds and algorithms improve, the difference (in terms of acceptable wall-clock
809 execution time) is becoming less significant.</p>
810 <p class="tent">Potential authors are cautioned that the referenced DeRemer and Pennello article previously cited identifies a bug
811 (an over-simplification of the computation of LALR(1) lookahead sets) in some of the LALR(1) algorithm statements that preceded it
812 to publication. They should take the time to seek out that paper, as well as current relevant work, particularly Aho's.</p>
813 <p class="tent">The <b>-b</b> option was added to provide a portable method for permitting <i>yacc</i> to work on multiple separate
814 parsers in the same directory. If a directory contains more than one <i>yacc</i> grammar, and both grammars are constructed at the
815 same time (by, for example, a parallel <a href="../utilities/make.html"><i>make</i></a> program), conflict results. While the
816 solution is not historical practice, it corrects a known deficiency in historical implementations. Corresponding changes were made
817 to all sections that referenced the filenames <b>y.tab.c</b> (now "the code file"), <b>y.tab.h</b> (now "the header file"), and
818 <b>y.output</b> (now "the description file").</p>
819 <p class="tent">The grammar for <i>yacc</i> input is based on System V documentation. The textual description shows there that the
820 <tt>';'</tt> is required at the end of the rule. The grammar and the implementation do not require this. (The use of
821 <b>C_IDENTIFIER</b> causes a reduce to occur in the right place.)</p>
822 <p class="tent">Also, in that implementation, the constructs such as <b>%token</b> can be terminated by a <semicolon>, but
823 this is not permitted by the grammar. The keywords such as <b>%token</b> can also appear in uppercase, which is again not
824 discussed. In most places where <tt>'%'</tt> is used, <backslash> can be substituted, and there are alternate spellings for
825 some of the symbols (for example, <b>%LEFT</b> can be <tt>"%<"</tt> or even <tt>"\<"</tt>).</p>
826 <p class="tent">Historically, <<i>tag</i>> can contain any characters except <tt>'>'</tt>, including white space, in the
827 implementation. However, since the <i>tag</i> must reference an ISO C standard union member, in practice conforming
828 implementations need to support only the set of characters for ISO C standard identifiers in this context.</p>
829 <p class="tent">Some historical implementations are known to accept actions that are terminated by a period. Historical
830 implementations often allow <tt>'$'</tt> in names. A conforming implementation does not need to support either of these
831 behaviors.</p>
832 <p class="tent">Deciding when to use <b>%prec</b> illustrates the difficulty in specifying the behavior of <i>yacc</i>. There may
833 be situations in which the <i>grammar</i> is not, strictly speaking, in error, and yet <i>yacc</i> cannot interpret it
834 unambiguously. The resolution of ambiguities in the grammar can in many instances be resolved by providing additional information,
835 such as using <b>%type</b> or <b>%union</b> declarations. It is often easier and it usually yields a smaller parser to take this
836 alternative when it is appropriate.</p>
837 <p class="tent">The size and execution time of a program produced without the runtime debugging code is usually smaller and
838 slightly faster in historical implementations.</p>
839 <p class="tent">Statistics messages from several historical implementations include the following types of information:</p>
840 <pre>
841 <i>n</i><tt>/512 terminals, </tt><i>n</i><tt>/300 non-terminals
842 </tt><i>n</i><tt>/600 grammar rules, </tt><i>n</i><tt>/1500 states
843 </tt><i>n</i><tt> shift/reduce, </tt><i>n</i><tt> reduce/reduce conflicts reported
844 </tt><i>n</i><tt>/350 working sets used
845 Memory: states, etc. </tt><i>n</i><tt>/15000, parser </tt><i>n</i><tt>/15000
846 </tt><i>n</i><tt>/600 distinct lookahead sets
847 </tt><i>n</i><tt> extra closures
848 </tt><i>n</i><tt> shift entries, </tt><i>n</i><tt> exceptions
849 </tt><i>n</i><tt> goto entries
850 </tt><i>n</i><tt> entries saved by goto default
851 Optimizer space used: input </tt><i>n</i><tt>/15000, output </tt><i>n</i><tt>/15000
852 </tt><i>n</i><tt> table entries, </tt><i>n</i><tt> zero
853 Maximum spread: </tt><i>n</i><tt>, Maximum offset: </tt><i>n</i><tt>
854 </tt></pre>
855 <p class="tent">The report of internal tables in the description file is left implementation-defined because all aspects of these
856 limits are also implementation-defined. Some implementations may use dynamic allocation techniques and have no specific limit
857 values to report.</p>
858 <p class="tent">The format of the <b>y.output</b> file is not given because specification of the format was not seen to enhance
859 applications portability. The listing is primarily intended to help human users understand and debug the parser; use of
860 <b>y.output</b> by a conforming application script would be unusual. Furthermore, implementations have not produced consistent
861 output and no popular format was apparent. The format selected by the implementation should be human-readable, in addition to the
862 requirement that it be a text file.</p>
863 <p class="tent">Standard error reports are not specifically described because they are seldom of use to conforming applications and
864 there was no reason to restrict implementations.</p>
865 <p class="tent">Some implementations recognize <tt>"={"</tt> as equivalent to <tt>'{'</tt> because it appears in historical
866 documentation. This construction was recognized and documented as obsolete as long ago as 1978, in the referenced <i>Yacc: Yet
867 Another Compiler-Compiler</i>. This volume of POSIX.1-2024 chose to leave it as obsolete and omit it.</p>
868 <p class="tent">Multi-byte characters should be recognized by the lexical analyzer and returned as tokens. They should not be
869 returned as multi-byte character literals. The token <b>error</b> that is used for error recovery is normally assigned the value
870 256 in the historical implementation. Thus, the token value 256, which is used in many multi-byte character sets, is not available
871 for use as the value of a user-defined token.</p>
872 <p class="tent">Earlier versions of this standard did not require the code file created by <i>yacc</i> to contain declarations of
873 <i>yyerror</i>(), <i>yylex</i>(), and <i>yyparse</i>(). This meant that portable applications that did not define them had to
874 declare them in the <i>grammar</i> file, to ensure they would not be diagnosed by the compiler as being called without being
875 declared, but this was not stated in those versions of the standard either. The standard developers decided it was preferable for
876 <i>yacc</i> to include the declarations in the code file and this is now a requirement. However, the declarations of
877 <i>yyerror</i>() and <i>yylex</i>() are only visible if a macro of the same name is not defined, which provides application writers
878 with a way to suppress the declaration if desired (for example, in order to provide their own declaration that would conflict with
879 the one written by <i>yacc</i>). These functions are not declared in the header file because a macro definition in the declaration
880 section would not be be able to suppress them there.</p>
881 <p class="tent">Earlier versions of this standard were also silent about a declaration of <i>main</i>(). However, the equivalent
882 solution was not adopted because a declaration of <i>main</i>() would only be needed if it is called recursively by an application.
883 Although in theory an application could call the <i>yacc</i> library version of <i>main</i>() from code in a <i>grammar</i> file,
884 it is questionable why any application (other than a test suite) would do so, in particular because that version of <i>main</i>()
885 does not accept any arguments and it calls <a href="../functions/exit.html"><i>exit</i>()</a>—it does not return—and therefore is
886 of little use recursively. An application that includes its own definition of <i>main</i>() could call it recursively, but can
887 reasonably be expected to ensure it does not call <i>main</i>() without previously defining or declaring it. An additional
888 complication is that <i>main</i>() has multiple different allowed prototypes. The standard developers decided the simplest solution
889 was to disallow <i>yacc</i> from providing a declaration of <i>main</i>() in the code file.</p>
890 </blockquote>
891 <h4 class="mansect"><a name="tag_20_154_19" id="tag_20_154_19"></a>FUTURE DIRECTIONS</h4>
892 <blockquote>
893 <p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a
894 <newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require
895 implementations to treat this as an error.</p>
896 </blockquote>
897 <h4 class="mansect"><a name="tag_20_154_20" id="tag_20_154_20"></a>SEE ALSO</h4>
898 <blockquote>
899 <p><a href="../utilities/c17.html#"><i>c17</i></a> , <a href="../utilities/lex.html#"><i>lex</i></a></p>
900 <p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href=
901 "../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p>
902 </blockquote>
903 <h4 class="mansect"><a name="tag_20_154_21" id="tag_20_154_21"></a>CHANGE HISTORY</h4>
904 <blockquote>
905 <p>First released in Issue 2.</p>
906 </blockquote>
907 <h4 class="mansect"><a name="tag_20_154_22" id="tag_20_154_22"></a>Issue 5</h4>
908 <blockquote>
909 <p>The FUTURE DIRECTIONS section is added.</p>
910 </blockquote>
911 <h4 class="mansect"><a name="tag_20_154_23" id="tag_20_154_23"></a>Issue 6</h4>
912 <blockquote>
913 <p>This utility is marked as part of the C-Language Development Utilities option.</p>
914 <p class="tent">Minor changes have been added to align with the IEEE P1003.2b draft standard.</p>
915 <p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p>
916 <p class="tent">IEEE PASC Interpretation 1003.2 #177 is applied, changing the comment on <b>RCURL</b> from the <b>}%</b> token to
917 the <b>%}</b>.</p>
918 </blockquote>
919 <h4 class="mansect"><a name="tag_20_154_24" id="tag_20_154_24"></a>Issue 7</h4>
920 <blockquote>
921 <p>Austin Group Interpretation 1003.1-2001 #190 is applied, clarifying the requirements for generated code to conform to the
922 ISO C standard.</p>
923 <p class="tent">Austin Group Interpretation 1003.1-2001 #191 is applied, clarifying the handling of C-language trigraphs and curly
924 brace preprocessing tokens.</p>
925 <p class="tent">SD5-XCU-ERN-6 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not apply.</p>
926 <p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p>
927 <p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0204 [977] is applied.</p>
928 </blockquote>
929 <h4 class="mansect"><a name="tag_20_154_25" id="tag_20_154_25"></a>Issue 8</h4>
930 <blockquote>
931 <p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that
932 have the encoded value of a <newline> character.</p>
933 <p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p>
934 <p class="tent">Austin Group Defect 1269 is applied, changing the required contents of the code file (including <b>#define</b>
935 statements for YYEMPTY and YYEOF) and adding new requirements for the interface to the lexical analyzer.</p>
936 <p class="tent">Austin Group Defect 1388 is applied, changing the requirements relating to declarations of <i>yyerror</i>(),
937 <i>yylex</i>(), <i>yyparse</i>(), and <i>main</i>().</p>
938 </blockquote>
939 <div class="box"><em>End of informative text.</em></div>
940 <hr>
941 <p> </p>
942 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
943 <hr size="2" noshade>
944 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
945 POSIX™ is a Trademark of The IEEE.<br>
946 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
947 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
948 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
949 ]</font></center>
950 <hr size="2" noshade>
951 <div class="NAVHEADER">
952 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
953 <tr class="nav">
954 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/xgettext.html" accesskey="P"><<<
955 Previous</a></td>
956 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
957 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/zcat.html" accesskey="N">Next >>></a></td>
958 </tr>
959 </table>
960 <hr align="left" width="100%"></div>
961 </body>
962 </html>