share/doc/psd/15.yacc/ss2

   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 .\"     @(#)ss2 8.1 (Berkeley) 6/8/93
  38 .\"
  39 .\" $FreeBSD$
  40 .SH
  41 2: Actions
  42 .PP
  43 With each grammar rule, the user may associate actions to be performed each time
  44 the rule is recognized in the input process.
  45 These actions may return values, and may obtain the values returned by previous
  46 actions.
  47 Moreover, the lexical analyzer can return values
  48 for tokens, if desired.
  49 .PP
  50 An action is an arbitrary C statement, and as such can do
  51 input and output, call subprograms, and alter
  52 external vectors and variables.
  53 An action is specified by
  54 one or more statements, enclosed in curly braces ``{'' and ``}''.
  55 For example,
  56 .DS
  57 A       :       \'(\'  B  \')\'
  58                         {       hello( 1, "abc" );  }
  59 .DE
  60 and
  61 .DS
  62 XXX     :       YYY  ZZZ
  63                         {       printf("a message\en");
  64                                 flag = 25;   }
  65 .DE
  66 are grammar rules with actions.
  67 .PP
  68 To facilitate easy communication between the actions and the parser, the action statements are altered
  69 slightly.
  70 The symbol ``dollar sign'' ``$'' is used as a signal to Yacc in this context.
  71 .PP
  72 To return a value, the action normally sets the
  73 pseudo-variable ``$$'' to some value.
  74 For example, an action that does nothing but return the value 1 is
  75 .DS
  76         {  $$ = 1;  }
  77 .DE
  78 .PP
  79 To obtain the values returned by previous actions and the lexical analyzer, the
  80 action may use the pseudo-variables $1, $2, . . .,
  81 which refer to the values returned by the
  82 components of the right side of a rule, reading from left to right.
  83 Thus, if the rule is
  84 .DS
  85 A       :       B  C  D   ;
  86 .DE
  87 for example, then $2 has the value returned by C, and $3 the value returned by D.
  88 .PP
  89 As a more concrete example, consider the rule
  90 .DS
  91 expr    :       \'(\'  expr  \')\'   ;
  92 .DE
  93 The value returned by this rule is usually the value of the
  94 .I expr
  95 in parentheses.
  96 This can be indicated by
  97 .DS
  98 expr    :        \'(\'  expr  \')\'             {  $$ = $2 ;  }
  99 .DE
 100 .PP
 101 By default, the value of a rule is the value of the first element in it ($1).
 102 Thus, grammar rules of the form
 103 .DS
 104 A       :       B    ;
 105 .DE
 106 frequently need not have an explicit action.
 107 .PP
 108 In the examples above, all the actions came at the end of their rules.
 109 Sometimes, it is desirable to get control before a rule is fully parsed.
 110 Yacc permits an action to be written in the middle of a rule as well
 111 as at the end.
 112 This rule is assumed to return a value, accessible
 113 .\" XXX What does this mean?  Nobody seems to understand it.
 114 .\" through the usual \$ mechanism by the actions to
 115 through the usual mechanism by the actions to
 116 the right of it.
 117 In turn, it may access the values
 118 returned by the symbols to its left.
 119 Thus, in the rule
 120 .DS
 121 A       :       B
 122                         {  $$ = 1;  }
 123                 C
 124                         {   x = $2;   y = $3;  }
 125         ;
 126 .DE
 127 the effect is to set
 128 .I x
 129 to 1, and
 130 .I y
 131 to the value returned by C.
 132 .PP
 133 Actions that do not terminate a rule are actually
 134 handled by Yacc by manufacturing a new nonterminal
 135 symbol name, and a new rule matching this
 136 name to the empty string.
 137 The interior action is the action triggered off by recognizing
 138 this added rule.
 139 Yacc actually treats the above example as if
 140 it had been written:
 141 .DS
 142 $ACT    :       /* empty */
 143                         {  $$ = 1;  }
 144         ;
 145
 146 A       :       B  $ACT  C
 147                         {   x = $2;   y = $3;  }
 148         ;
 149 .DE
 150 .PP
 151 In many applications, output is not done directly by the actions;
 152 rather, a data structure, such as a parse tree, is constructed in memory,
 153 and transformations are applied to it before output is generated.
 154 Parse trees are particularly easy to
 155 construct, given routines to build and maintain the tree
 156 structure desired.
 157 For example, suppose there is a C function
 158 .I node ,
 159 written so that the call
 160 .DS
 161 node( L, n1, n2 )
 162 .DE
 163 creates a node with label L, and descendants n1 and n2, and returns the index of
 164 the newly created node.
 165 Then parse tree can be built by supplying actions such as:
 166 .DS
 167 expr    :       expr  \'+\'  expr
 168                         {  $$ = node( \'+\', $1, $3 );  }
 169 .DE
 170 in the specification.
 171 .PP
 172 The user may define other variables to be used by the actions.
 173 Declarations and definitions can appear in
 174 the declarations section,
 175 enclosed in the marks ``%{'' and ``%}''.
 176 These declarations and definitions have global scope,
 177 so they are known to the action statements and the lexical analyzer.
 178 For example,
 179 .DS
 180 %{   int variable = 0;   %}
 181 .DE
 182 could be placed in the declarations section,
 183 making
 184 .I variable
 185 accessible to all of the actions.
 186 The Yacc parser uses only names beginning in ``yy'';
 187 the user should avoid such names.
 188 .PP
 189 In these examples, all the values are integers: a discussion of
 190 values of other types will be found in Section 10.