EasyExpression.Core 1.0.1

EasyExpression

English | 中文

A lightweight, extensible expression engine for .NET that supports scripting with variables, control flow, and built-in functions.

✨ Features

• Lightweight & Portable - Targets .NET Standard 2.0, compatible with .NET Framework 4.6.1+, .NET Core 2.0+, and .NET 5+
• Safe Execution - Built-in timeout, max depth, and node limits to prevent infinite loops and resource exhaustion
• Rich Expression Support - Arithmetic, comparison, logical operators, and string concatenation
• Control Flow - if/elseif/else, local blocks, return, return_local, and assert statements
• Built-in Functions - String, Math, and DateTime functions out of the box
• Extensible - Register custom functions and type converters via IEngineContributor
• Type Annotations - Optional type hints for field references like [fieldName:decimal]
• Compilation Cache - Improved performance for repeated script execution
• Detailed Error Reporting - Line/column positions and code snippets in error messages

📦 Installation

Install from NuGet:

dotnet add package EasyExpression.Core

Or via Package Manager:

Install-Package EasyExpression.Core

Or via PackageReference:

<ItemGroup>
  <PackageReference Include="EasyExpression.Core" Version="1.0.0" />
</ItemGroup>

Build from source (optional)

git clone https://github.com/yang-sanmu/EasyExpression.git
cd EasyExpression
dotnet build

🚀 Quick Start

Basic Usage

using EasyExpression.Core.Engine;

// Create engine
var factory = new DefaultExpressionEngineFactory();
var engine = factory.Create();

// Define input fields
var inputs = new Dictionary<string, object?>
{
    { "price", 100m },
    { "quantity", 5 }
};

// Execute script
var script = @"
{
    set(total, [price:decimal] * [quantity:decimal])
    set(discount, [total] * 0.1)
    set(finalPrice, [total] - [discount])
}";

var result = engine.Execute(script, inputs);

// Access results
Console.WriteLine(result.Assignments["total"]);      // 500
Console.WriteLine(result.Assignments["discount"]);   // 50
Console.WriteLine(result.Assignments["finalPrice"]); // 450

Script Validation

var validationResult = engine.Validate(script);
if (!validationResult.Success)
{
    Console.WriteLine($"Error at line {validationResult.ErrorLine}: {validationResult.ErrorMessage}");
}

📖 Language Syntax

Data Types

Operators

Field References

Access input fields using square brackets:

[fieldName]              // Basic reference
[fieldName:decimal]      // With type annotation
[fieldName:datetime]     // DateTime type
[fieldName:bool]         // Boolean type
[fieldName:string]       // String type

Statements

Set Statement

set(variableName, expression)
set(variableName:type, expression)  // With type annotation

If/ElseIf/Else

if(condition) {
    // statements
} elseif(condition) {
    // statements
} else {
    // statements
}

Local Block

local {
    // Isolated scope
    return_local  // Exit only this block
}

Assert

assert(condition, 'return', 'Error message', 'error')
assert(condition, 'continue', 'Warning message', 'warn')

Message

msg('Information message')
msg('Warning message', 'warn')
msg('Error message', 'error')

Return

return        // Exit entire script
return_local  // Exit current local block only

Comments

// Single-line comment

/* 
   Multi-line 
   comment 
*/

🔧 Built-in Functions

String Functions

Math Functions

DateTime Functions

TimeSpan units: ms (milliseconds), s (seconds), m (minutes), h (hours, default), d (days)

⚙️ Configuration Options

var engine = factory.Create(options =>
{
    // Execution limits
    options.MaxDepth = 64;                    // Max nesting depth
    options.MaxNodes = 2000;                  // Max AST nodes
    options.MaxNodeVisits = 10000;            // Max node visits
    options.TimeoutMilliseconds = 2000;       // Execution timeout
    
    // String handling
    options.StringComparison = StringComparison.OrdinalIgnoreCase;
    options.CaseInsensitiveFieldNames = true;
    
    // Number handling
    options.RoundingDigits = 2;
    options.MidpointRounding = MidpointRounding.AwayFromZero;
    
    // DateTime
    options.DateTimeFormat = "yyyy-MM-dd HH:mm:ss";
    options.NowUseLocalTime = true;
    
    // Null handling
    options.TreatNullStringAsEmpty = true;
    options.TreatNullDecimalAsZero = false;
    options.TreatNullBoolAsFalse = false;
    
    // Equality comparison mode
    options.EqualityCoercion = EqualityCoercionMode.Strict;
    
    // String concatenation behavior
    options.StringConcat = StringConcatMode.PreferStringIfAnyString;
    
    // Other
    options.EnableComments = true;
    options.EnableCompilationCache = true;
    options.RegexTimeoutMilliseconds = 0;     // 0 = no timeout
});

StringConcat Modes

StringConcat only affects the + operator when at least one side is a string.

Equality Coercion Modes

🔌 Extensibility

Custom Functions

public class MyFunction : IFunction
{
    public string Name => "MyFunc";
    
    public object? Invoke(object?[] args, InvocationContext ctx)
    {
        // Implementation
        return args[0]?.ToString()?.ToUpperInvariant();
    }
}

// Register via contributor
public class MyContributor : IEngineContributor
{
    public void Configure(EngineServices services)
    {
        services.Functions.Register(new MyFunction());
    }
}

// Use contributor
var engine = factory.Create(contributors: new[] { new MyContributor() });

Custom Type Converters

public class MyConverter : ITypeConverter
{
    public Type InputType => typeof(string);
    public Type OutputType => typeof(MyType);
    
    public bool TryConvert(object? value, out object? result)
    {
        // Conversion logic
    }
}

// Register in contributor
services.Converters.Register(new MyConverter());

📊 Execution Result

var result = engine.Execute(script, inputs);

// Check for errors
if (result.HasError)
{
    Console.WriteLine($"Error: {result.ErrorMessage}");
    Console.WriteLine($"Location: Line {result.ErrorLine}, Column {result.ErrorColumn}");
    Console.WriteLine($"Code: {result.ErrorSnippet}");
    Console.WriteLine($"Error Code: {result.ErrorCode}");
}

// Access assigned variables
foreach (var kvp in result.Assignments)
{
    Console.WriteLine($"{kvp.Key} = {kvp.Value}");
}

// Access messages
foreach (var msg in result.Messages)
{
    Console.WriteLine($"[{msg.Level}] {msg.Text}");
}

// Execution time
Console.WriteLine($"Elapsed: {result.Elapsed}");

🧪 Running Tests

cd EasyExpression
dotnet test

📁 Project Structure

EasyExpression/
├── EasyExpression.Core/
│   └── Engine/
│       ├── Ast/              # Abstract Syntax Tree nodes
│       ├── Conversion/       # Type converters
│       ├── Functions/        # Built-in and custom functions
│       │   └── BuiltIns/     # String, Math, DateTime functions
│       ├── Parsing/          # Lexer and Parser
│       ├── Runtime/          # Execution context and results
│       ├── ExpressionEngine.cs
│       ├── ExpressionEngineFactory.cs
│       └── ExpressionEngineOptions.cs
└── EasyExpression.Core.Tests/    # Unit tests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.