Pkg.go.dev is a new destination for Go discovery & docs. Check it out at pkg.go.dev/bitbucket.org/Ragnara/pars and share your feedback.

package pars

import "bitbucket.org/Ragnara/pars"

Package pars is a simple framework for parser combinators. It is designed to be easy to use, yet powerful enough to allow solving real world problems.

Parsers can be arranged into flexible stacks of more elemental parsers. Parser results can be transformed via transformers to easily convert their results into a more fitting format or to implement additional conditions that must be fulfilled for a successful parse.

Complex parsers can be debugged by wrapping them with a logger.

pars parsers can read from a string or from an io.Reader, so streaming parsing is possible if you need it.

buffer.go combinators.go dispatch.go errors.go fundamental_parsers.go logging.go pars.go pkg.go reader.go scanner.go utilities.go

AssignInto returns a setter for Into parsers. The setter will set a given field to the parsers result value on success and to the zero value on failure.

This function or the generated setter might panic if the types do not fit.

Example Code: data := "My name is 'Ark' " var name string parser := Seq(String("My name is"), Into(SwallowWhitespace(RuneDelimitedString('\'', '\'')), AssignInto(&name)), EOF) _, err := ParseString(data, parser) if err != nil { fmt.Println("Error while parsing:", err) return } fmt.Printf("Hello, %v!

", name) Output: Hello, Ark!

AssignIntoSlice returns a setter for Into parsers. The setter will set a given slice pointer to the parsers result value on success and to nil on failure.

This function or the generated setter might panic if the types do not fit.

Example Code: data := "123,456,789" var numbers []int parser := Seq(Into(Sep(Int(), Char(',')), AssignIntoSlice(&numbers)), EOF) _, err := ParseString(data, parser) if err != nil { fmt.Println("Error while parsing:", err) return } fmt.Printf("Type safe numbers from parsing:

%#v

", numbers) var sum int for _, number := range numbers { sum += number } fmt.Println("Sum:", sum) Output: Type safe numbers from parsing: []int{123, 456, 789} Sum: 1368

❖ func ParseFromReader(ior io.Reader, p Parser) (interface{}, error)

ParseFromReader parses from an io.Reader.

❖ func ParseString(s string, p Parser) (interface{}, error)

ParseString is a helper function to directly use a parser on a string.

❖ type Clause []Parser

Clause is the most simple DispatchClause. It is just a slice of parsers without any transformations.

Parsers returns the parser slice for this clause.

TransformError returns the given error unchanged.

TransformResult returns the only value if the slice of values has only one element. Otherwise it returns the slice of values unchanged.

❖ type ClonableDispatchClause interface { DispatchClause //Clone creates a functionally equivalent clause with unique state. Clone () ClonableDispatchClause }

ClonableDispatchClause is the interface of stateful DispatchClause types that need clones with unique state.

❖ type DescribeClause struct { DispatchClause Description string }

DescribeClause extends the error message of a clause so that a custom description is part of the message.

Clone calls clone of the inner clause if implemented.

TransformError extends the error message of a clause so that a custom description is part of the message.

❖ type DispatchClause interface { //Parsers returns the parsers of the clause. Parsers () []Parser //TransformResult allows the DispatchClause to combine the results of its parsers to a single result. TransformResult ([]interface{}) interface{} //TransformError allows the DispatchClause to replace or extend the error returned on a failed match. TransformError (error) error }

DispatchClause is the interface of a clause used by Dispatch.

❖ type InsteadOfClause struct { DispatchClause Result interface{} }

InsteadOfClause extends a clause so that it returns a fixed value as if it was wrapped in an InsteadOf.

Clone calls clone of the inner clause if implemented.

TransformResult returns the Result as if the clause was wrapped in an InsteadOf.

❖ type InsteadOfDerefClause struct { DispatchClause Result interface{} }

InsteadOfDerefClause extends a clause so that it returns a value that will be dereferenced as if the clause was wrapped in an InsteadOfDeref.

Clone calls clone of the inner clause if implemented.

TransformResult returns the dereferenced Result as if the clause was wrapped in an InsteadOfDeref.

❖ type Logger interface { Println (...interface{}) }

Logger is anything that lines can be printed to.

❖ type Parser interface { //Parse is used for the actual parsing. It reads from the reader and returns the result or an error value. // //Each parser must remember enough from the call to this method to undo the reading in case of a parsing error that occurs later. // //When Parse returns with an error, Parse must make sure that all read bytes are unread so that another parser could try to parse them. Parse (*Reader) (interface{}, error) //Unread puts read bytes back to the reader so that they can be read again by other parsers. Unread (*Reader) //Clone creates a parser that works the same as the receiver. This allows to create a single parser as a blueprint for other parsers. // //Internal state from reading operations should not be cloned. Clone () Parser }

Parser contains the methods that each parser in this framework has to provide.

❖ var EOF Parser = eof{}

EOF is a parser that never yields a value but that succeeds if and only if the source reached EOF

AnyByte returns a parser that reads exactly one byte from the source.

AnyRune returns a parser that parses a single valid rune. If no such rune can be read, ErrRuneExpected is returned.

BigInt returns a parser that parses an integer. The parsed integer is returned as a math/big.Int.

Byte returns a parser used to read a single known byte. A different byte is treated as a parsing error.

Char returns a parser used to read a single known rune. A different rune is treated as a parsing error.

CharPred returns a parser that parses a single rune as long as it fulfills the given predicate.

❖ func DelimitedString(beginDelimiter, endDelimiter string) Parser

DelimitedString returns a parser that parses a string between two given delimiter strings and returns the value between.

❖ func DiscardLeft(left, right Parser) Parser

DiscardLeft returns a parser that calls two other parsers but only returns the result of the second parser. Both parsers must succeed.

Example Code: data := "$123" dollarParser := DiscardLeft(Char('$'), Int()) result, err := ParseString(data, dollarParser) if err != nil { fmt.Println("Error while parsing:", err) return } fmt.Printf("%v: %T

", result, result) Output: 123: int

❖ func DiscardRight(left, right Parser) Parser

DiscardRight returns a parser that calls two other parsers but only returns the result of the first parser. Both parsers must succeed.

Dispatch returns a parser that is like a combination of Seq and Or with limited backtracking.

A Dispatch contains multiple clauses consisting of parsers. Dispatch parses by trying the clauses one by one. The first matching clause is used, later clauses are not tried. Each clause can contain multiple parsers. Clauses are special because they limit the backtracking: If the first parser of a clause matches, that clause is selected even if a later parser of that clause fails. If no clause matches, the error from the last clause is returned.

The motivation for limited backtracking is in better error reporting. When an Or parser fails, all you know is that not a single parser succeeded. When a Dispatch parser fails after a clause was selected, you know which subclause was supposed to be parsed and can return a fitting error message.

DispatchSome is a parser that combines Dispatch and Some. Like Dispatch, it tries to find a clause where the first parser succeeds and then commits to that clause. If the whole clause succeeds, the TransformResult method is called as usual. If a committed clause fails, the whole parser fails and returns the corresponding error (transformed by the TransformError method).

Unlike Dispatch, after a successful parse another round starts with the first clause again. DispatchSome parses until either an error occurs or no single clause matched. Different from Dispatch, if no clause matches, it is not an error but marks the end of the loop.

A successful DispatchSome returns a slice of all single results from each Dispatch round. This slice may be empty.

Error returns a parser that always fails with the given error

❖ func ErrorTransformer(parser Parser, transformer func(error) (interface{}, error)) Parser

ErrorTransformer wraps a parser so that an error result is transformed according to the given function. If the wrapped parser was successful, the result is not changed.

❖ func Except(parser, except Parser) Parser

Except returns a parser that wraps another parser so that it fails if a third, excepted parser would succeed.

Float returns a parser that parses a floating point number. The supported format is an optional minus sign followed by digits optionally followed by a decimal point and more digits.

❖ func InsteadOf(parser Parser, value interface{}) Parser

InsteadOf wraps a parser so that a different given value is used as a result on success.

❖ func InsteadOfDeref(parser Parser, value interface{}) Parser

InsteadOfDeref wraps a parser so that a different given value is used as a result on success. The given value has to be a pointer to something (not nil) and will be dereferenced.

Int returns a parser that parses an integer. The parsed integer is converted via strconv.Atoi.

❖ func Into(parser Parser, setter func(interface{})) Parser

Into wraps a parser so that a successful parse calls the given setter. If the wrapped parser fails, the setter is not called. If the returned parser succeeds at first, but is unread later, the setter will be called again with nil as the value.

It is recommended that the variable the setter writes into is not read from other parsers (e.g. via Into or Transformer) as it might become confusing to understand which parser has seen which setter result at which time.

Also, Into should be used as outmost as possible. A parser like 'Some(Into(AnyRune(), setter))' will have its setter called many times, so each value will be overwritten by the next one. On the other hand, you can use this for a setter that appends all values into a slice instead of just setting a single variable. Just have a clear idea of what your setter will do.

JoinString wraps a parser that returns a slice of runes or strings so that it returns a single string instead. Runes and strings can be mixed in the same slice. The slice also can contain other slices of runes and strings, recursively.

The returned parser WILL PANIC if the wrapped parser returns something that is not a slice of runes or strings!

Many returns a parser that matches a given parser one or more times. Not matching at all is an error.

Optional returns a parser that reads exactly one result according to a given other parser. If it fails, the error is discarded and nil is returned.

Or returns a parser that matches the first of a given set of parsers. A later parser will not be tried if an earlier match was found. The returned parser uses the error message of the last parser verbatim.

Example Code: data := "124" parser := Or(String("123"), String("124")) result, err := ParseString(data, parser) if err != nil { fmt.Println("Error while parsing:", err) return } fmt.Printf("%v: %T

", result, result) Output: 124: string

Recursive allows to recursively define a parser in terms of itself.

❖ func RuneDelimitedString(beginDelimiter, endDelimiter rune) Parser

RuneDelimitedString returns a parser that parses a string between two given delimiter runes and returns the value between.

RunesUntil returns a parser that parses runes as long as the given endCondition parser does not match.

❖ func Sep(item, separator Parser) Parser

Sep returns a parser that parses a sequence of items according to a first parser that are separated by matches of a second parser.

Seq returns a parser that matches all of its given parsers in order or none of them.

Example Code: data := "$123" dollarParser := Seq(Char('$'), Int()) result, err := ParseString(data, dollarParser) if err != nil { fmt.Println("Error while parsing:", err) return } values := result.([]interface{}) fmt.Printf("%c: %T

", values[0], values[0]) fmt.Printf("%v: %T

", values[1], values[1]) Output: $: int32 123: int

Some returns a parser that matches a given parser zero or more times. Not matching at all is not an error.

SplicingSeq returns a parser that works like a Seq but joins slices returned by its subparsers into a single slice.

String returns a parser for a single known string. Different strings are treated as a parsing error.

StringCI returns a case-insensitive parser for a single known string. Different strings are treated as a parsing error.

SwallowLeadingWhitespace wraps a parser so that it removes leading whitespace.

SwallowTrailingWhitespace wraps a parser so that it removes trailing whitespace.

SwallowWhitespace wraps a parser so that it removes leading and trailing whitespace.

❖ func Transformer(parser Parser, transformer func(interface{}) (interface{}, error)) Parser

Transformer wraps a parser so that the result is transformed according to the given function. If the transformer returns an error, the parsing is handled as failed.

Example Code: package main import ( "bitbucket.org/ragnara/pars/v2" "fmt" ) //Celsius contains a temperature in degree celsius. type Celsius int func (c Celsius) String() string { return fmt.Sprintf("%v°C", int(c)) } //TemperatureParser is a parser for temperature strings returning Celsius instances. type TemperatureParser struct { pars.Parser } //NewTemperatureParser creates a new TemperatureParser instance. func NewTemperatureParser() TemperatureParser { //Define the format simpleParser := pars.Seq(pars.Int(), pars.Or(pars.String("°C"), pars.String("°F"))) //Add an conversion transformedParser := pars.Transformer(simpleParser, transformParsedTemperatureToCelsius) return TemperatureParser{Parser: transformedParser} } //Parse returns the Celsius instance for a temperature string containing an integer followed by either "°C" or "°F". Fahrenheit strings are converted to celsius. //For other strings, an error is returned. func (t TemperatureParser) Parse(s string) (Celsius, error) { val, err := pars.ParseString(s, t.Parser) if err != nil { return Celsius(0), err } return val.(Celsius), nil } //MustParse parses exactly like Parse but panics if an invalid string was found. It should not be used on user input! func (t TemperatureParser) MustParse(s string) Celsius { val, err := t.Parse(s) if err != nil { panic(err) } return val } func transformParsedTemperatureToCelsius(parserResult interface{}) (interface{}, error) { values := parserResult.([]interface{}) degrees := values[0].(int) unit := values[1].(string) switch unit { case "°C": return Celsius(degrees), nil case "°F": return Celsius((degrees - 32) * 5 / 9), nil default: panic("Impossible unit: " + unit) } } func main() { sample1 := "32°C" sample2 := "104°F" sample3 := "128K" fmt.Println("Sample1:", NewTemperatureParser().MustParse(sample1)) fmt.Println("Sample2:", NewTemperatureParser().MustParse(sample2)) val, err := NewTemperatureParser().Parse(sample3) fmt.Println("Sample3:", val) fmt.Println("Sample3 error:", err.Error()) }

❖ func WithLogging(parser Parser, logger Logger) Parser

WithLogging wraps a parser so that calls to it are logged to a given logger.

❖ func WithStdLogging(parser Parser, prefix string) Parser

WithStdLogging wraps a parser so that calls to it are logged to a logger logging to StdErr with a given prefix.

❖ type Reader struct { // contains filtered or unexported fields }

Reader is an io.Reader that can Unread as many bytes as necessary.

NewReader creates a new Reader from an io.Reader.

❖ func (br *Reader) Read(p []byte) (n int, err error)

Read reads a slice of bytes.

Unread unreads a slice of bytes so that they will be read again by Read.

❖ type Scanner struct { // contains filtered or unexported fields }

Scanner provides a convenient interface to use a single parser multiple times on the same reader.

Successive calls to Scan will parse the input and allow the results to be accessed one at a time.

Scanner stops at the first error.

Example Code: data := "this is a text of words" reader := NewReader(strings.NewReader(data)) wordParser := SwallowTrailingWhitespace(JoinString(RunesUntil(CharPred(unicode.IsSpace)))) scanner := NewScanner(reader, wordParser) for scanner.Scan() { fmt.Println(scanner.ResultString()) } fmt.Println(scanner.Err()) Output: this is a text of words <nil>

❖ func NewScanner(r *Reader, p Parser) Scanner

NewScanner returns a new scanner using a given Reader and Parser.

Err returns the last encountered error that is not io.EOF. It returns nil otherwise.

Result returns the most recently parsed value from a call to Scan.

ResultString returns the most recently parsed value from a call to Scan, cast to a String.

This will panic if the last result is not a string!

Scan invokes the parser on the reader and makes the results available via Result and Err.

Scan returns true if the parsing succeeded and returns false otherwise.

❖ type StringJoiningClause struct { DispatchClause }

StringJoiningClause extends a clause that consists of parsers that return runes or strings so that it returnes a single string instead. Slices are handled recursively.

StringJoiningClause WILL PANIC if any of the parsers return something other than a rune or a string or a slice of these types.

Clone calls clone of the inner clause if implemented.

TransformResult joins runes and strings together like JoinString.

Path Synopsis examples/pars-calc pars-calc is a small cli calculator that takes floats or calculations of floats consisting of additions, substractions, multiplications or divisions on StdIn, parses them via the parser implemented in parser.go into something easily evaluable, and prints the result of the calculation.