## Design Philosophy

CS‑MIC is a small, embeddable expression interpreter designed primarily for UI scenarios where a user types flexible input (e.g., 2+2+someVar) but the host application needs a validated, deterministic numeric value. The library focuses on predictable evaluation, strong validation and extensibility through developer‑supplied variables and coded functions.

Goals

- Numeric‑first: Expressions evaluate to a numeric result the host can trust.
- Predictable semantics: No implicit coercions or surprising operator behavior.
- Embeddable: Tiny surface area, easy to host inside C# applications.
- Extensible: Developers inject variables and ICodedFunction implementations.
- Clear errors: Friendly, actionable diagnostics for invalid input.

Core Principles

- Determinism: The same input with the same variables/functions yields the same numeric output.
- Minimalism: Keep the grammar and runtime small; add features only when they reinforce the numeric‑first mission.
- Type clarity: Values carry explicit types; operators enforce type rules rather than auto‑converting.
- Safe composition: Functions are pure from the interpreter’s perspective; side effects are the host’s responsibility.

### Strings: Arguments‑Only, Numeric‑First

CS‑MIC’s v2 scope treats strings as helpers for functions, not as first‑class expression values. This preserves the “numeric guarantee” while enabling rich, domain‑specific function usage.

- Where strings are allowed: As literals in function argument lists (e.g., myFunc("key", 42)).
- Where strings are not allowed: As standalone primaries, in arithmetic (e.g., "a" + 1), or in comparisons; string variables are out of scope for v2.
- Function contract: ICodedFunction implementations may accept string arguments and should return a numeric result when the function’s value is used in an expression.
- Grammar posture: The grammar recognizes quoted string tokens; the parser accepts them only in function argument positions.
- Operator semantics: No string operators or concatenation; no implicit conversions from string to number.
- Errors: If a string is used outside an argument position or produced where a number is required, the interpreter emits a clear type error (e.g., "strings are only valid as function arguments").

Rationale

- Preserves the primary mission: turn flexible user input into a validated numeric value.
- Keeps complexity low by avoiding general string semantics (concatenation, ordering, variables, etc.).
- Maximizes developer power: functions can receive text payloads (formats, keys, expressions) and return numbers, leveraging CS‑MIC for parsing, validation and invocation.

Developer Guidance

- Implementing ICodedFunction: Inspect FunctionArgument.Value.Type to branch on expected input. If a string is required, validate and produce a numeric FunctionValue.
- Argument metadata: Optionally use ExpectedArguments to document names and intended types for better diagnostics.
- Error messaging: Prefer precise, actionable messages (e.g., "arg 'pattern' must be a string").

Example

// Pseudocode / sketch
// myFunc("HEX", 0xFF) → 255
// myFunc("BIN", 1010b) → 10
// sumWithLabel("groupA", 1, 2, 3) → 6 (label used for logging/selection)

Future Directions (Non‑Goals for v2)

- First‑class strings: Allow strings as values, variables, or return types in general expressions (would require defining operators and comparisons).
- Verbatim/opaque arguments: Special argument modes for embedding mini‑DSLs (higher parser complexity).
- Value tagging: Optional metadata (e.g., OriginalLiteral) attached to FunctionValue for advanced scenarios.