54 lines
3.6 KiB
Markdown
54 lines
3.6 KiB
Markdown
## 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.
|