share/doc/psd/15.yacc/ss8

   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 .\"     @(#)ss8 8.1 (Berkeley) 6/8/93
  38 .\"
  39 .\" $FreeBSD$
  40 .SH
  41 8: The Yacc Environment
  42 .PP
  43 When the user inputs a specification
  44 to Yacc, the output is a file of C programs, called
  45 .I y.tab.c
  46 on most
  47 systems
  48 (due to local file system conventions, the names may differ from
  49 installation to installation).
  50 The function produced by Yacc is called
  51 .I yyparse \|;
  52 it is an integer valued function.
  53 When it is called, it in turn repeatedly calls
  54 .I yylex ,
  55 the lexical analyzer
  56 supplied by the user (see Section 3)
  57 to obtain input tokens.
  58 Eventually, either an error is detected, in which case
  59 (if no error recovery is possible)
  60 .I yyparse
  61 returns the value 1,
  62 or the lexical analyzer returns the endmarker token
  63 and the parser accepts.
  64 In this case,
  65 .I yyparse
  66 returns the value 0.
  67 .PP
  68 The user must provide a certain amount of environment for this
  69 parser in order to obtain a working program.
  70 For example, as with every C program, a program called
  71 .I main
  72 must be defined, that eventually calls
  73 .I yyparse .
  74 In addition, a routine called
  75 .I yyerror
  76 prints a message
  77 when a syntax error is detected.
  78 .PP
  79 These two routines must be supplied in one form or another by the
  80 user.
  81 To ease the initial effort of using Yacc, a library has been
  82 provided with default versions of
  83 .I main
  84 and
  85 .I yyerror .
  86 The name of this library is system dependent;
  87 on many systems the library is accessed by a
  88 .B \-ly
  89 argument to the loader.
  90 To show the triviality of these default programs, the source is
  91 given below:
  92 .DS
  93 main(){
  94         return( yyparse() );
  95         }
  96 .DE
  97 and
  98 .DS
  99 # include <stdio.h>
 100
 101 yyerror(s) char *s; {
 102         fprintf( stderr, "%s\en", s );
 103         }
 104 .DE
 105 The argument to
 106 .I yyerror
 107 is a string containing an error message, usually
 108 the string ``syntax error''.
 109 The average application will want to do better than this.
 110 Ordinarily, the program should keep track of the input line number, and print it
 111 along with the message when a syntax error is detected.
 112 The external integer variable
 113 .I yychar
 114 contains the lookahead token number at the time the error was detected;
 115 this may be of some interest in giving better diagnostics.
 116 Since the
 117 .I main
 118 program is probably supplied by the user (to read arguments, etc.)
 119 the Yacc library is useful only in small
 120 projects, or in the earliest stages of larger ones.
 121 .PP
 122 The external integer variable
 123 .I yydebug
 124 is normally set to 0.
 125 If it is set to a nonzero value, the parser will output a
 126 verbose description of its actions, including
 127 a discussion of which input symbols have been read, and
 128 what the parser actions are.
 129 Depending on the operating environment,
 130 it may be possible to set this variable by using a debugging system.