parser

package
v4.27.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2024 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Boolean = func() Func[bool] {
	parser := Expect(OneOf(Term("true"), Term("false")), "boolean")
	return func(input []rune) Result[bool] {
		res := parser(input)
		if res.Err == nil {
			return Success(res.Payload == "true", res.Remaining)
		}
		return ResultInto[bool](res)
	}
}()

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

View Source 
var Comment = JoinStringPayloads(
	Sequence(
		charHash,
		JoinStringPayloads(
			Optional(UntilFail(NotChar('\n'))),
		),
		Newline,
	),
)

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

View Source 
var DiscardedWhitespaceNewlineComments = DiscardAll(OneOf(SpacesAndTabs, NewlineAllowComment))
View Source 
var Newline = Expect(
	JoinStringPayloads(
		Sequence(
			Optional(Char('\r')),
			Char('\n'),
		),
	),
	"line break",
)

Newline parses a line break.

View Source 
var NewlineAllowComment = Expect(OneOf(Comment, Newline), "line break")

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

View Source 
var Null = func() Func[any] {
	nullMatch := Term("null")
	return func(input []rune) Result[any] {
		res := ResultInto[any](nullMatch(input))
		if res.Err == nil {
			res.Payload = nil
		}
		return res
	}
}()

Null parses a null literal value.

View Source 
var Number = func() Func[any] {
	digitSet := InSet([]rune("0123456789")...)
	dot := charDot
	expectNumber := Expect(digitSet, "number")

	return func(input []rune) Result[any] {
		var negative bool
		res := charMinus(input)
		if res.Err == nil {
			negative = true
		}
		res = expectNumber(res.Remaining)
		if res.Err != nil {
			return ResultInto[any](res)
		}
		resStr := res.Payload
		if resTest := dot(res.Remaining); resTest.Err == nil {
			if resTest = digitSet(resTest.Remaining); resTest.Err == nil {
				resStr = resStr + "." + resTest.Payload
				res = resTest
			}
		}

		outRes := ResultInto[any](res)
		if strings.Contains(resStr, ".") {
			f, err := strconv.ParseFloat(resStr, 64)
			if err != nil {
				err = fmt.Errorf("failed to parse '%v' as float: %v", resStr, err)
				return Fail[any](NewFatalError(input, err), input)
			}
			if negative {
				f = -f
			}
			outRes.Payload = f
		} else {
			i, err := strconv.ParseInt(resStr, 10, 64)
			if err != nil {
				err = fmt.Errorf("failed to parse '%v' as integer: %v", resStr, err)
				return Fail[any](NewFatalError(input, err), input)
			}
			if negative {
				i = -i
			}
			outRes.Payload = i
		}
		return outRes
	}
}()

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

View Source 
var SnakeCase = Expect(JoinStringPayloads(UntilFail(OneOf(
	InRange('a', 'z'),
	InRange('0', '9'),
	charUnderscore,
))), "snake-case")

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.

View Source 
var SpacesAndTabs = Expect(InSet(' ', '\t'), "whitespace")

SpacesAndTabs parses any number of space or tab characters.

Functions

func LineAndColOf 

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

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

func ParseDotEnvFile 

func ParseDotEnvFile(envFileBytes []byte) (map[string]string, error)

ParseDotEnvFile attempts to parse a .env file containing environment variable assignments, and returns either a map of key/value assignments or an error.

Types

type Context 

type Context struct {
	Functions *query.FunctionSet
	Methods   *query.MethodSet
	// contains filtered or unexported fields
}

Context contains context used throughout a Bloblang parser for accessing function and method constructors.

func EmptyContext 

func EmptyContext() Context

EmptyContext returns a parser context with no functions, methods or import capabilities.

func GlobalContext 

func GlobalContext() Context

GlobalContext returns a parser context with globally defined functions and methods.

func (Context) CustomImporter 

func (pCtx Context) CustomImporter(fn func(name string) ([]byte, error)) Context

CustomImporter returns a version of the parser context where file imports are done exclusively through a provided closure function, which takes an import path (relative or absolute).

func (Context) Deactivated 

func (pCtx Context) Deactivated() Context

Deactivated returns a version of the parser context where all functions and methods exist but can no longer be instantiated. This means it's possible to parse and validate mappings but not execute them. If the context also has an importer then it will also be replaced with an implementation that always returns empty files.

func (Context) DisabledImports 

func (pCtx Context) DisabledImports() Context

DisabledImports returns a version of the parser context where file imports are entirely disabled. Any import statement within parsed mappings will return parse errors explaining that file imports are disabled.

func (Context) HasNamedContext 

func (pCtx Context) HasNamedContext(name string) bool

HasNamedContext returns true if a given name exists as a named context.

func (Context) ImportFile added in v4.21.0 

func (pCtx Context) ImportFile(name string) ([]byte, error)

ImportFile attempts to read a file for import via the customised Importer.

func (Context) InitFunction 

func (pCtx Context) InitFunction(name string, args *query.ParsedParams) (query.Function, error)

InitFunction attempts to initialise a function from the available constructors of the parser context.

func (Context) InitMethod 

func (pCtx Context) InitMethod(name string, target query.Function, args *query.ParsedParams) (query.Function, error)

InitMethod attempts to initialise a method from the available constructors of the parser context.

func (Context) WithImporter 

func (pCtx Context) WithImporter(importer Importer) Context

WithImporter returns a Context where imports are made from the provided Importer implementation.

func (Context) WithImporterRelativeToFile 

func (pCtx Context) WithImporterRelativeToFile(pathStr string) Context

WithImporterRelativeToFile returns a Context where any relative imports will be made from the directory of the provided file path. The provided path can itself be relative (to the current importer directory) or absolute.

func (Context) WithNamedContext 

func (pCtx Context) WithNamedContext(name string) Context

WithNamedContext returns a Context with a named execution context.

type DelimitedResult 

type DelimitedResult[P, D any] struct {
	Primary   []P
	Delimiter []D
}

DelimitedResult is an explicit result struct returned by the Delimited parser, containing a slice of primary parser payloads and a slice of delimited parser payloads.

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 ParseField 

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

ParseField attempts to parse a field expression.

func ParseMapping 

func ParseMapping(pCtx Context, 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 Func 

type Func[T any] func([]rune) Result[T]

Func is the common signature of a parser function.

func Array 

func Array() Func[[]any]

Array parses an array literal.

func BestMatch 

func BestMatch[T any](parsers ...Func[T]) Func[T]

BestMatch accepts one or more parsers and tries them all against an input. If all parsers return either a result or an error 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 Char 

func Char(c rune) Func[string]

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

func Delimited 

func Delimited[P, D any](primary Func[P], delimiter Func[D]) Func[DelimitedResult[P, D]]

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[S, P, D, E any](
	start Func[S], primary Func[P], delimiter Func[D], stop Func[E],
) Func[[]P]

DelimitedPattern attempts to parse zero or more primary parsers in between a 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.

func Discard 

func Discard[T any](parser Func[T]) Func[T]

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[T any](parser Func[T]) Func[T]

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[T any](parser Func[T], expected ...string) Func[T]

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 FuncAsAny added in v4.26.0 

func FuncAsAny[T any](f Func[T]) Func[any]

FuncAsAny converts a Func of type Tin into a Func of type any. The payload is passed unchanged but cast into an any.

func InRange 

func InRange(lower, upper rune) Func[string]

InRange parses any number of characters between two runes inclusive.

func InSet 

func InSet(set ...rune) Func[string]

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

func JoinStringPayloads 

func JoinStringPayloads(p Func[[]string]) Func[string]

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() Func[any]

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

func MustBe 

func MustBe[T any](parser Func[T]) Func[T]

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

func NotChar 

func NotChar(c rune) Func[string]

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

func NotInSet 

func NotInSet(set ...rune) Func[string]

NotInSet parses any number of characters until a rune within a given set is encountered.

func Object 

func Object() Func[map[string]any]

Object parses an object literal.

func OneOf 

func OneOf[T any](parsers ...Func[T]) Func[T]

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[T any](parser Func[T]) Func[T]

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

func OptionalPtr added in v4.26.0 

func OptionalPtr[T any](parser Func[T]) Func[*T]

OptionalPtr 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 (but converted to a pointer type).

func Sequence 

func Sequence[T any](parsers ...Func[T]) Func[[]T]

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

func TakeOnly added in v4.26.0 

func TakeOnly[T any](index int, p Func[[]T]) Func[T]

TakeOnly wraps an array based combinator with one that only extracts a single element of the resulting values. NOTE: If the index is

func Term 

func Term(term string) Func[string]

Term parses a single instance of a string.

func UntilFail 

func UntilFail[T any](parser Func[T]) Func[[]T]

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.

func UntilTerm 

func UntilTerm(term string) Func[string]

UntilTerm parses any number of characters until an instance of a string is met. The provided term is not included in the result.

func ZeroedFuncAs added in v4.26.0 

func ZeroedFuncAs[Tin, Tout any](f Func[Tin]) Func[Tout]

ZeroedFuncAs converts a Func of type Tin into a Func of type Tout.

WARNING: No conversion is made between payloads of Tin to Tout, instead a zero value of Tout will be emitted.

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 Importer 

type Importer interface {
	// Import a file from a relative or absolute path.
	Import(pathStr string) ([]byte, error)

	// Derive a new importer where relative import paths are resolved from the
	// directory of the provided file path. The provided path could be absolute,
	// or relative itself in which case it should be resolved from the
	// pre-existing relative directory.
	RelativeToFile(filePath string) Importer
}

Importer represents a repository of bloblang files that can be imported by mappings. It's possible for mappings to import files using relative paths, if the import is from a mapping which was itself imported then the path should be interpretted as relative to that file.

type Result 

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

Result represents the result of a parser given an input.

func EmptyLine 

func EmptyLine(r []rune) Result[any]

EmptyLine ensures that a line is empty, but doesn't advance the parser beyond the newline char.

func EndOfInput 

func EndOfInput(r []rune) Result[any]

EndOfInput ensures that the input is now empty.

func Fail 

func Fail[T any](err *Error, input []rune) Result[T]

Fail creates a result with an error from failed parsing.

func QuotedString 

func QuotedString(input []rune) Result[string]

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

func ResultInto added in v4.26.0 

func ResultInto[T, L any](from Result[L]) Result[T]

func Success 

func Success[T any](payload T, remaining []rune) Result[T]

Success creates a result with a payload from successful parsing.

func TripleQuoteString 

func TripleQuoteString(input []rune) Result[string]

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.