AlphaX.FormulaEngine 3.1.0

AlphaX.FormulaEngine

A robust, extensible, and blazing fast engine to parse and evaluate formulas dynamically. Built on top of AlphaX.Parserz, it seamlessly supports both natively provided formulas and your own custom logic.

🔗 AlphaX.FormulaEngine GitHub Repo | 💬 Feedback & Queries

🚀 What's New in v3.1.0

We're thrilled to introduce massive improvements to AlphaX.FormulaEngine!

• 14 New Native Formulas: Added full support for MIN, MAX, POWER, ROUND, SQRT, TRIM, SUBSTRING, INDEXOF, COALESCE, ISNUMBER, ISSTRING, INDEX, JOIN, COUNT, YEAR, MONTH, and DAY.
• Enhanced Arithmetic Engine: Flawless nested evaluation with accurate left-associative arithmetic (e.g. 1+1-(1+2)). Zero recursive timeout errors on deeply nested syntax!
• Complete Developer Reference: Be sure to check out our overhauled Formulas.md reference.

⚡ Quick Start

You can initialize the engine and evaluate expressions either synchronously or asynchronously:

using AlphaX.FormulaEngine;

AlphaXFormulaEngine engine = new AlphaXFormulaEngine();

// Synchronous Evaluation
IEvaluationResult resultSync = engine.Evaluate("SUM(1, 2, 12.3, 5.9)");
Console.WriteLine(resultSync.Value); // 21.2

// Asynchronous Evaluation
IEvaluationResult resultAsync = await engine.EvaluateAsync("SUM(1, 2, 12.3, 5.9)");
Console.WriteLine(resultAsync.Value); // 21.2

Pro Tip: Formulas can naturally nest! Feel free to parse deep trees natively: (SUM(1,2) + AVERAGE(5,10)) * 10.

📚 Inbuilt Formulas

AlphaX.FormulaEngine ships with a wide array of powerful formulas right out of the box:

• 🧮 Arithmetic: SUM, AVERAGE, FLOOR, ROUND, MIN, MAX, POWER, SQRT
• 🔤 String: LOWER, UPPER, TEXTSPLIT, CONCAT, LENGTH, TRIM, SUBSTRING, INDEXOF
• 📅 DateTime: TODAY, NOW, YEAR, MONTH, DAY
• 🧠 Logical: EQUALS, GREATERTHAN, OR, AND, IF, COALESCE, ISNUMBER, ISSTRING
• 📦 Array: ARRAYCONTAINS, ARRAYINCLUDES, INDEX, JOIN, COUNT

👉 Click here to see the full list of inbuilt formulas and examples

🛠 Creating Your Own Formulas

AlphaX.FormulaEngine provides maximum flexibility to write and integrate your own custom logic effortlessly.

1. Create a Formula Class

Inherit from AlphaX.FormulaEngine.Formula. Below is a custom StartsWith formula implementation:

public class StartsWithFormula : AlphaX.FormulaEngine.Formula
{
    public StartsWithFormula() : base("StartsWith") { }

    public override object Evaluate(IFormulaContext context)
    {
        // Throws error if argument count doesn't match
        ValidateArgumentCount(context.Args); 

        // Throws error if 0th/1st arguments aren't strings
        string source = context.GetStringArg(0); 
        string value = context.GetStringArg(1);

        // Safely retrieves the 3rd argument, or defaults to false
        context.TryGetArg(2, out bool matchCase); 
        
        return source.StartsWith(value, matchCase ? StringComparison.Ordinal : StringComparison.InvariantCultureIgnoreCase);
    }

    protected override FormulaInfo GetFormulaInfo()
    {
        FormulaInfo info = new FormulaInfo(Name)
        {
            Description = "Checks if the provided string starts with the specified value."
        };

        // Define arguments for function documentation/validation
        info.AddArgument(new StringArgument("source", true) { Description = "The source string." });
        info.AddArgument(new StringArgument("value", true) { Description = "The value to check for." });
        info.AddArgument(new BooleanArgument("matchCase", false) { Description = "Match case while checking." });
        
        return info;
    }
}

2. Register & Evaluate

Simply add your formula to the FormulaStore and it is immediately ready for use!

AlphaXFormulaEngine engine = new AlphaXFormulaEngine();
engine.FormulaStore.Add(new StartsWithFormula());

var result1 = engine.Evaluate("StartsWith(\"This is test\", \"This\")");
Console.WriteLine(result1.Value); // true

var result2 = engine.Evaluate("StartsWith(\"This is test\", \"hello\")");
Console.WriteLine(result2.Value); // false

Async Formulas: To implement asynchronous logic (e.g. hitting an API inside a formula), inherit from AlphaX.FormulaEngine.AsyncFormula and override the EvaluateAsync method.

⚙️ Advanced Configuration

AlphaXFormulaEngine allows you to configure the engine to fit your exact domain needs.

1. Toggle String Quotes

By default, strings are parsed with double quotes ("text"). You can toggle this to accept single quotes ('text') by updating the engine settings:

engine.ApplySettings(new EngineSettings()
{
     DoubleQuotedStrings = false
});

2. Logical Operator Modes

You can configure the engine to parse query-like operators (eq instead of =) via LogicalOperatorMode.

engine.ApplySettings(new EngineSettings()
{
     LogicalOperatorMode = LogicalOperatorMode.Query
});

Query Mode Operators:

• = → eq | != → ne
• < → lt | > → gt
• <= → le | >= → ge
• && → and | || → or

3. Parsing Optimization Order

You can manually sequence the type resolution tree (e.g. parse Numbers before Strings) to drastically improve performance if you know your data bounds:

ParseOrder order = new ParseOrder(ParseType.Number);
order.Add(ParseType.String);
order.Add(ParseType.Boolean);

engine.ApplySettings(new EngineSettings() { EngineParseOrder = order });

🎯 Variables (Custom Names)

AlphaXFormulaEngine allows you to inject dynamic variables (prefixed with $) directly into expressions by providing a custom IEngineContext.

public class TestEngineContext : IEngineContext
{
    public async Task<object> Resolve(string key)
    {
        return key switch
        {
            "UserId" => 1024,
            "Role" => "Admin",
            _ => throw new Exception("Invalid custom name")
        };
    }
}

// Pass the context into the Engine constructor
AlphaXFormulaEngine engine = new AlphaXFormulaEngine(new TestEngineContext());

// Expressions resolve variables at runtime
IEvaluationResult result = engine.Evaluate("EQUALS($UserId, 1024)");
Console.WriteLine(result.Value); // true

🔗 Sequenced / Chained Expressions

Evaluating massive, complicated expression walls can be extremely difficult to read or debug (e.g. SUM(1, 2, AVERAGE(1, 2, SUM(1, 2, 12)))).

AlphaX provides a SequencedExpressionBuilder to break these down natively into readable variables:

var engine = new AlphaXFormulaEngine();

var expression = SequencedExpressionBuilder
    .Create("Step1", "SUM(1, 2, 12)")
    .Next("Step2", "AVERAGE(1, 2, $Step1)")
    .Next("Final", "SUM(1, 2, $Step2)");

var result = engine.Evaluate(expression); 
// Final Result evaluates properly by cascading through the sequenced variables!

Built by developers, for developers 😃