CSMic 2.0.0

CS-MIC

CS-MIC is a small, embeddable expression interpreter for .NET applications. It is designed for places where users need to enter flexible numeric input, while the host application needs a deterministic decimal result and a controlled extension surface.

The 2.0 release separates the project into two NuGet packages:

• CSMic: the core parser, interpreter, variable store, and custom function API.
• CSMic.StandardLibrary: optional constants and common math functions built on top of the core package.

CS-MIC targets netstandard2.1.

Installation

Install the core interpreter when you want to parse expressions and provide your own functions:

dotnet add package CSMic

Install the standard library when you also want built-in constants and math helpers:

dotnet add package CSMic.StandardLibrary

CSMic.StandardLibrary references CSMic, so applications that use the standard library do not need to install both packages explicitly.

Basic Usage

using CSMic;

var interpreter = new InputInterpreter();

decimal result = interpreter.Interpret("2 + 3 * 4");
// result == 14
// interpreter.NumericValue == 14

Interpret returns the numeric result and also stores the last output on the interpreter. Parse and runtime errors are soft errors: the interpreter returns 0 and writes the error message to StringValue.

decimal result = interpreter.Interpret("1 / 0");

if (!string.IsNullOrEmpty(interpreter.StringValue))
{
    Console.WriteLine(interpreter.StringValue);
}

Create a new interpreter for an isolated evaluation context. Reuse an interpreter when variables, arrays, expression bindings, and registered functions should persist across calls.

Expressions

CS-MIC evaluates numeric expressions with the usual precedence rules for parentheses, powers, multiplication, division, modulus, addition, and subtraction.

Comparison operators return numeric booleans: 1 for true and 0 for false.

Literals

Numbers are decimal by default. Hexadecimal values use a 0x prefix, and binary values use a b suffix.

String literals are accepted only as function arguments. They are not standalone expression values, variables, or arithmetic operands.

Variables And Arrays

Use :: to assign a numeric value. Numeric variables are evaluated immediately and persist on the interpreter.

interpreter.Interpret("x :: 4");  // 4
interpreter.Interpret("x + 6");   // 10

Use := to assign an expression binding. Expression bindings are evaluated when referenced, so they can reflect later changes to other variables.

interpreter.Interpret("x :: 2");
interpreter.Interpret("doubleX := 2 * x");

interpreter.Interpret("doubleX"); // 4

interpreter.Interpret("x :: 5");
interpreter.Interpret("doubleX"); // 10

Use -> to assign a numeric array, then index it with zero-based indexes.

interpreter.Interpret("values -> [10, 20, 30]");
interpreter.Interpret("values[1]"); // 20

Standard Library

Add CSMic.StandardLibrary and initialize the interpreter to register the standard functions and constants:

using CSMic;
using CSMic.StandardLibrary;

var interpreter = new InputInterpreter();
Initializer.InitializeAll(interpreter);

decimal area = interpreter.Interpret("pi * 10^2");
decimal angle = interpreter.Interpret("degrees(pi / 2)");

InitializeAll registers all functions and constants. You can also opt into smaller groups with InitializeAllFunctions, InitializeConstants, InitializeBaseFunctions, InitializeAngleFunctions, InitializeRoundingFunctions, InitializeTrigonometryFunctions, InitializeNumberTheoryFunctions, and InitializeRandomFunctions.

The standard library includes:

• Base functions: abs, sign, min, max
• Angle helpers: degrees, radians, wrapangle
• Rounding helpers: floor, ceiling, truncate, frac, round, clamp
• Trigonometry: sin, cos, tan, asin, acos, atan, atan2
• Hyperbolic trigonometry: sinh, cosh, tanh, asinh, acosh, atanh
• Number theory: fac, ncr, npr, gcd, lcm
• Random helpers: flip, bern, rand, rands, randn, randns
• Constants: pi, e, tau, phi, goldenratio, eurler, omega

Custom Functions

Register custom functions by implementing ICodedFunction.

using CSMic;

public sealed class Square : ICodedFunction
{
    public string Name => "square";

    public IEnumerable<FunctionArgument> ExpectedArguments =>
        new[] { new FunctionArgument("value", FunctionValue.NUMBER) };

    public FunctionValue ReturnValue => FunctionValue.NUMBER;

    public FunctionValue Execute(params FunctionArgument[] args)
    {
        var value = (decimal)args[0].Value.Value!;
        return new FunctionValue(FunctionValueType.Numeric, value * value);
    }
}

var interpreter = new InputInterpreter();
interpreter.RegisterFunction(new Square());

decimal result = interpreter.Interpret("square(12)");
// result == 144

Functions can accept numeric or string arguments. String arguments are useful for host-defined keys, modes, or labels while preserving CS-MIC's numeric-first expression model.

Building From Source

dotnet restore src/CsMic.sln
dotnet test src/CsMic.sln
dotnet pack src/Core/CSMic.Core.csproj -c Release
dotnet pack src/StandardLibrary/CSMic.StandardLibrary.csproj -c Release

The core project uses Coco/R during build to generate parser and scanner code from src/Core/cocor/Interpreter.atg.