Updated godocs

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
+}