Goparsify

https://pkg.go.dev/github.com/vektah/goparsify
Admin
Goparsify is a parser-combinator library for building easy to test, read and maintain parsers using...
Tokens:12,421
Snippets:183
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Goparsify Debug Output Example

Source: https://pkg.go.dev/github.com/vektah/goparsify

This is an example of the detailed output generated when running tests with debug logging enabled. It shows the parser's step-by-step progress, including tokens found and expected.

```text
adam:goparsify(master)$ go test -tags debug ./html -v
=== RUN   TestParse
hTtml.go:48 | <body>hello <p  | tag {
hTtml.go:43 | <body>hello <p  |   tstart {
hTtml.go:43 | body>hello <p c |     < found <
hTtml.go:20 | >hello <p color |     identifier found body
hTtml.go:33 | >hello <p color |     attrs {
hTtml.go:32 | >hello <p color |       attr {
hTtml.go:20 | >hello <p color |         identifier did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:32 | >hello <p color |       } did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:33 | >hello <p color |     } found
hTtml.go:43 | hello <p color= |     > found >
hTtml.go:43 | hello <p color= |   } found [<,body,,map[string]string{},>]
hTtml.go:24 | hello <p color= |   elements {
hTtml.go:23 | hello <p color= |     element {
hTtml.go:21 | <p color="blue" |       text found hello
hTtml.go:23 | <p color="blue" |     } found "hello "
hTtml.go:23 | <p color="blue" |     element {
hTtml.go:21 | <p color="blue" |       text did not find <>
hTtml.go:48 | <p color="blue" |       tag {
hTtml.go:43 | <p color="blue" |         tstart {
hTtml.go:43 | p color="blue"> |           < found <
hTtml.go:20 |  color="blue">w |           identifier found p
hTtml.go:33 |  color="blue">w |           attrs {
hTtml.go:32 |  color="blue">w |             attr {
hTtml.go:20 | ="blue">world</ |               identifier found color
hTtml.go:32 | "blue">world</p |               = found =
hTtml.go:32 | >world</p></bod |               string literal found "blue"
hTtml.go:32 | >world</p></bod |             } found [color,=,"blue"]
hTtml.go:32 | >world</p></bod |             attr {
hTtml.go:20 | >world</p></bod |               identifier did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:32 | >world</p></bod |             } did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:33 | >world</p></bod |           } found [[color,=,"blue"]]
hTtml.go:43 | world</p></body |           > found >
hTtml.go:43 | world</p></body |         } found [<,p,,map[string]string{"color":"blue"},>]
hTtml.go:24 | world</p></body |         elements {
hTtml.go:23 | world</p></body |           element {
hTtml.go:21 | </p></body>     |             text found world
hTtml.go:23 | </p></body>     |           } found "world"
hTtml.go:23 | </p></body>     |           element {
hTtml.go:21 | </p></body>     |             text did not find <>
hTtml.go:48 | </p></body>     |             tag {
hTtml.go:43 | </p></body>     |               tstart {
hTtml.go:43 | /p></body>      |                 < found <
hTtml.go:20 | /p></body>      |                 identifier did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:43 | </p></body>     |               } did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:48 | </p></body>     |             } did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:21 | </p></body>     |             text did not find <>
hTtml.go:23 | </p></body>     |           } did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:24 | </p></body>     |         } found ["world"]
hTtml.go:44 | </p></body>     |         tend {
hTtml.go:44 | p></body>       |           </ found </
hTtml.go:20 | ></body>        |           identifier found p
hTtml.go:44 | </body>         |           > found >
hTtml.go:44 | </body>         |         } found [</,,p,>]
hTtml.go:48 | </body>         |       } found "hello "
hTtml.go:23 | </body>         |     } found html.htmlTag{Name:"p", Attributes:map[string]string{"color":"blue"}, Body:[]interface {}{"world"}}
hTtml.go:23 | </body>         |     element {
hTtml.go:48 | </body>         |       tag {
hTtml.go:43 | </body>         |         tstart {
hTtml.go:43 | /body>          |           < found <
hTtml.go:20 | /body>          |           identifier did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:43 | </body>         |         } did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:48 | </body>         |       } did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:21 | </body>         |       text did not find <>
hTtml.go:23 | </body>         |     } did not find [a-zA-Z][a-zA-Z0-9]*
hTtml.go:24 | </body>         |   } found ["hello ",html.htmlTag{Name:"p", Attributes:map[string]string{"color":"blue"}, Body:[]interface {}{"world"}}]
hTtml.go:44 | </body>         |   tend {
hTtml.go:44 | body>           |     </ found </
hTtml.go:20 | >               |     identifier found body
hTtml.go:44 |                 |     > found >
hTtml.go:44 |                 |   } found [</,,body,>]
hTtml.go:48 |                 | } found [[<,body,,map[string]string{},>],,[]interface {}{"hello ", html.htmlTag{Name:"p", Attributes:map[string]string{"color":"blue"}, Body:[]interface {}{"world"}}},[</,,body,>]]
--- PASS: TestParse (0.00s)
PASS
ok      github.com/vektah/goparsify/html        0.117s
```

--------------------------------

### Recursive Grammar Example without Parserish

Source: https://pkg.go.dev/github.com/vektah/goparsify

Illustrates defining a recursive grammar for balanced parentheses without using the Parserish interface, showing a more verbose approach with explicit pointer usage.

```go
var group ParserPtr{}
group.P = Seq(Exact("("), Maybe(group.Parse), Exact(")"))
```

--------------------------------

### Recursive Grammar Example with Parserish

Source: https://pkg.go.dev/github.com/vektah/goparsify

Demonstrates defining a recursive grammar for matching balanced parentheses using the Parserish interface and Seq combinator. This approach is cleaner for recursive structures.

```go
var group Parser
group = Seq("(", Maybe(&group), ")")
```

--------------------------------

### Get Current Input String

Source: https://pkg.go.dev/github.com/vektah/goparsify

Gets the remaining input string from the current state.

```go
Get() string
```

--------------------------------

### State.Preview

Source: https://pkg.go.dev/github.com/vektah/goparsify

Returns a preview of the input string starting from the current position, up to a specified number of characters.

```APIDOC
## State.Preview

### Description
Preview of the the next x characters.

### Method
func (s *State) Preview(x int) string

### Parameters
#### Path Parameters
- **x** (int) - Required - The number of characters to preview.
```

--------------------------------

### Prevent Backtracking with Cuts in Parsers

Source: https://pkg.go.dev/github.com/vektah/goparsify

Demonstrates how to use `Cut()` to prevent backtracking in parsers, leading to improved error messages. The first example shows the default behavior without a cut, while the second shows the improved error reporting with `Cut()`.

```go
alpha := Chars("a-z")

// without a cut if the close tag is left out the parser will backtrack and ignore the rest of the string
nocut := Many(Any(Seq("<", alpha, ">"), alpha))
_, err := Run(nocut, "asdf <foo")
fmt.Println(err.Error())
// Outputs: left unparsed: <foo

// with a cut, once we see the open tag we know there must be a close tag that matches it, so the parser will error
cut := Many(Any(Seq("<", Cut(), alpha, ">"), alpha))
_, err = Run(cut, "asdf <foo")
fmt.Println(err.Error())
// Outputs: offset 9: expected >
```

--------------------------------

### Get Remaining Input

Source: https://pkg.go.dev/github.com/vektah/goparsify

Get returns the portion of the input string that has not yet been parsed.

```go
func (s *State) Get() string
```

--------------------------------

### Get Error Position

Source: https://pkg.go.dev/github.com/vektah/goparsify

Returns the offset into the document where the error was found.

```go
func (e *Error) Pos() int
```

--------------------------------

### Preview Input String

Source: https://pkg.go.dev/github.com/vektah/goparsify

Previews a specified number of characters from the current state without advancing.

```go
Preview(x int) string
```

--------------------------------

### Combine Parsers with Any

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches any of the provided parsers.

```go
func Any(parsers ...Parserish) Parser
```

--------------------------------

### Match Exact String

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches an exact string.

```go
func Exact(match string) Parser
```

--------------------------------

### Initialize Parser State

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a new parser state from input string.

```go
NewState(input string) *State
```

--------------------------------

### Preview Input Characters

Source: https://pkg.go.dev/github.com/vektah/goparsify

Preview returns a string containing the next x characters of the input without consuming them.

```go
func (s *State) Preview(x int) string
```

--------------------------------

### Create a Parser that Matches Any of Several Parsers

Source: https://pkg.go.dev/github.com/vektah/goparsify

The Any function creates a parser that successfully matches the first parser in the provided list that succeeds. It returns the result of the first successful match.

```go
func Any(parsers ...Parserish) Parser

```

--------------------------------

### Create Named Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a new parser with a description.

```go
func NewParser(description string, p Parser) Parser
```

--------------------------------

### Any

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches the first successful parser from a list of parsers.

```APIDOC
## func Any

```go
func Any(parsers ...Parserish) Parser
```

Any matches the first successful parser and returns its result
```

--------------------------------

### Optional Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that optionally matches another parser.

```go
func Maybe(parser Parserish) Parser
```

--------------------------------

### Parsify All Inputs

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates parsers for all provided inputs.

```go
func ParsifyAll(parsers ...Parserish) []Parser
```

--------------------------------

### Match Sequence of Parsers

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches a sequence of other parsers.

```go
func Seq(parsers ...Parserish) Parser
```

--------------------------------

### Enable Goparsify Debug Logging

Source: https://pkg.go.dev/github.com/vektah/goparsify

To enable detailed logging for parser debugging, build your Go project with the `-tags debug` flag and then call `EnableLogging(os.Stdout)` in your code. This directs parser logs to standard output.

```bash
go test -tags debug ./html -v
```

```go
EnableLogging(os.Stdout)
```

--------------------------------

### Enable Logging

Source: https://pkg.go.dev/github.com/vektah/goparsify

Enables writing logs to a specified io.Writer during the next parse operation.

```go
func EnableLogging(w io.Writer)
```

--------------------------------

### Create Cut Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that acts as a cut, preventing backtracking.

```go
func Cut() Parser
```

--------------------------------

### Match Regular Expression

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches a regular expression pattern.

```go
func Regex(pattern string) Parser
```

--------------------------------

### Match String Literal

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches a string literal, supporting specified quote characters.

```go
func StringLit(allowedQuotes string) Parser
```

--------------------------------

### Create New State

Source: https://pkg.go.dev/github.com/vektah/goparsify

NewState initializes and returns a new State object from a given input string.

```go
func NewState(input string) *State
```

--------------------------------

### Match Character Sequences

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches a sequence of characters, optionally with repetition.

```go
func Chars(matcher string, repetition ...int) Parser
```

--------------------------------

### Instrument Parsers for Debugging

Source: https://pkg.go.dev/github.com/vektah/goparsify

NewParser should wrap the creation of every parser. While it has no runtime cost normally, it enables detailed timing information collection when compiled with the 'debug' tag, viewable with DumpDebugStats.

```go
func NewParser(description string, p Parser) Parser

```

--------------------------------

### GoParsify: Breaking Typechecking Loops

Source: https://pkg.go.dev/github.com/vektah/goparsify

Demonstrates how to break a typechecking loop in GoParsify using a pointer for a parser definition. The parser's value is set in an init function.

```go
var (
    value Parser
    prod = Seq(&value, Some(And(prodOp, &value)))
)

func init() {
	value = Any(number, groupExpr)
}

```

--------------------------------

### Run

Source: https://pkg.go.dev/github.com/vektah/goparsify

Applies input to a parser and returns the result, failing if the input isn't fully consumed. It is a convenience method for the most common way to invoke a parser.

```APIDOC
## Run

### Description
Applies input to a parser and returns the result, failing if the input isn't fully consumed. It is a convenience method for the most common way to invoke a parser.

### Function Signature
```go
func Run(parser Parserish, input string, ws ...VoidParser) (result interface{}, err error)
```
```

--------------------------------

### Run Parser with ASCII Whitespace

Source: https://pkg.go.dev/github.com/vektah/goparsify

This function is used to execute a parser with a given input and ASCII whitespace handling. It's a core function for applying parsers in the library.

```go
Run(parser, input, ASCIIWhitespace)

```

--------------------------------

### Match Some Repeated Sequences

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches a parser one or more times, optionally with a separator.

```go
func Some(parser Parserish, separator ...Parserish) Parser
```

--------------------------------

### NewParser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Wraps a parser for potential debugging instrumentation. Incurs no runtime overhead normally.

```APIDOC
## func NewParser

```go
func NewParser(description string, p Parser) Parser
```

NewParser should be called around the creation of every Parser. It does nothing normally and should incur no runtime overhead, but when building with -tags debug it will instrument every parser to collect valuable timing information displayable with DumpDebugStats.
```

--------------------------------

### Match Repeated Sequences

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches a parser zero or more times, optionally with a separator.

```go
func Many(parser Parserish, separator ...Parserish) Parser
```

--------------------------------

### Exact

Source: https://pkg.go.dev/github.com/vektah/goparsify

Fully matches the exact string supplied, or errors. The match is stored in .Token.

```APIDOC
## func Exact

```go
func Exact(match string) Parser
```

Exact will fully match the exact string supplied, or error. The match will be stored in .Token
```

--------------------------------

### Match Sequence of Parsers

Source: https://pkg.go.dev/github.com/vektah/goparsify

Seq matches all provided parsers in the specified order. The results of each parser are stored in the .Child slice.

```go
func Seq(parsers ...Parserish) Parser

```

--------------------------------

### Match Exact String

Source: https://pkg.go.dev/github.com/vektah/goparsify

Exact matches the supplied string precisely. If the string is found, it's stored in the .Token field; otherwise, it returns an error.

```go
func Exact(match string) Parser

```

--------------------------------

### Match Regular Expressions

Source: https://pkg.go.dev/github.com/vektah/goparsify

Regex returns a parser that successfully matches if the provided regular expression pattern matches the input.

```go
func Regex(pattern string) Parser

```

--------------------------------

### Run Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Applies a parser to an input string, returning the result or an error if the input is not fully consumed. This is a convenience method for common parser invocation.

```go
func Run(parser Parserish, input string, ws ...VoidParser) (result interface{}, err error)
```

--------------------------------

### Match Number Literal

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches a number literal.

```go
func NumberLit() Parser
```

--------------------------------

### Match Zero or One Occurrence of a Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Maybe creates a parser that attempts to match the given parser, but it will succeed even if the parser fails (matching zero times). It matches at most one occurrence.

```go
func Maybe(parser Parserish) Parser

```

--------------------------------

### Dump Debug Statistics

Source: https://pkg.go.dev/github.com/vektah/goparsify

Prints current parser timings if the library was built with the 'debug' tag.

```go
func DumpDebugStats()
```

--------------------------------

### Maybe

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches zero or one instance of the given parser.

```APIDOC
## func Maybe

```go
func Maybe(parser Parserish) Parser
```

Maybe will 0 or 1 of the parser
```

--------------------------------

### goparsify JSON Benchmark Results

Source: https://pkg.go.dev/github.com/vektah/goparsify

Benchmark results comparing goparsify's JSON unmarshalling performance against other libraries like Parsec and the standard library. Shows operations per second, bytes allocated, and allocations per operation.

```text
$ go test -benchmem -bench=. ./json
BenchmarkUnmarshalParsec-8         20000             74880 ns/op           50846 B/op       1318 allocs/op
BenchmarkUnmarshalParsify-8        30000             50631 ns/op           45055 B/op        233 allocs/op
BenchmarkUnmarshalStdlib-8         30000             46989 ns/op           14210 B/op        260 allocs/op
PASS
ok      github.com/vektah/goparsify/json        6.124s

```

--------------------------------

### Parsify Input

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that converts input into a specific format.

```go
func Parsify(p Parserish) Parser
```

--------------------------------

### ASCII Whitespace Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches standard whitespace characters. Faster than UnicodeWhitespace as it avoids rune decoding.

```go
func ASCIIWhitespace(s *State)
```

--------------------------------

### NewState

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a new State object initialized with the provided input string. The State tracks the current position and other parsing context.

```APIDOC
## NewState

### Description
Creates a new State from a string.

### Method
func NewState(input string) *State

### Parameters
#### Path Parameters
- **input** (string) - Required - The input string to parse.
```

--------------------------------

### Bind

Source: https://pkg.go.dev/github.com/vektah/goparsify

Sets the node's Result when the given parser matches. Useful for keywords and constant literals.

```APIDOC
## func Bind

```go
func Bind(parser Parserish, val interface{}) Parser
```

Bind will set the node .Result when the given parser matches This is useful for giving a value to keywords and constant literals like true and false. See the json parser for an example.
```

--------------------------------

### Regex

Source: https://pkg.go.dev/github.com/vektah/goparsify

Returns a match if the regular expression successfully matches the input.

```APIDOC
## func Regex

```go
func Regex(pattern string) Parser
```

Regex returns a match if the regex successfully matches
```

--------------------------------

### Many

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches zero or more parsers, optionally with a separator. The separator is consumed but not returned.

```APIDOC
## func Many

```go
func Many(parser Parserish, separator ...Parserish) Parser
```

Many matches zero or more parsers and returns the value as .Child[n] an optional separator can be provided and that value will be consumed but not returned. Only one separator can be provided.
```

--------------------------------

### Parser Combinators

Source: https://pkg.go.dev/github.com/vektah/goparsify

Provides various parser combinators to build complex parsers from simpler ones.

```APIDOC
## Parser Combinators

### Any()
Creates a parser that matches any of the provided parsers.
```go
func Any(parsers ...Parserish) Parser
```

### Bind()
Binds a parser to a specific value.
```go
func Bind(parser Parserish, val interface{}) Parser
```

### Chars()
Creates a parser that matches a set of characters, optionally with repetition.
```go
func Chars(matcher string, repetition ...int) Parser
```

### Exact()
Creates a parser that matches an exact string.
```go
func Exact(match string) Parser
```

### Many()
Creates a parser that matches a parser zero or more times, optionally with a separator.
```go
func Many(parser Parserish, separator ...Parserish) Parser
```

### Map()
Applies a function to the result of a parser.
```go
func Map(parser Parserish, f func(n *Result)) Parser
```

### Maybe()
Creates a parser that optionally matches a parser.
```go
func Maybe(parser Parserish) Parser
```

### Merge()
Merges the results of a parser.
```go
func Merge(parser Parserish) Parser
```

### NewParser()
Creates a new parser with a description.
```go
func NewParser(description string, p Parser) Parser
```

### NoAutoWS()
Disables automatic whitespace matching for a parser.
```go
func NoAutoWS(parser Parserish) Parser
```

### NotChars()
Creates a parser that matches characters not in the given set, optionally with repetition.
```go
func NotChars(matcher string, repetition ...int) Parser
```

### NumberLit()
Creates a parser for number literals.
```go
func NumberLit() Parser
```

### Parsify()
Parsifies a parser.
```go
func Parsify(p Parserish) Parser
```

### ParsifyAll()
Parsifies multiple parsers.
```go
func ParsifyAll(parsers ...Parserish) []Parser
```

### Regex()
Creates a parser from a regular expression.
```go
func Regex(pattern string) Parser
```

### Seq()
Creates a parser that matches a sequence of parsers.
```go
func Seq(parsers ...Parserish) Parser
```

### Some()
Creates a parser that matches a parser one or more times, optionally with a separator.
```go
func Some(parser Parserish, separator ...Parserish) Parser
```

### StringLit()
Creates a parser for string literals with specified allowed quotes.
```go
func StringLit(allowedQuotes string) Parser
```

### Until()
Creates a parser that matches until a terminator is found.
```go
func Until(terminators ...string) Parser
```
```

--------------------------------

### State.Get

Source: https://pkg.go.dev/github.com/vektah/goparsify

Retrieves the remaining portion of the input string that has not yet been parsed.

```APIDOC
## State.Get

### Description
Get the remaining input.

### Method
func (s *State) Get() string
```

--------------------------------

### Match Non-Character Sequences

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches sequences of characters NOT in the specified set, optionally with repetition.

```go
func NotChars(matcher string, repetition ...int) Parser
```

--------------------------------

### Shorthand for Mapping a Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

This is a shorthand method for the Map function, applied directly to a Parser instance. It simplifies applying a callback function to a parser's result.

```go
func (p Parser) Map(f func(n *Result)) Parser

```

--------------------------------

### Some

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches one or more parsers, optionally with a separator. The separator is consumed but not returned.

```APIDOC
## func Some

```go
func Some(parser Parserish, separator ...Parserish) Parser
```

Some matches one or more parsers and returns the value as .Child[n] an optional separator can be provided and that value will be consumed but not returned. Only one separator can be provided.
```

--------------------------------

### Convert Multiple Parserish to Parsers

Source: https://pkg.go.dev/github.com/vektah/goparsify

ParsifyAll calls Parsify on a slice of Parserish arguments, returning a slice of Parsers. This is a convenience function for batch conversion.

```go
func ParsifyAll(parsers ...Parserish) []Parser

```

--------------------------------

### Merge Parser Results

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that merges the results of another parser.

```go
func Merge(parser Parserish) Parser
```

--------------------------------

### GoParsify Calculator: Number Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Defines a parser for number literals and maps the results to float64. This is used as a base for more complex expressions in the calculator.

```go
var number = NumberLit().Map(func(n Result) Result {
    switch i := n.Result.(type) {
    case int64:
        return Result{Result: float64(i)}
    case float64:
        return Result{Result: i}
    default:
        panic(fmt.Errorf("unknown value %#v", i))
    }
})

func Calc(input string) (float64, error) {
	result, err := Run(y, input)
	if err != nil {
		return 0, err
	}

	return result.(float64), nil
}

```

--------------------------------

### GoParsify Calculator: Addition Operator

Source: https://pkg.go.dev/github.com/vektah/goparsify

Defines a parser for addition and subtraction operators and maps them to calculate the sum of numbers. It demonstrates accessing parsed results via the Child map.

```go
func TestAddition(t *testing.T) {
	result, err := Calc(`1+1`)
	require.NoError(t, err)
	require.EqualValues(t, 2, result)
}


var sumOp  = Chars("+-", 1, 1)

sum = Seq(number, Some(And(sumOp, number))).Map(func(n Result) Result {
    i := n.Child[0].Result.(float64)

    for _, op := range n.Child[1].Child {
        switch op.Child[0].Token {
        case "+":
            i += op.Child[1].Result.(float64)
        case "-":
            i -= op.Child[1].Result.(float64)
        }
    }

    return Result{Result: i}
})

// and update Calc to point to the new root parser -> `result, err := ParseString(sum, input)`

```

--------------------------------

### Unicode Whitespace Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches any Unicode space character. Slightly slower than ASCIIWhitespace due to rune-by-rune matching.

```go
func UnicodeWhitespace(s *State)
```

--------------------------------

### Seq

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches all of the given parsers in order and returns their results as .Child[n].

```APIDOC
## func Seq

```go
func Seq(parsers ...Parserish) Parser
```

Seq matches all of the given parsers in order and returns their result as .Child[n]
```

--------------------------------

### Bind Parser Result

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that binds the result of another parser to a specific value.

```go
func Bind(parser Parserish, val interface{}) Parser
```

--------------------------------

### Until

Source: https://pkg.go.dev/github.com/vektah/goparsify

Consumes all input until one of the given terminator sequences is found.

```APIDOC
## func Until

```go
func Until(terminators ...string) Parser
```

Until will consume all input until one of the given terminator sequences is found. If you want to stop when seeing single characters see NotChars instead
```

--------------------------------

### Match Until Terminators

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that matches characters until one of the specified terminators is encountered.

```go
func Until(terminators ...string) Parser
```

--------------------------------

### GoParsify Performance Debugging

Source: https://pkg.go.dev/github.com/vektah/goparsify

When built with the 'debug' tag, GoParsify instruments parsers. Call DumpDebugStats() to view performance statistics, which are free when the debug tag is not used.

```go
var name | matches | total time | self time | calls | errors | location  
---|---|---|---|---|---|---
_value | Any() | 5.0685431s | 34.0131ms | 878801 | 0 | json.go:36  
_object | Seq() | 3.7513821s | 10.5038ms | 161616 | 40403 | json.go:24  
_properties | Some() | 3.6863512s | 5.5028ms | 121213 | 0 | json.go:14  
_properties | Seq() | 3.4912614s | 46.0229ms | 818185 | 0 | json.go:14  
_array | Seq() | 931.4679ms | 3.5014ms | 65660 | 55558 | json.go:16  
_array | Some() | 911.4597ms | 0s | 10102 | 0 | json.go:16  
_properties | string literal | 126.0662ms | 44.5201ms | 818185 | 0 | json.go:14  
_string | string literal | 67.033ms | 26.0126ms | 671723 | 136369 | json.go:12  
_properties | : | 50.0238ms | 45.0205ms | 818185 | 0 | json.go:14  
_properties | , | 48.5189ms | 36.0146ms | 818185 | 121213 | json.go:14  
_number | number literal | 28.5159ms | 10.5062ms | 287886 | 106066 | json.go:13  
_true | true | 17.5086ms | 12.5069ms | 252537 | 232332 | json.go:10  
_null | null | 14.5082ms | 11.007ms | 252538 | 252535 | json.go:9  
_object | } | 10.5051ms | 10.5033ms | 121213 | 0 | json.go:24  
_false | false | 10.5049ms | 5.0019ms | 232333 | 222229 | json.go:11  
_object | { | 10.0046ms | 5.0052ms | 161616 | 40403 | json.go:24  
_array | , | 4.5024ms | 4.0018ms | 50509 | 10102 | json.go:16  
_array | [ | 4.5014ms | 2.0006ms | 65660 | 55558 | json.go:16  
_array | ] | 0s | 0s | 10102 | 0 | json.go:16  
```

--------------------------------

### Logging Functions

Source: https://pkg.go.dev/github.com/vektah/goparsify

Functions for controlling and inspecting parser logging.

```APIDOC
## Logging Functions

### EnableLogging()
Enables logging and writes logs to the given writer as the next parse happens.
```go
func EnableLogging(w io.Writer)
```

### DisableLogging()
Disables logging.
```go
func DisableLogging()
```

### DumpDebugStats()
Prints out the current timings for each parser if built with -tags debug.
```go
func DumpDebugStats()
```
```

--------------------------------

### Parsify

Source: https://pkg.go.dev/github.com/vektah/goparsify

Converts a Parserish into a Parser. Should be called during parser creation, not during parsing.

```APIDOC
## func Parsify

```go
func Parsify(p Parserish) Parser
```

Parsify takes a Parserish and makes a Parser out of it. It should be called by any Parser that accepts a Parser as an argument. It should never be called during instead call it during parser creation so there is no runtime cost.
See Parserish for details.
```

--------------------------------

### Define State Struct

Source: https://pkg.go.dev/github.com/vektah/goparsify

The State struct manages the current parsing state, including the input string, current position, cut-off point for backtracking, error handling, and whitespace skipping.

```go
type State struct {
	// The full input string
	Input string
	// An offset into the string, pointing to the current tip
	Pos int
	// Do not backtrack past this point
	Cut int
	// Error is a secondary return channel from parsers, but used so heavily
	// in backtracking that it has been inlined to avoid allocations.
	Error Error
	// Called to determine what to ignore when WS is called, or when WS fires
	WS VoidParser
}
```

--------------------------------

### NoAutoWS

Source: https://pkg.go.dev/github.com/vektah/goparsify

Disables automatic whitespace ignoring for all parsers underneath.

```APIDOC
## func NoAutoWS

```go
func NoAutoWS(parser Parserish) Parser
```

NoAutoWS disables automatically ignoring whitespace between tokens for all parsers underneath
```

--------------------------------

### String Representation of Result

Source: https://pkg.go.dev/github.com/vektah/goparsify

Returns the string representation of a parse result.

```go
func (r Result) String() string
```

--------------------------------

### ParsifyAll

Source: https://pkg.go.dev/github.com/vektah/goparsify

Calls Parsify on all provided parsers.

```APIDOC
## func ParsifyAll

```go
func ParsifyAll(parsers ...Parserish) []Parser
```

ParsifyAll calls Parsify on all parsers
```

--------------------------------

### Match Zero or More Parsers with Optional Separator

Source: https://pkg.go.dev/github.com/vektah/goparsify

Many matches zero or more occurrences of a parser. It can optionally consume a separator between matches, but the separator's value is not returned. Only one separator is supported.

```go
func Many(parser Parserish, separator ...Parserish) Parser

```

--------------------------------

### Apply a Callback to a Parser's Result

Source: https://pkg.go.dev/github.com/vektah/goparsify

Map creates a parser that applies a given callback function to the result if the underlying parser matches. This is useful for transforming or setting the Result based on the matched content.

```go
func Map(parser Parserish, f func(n *Result)) Parser

```

--------------------------------

### Map

Source: https://pkg.go.dev/github.com/vektah/goparsify

Applies a callback function if the parser matches, used to set the Result based on the matched result.

```APIDOC
## func Map

```go
func Map(parser Parserish, f func(n *Result)) Parser
```

Map applies the callback if the parser matches. This is used to set the Result based on the matched result.
```

--------------------------------

### Chars

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches characters based on ranges, alphabets, and repetition counts.

```APIDOC
## func Chars

```go
func Chars(matcher string, repetition ...int) Parser
```

Chars is the swiss army knife of character matches. It can match: 
  * ranges: Chars("a-z") will match one or more lowercase letter
  * alphabets: Chars("abcd") will match one or more of the letters abcd in any order
  * min and max: Chars("a-z0-9", 4, 6) will match 4-6 lowercase alphanumeric characters

the above can be combined in any order
```

--------------------------------

### State.Advance

Source: https://pkg.go.dev/github.com/vektah/goparsify

Advances the current parsing position (Pos) in the State by a specified number of bytes.

```APIDOC
## State.Advance

### Description
Advance the Pos along by i bytes.

### Method
func (s *State) Advance(i int)

### Parameters
#### Path Parameters
- **i** (int) - Required - The number of bytes to advance the position by.
```

--------------------------------

### Match One or More Parsers with Optional Separator

Source: https://pkg.go.dev/github.com/vektah/goparsify

Some matches one or more occurrences of a parser. It can optionally consume a separator between matches, but the separator's value is not returned. Only one separator is supported.

```go
func Some(parser Parserish, separator ...Parserish) Parser

```

--------------------------------

### GetDefinition Function Signature

Source: https://pkg.go.dev/github.com/vektah/goparsify/debug

This function returns the name and location of the variable by walking up the stack. It is useful for debugging and understanding variable scope.

```go
func GetDefinition() (varName string, location string)
```

--------------------------------

### State

Source: https://pkg.go.dev/github.com/vektah/goparsify

Represents the current state of the parser, including the input string and current position.

```APIDOC
## State Type

### Description
Represents the current state of the parser, including the input string and current position.

### Methods
#### NewState()
Creates a new parser state.
```go
func NewState(input string) *State
```

#### Advance()
Advances the parser state by a specified number of characters.
```go
func (s *State) Advance(i int)
```

#### ErrorHere()
Records an error at the current position.
```go
func (s *State) ErrorHere(expected string)
```

#### Errored()
Checks if the parser has encountered an error.
```go
func (s *State) Errored() bool
```

#### Get()
Gets the remaining input string from the current position.
```go
func (s *State) Get() string
```

#### Preview()
Previews a specified number of characters from the current position without advancing.
```go
func (s *State) Preview(x int) string
```

#### Recover()
Recovers the parser state, typically used after an error.
```go
func (s *State) Recover()
```
```

--------------------------------

### NotChars

Source: https://pkg.go.dev/github.com/vektah/goparsify

Accepts input until any character in the matcher is found. Stops matching when a character matches.

```APIDOC
## func NotChars

```go
func NotChars(matcher string, repetition ...int) Parser
```

NotChars accepts the full range of input from Chars, but it will stop when any character matches. If you need to match until you see a sequence use Until instead
```

--------------------------------

### Map Parser Result

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that applies a function to the result of another parser.

```go
func Map(parser Parserish, f func(n *Result)) Parser
```

--------------------------------

### Recover from Error

Source: https://pkg.go.dev/github.com/vektah/goparsify

Recover resets the error state, allowing parsing to continue. This is often used by combinators that can succeed if any of their sub-parsers succeed.

```go
func (s *State) Recover()
```

--------------------------------

### Map Parser Result (Method)

Source: https://pkg.go.dev/github.com/vektah/goparsify

Applies a function to the result of a parser using a method.

```go
func (p Parser) Map(f func(n *Result)) Parser
```

--------------------------------

### Convert Parserish to Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Parsify converts a Parserish into a Parser. It should be called when creating parsers that accept other parsers as arguments, ensuring no runtime cost.

```go
func Parsify(p Parserish) Parser

```

--------------------------------

### Whitespace Parsers

Source: https://pkg.go.dev/github.com/vektah/goparsify

Parsers for handling whitespace characters.

```APIDOC
## Whitespace Parsers

### ASCIIWhitespace()
Matches any of the standard ASCII whitespace characters. It is faster than UnicodeWhitespace as it does not need to decode unicode runes.
```go
func ASCIIWhitespace(s *State)
```

### UnicodeWhitespace()
Matches any unicode space character. It's a little slower than the ASCII parser because it matches a rune at a time.
```go
func UnicodeWhitespace(s *State)
```

### NoWhitespace()
Disables automatic whitespace matching.
```go
func NoWhitespace(s *State)
```
```

--------------------------------

### Consume Input Until Terminators

Source: https://pkg.go.dev/github.com/vektah/goparsify

Until consumes all input until one of the specified terminator strings is found. If you need to stop at single characters, consider using NotChars.

```go
func Until(terminators ...string) Parser

```

--------------------------------

### Bind a Value to a Parser's Result

Source: https://pkg.go.dev/github.com/vektah/goparsify

The Bind function creates a parser that sets the node's Result to a specific value if the given parser matches. This is useful for assigning values to keywords or literals.

```go
func Bind(parser Parserish, val interface{}) Parser

```

--------------------------------

### StringLit

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches a quoted string, supporting unicode, escaped characters, and unicode sequences. Returns the string in .Token.

```APIDOC
## func StringLit

```go
func StringLit(allowedQuotes string) Parser
```

StringLit matches a quoted string and returns it in .Token. It may contain: 
  * unicode
  * escaped characters, eg \" or \n
  * unicode sequences, eg \uBEEF
```

--------------------------------

### Parser.Map

Source: https://pkg.go.dev/github.com/vektah/goparsify

Shorthand for applying a map function to a parser.

```APIDOC
## func (Parser) Map

```go
func (p Parser) Map(f func(n *Result)) Parser
```

Map shorthand for Map(p, func())
```

--------------------------------

### Advance State Position

Source: https://pkg.go.dev/github.com/vektah/goparsify

Advance moves the current position (Pos) in the State forward by a specified number of bytes.

```go
func (s *State) Advance(i int)
```

--------------------------------

### Cut

Source: https://pkg.go.dev/github.com/vektah/goparsify

A cut is a marker that prevents backtracking past the point it was set. This greatly improves error messages when used correctly.

```APIDOC
## Cut

### Description
A cut is a marker that prevents backtracking past the point it was set. This greatly improves error messages when used correctly.

### Function Signature
```go
func Cut() Parser
```

### Example Usage
```go
// without a cut if the close tag is left out the parser will backtrack and ignore the rest of the string
nocut := Many(Any(Seq("<", alpha, ">"), alpha))
_, err := Run(nocut, "asdf <foo")
fmt.Println(err.Error())
// Outputs: left unparsed: <foo

// with a cut, once we see the open tag we know there must be a close tag that matches it, so the parser will error
cut := Many(Any(Seq("<", Cut(), alpha, ">"), alpha))
_, err = Run(cut, "asdf <foo")
fmt.Println(err.Error())
// Outputs: offset 9: expected >
```
```

--------------------------------

### TrashResult Variable

Source: https://pkg.go.dev/github.com/vektah/goparsify

A placeholder result used when the actual result is not needed but an interface value must be provided.

```go
var TrashResult = &Result{}
```

--------------------------------

### Disable Logging

Source: https://pkg.go.dev/github.com/vektah/goparsify

Stops writing logs during parsing operations.

```go
func DisableLogging()
```

--------------------------------

### Advance Parser State

Source: https://pkg.go.dev/github.com/vektah/goparsify

Advances the parser state by a specified number of characters.

```go
Advance(i int)
```

--------------------------------

### Error Interface Implementation

Source: https://pkg.go.dev/github.com/vektah/goparsify

Satisfies the golang error interface for parse errors.

```go
func (e *Error) Error() string
```

--------------------------------

### NumberLit

Source: https://pkg.go.dev/github.com/vektah/goparsify

Matches a floating point or integer number and returns it as an int64 or float64 in .Result.

```APIDOC
## func NumberLit

```go
func NumberLit() Parser
```

NumberLit matches a floating point or integer number and returns it as a int64 or float64 in .Result
```

--------------------------------

### Match Input Until Specific Terminators

Source: https://pkg.go.dev/github.com/vektah/goparsify

NotChars matches characters similar to Chars but stops when any of the specified characters are encountered. It's useful for matching content up to a certain point, but not for sequences.

```go
func NotChars(matcher string, repetition ...int) Parser

```

--------------------------------

### Merge

Source: https://pkg.go.dev/github.com/vektah/goparsify

Merges all child Tokens together recursively.

```APIDOC
## func Merge

```go
func Merge(parser Parserish) Parser
```

Merge all child Tokens together recursively
```

--------------------------------

### Unmarshal Function

Source: https://pkg.go.dev/github.com/vektah/goparsify/json

The Unmarshal function takes a JSON string as input and returns it as a map[string]interface{} or []interface{}.

```APIDOC
## func Unmarshal

### Description
Unmarshall json string into map[string]interface{} or []interface{}.

### Signature
```go
func Unmarshal(input string) (interface{}, error)
```

### Parameters
#### Path Parameters
- **input** (string) - Required - The JSON string to unmarshal.
```

--------------------------------

### GetDefinition

Source: https://pkg.go.dev/github.com/vektah/goparsify/debug

GetDefinition returns the name of the variable and location this parser was defined by walking up the stack.

```APIDOC
## func GetDefinition()

### Description
GetDefinition returns the name of the variable and location this parser was defined by walking up the stack.

### Signature
```go
func GetDefinition() (varName string, location string)
```
```

--------------------------------

### Define Parserish Interface

Source: https://pkg.go.dev/github.com/vektah/goparsify

The Parserish interface represents types that can be converted into a Parser. This includes existing Parsers and string literals, simplifying recursive grammar definitions.

```go
type Parserish interface{}
```

--------------------------------

### Result.String

Source: https://pkg.go.dev/github.com/vektah/goparsify

Converts a Result object into a string representation, primarily used for debugging purposes.

```APIDOC
## Result.String

### Description
Stringifies a node. This is only called from debug code.

### Method
func (r Result) String() string
```

--------------------------------

### Disable Automatic Whitespace Matching

Source: https://pkg.go.dev/github.com/vektah/goparsify

Creates a parser that disables automatic whitespace matching for a given parser.

```go
func NoAutoWS(parser Parserish) Parser
```

--------------------------------

### Cut

Source: https://pkg.go.dev/github.com/vektah/goparsify

Prevents backtracking beyond this point, improving performance and error reporting. Typically used after keywords.

```APIDOC
## func Cut

```go
func Cut() Parser
```

Cut prevents backtracking beyond this point. Usually used after keywords when you are sure this is the correct path. Improves performance and error reporting.
Example:
```
Output:
left unparsed: <foo
offset 9: expected >
```
```

--------------------------------

### Check if State is Errored

Source: https://pkg.go.dev/github.com/vektah/goparsify

Checks if the parser state has encountered an error.

```go
Errored() bool
```

--------------------------------

### Match Character Sequences or Ranges

Source: https://pkg.go.dev/github.com/vektah/goparsify

Chars is a versatile function for matching characters. It supports matching specific characters, ranges (e.g., 'a-z'), and can be configured to match a specific number of repetitions.

```go
func Chars(matcher string, repetition ...int) Parser

```

--------------------------------

### No Whitespace Parser

Source: https://pkg.go.dev/github.com/vektah/goparsify

Disables automatic whitespace matching for subsequent parsing operations.

```go
func NoWhitespace(s *State)
```

--------------------------------

### Raise Error at Current Position

Source: https://pkg.go.dev/github.com/vektah/goparsify

ErrorHere records an error at the current parsing position, indicating an expected token or pattern.

```go
func (s *State) ErrorHere(expected string)
```

--------------------------------

### Unmarshal JSON String

Source: https://pkg.go.dev/github.com/vektah/goparsify/json

Use this function to parse a JSON string into a map[string]interface{} or []interface{}. Ensure the input is a valid JSON string.

```go
func Unmarshal(input string) (interface{}, error)
```

--------------------------------

### Match Number Literals

Source: https://pkg.go.dev/github.com/vektah/goparsify

NumberLit matches floating-point or integer numbers and returns them as either an int64 or float64 in the .Result field.

```go
func NumberLit() Parser

```

--------------------------------

### Disable Automatic Whitespace Skipping

Source: https://pkg.go.dev/github.com/vektah/goparsify

NoAutoWS creates a parser that disables the automatic skipping of whitespace between tokens for all parsers nested within it. Use this when precise control over whitespace is required.

```go
func NoAutoWS(parser Parserish) Parser

```

--------------------------------

### Result

Source: https://pkg.go.dev/github.com/vektah/goparsify

Represents the result of a successful parse.

```APIDOC
## Result Type

### Description
Represents the result of a successful parse.

### Methods
#### String()
Returns a string representation of the result.
```go
func (r Result) String() string
```
```

--------------------------------

### State.ErrorHere

Source: https://pkg.go.dev/github.com/vektah/goparsify

Records an error at the current parsing position within the State, indicating an expected token or pattern.

```APIDOC
## State.ErrorHere

### Description
Raises an error at the current position.

### Method
func (s *State) ErrorHere(expected string)

### Parameters
#### Path Parameters
- **expected** (string) - Required - A description of the expected token or pattern that was not found.
```

--------------------------------

### Merge Child Tokens Recursively

Source: https://pkg.go.dev/github.com/vektah/goparsify

Merge creates a parser that combines all child tokens into a single token recursively. This can simplify the structure of the parse result.

```go
func Merge(parser Parserish) Parser

```

--------------------------------

### Prevent Backtracking with Cut

Source: https://pkg.go.dev/github.com/vektah/goparsify

The Cut function creates a parser that prevents backtracking beyond its point in the input. This is typically used after matching keywords to improve performance and error reporting by committing to a parse path.

```go
func Cut() Parser

```

--------------------------------

### State.Recover

Source: https://pkg.go.dev/github.com/vektah/goparsify

Recovers from a previously encountered error within the State. This is often used by combinators to attempt alternative parsing paths.

```APIDOC
## State.Recover

### Description
Recover from the current error. Often called by combinators that can match when one of their children succeed, but others have failed.

### Method
func (s *State) Recover()
```

--------------------------------

### Unparsed Input Error

Source: https://pkg.go.dev/github.com/vektah/goparsify

Represents an error when input remains unparsed after a parsing operation.

```go
func (e UnparsedInputError) Error() string
```

--------------------------------

### Recover Parser State

Source: https://pkg.go.dev/github.com/vektah/goparsify

Recovers the parser state, typically used after an error has been handled.

```go
Recover()
```

--------------------------------

### Report Parse Error

Source: https://pkg.go.dev/github.com/vektah/goparsify

Reports a parse error at the current position in the state.

```go
ErrorHere(expected string)
```
Tokens:
Raw