chomp

README

Chomp

A parser combinator library for chomping strings (a rune at a time) in Go. A more intuitive way to parse text without having to write a single regex. Happy to chomp both ASCII and Unicode (it all tastes the same).

Inspired by nom 💜.

Design

At the heart of chomp is a combinator. A higher-order function capable of parsing text under a defined condition and returning a tuple (1,2,3):

• 1: the remaining unparsed (or unchomped) text.
• 2: the parsed (or chomped) text.
• 3: an error if the combinator failed to parse.

Here's a sneak peek at its definition:

type Result interface {
	string | []string
}

type Combinator[T Result] func(string) (string, T, error)

A combinator in its simplest form would look like this:

func Tag(str string) chomp.Combinator[string] {
	return func(s string) (string, string, error) {
		if strings.HasPrefix(s, str) {
			// Return a tuple containing:
			// 1. the remaining string after the prefix
			// 2. the matched prefix
			// 3. no error
			return s[len(str):], str, nil
		}

		return s, "", chomp.CombinatorParseError{
			Input: str,
			Text: s,
			Type: "tag",
		}
	}
}

The true power of chomp comes from the ability to build parsers by chaining (or combining) combinators together.

Writing a Parser Combinator

Take a look at one of the examples of how to write a parser combinator.

1. GPG Private Key parser

Why use Chomp?

• Combinators are very easy to write and combine into more complex parsers.
• Code written with chomp looks like natural grammar and is easy to understand, maintain and extend.
• It is incredibly easy to unit test.

Badges

Documentation

Overview

Package chomp provides a parser combinator library for chomping strings (a byte at a time) in Go. A more intuitive way to parse text without having to write a single regex

Index

• Variables
• type Combinator
  • func All[T Result](c ...Combinator[T]) Combinator[[]string]
  • func Any(str string) Combinator[string]
  • func BracketAngled() Combinator[string]
  • func BracketSquare() Combinator[string]
  • func Crlf() Combinator[string]
  • func Delimited[T, U, V Result](left Combinator[T], str Combinator[U], right Combinator[V]) Combinator[U]
  • func First[T Result](c ...Combinator[T]) Combinator[T]
  • func I(c Combinator[[]string], i int) Combinator[string]
  • func NoneOf(str string) Combinator[string]
  • func Not(str string) Combinator[string]
  • func OneOf(str string) Combinator[string]
  • func Opt[T Result](c Combinator[T]) Combinator[T]
  • func Pair[T, U Result](c1 Combinator[T], c2 Combinator[U]) Combinator[[]string]
  • func Parentheses() Combinator[string]
  • func QuoteDouble() Combinator[string]
  • func QuoteSingle() Combinator[string]
  • func Repeat[T Result](c Combinator[T], n int) Combinator[[]string]
  • func S(c Combinator[string]) Combinator[[]string]
  • func SepPair[T, U, V Result](c1 Combinator[T], sep Combinator[U], c2 Combinator[V]) Combinator[[]string]
  • func Tag(str string) Combinator[string]
  • func Until(str string) Combinator[string]
  • func While(p Predicate) Combinator[string]
  • func WhileNot(p Predicate) Combinator[string]
• type CombinatorParseError
  • func (e CombinatorParseError) Error() string
• type ParserError
  • func (e ParserError) Error() string
  • func (e ParserError) Unwrap() error
• type Predicate
• type Result

Variables

var (
	// IsDigit determines whether a rune is a decimal digit. A rune is classed
	// as a digit if it is between the ASCII range of '0' or '9', or it belongs
	// within the Unicode [Nd] category.
	//
	// [Nd]: https://www.fileformat.info/info/unicode/category/Nd/list.htm
	IsDigit = unicode.IsDigit

	// IsLetter determines whether a rune is a letter. A rune is classed as a
	// letter if it is between the ASCII range of 'a' and 'z' (including its
	// uppercase equivalents), or it belongs within any of the Unicode letter
	// categories: [Lu] [LI] [Lt] [Lm] [Lo]
	//
	// [Lu]: https://www.fileformat.info/info/unicode/category/Lu/list.htm
	// [LI]: https://www.fileformat.info/info/unicode/category/Ll/list.htm
	// [Lt]: https://www.fileformat.info/info/unicode/category/Lt/list.htm
	// [Lm]: https://www.fileformat.info/info/unicode/category/Lm/list.htm
	// [Lo]: https://www.fileformat.info/info/unicode/category/Lo/list.htm
	IsLetter = unicode.IsLetter
)

Types

type Combinator

type Combinator[T Result] func(string) (string, T, error)

Combinator is a higher-order function capable of parsing text under a defined condition. Combinators can be combined to form more complex parsers. Upon success, a combinator will return both the unparsed and parsed text. All combinators are strict and must parse its input. Any failure to do so should raise a CombinatorParseError.

func All

func All[T Result](c ...Combinator[T]) Combinator[[]string]

All will match the input text against a series of combinators. All combinators must match in the order provided.

chomp.All(
	chomp.Tag("Hello"),
	chomp.Until("W"),
	chomp.Tag("World!"))("Hello, World!")
// ("", []string{"Hello", ", ", "World!"}, nil)

func Any

func Any(str string) Combinator[string]

Any must match at least one character at the beginning of the input text, from the provided sequence. Parsing immediately stops upon the first unmatched character.

chomp.Any("eH")("Hello, World!")
// ("llo, World!", "He", nil)

func BracketAngled

func BracketAngled() Combinator[string]

BracketAngled will match any text delimited (or surrounded) by a pair of <angled brackets>. The delimiters are discarded.

chomp.BracketAngled()("<Hello, World!>")
// ("", "Hello, World!", nil)

func BracketSquare

func BracketSquare() Combinator[string]

BracketSquare will match any text delimited (or surrounded) by a pair of [square brackets]. The delimiters are discarded.

chomp.BracketSquare()("[Hello, World!]")
// ("", "Hello, World!", nil)

func Crlf

func Crlf() Combinator[string]

Crlf must match either a CR or CRLF line ending.

chomp.Crlf()("\r\nHello")
// ("Hello", "\r\n", nil)

func Delimited

func Delimited[T, U, V Result](left Combinator[T], str Combinator[U], right Combinator[V]) Combinator[U]

Delimited will match a series of combinators against the input text. The left and right combinators are used to match a delimited sequence and are discarded. Only the text between the delimiters is extracted.

chomp.Delimited(
	chomp.Tag("'"),
	chomp.Tag("Hello, World!"),
	chomp.Tag("'"))("'Hello, World!'")
// ("", "Hello, World!", nil)

func First

func First[T Result](c ...Combinator[T]) Combinator[T]

First will match the input text against a series of combinators. Matching stops as soon as the first combinator succeeds. One combinator must match. For better performance, try and order the combinators from most to least likely to match.

chomp.First(
	chomp.Tag("Good Morning"),
	chomp.Tag("Hello"))("Good Morning, World!")
// (" ,World!", "Good Morning", nil)

func I

func I(c Combinator[[]string], i int) Combinator[string]

I extracts and returns a single string from the result of the inner combinator. Combinators of differing return types can be successfully chained together while using this conversion combinator.

chomp.I(chomp.SepPair(
	chomp.Tag("Hello"),
	chomp.Tag(", "),
	chomp.Tag("World")), 1)("Hello, World!")
// ("!", "World", nil)

func NoneOf

func NoneOf(str string) Combinator[string]

NoneOf must not match a single character at the beginning of the text from the provided sequence.

chomp.NoneOf("loWrd!e")("Hello, World!")
// ("ello, World!", "H", nil)

func Not

func Not(str string) Combinator[string]

Not must not match at least one character at the beginning of the input text from the provided sequence. Parsing immediately stops upon the first matched character.

chomp.Not("ol")("Hello, World!")
// ("llo, World!", "He", nil)

func OneOf

func OneOf(str string) Combinator[string]

OneOf must match a single character at the beginning of the text from the provided sequence.

chomp.OneOf("!,eH")("Hello, World!")
// ("ello, World!", "H", nil)

func Opt

func Opt[T Result](c Combinator[T]) Combinator[T]

Opt allows a combinator to be optional. Any error returned by the underlying combinator will be swallowed. The parsed text will not be modified if the underlying combinator did not run.

chomp.Opt(chomp.Tag("Hey"))("Hello, World!")
// ("Hello, World!", "", nil)

func Pair

func Pair[T, U Result](c1 Combinator[T], c2 Combinator[U]) Combinator[[]string]

Pair will scan the input text and match each Combinator in turn. Both combinators must match. The result of each will be returned in the slice in execution order.

chomp.Pair(chomp.Tag("Hello,"), chomp.Tag(" World"))("Hello, World!")
// ("!", []string{"Hello,", " World"}, nil)

func Parentheses

func Parentheses() Combinator[string]

Parentheses will match any text delimited (or surrounded) by a pair of (parentheses). The delimiters are discarded.

chomp.Parentheses()("(Hello, World!)")
// ("", "Hello, World!", nil)

func QuoteDouble

func QuoteDouble() Combinator[string]

QuoteDouble will match any text delimited (or surrounded) by a pair of "double quotes". The delimiters are discarded.

chomp.DoubleQuote()(`"Hello, World!"`)
// ("", "Hello, World!", nil)

func QuoteSingle

func QuoteSingle() Combinator[string]

QuoteSingle will match any text delimited (or surrounded) by a pair of 'single quotes'. The delimiters are discarded.

chomp.QuoteSingle()("'Hello, World!'")
// ("", "Hello, World!", nil)

func Repeat

func Repeat[T Result](c Combinator[T], n int) Combinator[[]string]

Repeat will scan the input text and repeat the Combinator the defined number of times. Each combinator must match, with the output of each contained in the returned slice.

chomp.Repeat(chomp.Parentheses(), 2)("(Hello)(World)(!)")
// ("(!)", []string{"(Hello)", "(World)"}, nil)

func S

func S(c Combinator[string]) Combinator[[]string]

S wraps the result of the inner combinator within a string slice. Combinators of differing return types can be successfully chained together while using this conversion combinator.

chomp.S(chomp.Until(","))("Hello, World!")
// (", World!", []string{"Hello"}, nil)

func SepPair

func SepPair[T, U, V Result](c1 Combinator[T], sep Combinator[U], c2 Combinator[V]) Combinator[[]string]

SepPair will scan the input text and match each Combinator in turn. All combinators must match. The result of the separator combinator is discarded and not included within the returned slice.

chomp.SepPair(
	chomp.Tag("Hello"),
	chomp.Tag(", "),
	chomp.Tag("World"))("Hello, World!")
// ("!", []string{"Hello", "World"}, nil)

func Tag

func Tag(str string) Combinator[string]

Tag must match a series of characters at the beginning of the input text, in the exact order and case provided.

chomp.Tag("Hello")("Hello, World!")
// (", World!", "Hello", nil)

func Until

func Until(str string) Combinator[string]

Until will scan the input text for the first occurrence of the provided series of characters. Everything until that point in the text will be matched.

chomp.Until("World")("Hello, World!")
// ("World!", "Hello, ", nil)

func While

func While(p Predicate) Combinator[string]

While will scan the input text, testing each character against the provided Predicate. Everything until the predicate returns false will be matched.

chomp.While(chomp.IsLetter)("Hello, World!")
// (", World!", "Hello", nil)

func WhileNot

func WhileNot(p Predicate) Combinator[string]

WhileNot will scan the input text, testing each character against the provided Predicate. Everything until the predicate returns true will be matched. This is the inverse of While.

chomp.WhileNot(chomp.IsDigit)("Hello, World!")
// ("", "Hello, World!", nil)

type CombinatorParseError

type CombinatorParseError struct {
	// Input to the [Combinator]. This can be empty, as a combinator may
	// not require any input to parse the text.
	Input string

	// Text that was being parsed by the [Combinator]. This will be truncated
	// in the error message.
	Text string

	// Type of [Combinator] that failed.
	Type string
}

CombinatorParseError defines an error that is raised when a combinator fails to parse the input text under its expected condition.

func (CombinatorParseError) Error

func (e CombinatorParseError) Error() string

Error returns a friendly string representation of the current error.

type ParserError

type ParserError struct {
	// Err contains the [CombinatorParseError] that caused the parser to fail.
	Err error

	// Type of [Parser] that failed.
	Type string
}

ParserError defines an error that is raised when a parser fails to parse the input text due to a failed Combinator

func (ParserError) Error

func (e ParserError) Error() string

Error returns a friendly string representation of the current error.

func (ParserError) Unwrap

func (e ParserError) Unwrap() error

Unwrap returns the inner CombinatorParseError.

type Predicate

type Predicate func(rune) bool

Predicate defines an expression that will return either true or false

type Result

type Result interface {
	string | []string
}

Result is the expected output from a Combinator