comb

A Parser Combinator Library For Go

Comb is a library that simplifies building parsers in Go.

For me, it has got the optimal feature set:

1. Simple maintainability of a normal library thanks to being a parser combinator library.
2. Report errors with the line and column position and code snippet.
3. Reporting of multiple errors.
4. UNICODE support (working on UTF-8 encoded UNICODE code points instead of bytes if requested).
5. Support for binary input (including byte position and hex dump for errors).
6. Type safety (including filling arbitrary typed data) using generics.
7. Idiomatic Go code (no generated code, ...).
8. Good performance (for the feature set).

It's based on Gomme that showed how to get the general developer experience and type safety right.

Table of content

• A Parser Combinator Library For Go
  • Table of content
  • Getting started
  • Examples
  • Documentation
  • Installation
  • Guide
    • List of combinators
      • Base combinators
      • Bytes combinators
      • Character combinators
      • Combinators for Sequences
      • Combinators for Applying Parsers Many Times
      • Combinators for Choices
  • Frequently asked questions
    • Q: What's the name?
    • Q: What are parser combinators?
    • Q: Why would I use parser combinators instead of a specific parser?
    • Q: Where can I learn more about parser combinators?
  • Acknowledgements
  • Authors

Getting started

Here's how to quickly parse hexadecimal color codes using Gomme:

// RGBColor stores the three bytes describing a color in the RGB space.
type RGBColor struct {
    red   uint8
    green uint8
    blue  uint8
}

// ParseRGBColor creates a new RGBColor from a hexadecimal color string.
// The string must be a six-digit hexadecimal number, prefixed with a "#".
func ParseRGBColor(input string) (RGBColor, error) {
    parse := cmb.Map4(
        SaveSpot(C('#')),
        HexColorComponent("red hex color"),
        HexColorComponent("green hex color"),
        HexColorComponent("blue hex color"),
        func(_ rune, r, g, b string) (RGBColor, error) {
            return RGBColor{fromHex(r), fromHex(g), fromHex(b)}, nil
        },
    )

    return comb.RunOnString(input, parse)
}

// HexColorComponent produces a parser that parses a single hex color component,
// which is a two-digit hexadecimal number.
func HexColorComponent() comb.Parser[string] {
    return SaveSpot(cmb.SatisfyMN(expected, 2, 2, cmb.IsHexDigit))
}

// fromHex converts a two digits hexadecimal number to its decimal value.
func fromHex(input string) uint8 {
    res, _ := strconv.ParseUint(input, 16, 8) // errors have been caught by the parser
    return uint8(res)
}

It's as simple as that! Feel free to explore more in the examples directory.

Examples

See Comb in action with these handy examples:

• Parsing hexadecimal color codes
• Parsing a simple CSV file
• Parsing Redis' RESP protocol
• Parsing JSON

Documentation

For more detailed information, refer to the official documentation.

Installation

Like any other library:

go get github.com/flowdev/comb

Guide

In this guide, we provide a detailed overview of the various combinators available in Comb. Combinators are fundamental building blocks in parser construction, each designed for a specific task. By combining them, you can create complex parsers suited to your specific needs. For each combinator, we've provided a brief description and a usage example. Let's explore!

List of combinators

Base combinators

Bytes combinators

Character combinators

Combinators for Sequences

Combinators for Applying Parsers Many Times

Combinators for Choices

Frequently asked questions

Q: What's the name?

A: Comb first of all got its name from being a parser COMBinatior library. But it is also very good at "combing" through input, finding errors. Since the error handling system is by far the hardest part of the project, the name feels right.

Q: What are parser combinators?

A: Parser combinators offer a new way of building parsers. Instead of writing a complex parser that analyzes an entire format, you create small, simple parsers that handle the smallest units of the format. These small parsers can then be combined to build more complex parsers. It's a bit like using building blocks to construct whatever structure you want.

Q: Why would I use parser combinators instead of a specific parser?

A: Parser combinators are incredibly flexible and intuitive. Once you're familiar with them, they enable you to quickly create, maintain, and modify parsers. They offer you a high degree of freedom in designing your parser and how it's used.

Q: Where can I learn more about parser combinators?

A: Here are some resources we recommend:

• You could have invented parser combinators
• Functional Parsing
• Building a Mapping Language in Go with Parser Combinators

Acknowledgements

We've stood on the shoulders of giants to create Comb. The library draws heavily on the extensive theoretical work done in the parser combinators space, and we owe a huge thanks to Gomme that solved two important problems for us and gave hints for others.

Getting the error recovery mechanism right took at least 90% of the time put into the project until now.

Authors

• @ole108 (main developer behind the flowdev organization)
• @oleiade (for Gomme)