README
¶
go-ungrammar
Ungrammar implementation and API in Go. Ungrammar is a DSL for concrete syntax trees (CST). For some background on CSTs and how they relate to ASTs, see this blog post.
This implementation is based on the original ungrammar crate, also borrowing some test files from it.
Ungrammar syntax
The syntax of Ungrammar files is very simple:
// -- comment
Name = -- non-terminal definition
'ident' -- token (terminal)
A B -- sequence
A | B -- alternation
A* -- repetition (zero or more)
A? -- optional (zero or one)
(A B) -- grouping elements for precedence control
label:A -- label hint for naming
For some concrete examples, look at files in the testdata directory.
Usage
Usage example:
For somewhat more sophisticated usage, see the cmd/ungrammar2json command.
Documentation
¶
Overview ¶
package ungrammar provides a parser and representation for Ungrammar concrete syntax trees.
Index ¶
Examples ¶
Constants ¶
const ( // Special tokens ERROR tokenName = iota EOF NODE TOKEN EQ STAR PIPE QMARK COLON LPAREN RPAREN )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ErrorList ¶
type ErrorList []error
ErrorList represents multiple parse errors reported by the parser on a given source. It's loosely modeled on scanner.ErrorList in the Go standard library. ErrorList implements the error interface.
type Grammar ¶
type Grammar struct {
// Rules maps ruleName --> Rule
Rules map[string]Rule
// NameLoc maps ruleName --> its location in the input, for accurate error
// reporting. Rules carry their own locations, but since names are just
// strings, locations are kept here.
NameLoc map[string]location
}
Grammar represents a parsed Ungrammar file. The input is represented as a mapping between strings (rule names on the left-hand-side of Ungrammar rules) and rules (CST). For example, if we have a rule like "Foo = Bar Baz", the Rules map will contain a mapping between the string "Foo" and the CST Seq(Node(Bar), Node(Baz)).
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser parses ungrammar syntax into a Grammar. Create a new parser with NewParser, and then call its ParseGrammar method.
Example ¶
input := `
Foo = Bar Baz
Baz = ( Kay Jay )* | 'id'`
// Create an Ungrammar parser and parse input.
p := ungrammar.NewParser(input)
ungram, err := p.ParseGrammar()
if err != nil {
panic(err)
}
// Display the string representation of the parsed ungrammar.
fmt.Println(ungram.Rules["Foo"].String())
fmt.Println(ungram.Rules["Baz"].String())
Output: Seq(Bar, Baz) Alt(Rep(Seq(Kay, Jay)), 'id')
func (*Parser) ParseGrammar ¶
ParseGrammar takes the input the Parser was initialized with and parses it into a Grammar. It returns an ErrorList which collects all the errors encountered during parsing, and in case of errors the returned Grammar may be partial.
type Rule ¶
type Rule interface {
Location() location
String() string
}
Rule is the interface defining an Ungrammar CST subtree. At runtime, a value implemeting the Rule interface will have a concrete type which is one of the exported types in this file.
Source Files
Directories