189 lines
6 KiB
Markdown
189 lines
6 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
dotnet add package CSMic
|
|
```
|
|
|
|
Install the standard library when you also want built-in constants and math helpers:
|
|
|
|
```sh
|
|
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
|
|
|
|
```csharp
|
|
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`.
|
|
|
|
```csharp
|
|
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.
|
|
|
|
| Input | Result |
|
|
| --- | ---: |
|
|
| `5 + 5` | `10` |
|
|
| `1 + 2 * 3` | `7` |
|
|
| `(1 + 2) * 3` | `9` |
|
|
| `2 ^ 8` | `256` |
|
|
| `7 % 4` | `3` |
|
|
| `2(3 + 1)` | `8` |
|
|
|
|
Comparison operators return numeric booleans: `1` for true and `0` for false.
|
|
|
|
| Input | Result |
|
|
| --- | ---: |
|
|
| `2 == 2` | `1` |
|
|
| `2 < 3` | `1` |
|
|
| `3 < 2` | `0` |
|
|
| `2 >= 2` | `1` |
|
|
| `2 <= 1` | `0` |
|
|
|
|
## Literals
|
|
|
|
Numbers are decimal by default. Hexadecimal values use a `0x` prefix, and binary values use a `b` suffix.
|
|
|
|
| Input | Result |
|
|
| --- | ---: |
|
|
| `100` | `100` |
|
|
| `0xFF` | `255` |
|
|
| `1010b` | `10` |
|
|
| `0xFF * 1010b` | `2550` |
|
|
|
|
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.
|
|
|
|
```csharp
|
|
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.
|
|
|
|
```csharp
|
|
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.
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```csharp
|
|
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`.
|
|
|
|
```csharp
|
|
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
|
|
|
|
```sh
|
|
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`.
|