parser

Documentation

Overview

Package parser declares an expression parser with support for macro expansion.

Index

• Constants
• Variables
• func Parse(source common.Source) (*exprpb.ParsedExpr, *common.Errors)
• func ParseWithMacros(source common.Source, macros []Macro) (*exprpb.ParsedExpr, *common.Errors)
• func Unparse(expr *exprpb.Expr, info *exprpb.SourceInfo) (string, error)
• type ExprHelper
• type Macro
  • func NewGlobalMacro(function string, argCount int, expander MacroExpander) Macro
  • func NewGlobalVarArgMacro(function string, expander MacroExpander) Macro
  • func NewReceiverMacro(function string, argCount int, expander MacroExpander) Macro
  • func NewReceiverVarArgMacro(function string, expander MacroExpander) Macro
• type MacroExpander

Constants

const AccumulatorName = "__result__"

AccumulatorName is the traditional variable name assigned to the fold accumulator variable.

Variables

var (
	// AllMacros includes the list of all spec-supported macros.
	AllMacros = []Macro{

		NewGlobalMacro(operators.Has, 1, makeHas),

		NewReceiverMacro(operators.All, 2, makeAll),

		NewReceiverMacro(operators.Exists, 2, makeExists),

		NewReceiverMacro(operators.ExistsOne, 2, makeExistsOne),

		NewReceiverMacro(operators.Map, 2, makeMap),

		NewReceiverMacro(operators.Map, 3, makeMap),

		NewReceiverMacro(operators.Filter, 2, makeFilter),
	}

	// NoMacros list.
	NoMacros = []Macro{}
)

Functions

func Parse

func Parse(source common.Source) (*exprpb.ParsedExpr, *common.Errors)

Parse converts a source input a parsed expression. This function calls ParseWithMacros with AllMacros.

func ParseWithMacros

func ParseWithMacros(source common.Source, macros []Macro) (*exprpb.ParsedExpr, *common.Errors)

ParseWithMacros converts a source input and macros set to a parsed expression.

func Unparse

func Unparse(expr *exprpb.Expr, info *exprpb.SourceInfo) (string, error)

Unparse takes an input expression and source position information and generates a human-readable expression.

Note, unparsing an AST will often generate the same expression as was originally parsed, but some formatting may be lost in translation, notably:

- All quoted literals are doubled quoted. - Byte literals are represented as octal escapes (same as Google SQL). - Floating point values are converted to the small number of digits needed to represent the value. - Spacing around punctuation marks may be lost. - Parentheses will only be applied when they affect operator precedence.

Types

type ExprHelper

type ExprHelper interface {
	// LiteralBool creates an Expr value for a bool literal.
	LiteralBool(value bool) *exprpb.Expr

	// LiteralBytes creates an Expr value for a byte literal.
	LiteralBytes(value []byte) *exprpb.Expr

	// LiteralDouble creates an Expr value for double literal.
	LiteralDouble(value float64) *exprpb.Expr

	// LiteralInt creates an Expr value for an int literal.
	LiteralInt(value int64) *exprpb.Expr

	// LiteralString creates am Expr value for a string literal.
	LiteralString(value string) *exprpb.Expr

	// LiteralUint creates an Expr value for a uint literal.
	LiteralUint(value uint64) *exprpb.Expr

	// NewList creates a CreateList instruction where the list is comprised of the optional set
	// of elements provided as arguments.
	NewList(elems ...*exprpb.Expr) *exprpb.Expr

	// NewMap creates a CreateStruct instruction for a map where the map is comprised of the
	// optional set of key, value entries.
	NewMap(entries ...*exprpb.Expr_CreateStruct_Entry) *exprpb.Expr

	// NewMapEntry creates a Map Entry for the key, value pair.
	NewMapEntry(key *exprpb.Expr, val *exprpb.Expr) *exprpb.Expr_CreateStruct_Entry

	// NewObject creates a CreateStruct instruction for an object with a given type name and
	// optional set of field initializers.
	NewObject(typeName string, fieldInits ...*exprpb.Expr_CreateStruct_Entry) *exprpb.Expr

	// NewObjectFieldInit creates a new Object field initializer from the field name and value.
	NewObjectFieldInit(field string, init *exprpb.Expr) *exprpb.Expr_CreateStruct_Entry

	// Fold creates a fold comprehension instruction.
	//
	// - iterVar is the iteration variable name.
	// - iterRange represents the expression that resolves to a list or map where the elements or
	//   keys (respectively) will be iterated over.
	// - accuVar is the accumulation variable name, typically parser.AccumulatorName.
	// - accuInit is the initial expression whose value will be set for the accuVar prior to
	//   folding.
	// - condition is the expression to test to determine whether to continue folding.
	// - step is the expression to evaluation at the conclusion of a single fold iteration.
	// - result is the computation to evaluate at the conclusion of the fold.
	//
	// The accuVar should not shadow variable names that you would like to reference within the
	// environment in the step and condition expressions. Presently, the name __result__ is commonly
	// used by built-in macros but this may change in the future.
	Fold(iterVar string,
		iterRange *exprpb.Expr,
		accuVar string,
		accuInit *exprpb.Expr,
		condition *exprpb.Expr,
		step *exprpb.Expr,
		result *exprpb.Expr) *exprpb.Expr

	// Ident creates an identifier Expr value.
	Ident(name string) *exprpb.Expr

	// GlobalCall creates a function call Expr value for a global (free) function.
	GlobalCall(function string, args ...*exprpb.Expr) *exprpb.Expr

	// ReceiverCall creates a function call Expr value for a receiver-style function.
	ReceiverCall(function string, target *exprpb.Expr, args ...*exprpb.Expr) *exprpb.Expr

	// PresenceTest creates a Select TestOnly Expr value for modelling has() semantics.
	PresenceTest(operand *exprpb.Expr, field string) *exprpb.Expr

	// Select create a field traversal Expr value.
	Select(operand *exprpb.Expr, field string) *exprpb.Expr

	// OffsetLocation returns the Location of the expression identifier.
	OffsetLocation(exprID int64) common.Location
}

ExprHelper assists with the manipulation of proto-based Expr values in a manner which is consistent with the source position and expression id generation code leveraged by both the parser and type-checker.

type Macro

type Macro interface {
	// Function name to match.
	Function() string

	// ArgCount for the function call.
	//
	// When the macro is a var-arg style macro, the return value will be zero, but the MacroKey
	// will contain a `*` where the arg count would have been.
	ArgCount() int

	// IsReceiverStyle returns true if the macro matches a receiver style call.
	IsReceiverStyle() bool

	// MacroKey returns the macro signatures accepted by this macro.
	//
	// Format: `<function>:<arg-count>:<is-receiver>`.
	//
	// When the macros is a var-arg style macro, the `arg-count` value is represented as a `*`.
	MacroKey() string

	// Expander returns the MacroExpander to apply when the macro key matches the parsed call
	// signature.
	Expander() MacroExpander
}

Macro interface for describing the function signature to match and the MacroExpander to apply.

Note: when a Macro should apply to multiple overloads (based on arg count) of a given function, a Macro should be created per arg-count.

func NewGlobalMacro

func NewGlobalMacro(function string, argCount int, expander MacroExpander) Macro

NewGlobalMacro creates a Macro for a global function with the specified arg count.

func NewGlobalVarArgMacro

func NewGlobalVarArgMacro(function string, expander MacroExpander) Macro

NewGlobalVarArgMacro creates a Macro for a global function with a variable arg count.

func NewReceiverMacro

func NewReceiverMacro(function string, argCount int, expander MacroExpander) Macro

NewReceiverMacro creates a Macro for a receiver function matching the specified arg count.

func NewReceiverVarArgMacro

func NewReceiverVarArgMacro(function string, expander MacroExpander) Macro

NewReceiverVarArgMacro creates a Macro for a receiver function matching a variable arg count.

type MacroExpander

type MacroExpander func(eh ExprHelper,
	target *exprpb.Expr,
	args []*exprpb.Expr) (*exprpb.Expr, *common.Error)

MacroExpander converts the target and args of a function call that matches a Macro.

Note: when the Macros.IsReceiverStyle() is true, the target argument will be nil.