github.com/powerman/golang-tools@v0.1.11-0.20220410185822-5ad214d8d803/cmd/goyacc/doc.go (about)

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  
     7  Goyacc is a version of yacc for Go.
     8  It is written in Go and generates parsers written in Go.
     9  
    10  Usage:
    11  
    12  	goyacc args...
    13  
    14  It is largely transliterated from the Inferno version written in Limbo
    15  which in turn was largely transliterated from the Plan 9 version
    16  written in C and documented at
    17  
    18  	https://9p.io/magic/man2html/1/yacc
    19  
    20  Adepts of the original yacc will have no trouble adapting to this
    21  form of the tool.
    22  
    23  The directory $GOPATH/src/github.com/powerman/golang-tools/cmd/goyacc/testdata/expr
    24  is a yacc program for a very simple expression parser. See expr.y and
    25  main.go in that directory for examples of how to write and build
    26  goyacc programs.
    27  
    28  The generated parser is reentrant. The parsing function yyParse expects
    29  to be given an argument that conforms to the following interface:
    30  
    31  	type yyLexer interface {
    32  		Lex(lval *yySymType) int
    33  		Error(e string)
    34  	}
    35  
    36  Lex should return the token identifier, and place other token
    37  information in lval (which replaces the usual yylval).
    38  Error is equivalent to yyerror in the original yacc.
    39  
    40  Code inside the grammar actions may refer to the variable yylex,
    41  which holds the yyLexer passed to yyParse.
    42  
    43  Clients that need to understand more about the parser state can
    44  create the parser separately from invoking it. The function yyNewParser
    45  returns a yyParser conforming to the following interface:
    46  
    47  	type yyParser interface {
    48  		Parse(yyLex) int
    49  		Lookahead() int
    50  	}
    51  
    52  Parse runs the parser; the top-level call yyParse(yylex) is equivalent
    53  to yyNewParser().Parse(yylex).
    54  
    55  Lookahead can be called during grammar actions to read (but not consume)
    56  the value of the current lookahead token, as returned by yylex.Lex.
    57  If there is no current lookahead token (because the parser has not called Lex
    58  or has consumed the token returned by the most recent call to Lex),
    59  Lookahead returns -1. Calling Lookahead is equivalent to reading
    60  yychar from within in a grammar action.
    61  
    62  Multiple grammars compiled into a single program should be placed in
    63  distinct packages.  If that is impossible, the "-p prefix" flag to
    64  goyacc sets the prefix, by default yy, that begins the names of
    65  symbols, including types, the parser, and the lexer, generated and
    66  referenced by yacc's generated code.  Setting it to distinct values
    67  allows multiple grammars to be placed in a single package.
    68  
    69  */
    70  package main