JexlNet.ExtendedGrammar 2.1.4

JexlNet

Powerful context-based expression parser and evaluator in C# using JEXL (Javascript Expression Language) expressions.

NOTE: This library handles the JEXL from TomFrost's JEXL library. It does NOT handle the similarly-named Apache Commons JEXL language.

Quick start

Expressions can be evaluated synchronously or asynchronously by using the Eval and EvalAsync methods respectively. Context should be a JsonObject (or a string which will internally be converted to a JsonObject). The output is always a JsonNode (can be JsonObject, JsonArray or JsonValue).

The Grammar can be expanded by adding new operators, functions and transforms.

// Define context as a JsonObject (System.Text.Json)
var context = new JsonObject {
    { "name", new JsonObject {
        { "first", "Sterling" },
        { "last", "Archer" }
    }},
    { "assoc", new JsonArray {
        new JsonObject {
            { "first", "Lana" },
            { "last", "Kane" }
        },
        new JsonObject {
            { "first", "Cyril" },
            { "last", "Figgis" }
        },
        new JsonObject {
            { "first", "Pam" },
            { "last", "Poovey" }
        }
    }},
    { "age", 36 }
};

// Or as a JSON string
string context = 
@"{
    ""name"": {
        ""first"": ""Sterling"",
        ""last"": ""Archer""
    },
    ""assoc"": [
        {
            ""first"": ""Lana"",
            ""last"": ""Kane""
        },
        {
            ""first"": ""Cyril"",
            ""last"": ""Figgis""
        },
        {
            ""first"": ""Pam"",
            ""last"": ""Poovey""
        }
    ],
    ""age"": 36
}";

// Initialize Jexl
var jexl = new Jexl();

// Use it with asynchronously or synchronously:

// Filter an array asynchronously...
await jexl.EvalAsync(@"assoc[.first == ""Lana""].last", context);
// Kane

// Or synchronously!
jexl.Eval(@"assoc[.first == ""Lana""].last", context);
// Kane

// Do math
await jexl.Eval(@"age * (3 - 1)", context);
// 72

// Concatenate
await jexl.EvalAsync(@"name.first + "" "" + name[""la"" + ""st""]", context);
// "Sterling Archer"

// Compound
await jexl.EvalAsync(
  'assoc[.last == "Figgis"].first == "Cyril" && assoc[.last == "Poovey"].first == "Pam"',
  context
)
// true

// Use array indexes and return objects
await jexl.EvalAsync(@"assoc[1]", context);
// new JsonObject {
//             { "first", "Cyril" },
//             { "last", "Figgis" }
//         }
// 

// Use conditional logic
await jexl.EvalAsync(@"age > 62 ? ""retired"" : ""working""", context);
// "working"

// Transform
jexl.Grammar.AddTransform("upper", (JsonValue? val) => val?.ToString().ToUpper());
await jexl.EvalAsync(@"""duchess""|upper + "" "" + name.last|upper", context);
// "DUCHESS ARCHER"

// Transform asynchronously, with arguments
jexl.Grammar.AddTransform("getStat", async (JsonNode?[] args) => await DbSelectByLastName(args[0], args[1]));
await jexl.EvalAsync(@"name.last|getStat(""weight"")", context);
// Output: 184

// Functions too, sync or async, args or no args
jexl.Grammar.AddFunction("getOldestAgent", GetOldestAgent);
await jexl.EvalAsync(@"age == getOldestAgent().age", context);
// false

// Add your own (a)synchronous operators
// Here's a case-insensitive string equality
jexl.Grammar.AddBinaryOperator("_=", 20, (JsonNode?[] args) => args[0]?.ToString().ToLower() == args[1]?.ToString().ToLower());
await jexl.EvalAsync(@"""Guest"" _= ""gUeSt""");
// true

// Compile your expression once, evaluate many times!
const { expr } = jexl
var danger = jexl.CreateExpression(@"""Danger "" + place");
await danger.EvalAsync(new JsonObject { { "place", "Zone" } }); // Danger zone
await danger.EvalAsync(new JsonObject { { "place", "ZONE!!!" } }); // Danger ZONE!!! (Doesn't recompile the expression!)

Play with it

• Jexl Playground - An interactive Jexl sandbox by Christian Zosel @czosel.

Installation

Install from NuGet:

Install-Package JexlNet

Add using statement:

using JexlNet;

And use it:

var jexl = new Jexl();
var result = jexl.Eval("1 + 1");

Async vs Sync: Which to use

There is little performance difference between EvalAsync and Eval. Both support async functions and transforms. The only difference is that EvalAsync returns a Task<dynamic> and Eval returns a dynamic.

All the details

Unary Operators

Binary Operators

Comparisons

A note about in

The in operator can be used to check for a substring: "Cad" in "Ron Cadillac", and it can be used to check for an array element: "coarse" in ['fine', 'medium', 'coarse']. However, the == operator is used behind-the-scenes to search arrays, so it should not be used with arrays of objects. The following expression returns false: {a: 'b'} in [{a: 'b'}].

Ternary operator

Conditional expressions check to see if the first segment evaluates to a truthy value. If so, the consequent segment is evaluated. Otherwise, the alternate is. If the consequent section is missing, the test result itself will be used instead.

Native Types

Groups

Parentheses work just how you'd expect them to:

Identifiers

Access variables in the context object by just typing their name. Objects can be traversed with dot notation, or by using brackets to traverse to a dynamic property name.

Example context:

var context = new JsonObject 
{
    { "name", new JsonObject {
        { "first", "Malory" },
        { "last", "Archer" }
    }},
    { "exes", new List<string> {
        "Nikolai Jakov",
        "Len Trexler",
        "Burt Reynolds"
    }},
    { "lastEx", 2 }
};

Collections

Collections, or arrays of objects, can be filtered by including a filter expression in brackets. Properties of each collection can be referenced by prefixing them with a leading dot. The result will be a list of the objects for which the filter expression resulted in a truthy value.

Example context:

var context = new JsonObject
{
    {
        "employees", new List<dynamic>
        {
            new JsonObject { { "first", "Sterling" }, { "last", "Archer" }, { "age", 36 } },
            new JsonObject { { "first", "Malory" }, { "last", "Archer" }, { "age", 75 } },
            new JsonObject { { "first", "Lana" }, { "last", "Kane" }, { "age", 33 } },
            new JsonObject { { "first", "Cyril" }, { "last", "Figgis" }, { "age", 45 } },
            new JsonObject { { "first", "Cheryl" }, { "last", "Tunt" }, { "age", 28 } }
        }
    },
    { "retireAge", 62 }
};

Transforms

The power of Jexl is in transforming data, synchronously or asynchronously. Transform functions take one argument or an array or list of more arguments. The first argument is the value to be transformed, and the rest are any other arguments passed to the transform in the expression. They must return either the transformed value, or a Promise that resolves with the transformed value. Add them with jexl.AddTransform(name, function). Arguments can be JsonNode? or JsonNode?[]. In case of enumerables the first element is the value to be transformed and the rest are the arguments. It is also possible to use a first JsonNode? argument as the value to be transformed and the rest as the arguments.

jexl.Grammar.AddTransform("lower", (JsonNode? val) => val?.ToString().ToLower());
jexl.Grammar.AddTransform("split", (JsonNode?[] args) => new JsonArray((args[0]?.ToString().Split(args[1]?.ToString()) ?? []).Select(x => (JsonNode?)x).ToArray()));
jexl.Grammar.AddTransform("split", (JsonNode? arg0, JsonNode?[] args) => new JsonArray((arg0?.ToString().Split(args[0]?.ToString()) ?? []).Select(x => (JsonNode?)x).ToArray()));

Functions

While Transforms are the preferred way to change one value into another value, Jexl also allows top-level expression functions to be defined. Use these to provide access to functions that either don't require an input, or require multiple equally-important inputs. They can be added with jexl.AddFunction(name, function). Like transforms, functions can return a value, or a Promise that resolves to the resulting value. For functions, arguments are not required, but if they are defined, they must be JsonNode? or JsonNode?[].

jexl.Grammar.AddFunction("getTrue", () => true);
jexl.Grammar.AddFunction("min", (JsonNode?[] args) => args.Select(x => x?.AsValue().ToDecimal()).Min());
jexl.Grammar.AddFunction("expensiveQuery", Db.RunExpensiveQuery);

Other implementations

Jexl - The original JavaScript implementation of JEXL. jexl-rs - A Rust-based JEXL parser and evaluator. PyJEXL - A Python-based JEXL parser and evaluator.

License

JexlNet is licensed under the MIT license. Please see LICENSE for full details.

Credits

This library is a port of TomFrost's JEXL library so all credit goes to the author and the contributors of that library.