parser

Documentation

Overview

Package parser provides AIP-160 compliant parser for filtering expressions. The parser is not thread-safe.

The implementation satisfies all the requirements of AIP-160, and parses an input string filter expression into an AST.

A parser is created by calling NewParser, and can be optimized for a specific needs by providing a set of options.

Example:

func main() {
 p := parser.NewParser(parser.ErrorHandler(func(pos token.Position, msg string) {
     log.Printf("Error at %s: %s", pos, msg)
 }))

 expr, err := p.Parse("foo:bar")
 if err != nil {
     log.Fatal(err)
 }

The parser by default doesn't recognize any identifiers, and values. The literals are either a *ast.TextLiteral or *ast.StringLiteral. What's more as defined in the ebnf grammar, if a TEXT literal contains a dot (.) character, it is separated into two TEXT literals. This behavior can be difficult to handle literals with a period (.) in their definitions. To solve this problem, the parser provides MemberHandler functions which can be used to merge and (if needed) split literals. An example of such a function is the ParseMemberNumber function, which tries to decode a *ast.MemberExpr elements, and parses their value either as a float64 or int64. What's more in case of a float64, it merges the two literals into one, and sets the value of the first literal to the string representation of the float64 value. In addition, it keeps the decoded value in a DecodedValue field of the *ast.MemberExpr, which could be reused later.

Example:

func main() {
 p := parser.NewParser(parser.ArgMemberModifierOption(parser.ParseMemberNumber))

 expr, err := p.Parse("m = 1.0")
 if err != nil {
     log.Fatal(err)
 }
 // expr is a *parser.ParsedFilter, which contains a *ast.RestrictionExpr.
 // it has a Comparable field set to a 'm' *ast.MemberExpr, with a Value of *ast.TextLiteral.Value = "a",
 // in addition it has an Arg ast.ArgExpr which is a *ast.MemberExpr with a single Value of
 // *ast.TextLiteral.Value = "1.0", and a DecodedValue == float64(1.0).
 // If no ArgMemberModifierOption was provided, the Arg would be a *ast.MemberExpr with a
 // Value = *ast.TextLiteral.Value = "1" and a Field = *ast.TextLiteral.Value = "0".

Index

• Variables
• type ParsedFilter
  • func (p *ParsedFilter) Free()
• type Parser
  • func NewParser(src string, opts ...ParserOption) *Parser
  • func (p *Parser) Parse() (*ParsedFilter, error)
  • func (p *Parser) Reset(src string, opts ...ParserOption)
• type ParserOption
  • func ErrorHandlerOption(err scanner.ErrorHandler) ParserOption
  • func StrictWhitespacesOption() ParserOption

Examples

• NewParser

Variables

var ErrInvalidFilterSyntax = errors.New("invalid filter")

ErrInvalidFilterSyntax is returned when the input string filter has invalid syntax.

Types

type ParsedFilter

type ParsedFilter struct {
	// Expr is a parsed filter expression, possibly nil (for empty filter).
	Expr *ast.Expr
}

ParsedFilter is a parsed filter expression.

func (*ParsedFilter) Free

func (p *ParsedFilter) Free()

Free frees the resource associated with the parsed filter. This should be used in a defer statement immediately after calling Parse. No further use of any filter expressions is allowed after calling Free.

type Parser

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

Parser is responsible for parsing the input string filter into an AST.

func NewParser

func NewParser(src string, opts ...ParserOption) *Parser

NewParser creates a new parser with the given options.

Example

package main

import (
	"fmt"
	"os"

	"github.com/blockysource/blocky-aip/filtering/ast"
	"github.com/blockysource/blocky-aip/filtering/parser"
)

func main() {
	p := parser.NewParser("m = 10")

	parsed, err := p.Parse()
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	defer parsed.Free()

	r := parsed.Expr.Sequences[0].Factors[0].Terms[0].Expr.(*ast.RestrictionExpr)

	left := r.Comparable.(*ast.MemberExpr).Value.(*ast.TextLiteral)

	right := r.Arg.(*ast.MemberExpr).Value.(*ast.TextLiteral)

	fmt.Printf("left: %s, right: %s", left.Value, right.Value)

}

Output:

left: m, right: 10

func (*Parser) Parse

func (p *Parser) Parse() (*ParsedFilter, error)

Parse parses the input string filter into an AST. If the input was an empty string, the returned ParsedFilter will have a nil Expr.

func (*Parser) Reset

func (p *Parser) Reset(src string, opts ...ParserOption)

Reset resets the parser with the given input string.

type ParserOption

type ParserOption func(p *Parser)

ParserOption changes the behavior of the parser.

func ErrorHandlerOption

func ErrorHandlerOption(err scanner.ErrorHandler) ParserOption

ErrorHandlerOption sets the error handler of the parser.

func StrictWhitespacesOption

func StrictWhitespacesOption() ParserOption

StrictWhitespacesOption makes the parser to fail if there are more than one whitespace between specific expresions.