parser

Documentation

Index

• func LineAndColOf(input, clip []rune) (int, int)
• type Error
  • func NewError(input []rune, expected ...string) *Error
  • func NewFatalError(input []rune, err error, expected ...string) *Error
  • func NewQuery(queryStr string) (query.Function, *Error)
  • func ParseField(expr string) (field.Expression, *Error)
  • func ParseMapping(filepath string, expr string) (*mapping.Executor, *Error)
  • func (e *Error) Add(from *Error)
  • func (e *Error) Error() string
  • func (e *Error) ErrorAtChar(input []rune) string
  • func (e *Error) ErrorAtPosition(input []rune) string
  • func (e *Error) ErrorAtPositionStructured(filepath string, input []rune) string
  • func (e *Error) IsFatal() bool
  • func (e *Error) Unwrap() error
• type ImportError
  • func NewImportError(path string, input []rune, err *Error) *ImportError
  • func (i *ImportError) Error() string
• type Result
  • func ParseDeprecatedQuery(input []rune) Result
  • func ParseQuery(input []rune) Result
• type Type
  • func Array() Type
  • func BestMatch(parsers ...Type) Type
  • func Boolean() Type
  • func Char(c rune) Type
  • func Comment() Type
  • func Delimited(primary, delimiter Type) Type
  • func DelimitedPattern(start, primary, delimiter, stop Type, allowTrailing, returnDelimiters bool) Type
  • func Discard(parser Type) Type
  • func DiscardAll(parser Type) Type
  • func Expect(parser Type, expected ...string) Type
  • func InRange(lower, upper rune) Type
  • func InSet(set ...rune) Type
  • func JoinStringPayloads(p Type) Type
  • func LiteralValue() Type
  • func MustBe(parser Type) Type
  • func Newline() Type
  • func NewlineAllowComment() Type
  • func NotChar(c rune) Type
  • func NotEnd(p Type, exp ...string) Type
  • func Null() Type
  • func Number() Type
  • func Object() Type
  • func OneOf(parsers ...Type) Type
  • func Optional(parser Type) Type
  • func QuotedString() Type
  • func Sequence(parsers ...Type) Type
  • func SnakeCase() Type
  • func SpacesAndTabs() Type
  • func Term(str string) Type
  • func TripleQuoteString() Type
  • func UntilFail(parser Type) Type

Functions

func LineAndColOf

func LineAndColOf(input, clip []rune) (int, int)

LineAndColOf returns the line and column position of a tailing clip from an input.

Types

type Error

type Error struct {
	Input    []rune
	Err      error
	Expected []string
}

Error represents an error that has occurred whilst attempting to apply a parser function to a given input. A slice of abstract names should be provided outlining tokens or characters that were expected and not found at the input in order to provide a useful error message.

The input at the point of the error can be used in order to infer where exactly in the input the error occurred with len(input) - len(err.Input).

func NewError

func NewError(input []rune, expected ...string) *Error

NewError creates a parser error from the input and a list of expected tokens. This is a passive error indicating that this particular parser did not succeed, but that other parsers should be tried if applicable.

func NewFatalError

func NewFatalError(input []rune, err error, expected ...string) *Error

NewFatalError creates a parser error from the input and a wrapped fatal error indicating that this parse succeeded partially, but a requirement was not met that means the parsed input is invalid and that all parsing should stop.

func NewQuery

func NewQuery(queryStr string) (query.Function, *Error)

NewQuery parses a new query function from a query string.

func ParseField

func ParseField(expr string) (field.Expression, *Error)

ParseField attempts to parse a field expression.

func ParseMapping

func ParseMapping(filepath string, expr string) (*mapping.Executor, *Error)

ParseMapping parses a bloblang mapping and returns an executor to run it, or an error if the parsing fails.

The filepath is optional and used for relative file imports and error messages.

func (*Error) Add

func (e *Error) Add(from *Error)

Add context from another error into this one.

func (*Error) Error

func (e *Error) Error() string

Error returns a human readable error string.

func (*Error) ErrorAtChar

func (e *Error) ErrorAtChar(input []rune) string

ErrorAtChar returns a human readable error string including the character position of the error.

func (*Error) ErrorAtPosition

func (e *Error) ErrorAtPosition(input []rune) string

ErrorAtPosition returns a human readable error string including the line and character position of the error.

func (*Error) ErrorAtPositionStructured

func (e *Error) ErrorAtPositionStructured(filepath string, input []rune) string

ErrorAtPositionStructured returns a human readable error string including the line and character position of the error formatted in a more structured way, this message isn't appropriate to write within structured logs as the formatting will be broken.

func (*Error) IsFatal

func (e *Error) IsFatal() bool

IsFatal returns whether this parser error should be considered fatal, and therefore sibling parser candidates should not be tried.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying fatal error (or nil).

type ImportError

type ImportError struct {
	// contains filtered or unexported fields
}

ImportError wraps a parser error with an import file path. When a fatal error wraps

func NewImportError

func NewImportError(path string, input []rune, err *Error) *ImportError

NewImportError wraps a parser error with a filepath for when a parser has attempted to parse content of an imported file.

func (*ImportError) Error

func (i *ImportError) Error() string

Error implements the standard error interface.

type Result

type Result struct {
	Payload   interface{}
	Err       *Error
	Remaining []rune
}

Result represents the result of a parser given an input.

func ParseDeprecatedQuery

func ParseDeprecatedQuery(input []rune) Result

ParseDeprecatedQuery parses an input into a query.Function, but permits deprecated function interpolations. In order to support old functions this parser does not include field literals.

func ParseQuery

func ParseQuery(input []rune) Result

ParseQuery parses an input into a query.Function.

type Type

type Type func([]rune) Result

Type is a general parser method.

func Array

func Array() Type

Array parses an array literal.

func BestMatch

func BestMatch(parsers ...Type) Type

BestMatch accepts one or more parsers and tries them all against an input. If any parser returns a non ExpectedError error then it is returned. If all parsers return either a result or an ExpectedError then the parser that got further through the input will have its result returned. This means that an error may be returned even if a parser was successful.

For example, given two parsers, A searching for 'aa', and B searching for 'aaaa', if the input 'aaab' were provided then an error from parser B would be returned, as although the input didn't match, it matched more of parser B than parser A.

func Boolean

func Boolean() Type

Boolean parses either 'true' or 'false' into a boolean value.

func Char

func Char(c rune) Type

Char parses a single character and expects it to match one candidate.

func Comment

func Comment() Type

Comment parses a # comment (always followed by a line break).

func Delimited

func Delimited(primary, delimiter Type) Type

Delimited attempts to parse one or more primary parsers, where after the first parse a delimiter is expected. Parsing is stopped only once a delimiter parse is not successful.

Two slices are returned, the first element being a slice of primary results and the second element being the delimiter results.

func DelimitedPattern

func DelimitedPattern(
	start, primary, delimiter, stop Type,
	allowTrailing, returnDelimiters bool,
) Type

DelimitedPattern attempts to parse zero or more primary parsers in between an start and stop parser, where after the first parse a delimiter is expected. Parsing is stopped only once an explicit stop parser is successful.

If allowTrailing is set to false and a delimiter is parsed but a subsequent primary parse fails then an error is returned.

Only the results of the primary parser are returned, the results of the start, delimiter and stop parsers are discarded. If returnDelimiters is set to true then two slices are returned, the first element being a slice of primary results and the second element being the delimiter results.

func Discard

func Discard(parser Type) Type

Discard the result of a child parser, regardless of the result. This has the effect of running the parser and returning only Remaining.

func DiscardAll

func DiscardAll(parser Type) Type

DiscardAll the results of a child parser, applied until it fails. This has the effect of running the parser and returning only Remaining.

func Expect

func Expect(parser Type, expected ...string) Type

Expect applies a parser and if an error is returned the list of expected candidates is replaced with the given strings. This is useful for providing better context to users.

func InRange

func InRange(lower, upper rune) Type

InRange parses any number of characters between two runes inclusive.

func InSet

func InSet(set ...rune) Type

InSet parses any number of characters within a set of runes.

func JoinStringPayloads

func JoinStringPayloads(p Type) Type

JoinStringPayloads wraps a parser that returns a []interface{} of exclusively string values and returns a result of a joined string of all the elements.

Warning! If the result is not a []interface{}, or if an element is not a string, then this parser returns a zero value instead.

func LiteralValue

func LiteralValue() Type

LiteralValue parses a literal bool, number, quoted string, null value, array of literal values, or object.

func MustBe

func MustBe(parser Type) Type

MustBe applies a parser and if the result is a non-fatal error then it is upgraded to a fatal one.

func Newline

func Newline() Type

Newline parses a line break.

func NewlineAllowComment

func NewlineAllowComment() Type

NewlineAllowComment parses an optional comment followed by a mandatory line break.

func NotChar

func NotChar(c rune) Type

NotChar parses any number of characters until they match a single candidate.

func NotEnd

func NotEnd(p Type, exp ...string) Type

NotEnd parses zero characters from an input and expects it to not have ended. An ExpectedError must be provided which provides the error returned on empty input.

func Null

func Null() Type

Null parses a null literal value.

func Number

func Number() Type

Number parses any number of numerical characters into either an int64 or, if the number contains float characters, a float64.

func Object

func Object() Type

Object parses an object literal.

func OneOf

func OneOf(parsers ...Type) Type

OneOf accepts one or more parsers and tries them in order against an input. If a parser returns an ExpectedError then the next parser is tried and so on. Otherwise, the result is returned.

func Optional

func Optional(parser Type) Type

Optional applies a child parser and if it returns an ExpectedError then it is cleared and a nil result is returned instead. Any other form of error will be returned unchanged.

func QuotedString

func QuotedString() Type

QuotedString parses a single instance of a quoted string. The result is the inner contents unescaped.

func Sequence

func Sequence(parsers ...Type) Type

Sequence applies a sequence of parsers and returns either a slice of the results or an error if any parser fails.

func SnakeCase

func SnakeCase() Type

SnakeCase parses any number of characters of a camel case string. This parser is very strict and does not support double underscores, prefix or suffix underscores.

func SpacesAndTabs

func SpacesAndTabs() Type

SpacesAndTabs parses any number of space or tab characters.

func Term

func Term(str string) Type

Term parses a single instance of a string.

func TripleQuoteString

func TripleQuoteString() Type

TripleQuoteString parses a single instance of a triple-quoted multiple line string. The result is the inner contents.

func UntilFail

func UntilFail(parser Type) Type

UntilFail applies a parser until it fails, and returns a slice containing all results. If the parser does not succeed at least once an error is returned.