Tramaj.Eval

data EvalError

Constructors

• UnboundName String
• PathNotFound (Array String)
• TypeMismatch String
• UnknownLibrary String
• ImportCycle String
• ConcatMismatch String String

  a <> b where the two sides are not the same concatenable type.

• InLibrary String EvalError

  Whatever went wrong inside an imported library, tagged with which library it was. Nests, so a failure three imports deep reads as the chain that reached it. This matters most for the parameter a library needs and the import never supplied: that surfaces as this library's own PathNotFound ["ctx", ...], and without the tag there would be nothing on it to say whose context was short.

• SymbolsUnavailable

  A symbol would have to be minted in concrete mode: an allocation (?(k), v3-symbols §4) or an unsupplied ?ctx.path demand at the root (§1.3). Concrete mode has no way to represent either. Symbolic mode never raises it: that is the one mode where a symbol is representable.

• NotConcrete String

  A symbolic value where the language requires a concrete one (§1.5's table, and a symbol used as an allocation key).

• AllocationInLibrary String

  A program containing ?(k) is loaded as a library (§1.4): only the root may allocate, because the root runs exactly once and a library does not. Lexical, not data-flow — raised because the library's own source contains an allocation site, whether or not evaluation would ever reach it.

• TypeErr TypeError

  A static v4-types failure (v4-types §10), surfaced from either the erasure pass every entry point below runs before evaluating anything (§7, roadmap Phase 11) or from building the symbolic envelope's "types"/"type-constraints" lists (§8, Phase 13). Not a new evaluation failure mode — nothing here is raised during evaluation — but Tramaj.Types.TypeError still needs a home in the one error type every entry point already returns.

• NotRepresentable String

  An arithmetic operation has no result in the type of its operands (reference.md §11, §12): an integer result outside the integer range, a zero divisor, a float result that is not finite. Nothing wraps, saturates or rounds instead.

Instances

• Eq EvalError
• Show EvalError

data Output

What a program produced. Which one it is follows from the value the root actually evaluated to, not from how the root was written: a program whose root is $header yields a document if that binding holds one.

Constructors

• ONode Node
• OValue Json

Instances

• Eq Output
• Show Output

data Mode

A host parameter, not a property of the program (v3-symbols §5): what an interpreter is willing to read back out, not anything the template itself declares. Concrete is reference.md exactly — Node JSON or a plain value, byte for byte. Symbolic wraps the same evaluation in the v3 envelope (§5.2); until §3/§4 land, that envelope's "symbols" and "constraints" are always empty, because nothing yet produces either.

Constructors

• Concrete
• Symbolic

Instances

• Eq Mode
• Show Mode

type Options = { arithmetic :: Boolean, mode :: Mode }

What a host chooses for one evaluation. Like Mode, each field is a host parameter and not a property of the program.

arithmetic is reference.md §11's arithmetic profile, per evaluation: with it on, the ten names of Tramaj.Analysis.arithmeticNames are in the initial environment of the program and of every library it runs, and a seeded term is accepted in symbolic mode (v3-symbols §5.4). With it off they are unbound, so a program that uses one fails with UnboundName, and every seeded term is refused. The two number types and the reserved "$term" key do not depend on it.

defaultOptions :: Options

Concrete mode, without the arithmetic profile. evalProgram and runProgram run with these options and the mode they are given. The profile is off unless a host asks for it, so that a host which has not opted in never receives a term, and can refuse a program up front with Tramaj.Analysis.deepArithmeticOps.

type LibraryTable = Map String Program

Host-supplied library store. Where a library came from — a file, an embedded string, a fetch — is entirely the host's business; the evaluator only ever sees an already-parsed Program.

evalProgram :: Mode -> LibraryTable -> Json -> Program -> Either EvalError Output

Evaluation now depends on the mode (v3-symbols §5): an allocation or an unsupplied root demand mints a symbol in symbolic mode and raises SymbolsUnavailable in concrete mode. There is no mode-independent evaluation any more, so every entry point takes one.

evalProgramWith :: Options -> LibraryTable -> Json -> Program -> Either EvalError Output

As evalProgram, with every per-evaluation option given (Options).

runProgram :: Mode -> LibraryTable -> Json -> Program -> Either EvalError Json

The mode-aware entry point: what a host actually serializes. Concrete mode is evalProgram unchanged, projected down to plain JSON — Node JSON for a document, the value itself for an expression, with any emissions discarded (v3-symbols §5.1). Symbolic mode wraps the same Output in the v3 envelope (§5.2), including the deduplicated symbol table and constraint list.

runProgramWith :: Options -> LibraryTable -> Json -> Program -> Either EvalError Json

As runProgram, with every per-evaluation option given (Options).

builtinNames :: Array String

The fixed builtin vocabulary of every profile; the arithmetic profile adds Tramaj.Analysis.arithmeticNames to it. Builtins are ordinary values in the initial environment rather than a separate call form, so cardinality($xs), $f($x) and map($xs, $not) all go through Call.

emittedConstraintCount :: Options -> LibraryTable -> Json -> Program -> Either EvalError Int

How many constraints an evaluation emitted, counted before dedupe makes equal ones one. No program and no output can tell this number: it is here for tests, as the one way to count how many times a function was applied, which reference.md §11 fixes for the key function of a sort.