share/doc/psd/15.yacc/ss1

   1 .\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions are
   5 .\" met:
   6 .\"
   7 .\" Redistributions of source code and documentation must retain the above
   8 .\" copyright notice, this list of conditions and the following
   9 .\" disclaimer.
  10 .\"
  11 .\" Redistributions in binary form must reproduce the above copyright
  12 .\" notice, this list of conditions and the following disclaimer in the
  13 .\" documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" All advertising materials mentioning features or use of this software
  16 .\" must display the following acknowledgement:
  17 .\"
  18 .\" This product includes software developed or owned by Caldera
  19 .\" International, Inc.  Neither the name of Caldera International, Inc.
  20 .\" nor the names of other contributors may be used to endorse or promote
  21 .\" products derived from this software without specific prior written
  22 .\" permission.
  23 .\"
  24 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
  25 .\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
  26 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  27 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  28 .\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
  30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  32 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  33 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  34 .\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  35 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36 .\"
  37 .\"     @(#)ss1 8.1 (Berkeley) 6/8/93
  38 .\"
  39 .\" $FreeBSD$
  40 .tr *\(**
  41 .tr |\(or
  42 .SH
  43 1: Basic Specifications
  44 .PP
  45 Names refer to either tokens or nonterminal symbols.
  46 Yacc requires
  47 token names to be declared as such.
  48 In addition, for reasons discussed in Section 3, it is often desirable
  49 to include the lexical analyzer as part of the specification file;
  50 it may be useful to include other programs as well.
  51 Thus, every specification file consists of three sections:
  52 the
  53 .I declarations ,
  54 .I "(grammar) rules" ,
  55 and
  56 .I programs .
  57 The sections are separated by double percent ``%%'' marks.
  58 (The percent ``%'' is generally used in Yacc specifications as an escape character.)
  59 .PP
  60 In other words, a full specification file looks like
  61 .DS
  62 declarations
  63 %%
  64 rules
  65 %%
  66 programs
  67 .DE
  68 .PP
  69 The declaration section may be empty.
  70 Moreover, if the programs section is omitted, the second %% mark may be omitted also;
  71 thus, the smallest legal Yacc specification is
  72 .DS
  73 %%
  74 rules
  75 .DE
  76 .PP
  77 Blanks, tabs, and newlines are ignored except
  78 that they may not appear in names or multi-character reserved symbols.
  79 Comments may appear wherever a name is legal; they are enclosed
  80 in /* . . . */, as in C and PL/I.
  81 .PP
  82 The rules section is made up of one or more grammar rules.
  83 A grammar rule has the form:
  84 .DS
  85 A  :  BODY  ;
  86 .DE
  87 A represents a nonterminal name, and BODY represents a sequence of zero or more names and literals.
  88 The colon and the semicolon are Yacc punctuation.
  89 .PP
  90 Names may be of arbitrary length, and may be made up of letters, dot ``.'', underscore ``\_'', and
  91 non-initial digits.
  92 Upper and lower case letters are distinct.
  93 The names used in the body of a grammar rule may represent tokens or nonterminal symbols.
  94 .PP
  95 A literal consists of a character enclosed in single quotes ``\'''.
  96 As in C, the backslash ``\e'' is an escape character within literals, and all the C escapes
  97 are recognized.
  98 Thus
  99 .DS
 100 \'\en\' newline
 101 \'\er\' return
 102 \'\e\'\'        single quote ``\'''
 103 \'\e\e\'        backslash ``\e''
 104 \'\et\' tab
 105 \'\eb\' backspace
 106 \'\ef\' form feed
 107 \'\exxx\'       ``xxx'' in octal
 108 .DE
 109 For a number of technical reasons, the
 110 \s-2NUL\s0
 111 character (\'\e0\' or 0) should never
 112 be used in grammar rules.
 113 .PP
 114 If there are several grammar rules with the same left hand side, the vertical bar ``|''
 115 can be used to avoid rewriting the left hand side.
 116 In addition,
 117 the semicolon at the end of a rule can be dropped before a vertical bar.
 118 Thus the grammar rules
 119 .DS
 120 A       :       B  C  D   ;
 121 A       :       E  F   ;
 122 A       :       G   ;
 123 .DE
 124 can be given to Yacc as
 125 .DS
 126 A       :       B  C  D
 127         |       E  F
 128         |       G
 129         ;
 130 .DE
 131 It is not necessary that all grammar rules with the same left side appear together in the grammar rules section,
 132 although it makes the input much more readable, and easier to change.
 133 .PP
 134 If a nonterminal symbol matches the empty string, this can be indicated in the obvious way:
 135 .DS
 136 empty :   ;
 137 .DE
 138 .PP
 139 Names representing tokens must be declared; this is most simply done by writing
 140 .DS
 141 %token   name1  name2 . . .
 142 .DE
 143 in the declarations section.
 144 (See Sections 3 , 5, and 6 for much more discussion).
 145 Every name not defined in the declarations section is assumed to represent a nonterminal symbol.
 146 Every nonterminal symbol must appear on the left side of at least one rule.
 147 .PP
 148 Of all the nonterminal symbols, one, called the
 149 .I "start symbol" ,
 150 has particular importance.
 151 The parser is designed to recognize the start symbol; thus,
 152 this symbol represents the largest,
 153 most general structure described by the grammar rules.
 154 By default,
 155 the start symbol is taken to be the left hand side of the first
 156 grammar rule in the rules section.
 157 It is possible, and in fact desirable, to declare the start
 158 symbol explicitly in the declarations section using the %start keyword:
 159 .DS
 160 %start   symbol
 161 .DE
 162 .PP
 163 The end of the input to the parser is signaled by a special token, called the
 164 .I endmarker .
 165 If the tokens up to, but not including, the endmarker form a structure
 166 which matches the start symbol, the parser function returns to its caller
 167 after the endmarker is seen; it
 168 .I accepts
 169 the input.
 170 If the endmarker is seen in any other context, it is an error.
 171 .PP
 172 It is the job of the user-supplied lexical analyzer
 173 to return the endmarker when appropriate; see section 3, below.
 174 Usually the endmarker represents some reasonably obvious
 175 I/O status, such as ``end-of-file'' or ``end-of-record''.