goyacc

README

goyacc

Goyacc is a version of yacc generating Go programs.

Installation

$ go get github.com/cznic/goyacc

Documentation: godoc.org/github.com/cznic/goyacc

Documentation

Overview

Goyacc is a version of yacc generating Go parsers.

Usage

Note: If no non flag arguments are given, goyacc reads standard input.

goyacc [options] [input]

options and (defaults)
	-c                  Report state closures. (false)
	-cr                 Check all states are reducible. (false)
	-dlval              Debug value when runtime yyDebug >= 3. ("lval")
	-dlvalf             Debug format of -dlval. ("%+v")
	-ex                 Explain how were conflicts resolved. (false)
	-l                  Disable line directives, for compatibility only - ignored. (false)
	-la                 Report all lookahead sets. (false)
	-o outputFile       Parser output. ("y.go")
	-p prefix           Name prefix to use in generated code. ("yy")
	-v reportFile       Create grammar report. ("y.output")
	-xe examplesFile    Generate error messages by examples. ("")
	-xegen examplesFile Generate a file suitable for -xe automatically from the grammar.
	                    The file must not exist. ("")

Changelog

2015-03-24: The search for a custom error message is now extended to include also the last state that was shifted into, if any. This change resolves a problem in which a lookahead symbol is valid for a reduce action in state A, but the same symbol is later never accepted by any shift action in some state B which is popped from the state stack after the reduction is performed. The computed from example state is A but when the error is actually detected, the state is now B and the custom error was thus not used.

2015-02-23: Added -xegen flag. It can be used to automagically generate a skeleton errors by example file which can be, for example, edited and/or submited later as an argument of the -xe option.

2014-12-18: Support %precedence for better bison compatibility[3]. The actual changes are in packages goyacc is dependent on. Goyacc users should rebuild the binary:

$ go get -u github.com/cznic/goyacc

2014-12-02: Added support for the optional yyLexerEx interface. The Reduced method can be useful for debugging and/or automatically producing examples by parsing code fragments. If it returns true the parser exits immediately with return value -1.

Overview

The generated parser is reentrant and mostly backwards compatible with parsers generated by go tool yacc[0]. yyParse expects to be given an argument that conforms to the following interface:

type yyLexer interface {
	Lex(lval *yySymType) int
	Error(e string)
}

Optionally the argument to yyParse may implement the following interface:

type yyLexerEx interface {
	yyLexer
	// Hook for recording a reduction.
	Reduced(rule, state int, lval *yySymType) (stop bool) // Client should copy *lval.
}

Lex should return the token identifier, and place other token information in lval (which replaces the usual yylval). Error is equivalent to yyerror in the original yacc.

Code inside the parser may refer to the variable yylex, which holds the yyLexer passed to Parse.

Multiple grammars compiled into a single program should be placed in distinct packages. If that is impossible, the "-p prefix" flag to yacc sets the prefix, by default yy, that begins the names of symbols, including types, the parser, and the lexer, generated and referenced by yacc's generated code. Setting it to distinct values allows multiple grammars to be placed in a single package.

Differences wrt go tool yacc

- goyacc implements ideas from "Generating LR Syntax Error Messages from Examples"[1]. Use the -xe flag to pass a name of the example file. For more details about the example format please see [2].

- The grammar report includes example token sequences leading to the particular state. Can help understanding conflicts.

- Minor changes in parser debug output.