A micro conditional javascript engine used to parse the raw logical and comparison expressions, evaluate the expression in the given data context, and provide access to a text form of the given expressions.
Revision: Feb 7, 2023.
Other implementations:
This project has been developed to provide Go(lang) implementation of spaceavocado/illogical.
go get -u github.com/spaceavocado/goillogical@latest
Table of Content
- (go)illogical
import (
illogical "github.com/spaceavocado/goillogical
)
// Create a new instance of the engine
i := illogical.New()
// Evaluate the raw expression
res, err := i.Evaluate([]any{"==", 1, 1}, map[string]any{})
For advanced usage, please Engine Options.
Evaluate comparison or logical expression:
i.evaluate(
Comparison Expression or Logical Expression, Evaluation Data Context)
=> boolean
Data context is optional.
Example
ctx := map[string]any{
"name": "peter",
}
// Comparison expression
i.Evaluate([]any{"==", 5, 5}, ctx)
i.Evaluate([]any{"==", "circle", "circle"}, ctx)
i.Evaluate([]any{"==", true, true}, ctx)
i.Evaluate([]any{"==", "$name", "peter"}, ctx)
i.Evaluate([]any{"NIL", "$RefA"}, ctx)
// Logical expression
i.Evaluate([]any{"AND", []any{"==", 5, 5}, []any{"==", 10, 10}}, ctx)
i.Evaluate([]any{"AND", []any{"==", "circle", "circle"}, []any{"==", 10, 10}}, ctx)
i.Evaluate([]any{"OR", []any{"==", "$name", "peter"}, []any{"==", 5, 10}}, ctx)
Get expression string representation:
i.Statement(
Comparison Expression or Logical Expression)
=> string
Example
// Comparison expression
i.Statement([]any{"==", 5, 5}) // (5 == 5)
i.Statement([]any{"==", "circle", "circle"}) // ("circle" == "circle")
i.Statement([]any{"==", true, true}) // (true == true)
i.Statement([]any{"==", "$name", "peter"}) // ({name} == "peter")
i.Statement([]any{"NIL", "$RefA"}) // ({RefA} <is nil>)
// Logical expression
i.Statement([]any{"AND", []any{"==", 5, 5}, []any{"==", 10, 10}}) // ((5 == 5) AND (10 == 10))
i.Statement([]any{"AND", []any{"==", "circle", "circle"}, []any{"==", 10, 10}}) // (("circle" == "circle") AND (10 == 10))
i.Statement([]any{"OR", []any{"==", "$name", "peter"}, []any{"==", 5, 10}}) // (({name} == "peter") OR (5 == 10))
Parse the expression into a Evaluable object, i.e. it returns the parsed self-evaluable condition expression.
i.Parse(
Comparison Expression or Logical Expression)
=> Evaluable
evaluable.Evaluate(context)
please see Evaluation Data Context.evaluable.String()
please see Statement.evaluable.Simplify(context)
please see Simplify.
Example
e, err := i.Parse([]any{"==", "$name", "peter"})
e.Evaluate(map[string]any{"name": "peter"}) // true
e.String() // ({name} == "peter")
Simplifies an expression with a given context. This is useful when you already have some of the properties of context and wants to try to evaluate the expression.
Example
e, err := i.Parse([]any{"AND", []any{"==", "$a", 10}, []any{"==", "$b", 20}})
e.Simplify(map[string]any{"a": 10}) // ({b} == 20)
e.simplify(map[string]any{"a": 20}) // false
Values not found in the context will cause the parent operand not to be evaluated and returned as part of the simplified expression.
In some situations we might want to evaluate the expression even if referred value is not present. You can provide a list of keys that will be strictly evaluated even if they are not present in the context.
Example
simplifyOptions := illogical.WithReferenceSimplifyOptions(illogical.SimplifyOptions{
IgnoredPaths: []string{"ignored"},
IgnoredPathsRx: []regexp.Regexp{*regexp.MustCompile("^ignored")},
})
i := illogical.New(simplifyOptions)
e, err := i.Parse([]any{"AND", []any{"==", "$a", 10}, []any{"==", "$ignored", 20}})
e.Simplify(map[string]any{"a": 10})
// false
// $ignored" will be evaluated to nil.
Alternatively we might want to do the opposite and strictly evaluate the expression for all referred values not present in the context except for a specified list of optional keys.
Example
simplifyOptions := illogical.WithReferenceSimplifyOptions(illogical.SimplifyOptions{
IgnoredPaths: []string{"b"},
IgnoredPathsRx: []regexp.Regexp{},
})
i := illogical.New(simplifyOptions)
e, err := i.Parse([]any{"OR", []any{"==", "$a", 10}, []any{"==", "$b", 20}, []any{"==", "$c", 20}})
e.Simplify(map[string]any{"c": 10})
// ({a} == 10)
// except for "$b" everything not in context will be evaluated to nil.
Serializes an expression into the raw data form, reverse parse operation.
Example
e, err := i.Parse([]any{"AND", []any{"==", "$a", 10}, []any{"==", 10, 20}})
e.Serialize() // [AND [== $a 10] [== 10 20]]
The evaluation data context is used to provide the expression with variable references, i.e. this allows for the dynamic expressions. The data context is object with properties used as the references keys, and its values as reference values.
Valid reference values: object, string, number, [] boolean | string | number.
To reference the nested reference, please use "." delimiter, e.g.:
$address.city
$options[1]
$options[{index}]
- The index reference is resolved within the data context as an array index.
$address.{segment}
- The segment reference is resolved within the data context as a property key.
$shape{shapeType}
- The shapeType reference is resolved within the data context, and inserted into the outer reference key.
- E.g. shapeType is resolved as "B" and would compose the $shapeB outer reference.
- This resolution could be n-nested.
$payment.amount.(Type)
Cast the given data context into the desired data type before being used as an operand in the evaluation.
Note: If the conversion is invalid, then a warning message is being logged.
Supported data type conversions:
- .(String): cast a given reference to String.
- .(Number): cast a given reference to Number.
- .(Integer): cast a given reference to Integer.
- .(Float): cast a given reference to Float.
- .(Boolean): cast a given reference to Boolean.
Example
// Data context
ctx := map[string]any{
"name": "peter",
"country": "canada",
"age": 21,
"options": []int{1, 2, 3},
"address": struct {
city string
country string
}{
city: "Toronto",
country: "Canada",
},
"index": 2,
"segment": "city",
"shapeA": "box",
"shapeB": "circle",
"shapeType": "B",
}
// Evaluate an expression in the given data context
i.Evaluate([]any{">", "$age", 20}, ctx) // true
// Evaluate an expression in the given data context
i.Evaluate([]any{"==", "$address.city", "Toronto"}, ctx) // true
// Accessing Array Element
i.Evaluate([]any{"==", "$options[1]", 2}, ctx) // true
// Accessing Array Element via Reference
i.Evaluate([]any{"==", "$options[{index}]", 3}, ctx) // true
// Nested Referencing
i.Evaluate([]any{"==", "$address.{segment}", "Toronto"}, ctx) // true
// Composite Reference Key
i.Evaluate([]any{"==", "$shape{shapeType}", "circle"}, ctx) // true
// Data Type Casting
i.Evaluate([]any{"==", "$age.(String)", "21"}, ctx) // true
The Comparison Expression expect operands to be one of the below:
Simple value types: string, number, boolean.
Example
val1 := 5
var2 := "cirle"
var3 := true
i.Parse([]any{"AND", []any{"==", val1, var2}, []any{"==", var3, var3}})
The reference operand value is resolved from the Evaluation Data Context, where the the operands name is used as key in the context.
The reference operand must be prefixed with $
symbol, e.g.: $name
. This might be customized via Reference Predicate Parser Option.
Example
Expression | Data Context |
---|---|
["==", "$age", 21] |
{age: 21} |
["==", "circle", "$shape"] |
{shape: "circle"} |
["==", "$visible", true] |
{visible: true} |
The operand could be an array mixed from Value and Reference.
Example
Expression | Data Context |
---|---|
["IN", [1, 2], 1] |
{} |
["IN", "circle", ["$shapeA", "$shapeB"] |
{shapeA: "circle", shapeB: "box"} |
["IN", ["$number", 5], 5] |
{number: 3} |
Expression format: ["==",
Left Operand, Right Operand]
.
Valid operand types: string, number, boolean.
["==", 5, 5]
i.Evaluate([]any{"==", 5, 5}, ctx) // true
Expression format: ["!=",
Left Operand, Right Operand]
.
Valid operand types: string, number, boolean.
["!=", "circle", "square"]
i.Evaluate([]any{"!=", "circle", "square"}, ctx) // true
Expression format: [">",
Left Operand, Right Operand]
.
Valid operand types: number.
[">", 10, 5]
i.Evaluate([]any{">", 10, 5}, ctx) // true
Expression format: [">=",
Left Operand, Right Operand]
.
Valid operand types: number.
[">=", 5, 5]
i.Evaluate([]any{">=", 5, 5}, ctx) // true
Expression format: ["<",
Left Operand, Right Operand]
.
Valid operand types: number.
["<", 5, 10]
i.Evaluate([]any{"<", 5, 10}, ctx) // true
Expression format: ["<=",
Left Operand, Right Operand]
.
Valid operand types: number.
["<=", 5, 5]
i.Evaluate([]any{"<=", 5, 5}, ctx) // true
Expression format: ["IN",
Left Operand, Right Operand]
.
Valid operand types: number and number[] or string and string[].
["IN", 5, [1, 2, 3, 4, 5]]
["IN", ["circle", "square", "triangle"], "square"]
i.Evaluate([]any{"IN", 5, []int{1, 2, 3, 4, 5}}, ctx) // true
i.Evaluate([]any{"IN", []string{"circle", "square", "triangle"}, "square"}, ctx) // true
Expression format: ["NOT IN",
Left Operand, Right Operand]
.
Valid operand types: number and number[] or string and string[].
["IN", 10, [1, 2, 3, 4, 5]]
["IN", ["circle", "square", "triangle"], "oval"]
i.Evaluate([]any{"NOT IN", 10, []int{1, 2, 3, 4, 5}}, ctx) // true
i.Evaluate([]any{"NOT IN", []string{"circle", "square", "triangle"}, "oval"}, ctx) // true
Expression format: ["PREFIX",
Left Operand, Right Operand]
.
Valid operand types: string.
- Left operand is the PREFIX term.
- Right operand is the tested word.
["PREFIX", "hemi", "hemisphere"]
i.Evaluate([]any{"PREFIX", "hemi", "hemisphere"}, ctx) // true
i.Evaluate([]any{"PREFIX", "hemi", "sphere"}, ctx) // false
Expression format: ["SUFFIX",
Left Operand, Right Operand]
.
Valid operand types: string.
- Left operand is the tested word.
- Right operand is the SUFFIX term.
["SUFFIX", "establishment", "ment"]
i.Evaluate([]any{"SUFFIX", "establishment", "ment"}, ctx) // true
i.Evaluate([]any{"SUFFIX", "establish", "ment"}, ctx) // false
Expression format: ["OVERLAP",
Left Operand, Right Operand]
.
Valid operand types number[] or string[].
["OVERLAP", [1, 2], [1, 2, 3, 4, 5]]
["OVERLAP", ["circle", "square", "triangle"], ["square"]]
i.Evaluate([]any{"OVERLAP", []int{1, 2, 6}, []int{1, 2, 3, 4, 5}}, ctx) // true
i.Evaluate([]any{"OVERLAP", []string{"circle", "square", "triangle"}, []string{"square", "oval"}}, ctx) // true
Expression format: ["NIL",
Reference Operand]
.
["NIL", "$RefA"]
i.Evaluate([]any{"NIL", "RefA"}, map[string]any{}) // true
i.Evaluate([]any{"NIL", "RefA"}, map[string]any{"RefA": 10}) // false
Evaluates as FALSE when the operand is UNDEFINED or NULL.
Expression format: ["PRESENT",
Reference Operand]
.
["PRESENT", "$RefA"]
i.Evaluate([]any{"PRESENT", "RefA"}, map[string]any{}) // false
i.Evaluate([]any{"PRESENT", "RefA"}, map[string]any{"RefA": 10}) // true
i.Evaluate([]any{"PRESENT", "RefA"}, map[string]any{"RefA": false}) // true
i.Evaluate([]any{"PRESENT", "RefA"}, map[string]any{"RefA": "val"}) // true
The logical AND operator (&&) returns the boolean value TRUE if both operands are TRUE and returns FALSE otherwise.
Expression format: ["AND", Left Operand 1, Right Operand 2, ... , Right Operand N]
.
Valid operand types: Comparison Expression or Nested Logical Expression.
["AND", ["==", 5, 5], ["==", 10, 10]]
i.Evaluate([]any{"AND", []any{"==", 5, 5}, []any{"==", 10, 10}}, ctx) // true
The logical OR operator (||) returns the boolean value TRUE if either or both operands is TRUE and returns FALSE otherwise.
Expression format: ["OR", Left Operand 1, Right Operand 2, ... , Right Operand N]
.
Valid operand types: Comparison Expression or Nested Logical Expression.
["OR", ["==", 5, 5], ["==", 10, 5]]
i.Evaluate([]any{"OR", []any{"==", 5, 5}, []any{"==", 10, 5}}, ctx) // true
The logical NOR operator returns the boolean value TRUE if both operands are FALSE and returns FALSE otherwise.
Expression format: ["NOR", Left Operand 1, Right Operand 2, ... , Right Operand N]
Valid operand types: Comparison Expression or Nested Logical Expression.
["NOR", ["==", 5, 1], ["==", 10, 5]]
i.Evaluate([]any{"NOR", []any{"==", 5, 1}, []any{"==", 10, 5}}, ctx) // true
The logical NOR operator returns the boolean value TRUE if both operands are FALSE and returns FALSE otherwise.
Expression format: ["XOR", Left Operand 1, Right Operand 2, ... , Right Operand N]
Valid operand types: Comparison Expression or Nested Logical Expression.
["XOR", ["==", 5, 5], ["==", 10, 5]]
i.Evaluate([]any{"XOR", []any{"==", 5, 5}, []any{"==", 10, 5}}, ctx) // true
["XOR", ["==", 5, 5], ["==", 10, 10]]
i.Evaluate([]any{"XOR", []any{"==", 5, 5}, []any{"==", 10, 10}}, ctx) // false
The logical NOT operator returns the boolean value TRUE if the operand is FALSE, TRUE otherwise.
Expression format: ["NOT", Operand]
Valid operand types: Comparison Expression or Nested Logical Expression.
["NOT", ["==", 5, 5]]
i.Evaluate([]any{"NOT", []any{"==", 5, 5}}, ctx) // true
Usage
referenceSerializeOptions := illogical.WithReferenceSerializeOptions(illogical.ReferenceSerializeOptions{
From: func(string) (string, error)
To: func(string) string
})
i := illogical.New(referenceSerializeOptions)
A function used to determine if the operand is a reference type, otherwise evaluated as a static value.
func(string) (string, error)
Return value:
true
= reference typefalse
= value type
Default reference predicate:
The
$
symbol at the begging of the operand is used to predicate the reference type., E.g.$State
,$Country
.
A function used to transform the operand into the reference annotation stripped form. I.e. remove any annotation used to detect the reference type. E.g. "$Reference" => "Reference".
func(string) string
Default reference transform: It removes the
$
symbol at the begging of the operand name.
Usage
collectionSerializeOptions := illogical.WithCollectionSerializeOptions(illogical.CollectionSerializeOptions{
EscapeCharacter string
})
i := illogical.New(collectionSerializeOptions)
Charter used to escape fist value within a collection, if the value contains operator value.
Example
["==", 1, 1]
// interpreted as EQ expression["\==", 1, 1]
// interpreted as a collection
EscapeCharacter string
Default escape character:
\
Options applied while an expression is being simplified.
Usage
referenceSimplifyOptions := illogical.WithReferenceSimplifyOptions(illogical.SimplifyOptions{
IgnoredPaths []string
IgnoredPathsRx []regexp.Regexp
})
i := illogical.New(referenceSimplifyOptions)
Reference paths which should be ignored while simplification is applied. Must be an exact match.
IgnoredPaths []string
Reference paths which should be ignored while simplification is applied. Matching regular expression patterns.
IgnoredPathsRx []regexp.Regexp
Mapping of the operators. The key is unique operator key, and the value is the key used to represent the given operator in the raw expression.
Usage
import (
e "github.com/spaceavocado/goillogical/evaluable"
)
operatorMapping := illogical.WithOperatorMappingOptions(map[e.Kind]string{})
i := illogical.New(operatorMapping)
Default operator mapping:
operatorMapping := e.OperatorMapping{
// Comparison
e.Eq: "==",
e.Ne: "!=",
e.Gt: ">",
e.Ge: ">=",
e.Lt: "<",
e.Le: "<=",
e.In: "IN",
e.Nin: "NOT IN",
e.Prefix: "PREFIX",
e.Suffix: "SUFFIX",
e.Overlap:, "OVERLAP",
e.Nil: "NIL",
e.Present: "PRESENT",
// Logical
e.And: "AND",
e.Or: "OR",
e.Nor: "NOR",
e.Xor: "XOR",
e.Not: "NOT",
}
All options could be used simultaneously.
operatorMapping := illogical.WithOperatorMappingOptions(map[e.Kind]string{})
referenceSimplifyOptions := illogical.WithReferenceSimplifyOptions(illogical.SimplifyOptions{
IgnoredPaths: []string{},
IgnoredPathsRx: []regexp.Regexp{},
})
i := illogical.New(operatorMapping, referenceSimplifyOptions)
See contributing.md.
Illogical is released under the MIT license. See license.txt.