XExpressions 1.0.10

XExpressions

A library for evaluating arbitrary expressions. For example:

Evaluator eval = new Evaluator("1 + 2");
Variant result = eval.Evaluate();

Features

Basic Usage

The Evaluator class is used to evaluate the expression. For example:

Evaluator eval = new Evaluator("1 + 2");
Variant result = eval.Evaluate();

Variant Data Type

The result of an expression is a Variant. The variant can represent a decimal, string or boolean. For example:

Evaluator eval = new Evaluator("1 + 2 * 3 / 4");
Variant result = eval.Evaluate();

if (result.Kind == VariantKind.Decimal)
	Console.WriteLine($"Result is: {(decimal)result}");
else if (result.Kind == VariantKind.String)
	Console.WriteLine($"Result is: {(string)result}");
else if (result.Kind == VariantKind.Boolean)
	Console.WriteLine($"Result is: {(bool)result}");

Custom Functions

To add your own functions use XExpressionsSettings to specify the name of the function and a delegate to invoke when it is used. For example:

XExpressionsSettings settings = new XExpressionsSettings();

// Add a function called MyFunc that takes two parameters and adds them
settings.AddFunction(name: "MyFunc", parameterCount: 2, 
	(name, args) => args[0] + args[1]);

// Evaluate an expression using the function
Evaluator eval = new Evaluator("myfunc(100, 200)", settings);
Variant result = eval.Evaluate();

// result is 300

Custom Constants or Variables

To add your own constants or variables use XExpressionsSettings to specify the name and a delegate to invoke when it is used. For example:

XExpressionsSettings settings = new XExpressionsSettings();

// Add a constant call pi
settings.AddIdentifier(name: "pi", (name) => 3.14);

// Add a variable called radius
settings.AddIdentifier(name: "radius", (name) => 5);

// Evaluate an expression using the constant/variable
Evaluator eval = new Evaluator("2 * pi * radius", settings);
Variant result = eval.Evaluate();

Asynchronous (Task) Support

Evaluation can be synchronous via the Evaluator.Evaluate method or asynchronous via the Evaluator.EvaluateAsync method. For example:

Evaluator eval = new Evaluator("1 + 2 * 3 / 4");

Variant result = await eval.EvaluateAsync();

This is particularly useful when adding custom functions/variables/constants that are also async. For example, you might add a function that calls a REST API:

XExpressionsSettings settings = new XExpressionsSettings();

// Add a function that calls a REST API
settings.AddFunction(name: "MyFunc", parameterCount: 0,
	async(name, args, cancellation) =>
	{
		// ... call a REST API and return a result ...
	});

// Evaluate the expression
Evaluator eval = new Evaluator("myfunc()");
Variant result = await eval.EvaluateAsync();

Expression Tree

The expression text is broken down into an expression tree which is then evaluated. The tree is available using the Evaluator.RootNode property. For example:

Evaluator eval = new Evaluator("1 + 2 * 3 / 4");

// Get the tree
ExpressionNode node = eval.RootNode;

// Convert the tree into an SVG
string svg = node.CreateSvg();

The CreateSvg method requires adding the XExpressions.SVG package.

NOTE: The SVG functionality was an after thought, is not beautiful and has its issues but is sufficient to get an understanding of what the tree looks like.

For the expression 1 + 2 * pi / 4 + min(10, 20) the tree looks like:

<img src="docs/tree.png" width="431" height="288"/>

Example Application

The repo contains an example application that allows you to enter an expression and get a result. It also displays an image of the tree that was generated to evaluate the expression:

<img src="docs/ExampleApp.gif" width="460" height="437"/>

The example application consists of a REST API to evaluate an expression and an angular app for the user to enter the expression.

To build the application, clone the repository and run the following:

1. cd ExampleApp\\ClientApp
2. npm install
3. cd ..\\..
4. dotnet run --project ExampleApp --framework net7.0

Then navigate to http://localhost:5209 in your browser.