diff --git a/bexpr.go b/bexpr.go index c89dc67..4b5a35c 100644 --- a/bexpr.go +++ b/bexpr.go @@ -1,10 +1,10 @@ // Copyright (c) HashiCorp, Inc. // SPDX-License-Identifier: MPL-2.0 -// bexpr is an implementation of a generic boolean expression evaluator. +// Package bexpr is an implementation of a generic boolean expression evaluator. // The general goal is to be able to evaluate some expression against some -// arbitrary data and get back a boolean of whether or not the data -// was matched by the expression +// arbitrary data and get back a boolean indicating if the data was matched by +// the expression package bexpr //go:generate pigeon -o grammar/grammar.go -optimize-parser grammar/grammar.peg @@ -15,7 +15,7 @@ import ( "github.com/mitchellh/pointerstructure" ) -// HookFn provides a way to translate one reflect.Value to another during +// ValueTransformationHookFn provides a way to translate one reflect.Value to another during // evaluation by bexpr. This facilitates making Go structures appear in a way // that matches the expected JSON Pointers used for evaluation. This is // helpful, for example, when working with protocol buffers' well-known types. @@ -27,8 +27,13 @@ type Evaluator struct { tagName string valueTransformationHook ValueTransformationHookFn unknownVal *interface{} + expression string } +// CreateEvaluator is used to create and configure a new Evaluator, the expression +// will be used by the evaluator when evaluating against any supplied datum. +// The following Option types are supported: +// WithHookFn, WithMaxExpressions, WithTagName, WithUnknownValue. func CreateEvaluator(expression string, opts ...Option) (*Evaluator, error) { parsedOpts := getOpts(opts...) var parserOpts []grammar.Option @@ -46,11 +51,15 @@ func CreateEvaluator(expression string, opts ...Option) (*Evaluator, error) { tagName: parsedOpts.withTagName, valueTransformationHook: parsedOpts.withHookFn, unknownVal: parsedOpts.withUnknown, + expression: expression, } return eval, nil } +// Evaluate attempts to match the configured expression against the supplied datum. +// It returns a value indicating if a match was found and any error that occurred. +// If an error is returned, the value indicating a match will be false. func (eval *Evaluator) Evaluate(datum interface{}) (bool, error) { opts := []Option{ WithTagName(eval.tagName), @@ -62,3 +71,8 @@ func (eval *Evaluator) Evaluate(datum interface{}) (bool, error) { return evaluate(eval.ast, datum, opts...) } + +// Expression can be used to return the initial expression used to create the Evaluator. +func (eval *Evaluator) Expression() string { + return eval.expression +}