Skip to content


Switch branches/tags

Latest commit

parseLitMatcher() was calling strconv.AppendQuote() each time, which my
profiler discovered was costing a measurably large amount of runtime
during parsing within dhall-golang.

This commit calculates litMatcher.want at codegen time so that we don't
have to compute the `want` value each time we parse with the litMatcher.

Git stats


Failed to load latest commit information.
Latest commit message
Commit time

pigeon - a PEG parser generator for Go

GoDoc build status GoReportCard Software License

The pigeon command generates parsers based on a parsing expression grammar (PEG). Its grammar and syntax is inspired by the PEG.js project, while the implementation is loosely based on the parsing expression grammar for C# 3.0 article. It parses Unicode text encoded in UTF-8.

See the godoc page for detailed usage. Also have a look at the Pigeon Wiki for additional information about Pigeon and PEG in general.


  • v1.0.0 is the tagged release of the original implementation.
  • Work has started on v2.0.0 with some planned breaking changes.

Github user @mna created the package in April 2015, and @breml is the package's maintainer as of May 2017.

Breaking Changes since v1.0.0

  • Removed support for Go < v1.11 to support go modules for dependency tracking.

  • Removed support for Go < v1.9 due to the requirement, which was updated to reflect changes in recent versions of Go. This is in compliance with the Go Release Policy respectively the Go Release Maintenance, which states support for each major release until there are two newer major releases.


Provided you have Go correctly installed with the $GOPATH and $GOBIN environment variables set, run:

$ go get -u

This will install or update the package, and the pigeon command will be installed in your $GOBIN directory. Neither this package nor the parsers generated by this command require any third-party dependency, unless such a dependency is used in the code blocks of the grammar.

Basic usage

$ pigeon [options] [PEG_GRAMMAR_FILE]

By default, the input grammar is read from stdin and the generated code is printed to stdout. You may save it in a file using the -o flag.


Given the following grammar:

// part of the initializer code block omitted for brevity

var ops = map[string]func(int, int) int {
    "+": func(l, r int) int {
        return l + r
    "-": func(l, r int) int {
        return l - r
    "*": func(l, r int) int {
        return l * r
    "/": func(l, r int) int {
        return l / r

func toIfaceSlice(v interface{}) []interface{} {
    if v == nil {
        return nil
    return v.([]interface{})

func eval(first, rest interface{}) int {
    l := first.(int)
    restSl := toIfaceSlice(rest)
    for _, v := range restSl {
        restExpr := toIfaceSlice(v)
        r := restExpr[3].(int)
        op := restExpr[1].(string)
        l = ops[op](l, r)
    return l

Input <- expr:Expr EOF {
    return expr, nil

Expr <- _ first:Term rest:( _ AddOp _ Term )* _ {
    return eval(first, rest), nil

Term <- first:Factor rest:( _ MulOp _ Factor )* {
    return eval(first, rest), nil

Factor <- '(' expr:Expr ')' {
    return expr, nil
} / integer:Integer {
    return integer, nil

AddOp <- ( '+' / '-' ) {
    return string(c.text), nil

MulOp <- ( '*' / '/' ) {
    return string(c.text), nil

Integer <- '-'? [0-9]+ {
    return strconv.Atoi(string(c.text))

_ "whitespace" <- [ \n\t\r]*

EOF <- !.

The generated parser can parse simple arithmetic operations, e.g.:

18 + 3 - 27 * (-18 / -3)

=> -141

More examples can be found in the examples/ subdirectory.

See the godoc page for detailed usage.


See the file.


The BSD 3-Clause license. See the LICENSE file.