Documentation
¶
Overview ¶
Package formulaident is the one OVERLAY_FORMULA identifier reading: the AST walk that splits a formula's references into variables, called functions and Compose `slot.<label>.<field>` paths (Collect), the function set an overlay formula may call (AllowedFuncs), and the Compose-host namespace plus its refusal (ComposeRefusal).
Predict (internal/descriptor) and the runtime Compose dispatcher (internal/processing) both call ComposeRefusal on the same inputs — the reference slot's authored shape, the slots the spec names and the instance's functions — so a Compose FORMULA that names an identifier outside its namespace is refused with the same code, message and Details on both sides, before the runtime compiles it.
Leaf: stdlib + expr-lang parser/ast + types + errors + internal/exprenv. No-execute.
Index ¶
- Constants
- func AllowedFuncs(exprFunctions []string, hasLookup bool) map[string]struct{}
- func BaselineOutOfRange(kind types.OverlayKind, index, position, seriesLength int) *errors.CodedError
- func BaselinePosition(params map[string]any) (position int, set, bad bool)
- func BuiltinRefusal(kind types.OverlayKind, formula string, index int) *errors.CodedError
- func ComposeFormula(params map[string]any) (formula, reason string)
- func ComposeRefVar(shape types.OverlayShape) string
- func ComposeRefusal(kind types.OverlayKind, params map[string]any, index int, ...) *errors.CodedError
- func ComposeSlotPaths(slots []Slot) map[string]struct{}
- func ComposeVars(shape types.OverlayShape) map[string]struct{}
- func MissingFormula(kind, msg string, index int, reason string) *errors.CodedError
- func RequestRefusal(kind types.OverlayKind, formula string, node *exprast.Node, index int, ...) *errors.CodedError
- func RequestSpecRefusal(spec *types.OverlaySpec, index int, shape types.OverlayShape, ...) *errors.CodedError
- func RequestVars(shape types.OverlayShape, baseline bool) map[string]struct{}
- func SlotField(shape types.OverlayShape) string
- func SpecBaselinePosition(spec *types.OverlaySpec) (position int, set bool)
- type Refs
- type Slot
Constants ¶
const ( ReasonMissingFormula = "missing formula param" ReasonEmptyFormula = "formula param is empty or non-string" )
Reasons a FORMULA spec carries no usable formula (Details.reason of MissingFormula).
const BaselineParam = "baseline_position"
BaselineParam is the Request-host SERIES FORMULA param naming the positional baseline row `baseline` reads.
Variables ¶
This section is empty.
Functions ¶
func AllowedFuncs ¶
AllowedFuncs is the function set an OVERLAY_FORMULA may call: the overlay scalar-maths built-ins, the set helpers, every embedder ExprFunction name and, when the instance registers a LookupTable, `lookup` — exactly what the runtime overlay compile registers.
func BaselineOutOfRange ¶
func BaselineOutOfRange(kind types.OverlayKind, index, position, seriesLength int) *errors.CodedError
BaselineOutOfRange is the refusal of a SERIES FORMULA whose params.baseline_position is at or past the end of a partition of seriesLength rows: PULSE_OVERLAY_REF_UNKNOWN {index, kind, baseline_position, series_length}. The runtime raises it off the materialised partition; predict raises it when the partition length is bounded by the schema (every in-partition grouper a GROUP_CATEGORY over a categorical field: the product of the dictionary sizes) and the position reaches the bound — series_length then carries the bound. A data-dependent axis is judged by the runtime only. A negative index omits Details.index (the runtime handler, whose dispatcher stamps it).
func BaselinePosition ¶
BaselinePosition reads params.baseline_position: (position, true, false) for a non-negative integer, (0, false, false) when it is absent or null, (0, false, true) for any other value.
func BuiltinRefusal ¶
func BuiltinRefusal(kind types.OverlayKind, formula string, index int) *errors.CodedError
BuiltinRefusal refuses a FORMULA calling a reserved built-in outside the overlay scalar subset (exprenv.OverlayRefused — the vector families and the calendar helpers) with PULSE_OVERLAY_FORMULA_INVALID_IDENT, Details {kind, unknown_identifier, allowed_builtins, formula} plus `index` when index >= 0. nil when the formula calls none (or fails to parse). Every host runs it before its identifier gate, predict and runtime alike, so a vector built-in reads this message, not "unknown function".
func ComposeFormula ¶
ComposeFormula reads params["formula"]: (formula, "") when it is a non-empty string, else ("", reason).
func ComposeRefVar ¶
func ComposeRefVar(shape types.OverlayShape) string
ComposeRefVar is the reference-slot variable of a Compose FORMULA over a host of shape: ref_cell (MATRIX), ref_value (SERIES), ref (SCALAR).
func ComposeRefusal ¶
func ComposeRefusal(kind types.OverlayKind, params map[string]any, index int, shape types.OverlayShape, slots []Slot, funcs map[string]struct{}) *errors.CodedError
ComposeRefusal judges the Compose OVERLAY_FORMULA spec at index over a host of shape (the reference slot's authored shape), naming slots (its reference and targets) and allowed to call funcs. nil when the formula reads only its namespace; otherwise, first hit wins:
- no usable params.formula: MissingFormula's PULSE_OVERLAY_PARAM_MISSING, Details {index, kind, param, reason};
- a parse failure: PULSE_OVERLAY_FORMULA_PARSE_ERROR, Details {index, kind, formula, parse_error};
- an unknown variable, function or slot path (each in sorted order): PULSE_OVERLAY_FORMULA_INVALID_IDENT, Details {index, kind, unknown_identifier, host_shape, formula} plus `allowed`, `allowed_funcs` or `allowed_slots`.
func ComposeSlotPaths ¶
ComposeSlotPaths is every `slot.<label>.<field>` path a Compose FORMULA naming slots may read.
func ComposeVars ¶
func ComposeVars(shape types.OverlayShape) map[string]struct{}
ComposeVars is a Compose FORMULA's variable namespace over a host of shape: types.FormulaNamespace(shape) plus ComposeRefVar(shape).
func MissingFormula ¶
func MissingFormula(kind, msg string, index int, reason string) *errors.CodedError
MissingFormula is the refusal of an OVERLAY_FORMULA spec that carries no usable formula — Params absent or not an object, no "formula" key, an empty or non-string value — on EVERY FORMULA arm (Request host MATRIX and SERIES, Compose) and on both sides: PULSE_OVERLAY_PARAM_MISSING (the more specific code for "no formula"), Details {index, kind, param: "formula", reason}. A formula that is present but does not parse, or names an unknown identifier, keeps its formula-specific code (PULSE_OVERLAY_FORMULA_PARSE_ERROR / _INVALID_IDENT).
func RequestRefusal ¶
func RequestRefusal(kind types.OverlayKind, formula string, node *exprast.Node, index int, shape types.OverlayShape, vars, funcs map[string]struct{}) *errors.CodedError
RequestRefusal judges the identifiers of the Request-host OVERLAY_FORMULA spec at index whose parsed formula is node, over a host of shape, against the variables vars (RequestVars) and the callable funcs (AllowedFuncs). nil when every reference is in reach; otherwise PULSE_OVERLAY_FORMULA_INVALID_IDENT for the first unknown variable, then function, then `slot.<label>.<field>` path (the slot namespace is Compose-only), each class in sorted order. Details {index, kind, unknown_identifier, host_shape, formula} plus `allowed`, `allowed_funcs` or `reason`.
func RequestSpecRefusal ¶
func RequestSpecRefusal(spec *types.OverlaySpec, index int, shape types.OverlayShape, funcs map[string]struct{}) *errors.CodedError
RequestSpecRefusal judges the Request-host OVERLAY_FORMULA spec at index over a host of shape (MATRIX or SERIES), allowed to call funcs (AllowedFuncs). Predict (descriptor.validateFormulaOverlay) and the runtime MATRIX and SERIES dispatchers call it before any compile, so every refusal below carries one code, message and Details on both sides. nil when the spec is in reach; otherwise, first hit wins:
- no usable params.formula (Params absent or not an object, the key absent, an empty or non-string value): PULSE_OVERLAY_PARAM_MISSING {index, kind, param, reason} (MissingFormula — every FORMULA arm's rule);
- a parse failure: PULSE_OVERLAY_FORMULA_PARSE_ERROR {index, kind, formula, parse_error};
- a total() call: totalcall.Refusal's code, Details + index, kind;
- a vector built-in: BuiltinRefusal;
- SERIES only: a params.baseline_position that is not a non-negative integer: PULSE_OVERLAY_LEVEL_OUT_OF_RANGE {index, kind, param, baseline_position};
- an unknown variable, function or slot path: RequestRefusal over RequestVars(shape, baseline_position set).
func RequestVars ¶
func RequestVars(shape types.OverlayShape, baseline bool) map[string]struct{}
RequestVars is a Request-host FORMULA's variable namespace over a host of shape: types.FormulaNamespace(shape), plus `baseline` on a SERIES host whose spec sets params.baseline_position (baseline).
func SlotField ¶
func SlotField(shape types.OverlayShape) string
SlotField is the field a `slot.<label>.<field>` path reads on a slot of shape: cell (MATRIX) or value (SERIES / SCALAR).
func SpecBaselinePosition ¶
func SpecBaselinePosition(spec *types.OverlaySpec) (position int, set bool)
SpecBaselinePosition is BaselinePosition over spec.Params (a non-object Params reads as absent).
Types ¶
type Refs ¶
type Refs struct {
// Vars holds every plain identifier that is neither a call callee
// nor a member-chain root.
Vars map[string]struct{}
// Funcs holds every identifier called as a function (a CallNode
// callee). expr-lang stdlib helpers parse as BuiltinNodes and never
// land here.
Funcs map[string]struct{}
// SlotPaths holds every outermost member chain rooted at `slot`,
// flattened ("slot.us.cell"). Chains rooted elsewhere are dropped:
// their root identifier governs them.
SlotPaths map[string]struct{}
}
Refs is the identifier split of one formula.
type Slot ¶
type Slot struct {
Label string
Shape types.OverlayShape
}
Slot is one Compose slot a FORMULA spec names (its reference or a target): the resolved label and the slot's authored host shape.
Source Files