MathExprEngine 2.0.0

dotnet add package MathExprEngine --version 2.0.0
                    
NuGet\Install-Package MathExprEngine -Version 2.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="MathExprEngine" Version="2.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="MathExprEngine" Version="2.0.0" />
                    
Directory.Packages.props
<PackageReference Include="MathExprEngine" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add MathExprEngine --version 2.0.0
                    
#r "nuget: MathExprEngine, 2.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package MathExprEngine@2.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=MathExprEngine&version=2.0.0
                    
Install as a Cake Addin
#tool nuget:?package=MathExprEngine&version=2.0.0
                    
Install as a Cake Tool

MathExprEngine is a lightweight, embeddable C# expression engine that parses and evaluates mathematical and logical expressions using an Abstract Syntax Tree (AST).

It is designed for scenarios where:

  • expressions must be user-defined or configurable
  • correctness of operator precedence matters
  • short-circuit logic is required (logical operators, conditional expressions)
  • clear error diagnostics (with column numbers) are important

The engine intentionally avoids scripting engines and eval-style execution, giving you control, safety, and extensibility.


What Problems Does It Solve?

Typical use cases:

  • Business rules stored as expressions in configuration or databases
  • Dynamic calculations (pricing formulas, scoring systems, validation rules)
  • Feature flags or conditional behavior without recompilation
  • Math-heavy domains (finance, engineering, analytics)
  • DSL foundations for more complex rule engines

The engine is intentionally small, explicit, and deterministic.


Key Features

Arithmetic

  • + - * / ^ %
  • Correct precedence and associativity-> ^ binds tighter than unary minus (-2^2 is -4, not 4) and is right-associative (2^3^2 is 512)
  • Unary + and -

% has two meanings, decided per use. As an infix operator, it is modulo: 10 % 3 is 1, and 10 % -3 is 1 (not -2.9). As a postfix operator, when nothing that could start a new operand follows it → it is percentage: 50% is 0.5. This means 100% + 2 is 0 (modulo), not 3; write (100%) + 2 if you want the old percentage-then-add reading. See Usage Guide → The % Operator for the full rule and worked examples.

Comparisons

  • < > <= >= == !=
  • Return numeric booleans (1.0 = true, 0.0 = false)

Logical Operators (Short-Circuit)

  • && (AND)
  • || (OR)

Only the necessary side of the expression is evaluated.

Conditional (Ternary)

condition ? exprIfTrue : exprIfFalse
  • Fully short-circuited
  • Only the selected branch is evaluated

Functions

Built-in:

  • sin(x)
  • cos(x)
  • sqrt(x)
  • pow(x, y)
  • max(x1, x2, ...)
  • sum(x1, x2, ...)
  • neg(x)
  • mod(x, y)

Custom functions:

  • Register your own C# functions at runtime

sum() and max() called with zero arguments throw rather than silently returning 0.

Parameters (Variables)

  • Bare names in an expression (e.g. basePrice, quantity) are resolved from a parameters dictionary passed to Evaluate
  • Lookup is case-insensitive
  • Accepted value types: all numeric primitives, decimal, bool, and string (parsed with InvariantCulture)
  • null and unconvertible types (e.g. DateTime) throw rather than silently becoming 0

See Usage Guide ⇒ Parameters for the full type table.

Compiled Expressions

  • engine.Compile(expression) parses and compiles a rule once and returns a reusable, thread-safe CompiledExpression; call Evaluate(parameters) on it as often as you like
  • Plain Evaluate calls get faster on their own: each engine keeps a bounded cache of parsed expressions, and by default the second Evaluate of the same text compiles it to a delegate
  • Results, exception types, messages, and columns are identical whether an expression is interpreted or compiled
  • Functions are looked up when the expression runs, so RegisterFunction replacing a function after Compile takes effect immediately
  • Platforms without runtime code generation (Native AOT, iOS) keep interpreting, with the same results
var engine = new MathRuleEngine();
CompiledExpression rule = engine.Compile("basePrice * quantity * (1 - discount)");

double total = rule.Evaluate(new Dictionary<string, object>
{
    ["basePrice"] = 20, ["quantity"] = 3, ["discount"] = 0.25
});
// total = 45

See Usage Guide ⇒ Compiled Expressions and the Expression Cache for the cache options, when compilation is skipped, and how to turn it off.

Error Reporting

  • Syntax and runtime errors include exact column numbers

  • All exceptions derive from one common base, MathExprEngineException, so a single catch handles every engine failure

  • Examples:

    • unexpected tokens
    • missing parentheses
    • division/modulo by zero
    • invalid function usage
    • a configured resource limit (expression length, tokens, nodes, nesting depth) exceeded
    • a non-finite result (NaN / Infinity), rejected instead of returned
    • the thread stack running low during parsing or evaluation, reported as a catchable exception instead of crashing the process

Design Principles

The engine parses expressions into an Abstract Syntax Tree, not Reverse Polish Notation.

This enables:

  • true short-circuit evaluation
  • clean implementation of ternary operators
  • better error localization
  • future extensibility

Numeric Boolean Model

  • true → 1.0
  • false → 0.0

This keeps the engine simple and interoperable with math-heavy formulas.

Thread Safety and Resource Limits

A MathRuleEngine instance holds no per-call state → construct one and share it, including across threads and while registering additional functions. Each Evaluate call runs against its own isolated copy of the parameters you pass in. The engine's expression cache is shared by all its callers; it stores only parsed and compiled expressions, never parameter values, results, or exceptions. Use one engine per trust domain if tenants must not affect each other's cache.

Construction accepts an optional MathRuleEngineOptions with resource limits (expression length, token count, node count, nesting depth, evaluation depth, function-argument count) so that a hostile or accidental runaway expression throws instead of exhausting memory or the call stack. Defaults are generous for hand-authored rules; see Usage Guide → Resource Limits for every default and what it protects against.


Execution Overview

Expression String
    ↳ Expression cache (per engine, keyed by exact text)
        ↳ on a miss: Tokenizer
            ↳ Parser
                ↳ AST Nodes
        ↳ Evaluation
            ↳ interpreted (walk the AST), or
            ↳ compiled delegate (once the text is hot, or after Compile)
  • Expression cache: keeps the parsed tree (and, once compiled, the delegate) for recently used texts
  • Tokenizer: converts text into tokens with column tracking
  • Parser: recursive-descent + precedence handling
  • AST Nodes: executable expression tree
  • Evaluator: walks the tree with short-circuit semantics
  • Compiler: turns the tree into a delegate with System.Linq.Expressions, preserving the same short-circuit rules, checks and error messages
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.0 161 11/2/2026
1.3.0.8086 200 3/16/2026
1.2.0.6785 2,778 2/17/2026
1.1.1.4273 160 2/10/2026
1.1.0.4548 141 2/3/2026
1.0.0 155 1/29/2026