Parser combinator library in Golang
A library to construct top-down recursive backtracking parsers using
parser-combinators. Before proceeding you might want to take at peep
at theory of parser combinators. As for this package, it
provides:
- A standard set of combinators.
- Regular expression based simple-scanner.
- Standard set of tokenizers based on the simple-scanner.
To construct syntax-trees based on detailed grammar try with
AST struct
- Standard set of combinators are exported as methods to AST.
- Generate dot-graph EG: dotfile
for html. - Pretty print on the console.
- Make debugging easier.
NOTE that AST object is a recent development and expect user to adapt to
newer versions
Quick links
- Go documentation.
- Using the builtin scanner.
- Simple HTML parser.
- Querying Abstract Syntax Tree
- Projects using goparsec.
- Articles.
- How to contribute.
Combinators
Every combinator should confirm to the following signature,
// ParsecNode type defines a node in the AST
type ParsecNode interface{}
// Parser function parses input text, higher order parsers are
// constructed using combinators.
type Parser func(Scanner) (ParsecNode, Scanner)
// Nodify callback function to construct custom ParsecNode.
type Nodify func([]ParsecNode) ParsecNode
Combinators take a variable number of parser functions and
return a new parser function.
Using the builtin scanner
Builtin scanner library manages the input buffer and implements a cursor
into the buffer. Create a new scanner instance,
s := parsec.NewScanner(text)
The scanner library supplies method like Match(pattern),
SkipAny(pattern) and Endof(), refer to for
more information on each of these methods.
Panics and Recovery
Panics are to be expected when APIs are misused. Programmers might choose
to ignore errors, but not panics. For example:
- Kleene and Many combinators take one or two parsers as arguments. Less than
one or more than two will throw a panic. - ManyUntil combinator take two or three parsers as arguments. Less than two
or more than three will throw a panic. - Combinators accept Parser function or pointer to Parser function. Anything
else will panic. - When using invalid regular expression to match a token.
Examples
- expr/expr.go, implements a parsec grammar to parse arithmetic expressions.
- json/json.go, implements a parsec grammar to parse JSON document.
Clone the repository run the benchmark suite
$ cd expr/
$ go test -test.bench=. -test.benchmem=true
$ cd json/
$ go test -test.bench=. -test.benchmem=true
To run the example program,
# to parse expression
$ go run tools/parsec/parsec.go -expr "10 + 29"
# to parse JSON string
$ go run tools/parsec/parsec.go -json '{ "key1" : [10, "hello", true, null, false] }'
Projects using goparsec
If your project is using goparsec you can raise an issue to list them under
this section.
Articles
- [Parsing by composing functions][article1-link]
- [Parser composition for recursive grammar][article2-link]
- [How to use the
Maybecombinator][article3-link]
How to contribute
- Pick an issue, or create an new issue. Provide adequate documentation for
the issue. - Assign the issue or get it assigned.
- Work on the code, once finished, raise a pull request.
- Goparsec is written in golang, hence expected to
follow the global guidelines for writing go programs. - If the changeset is more than few lines, please generate a
[report card][report-link]. - As of now, branch
masteris the development branch.
article1-link
article2-link
article3-link
[report-link]: https://goreportcard.com/report/github.com/prataprc/goparsec