exp

package module
v0.8.3 Latest Latest
Warning

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

Go to latest
Published: Jan 22, 2024 License: Apache-2.0 Imports: 1 Imported by: 12

README

Expressions 🤩

GoDoc Version Build Status Go Report Card Codecov

Intermediate Expression Formats for the Masses

Every database has its own query language, so this library provides in intermediate format that should be easy to convert into whatever specific language you need to use.

The expression library only represents the structure of the logical expression, and does not include implementations for any data sources. Those should be implemented in each individual data source adapter library.


// build single predicate expressions
criteria := exp.Equal("_id", 42)

// use chaining for logical constructs
criteria := exp.Equal("_id", 42).AndEqual("deleteDate",  0)
criteria := exp.Equal("name", "John").OrEqual("name", "Sarah")

// Also supports complex and/or logic

criteria := exp.Or(
    exp.Equal("_id", 42).AndEqual("deleteDate",  0),
    exp.Equal("_id", 42).AndEqual("name", "Sarah"),
)

// Constants define standard expected operators
data.OperatorEqual          = "="
data.OperatorNotEqual       = "!="
data.OperatorLessThan       = "<"
data.OperatorLessOrEqual    = "<="
data.OperatorGreaterThan    = ">"
data.OperatorGreaterOrEqual = ">="

Interfaces

This is accomplished with three very similar data types that all implement the same Expression interface.

Predicate represents a single predicate/comparison. Using .And() and .Or() will return the corresponding AndExpression or OrExpression object

AndExpression represents multiple predicates, all chained together with AND logic. Only supports the .And() method for additional predicates

OrExpression represents multiple predicates, all chained together with OR logic. Only supports the .Or() method for additional predicates.

Manually Walking the Logic Tree

Each of the three interfaces above implements a .Match() function that can be used by external programs to see if a dataset matches this exp. You must pass in a MatcherFunc that accepts a predicate and returns TRUE if that predicate matches the dataaset. AndExpression and OrExpression objects will call this function repeatedly for each element in their logic tree, and return a final boolean value for the entire logic structure.

Pull Requests Welcome

This library is a work in progress, and will benefit from your experience reports, use cases, and contributions. If you have an idea for making this library better, send in a pull request. We're all in this together! 🤩

Documentation

Index

Constants

View Source
const OperatorBeginsWith = "BEGINS"

OperatorBeginsWith represents a "begins with" comparison, when used in Predicates and Criteria. It is only valid for string values.

View Source
const OperatorContainedBy = "CONTAINED BY"

OperatorContainedBy represents a "contained by" comparison, when used in Predicates and Criteria. It is only valid for string values.

View Source
const OperatorContains = "CONTAINS"

OperatorContains represents a "contains" comparison, when used in Predicates and Criteria. It is only valid for string values.

View Source
const OperatorEndsWith = "ENDS"

OperatorEndsWith represents a "ends with" comparison, when used in Predicates and Criteria. It is only valid for string values.

View Source
const OperatorEqual = "="

OperatorEqual represents an "equals" comparison, when used in Predicates and Criteria

View Source
const OperatorGreaterOrEqual = ">="

OperatorGreaterOrEqual represents an "greater or equal" comparison, when used in Predicates and Criteria

View Source
const OperatorGreaterThan = ">"

OperatorGreaterThan represents an "greater than" comparison, when used in Predicates and Criteria

View Source
const OperatorIn = "IN"

OperatorIn represents a "in" comparison, when used in Predicates and Criteria.

View Source
const OperatorLessOrEqual = "<="

OperatorLessOrEqual represents an "less or equal" comparison, when used in Predicates and Criteria

View Source
const OperatorLessThan = "<"

OperatorLessThan represents a "less than" comparison, when used in Predicates and Criteria

View Source
const OperatorNotEqual = "!="

OperatorNotEqual represents a "not equals" comparison, when used in Predicates and Criteria

View Source
const OperatorNotIn = "NOT IN"

OperatorNotIn represents a "not in" comparison, when used in Predicates and Criteria.

Variables

This section is empty.

Functions

func Operator added in v0.1.0

func Operator(value string) string

func OperatorOk added in v0.8.1

func OperatorOk(value string) (string, bool)

OperatorOk tries to convert non-standard values into standard operators. If a match is found, then it returns the standardized value and TRUE. If a match is not found, then the default EQUAL is returned along with a FALSE.

Types

type AndExpression

type AndExpression []Expression

AndExpression combines a series of sub-expressions using AND logic

func And

func And(expressions ...Expression) AndExpression

And combines one or more expression parameters into an AndExpression

func (AndExpression) And

func (e AndExpression) And(exp Expression) Expression

func (AndExpression) AndEqual

func (e AndExpression) AndEqual(name string, value any) Expression

func (AndExpression) AndGreaterOrEqual

func (e AndExpression) AndGreaterOrEqual(name string, value any) Expression

func (AndExpression) AndGreaterThan

func (e AndExpression) AndGreaterThan(name string, value any) Expression

func (AndExpression) AndIn added in v0.1.2

func (e AndExpression) AndIn(name string, value any) Expression

func (AndExpression) AndLessOrEqual

func (e AndExpression) AndLessOrEqual(name string, value any) Expression

func (AndExpression) AndLessThan

func (e AndExpression) AndLessThan(name string, value any) Expression

func (AndExpression) AndNotEqual

func (e AndExpression) AndNotEqual(name string, value any) Expression

func (AndExpression) AndNotIn added in v0.1.2

func (e AndExpression) AndNotIn(name string, value any) Expression

func (AndExpression) IsEmpty added in v0.8.0

func (e AndExpression) IsEmpty() bool

func (AndExpression) Match

func (e AndExpression) Match(fn MatcherFunc) bool

Match implements the Expression interface. It loops through all sub-expressions and returns TRUE if all of them match

func (AndExpression) NotEmpty added in v0.8.0

func (e AndExpression) NotEmpty() bool

func (AndExpression) Or added in v0.1.0

type EmptyExpression added in v0.1.0

type EmptyExpression struct{}

func (EmptyExpression) And added in v0.1.0

func (EmptyExpression) AndEqual added in v0.1.2

func (e EmptyExpression) AndEqual(name string, value any) Expression

func (EmptyExpression) AndGreaterOrEqual added in v0.1.2

func (e EmptyExpression) AndGreaterOrEqual(name string, value any) Expression

func (EmptyExpression) AndGreaterThan added in v0.1.2

func (e EmptyExpression) AndGreaterThan(name string, value any) Expression

func (EmptyExpression) AndIn added in v0.1.2

func (e EmptyExpression) AndIn(name string, value any) Expression

func (EmptyExpression) AndLessOrEqual added in v0.1.2

func (e EmptyExpression) AndLessOrEqual(name string, value any) Expression

func (EmptyExpression) AndLessThan added in v0.1.2

func (e EmptyExpression) AndLessThan(name string, value any) Expression

func (EmptyExpression) AndNotEqual added in v0.1.2

func (e EmptyExpression) AndNotEqual(name string, value any) Expression

func (EmptyExpression) AndNotIn added in v0.1.2

func (e EmptyExpression) AndNotIn(name string, value any) Expression

func (EmptyExpression) IsEmpty added in v0.8.0

func (e EmptyExpression) IsEmpty() bool

func (EmptyExpression) Match added in v0.1.0

func (e EmptyExpression) Match(fn MatcherFunc) bool

func (EmptyExpression) NotEmpty added in v0.8.0

func (e EmptyExpression) NotEmpty() bool

func (EmptyExpression) Or added in v0.1.0

type Expression

type Expression interface {

	// And returns a new expression that combines this expression with another as an AndExpression
	And(Expression) Expression

	// Or returns a new expression that combines this expression with another as an OrExpression
	Or(Expression) Expression

	Match(MatcherFunc) bool

	// AndEqual is a shortcut that creates a new AndExpression using the Equal comparison
	AndEqual(name string, value any) Expression

	// AndNotEqual is a shortcut that creates a new AndExpression using the NotEqual comparison
	AndNotEqual(name string, value any) Expression

	// AndLessThan is a shortcut that creates a new AndExpression using the LessThan comparison
	AndLessThan(name string, value any) Expression

	// AndLessOrEqual is a shortcut that creates a new AndExpression using the LessOrEqual comparison
	AndLessOrEqual(name string, value any) Expression

	// AndGreaterThan is a shortcut that creates a new AndExpression using the GreaterThan comparison
	AndGreaterThan(name string, value any) Expression

	// AndGreaterOrEqual is a shortcut that creates a new AndExpression using the GreaterOrEqual comparison
	AndGreaterOrEqual(name string, value any) Expression

	// AndIn is a shortcut that creates a new AndExpression using the In comparison
	AndIn(name string, value any) Expression

	// AndNotIn is a shortcut that creates a new AndExpression using the NotIn comparison
	AndNotIn(name string, value any) Expression

	// IsEmpty returns TRUE if an expression does not have any predicates
	IsEmpty() bool

	// NotEmpty returns TRUE if an expression has one or more predicates
	NotEmpty() bool
}

Expression is an interface that is implemented by Predicates, AndExpressions, and OrExpressions. It enables any of these items to be embedded into the criteria of a data.Query

func All

func All() Expression

All a syntactic sugar alias for And(), so that expressions that query all values in a dataset read nicely.

func Empty added in v0.1.0

func Empty() Expression

func Parse added in v0.7.0

func Parse(value string) Expression

Parse converts a string into an Expression

type MatcherFunc

type MatcherFunc func(Predicate) bool

MatcherFunc is a function signature that is passed in to the .Match() functions of every Expression. It allows the caller to handle the actual matching independently of their underlying data, while the Expression objects handle the program flow.

type OrExpression

type OrExpression []Expression

OrExpression compares a series of sub-expressions, using the OR logic

func Or

func Or(expressions ...Expression) OrExpression

Or combines one or more expression parameters into an OrExpression

func (OrExpression) And added in v0.1.0

func (e OrExpression) And(exp Expression) Expression

And returns a fully populated AndExpression

func (OrExpression) AndEqual added in v0.1.2

func (e OrExpression) AndEqual(name string, value any) Expression

func (OrExpression) AndGreaterOrEqual added in v0.1.2

func (e OrExpression) AndGreaterOrEqual(name string, value any) Expression

func (OrExpression) AndGreaterThan added in v0.1.2

func (e OrExpression) AndGreaterThan(name string, value any) Expression

func (OrExpression) AndIn added in v0.1.2

func (e OrExpression) AndIn(name string, value any) Expression

func (OrExpression) AndLessOrEqual added in v0.1.2

func (e OrExpression) AndLessOrEqual(name string, value any) Expression

func (OrExpression) AndLessThan added in v0.1.2

func (e OrExpression) AndLessThan(name string, value any) Expression

func (OrExpression) AndNotEqual added in v0.1.2

func (e OrExpression) AndNotEqual(name string, value any) Expression

func (OrExpression) AndNotIn added in v0.1.2

func (e OrExpression) AndNotIn(name string, value any) Expression

func (OrExpression) IsEmpty added in v0.8.0

func (e OrExpression) IsEmpty() bool

func (OrExpression) Match

func (e OrExpression) Match(fn MatcherFunc) bool

Match implements the Expression interface. It loops through all sub-expressions and returns TRUE if any of them match

func (OrExpression) NotEmpty added in v0.8.0

func (e OrExpression) NotEmpty() bool

func (OrExpression) Or

Or appends a new expression into this compound expression

type Predicate

type Predicate struct {
	Field    string
	Operator string
	Value    any
}

Predicate represents a single true/false comparison

func BeginsWith

func BeginsWith(field string, value any) Predicate

BeginsWith creates a new Predicate using an "BeginsWith" comparison

func ContainedBy added in v0.1.0

func ContainedBy(field string, value any) Predicate

ContainedBy creates a new Predicate using an "ContainedBy" comparison

func Contains

func Contains(field string, value any) Predicate

Contains creates a new Predicate using an "Contains" comparison

func EndsWith

func EndsWith(field string, value any) Predicate

EndsWith creates a new Predicate using an "EndsWith" comparison

func Equal

func Equal(field string, value any) Predicate

Equal creates a new Predicate using an "Equals" comparison

func GreaterOrEqual

func GreaterOrEqual(field string, value any) Predicate

GreaterOrEqual creates a new Predicate using an "Greater Or Equal" comparison

func GreaterThan

func GreaterThan(field string, value any) Predicate

GreaterThan creates a new Predicate using an "Greater Than" comparison

func In added in v0.1.1

func In(field string, value any) Predicate

In creates a new Predicate using an "in" comparison

func LessOrEqual

func LessOrEqual(field string, value any) Predicate

LessOrEqual creates a new Predicate using an "Less Or Equal" comparison

func LessThan

func LessThan(field string, value any) Predicate

LessThan creates a new Predicate using an "Less Than" comparison

func New

func New(field string, operator string, value any) Predicate

New returns a fully populated Predicate

func NotEqual

func NotEqual(field string, value any) Predicate

NotEqual creates a new Predicate using an "Not Equals" comparison

func (Predicate) And

func (predicate Predicate) And(exp Expression) Expression

And combines this predicate with another pre-existing expression into a new And expression

func (Predicate) AndEqual

func (predicate Predicate) AndEqual(name string, value any) Expression

AndEqual combines this predicate with another one (created from the arguments) into an AndExpression

func (Predicate) AndGreaterOrEqual

func (predicate Predicate) AndGreaterOrEqual(name string, value any) Expression

AndGreaterOrEqual combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) AndGreaterThan

func (predicate Predicate) AndGreaterThan(name string, value any) Expression

AndGreaterThan combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) AndIn added in v0.1.2

func (predicate Predicate) AndIn(name string, value any) Expression

AndIn combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) AndLessOrEqual

func (predicate Predicate) AndLessOrEqual(name string, value any) Expression

AndLessOrEqual combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) AndLessThan

func (predicate Predicate) AndLessThan(name string, value any) Expression

AndLessThan combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) AndNotEqual

func (predicate Predicate) AndNotEqual(name string, value any) Expression

AndNotEqual combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) AndNotIn added in v0.1.2

func (predicate Predicate) AndNotIn(name string, value any) Expression

AndNotIn combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) IsEmpty added in v0.8.0

func (predicate Predicate) IsEmpty() bool

func (Predicate) Match

func (predicate Predicate) Match(fn MatcherFunc) bool

Match implements the Expression interface. It uses a MatcherFunc to determine if this predicate matches an arbitrary dataset.

func (Predicate) NotEmpty added in v0.8.0

func (predicate Predicate) NotEmpty() bool

func (Predicate) Or

func (predicate Predicate) Or(exp Expression) Expression

Or combines this predicate with another pre-existing expression into a new Or expression

func (Predicate) OrEqual added in v0.6.0

func (predicate Predicate) OrEqual(name string, value any) Expression

OrEqual combines this predicate with another one (created from the arguments) into an OrExpression

func (Predicate) OrGreaterOrEqual added in v0.6.0

func (predicate Predicate) OrGreaterOrEqual(name string, value any) Expression

OrGreaterOrEqual combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) OrGreaterThan added in v0.6.0

func (predicate Predicate) OrGreaterThan(name string, value any) Expression

OrGreaterThan combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) OrIn added in v0.6.0

func (predicate Predicate) OrIn(name string, value any) Expression

OrIn combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) OrLessOrEqual added in v0.6.0

func (predicate Predicate) OrLessOrEqual(name string, value any) Expression

OrLessOrEqual combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) OrLessThan added in v0.6.0

func (predicate Predicate) OrLessThan(name string, value any) Expression

OrLessThan combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) OrNotEqual added in v0.6.0

func (predicate Predicate) OrNotEqual(name string, value any) Expression

OrNotEqual combines this predicate with another one (created from the arguments) into an Expression

func (Predicate) OrNotIn added in v0.6.0

func (predicate Predicate) OrNotIn(name string, value any) Expression

OrNotIn combines this predicate with another one (created from the arguments) into an Expression

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL