pars

func AnyByte ¶

func AnyByte() Parser

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

func AnyRune ¶

func AnyRune() Parser

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

func BigInt ¶

func BigInt() Parser

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

func Byte ¶

func Byte(b byte) Parser

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

func Char ¶

func Char(r rune) Parser

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

func CharPred ¶

func CharPred(pred func(rune) bool) Parser

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

func DelimitedString ¶

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 ¶

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.

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\n", result, result)

Output:

123: int

func DiscardRight ¶

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.

func Dispatch ¶

func Dispatch(clauses ...DispatchClause) Parser

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.

func DispatchSome ¶ added in v2.1.0

func DispatchSome(clauses ...DispatchClause) Parser

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.

func Error ¶

func Error(err error) Parser

Error returns a parser that always fails with the given error

func ErrorTransformer ¶

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 ¶

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.

func Float ¶

func Float() Parser

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 ¶ added in v2.1.0

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 ¶ added in v2.1.0

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.

func Int ¶

func Int() Parser

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

func Into ¶ added in v2.1.0

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.

func JoinString ¶

func JoinString(parser Parser) Parser

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!

func Many ¶

func Many(parser Parser) Parser

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

func Optional ¶

func Optional(parser Parser) Parser

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.

func Or ¶

func Or(parsers ...Parser) Parser

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.

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\n", result, result)

Output:

124: string

func Recursive ¶

func Recursive(factory func() Parser) Parser

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

func RuneDelimitedString ¶ added in v2.1.0

func RuneDelimitedString(beginDelimiter, endDelimiter rune) Parser

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

func RunesUntil ¶

func RunesUntil(endCondition Parser) Parser

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

func Sep ¶

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.

func Seq ¶

func Seq(parsers ...Parser) Parser

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

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\n", values[0], values[0])
fmt.Printf("%v: %T\n", values[1], values[1])

Output:

$: int32
123: int

func Some ¶

func Some(parser Parser) Parser

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

func SplicingSeq ¶

func SplicingSeq(parsers ...Parser) Parser

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

func String ¶

func String(expected string) Parser

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

func StringCI ¶

func StringCI(expected string) Parser

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

func SwallowLeadingWhitespace ¶

func SwallowLeadingWhitespace(parser Parser) Parser

SwallowLeadingWhitespace wraps a parser so that it removes leading whitespace.

func SwallowTrailingWhitespace ¶

func SwallowTrailingWhitespace(parser Parser) Parser

SwallowTrailingWhitespace wraps a parser so that it removes trailing whitespace.

func SwallowWhitespace ¶

func SwallowWhitespace(parser Parser) Parser

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

func Transformer ¶

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.

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())

}

Output:

Sample1: 32°C
Sample2: 40°C
Sample3: 0°C
Sample3 error: Could not find expected sequence item 1: Could not parse expected string "°F": EOF

func WithLogging ¶

func WithLogging(parser Parser, logger Logger) Parser

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

func WithStdLogging ¶

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.

func NewReader ¶

func NewReader(r io.Reader) *Reader

NewReader creates a new Reader from an io.Reader.

func NewScanner ¶

func NewScanner(r *Reader, p Parser) Scanner

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