🥮 mooncakes.io
    Sign in

    rinnein/moonata/value does not have a README file

    EvalContext

    source
    pub struct EvalContext {
      root : JsonataValue
      bindings : Map[String, JsonataValue]
      depth : Int
      max_depth : Int
      steps : Int
      max_steps : Int
      max_sequence : Int
      depth_exceeded_code : String
      steps_exceeded_code : String
      sequence_exceeded_code : String
      current : JsonataValue
      parent : JsonataValue
      ancestors : Array[JsonataValue]
    }

    求值上下文：持有根数据、绑定表与递归/步数/序列护栏。

    • root：$ 根数据（不可变，JSONata 中 $ 始终指原始根）。
    • bindings：变量绑定表（含内建函数），Map 本身可变，字段无需 mut。
    • depth/max_depth：递归深度护栏。
    • steps/max_steps：求值步数护栏。
    • max_sequence：序列长度护栏（-1 不限制），对齐 JSONata guardrails sequence 选项。
    • depth_exceeded_code/steps_exceeded_code/sequence_exceeded_code： 护栏超限时抛出的错误码。默认 U1001/U1001/D2015， 通过 EvalOptions::stack/timeout/sequence 启用时改用 D1011/D1012/D2015 对齐 JSONata 官方文档（U1001 仅用于 jsonata-js test runner 的 timeboxExpression 兼容路径）。
    • current：@ 当前项（谓词过滤/路径迭代时绑定）。
    • parent：$$ 父级上下文。
    • ancestors：当前项的父级链，首项为 %，后续项支持 %.%。

    EvalContext::ancestors

    source
    fn EvalContext::ancestors(self : EvalContext) -> Array[JsonataValue]

    获取父级链副本。

    EvalContext::bind

    source
    fn EvalContext::bind(self : EvalContext, name : String, value : JsonataValue) -> Unit

    绑定变量。

    EvalContext::bindings_snapshot

    source
    fn EvalContext::bindings_snapshot(self : EvalContext) -> Map[String, JsonataValue]

    获取绑定的不可变快照（用于块级作用域保存/恢复）。

    EvalContext::capture

    source
    fn EvalContext::capture(self : EvalContext) -> EvalContext

    复制求值上下文，保留当前项、父级、护栏计数与已有绑定。

    EvalContext::check_sequence_length

    source
    fn EvalContext::check_sequence_length(self : EvalContext, length : Int) -> Unit raise 
    JsonataError

    检查序列长度是否超限（护栏：超限抛 GuardrailError，错误码 D2015）。

    对齐 JSONata guardrails 文档 sequence 选项：
    The sequence option can be set to specify the maximum sequence length that can be created by an expression, including any intermediate sequences created by sub-expressions. Error D2015 will be thrown if, during the evaluation of an expression, the evaluator attempts to generate a sequence exceeding this upper limit.

    当 max_sequence <= 0 时不限制（默认行为）。

    EvalContext::current

    source
    fn EvalContext::current(self : EvalContext) -> JsonataValue

    获取当前项（@）。

    EvalContext::enter

    source

    进入递归层（护栏：超限抛 GuardrailError）。

    错误码：
    • 默认 U1001（对齐 jsonata-js test runner timeboxExpression 语义， 用于 evaluate_with_max_depth 等 legacy 路径）
    • 通过 EvalOptions::stack 启用时改用 D1011（对齐 JSONata guardrails 文档）

    EvalContext::exit

    source
    fn EvalContext::exit(self : EvalContext) -> Unit

    退出递归层。

    EvalContext::inherit_missing_bindings_from

    source
    fn EvalContext::inherit_missing_bindings_from(self : EvalContext, other : EvalContext) -> Unit

    从另一个上下文补齐当前尚未捕获的绑定。

    EvalContext::lookup

    source
    fn EvalContext::lookup(self : EvalContext, name : String) -> JsonataValue?

    查找绑定，未找到返回 None。

    EvalContext::new

    source

    构造上下文（使用默认护栏阈值）。

    EvalContext::new_with_guardrails

    source
    fn EvalContext::new_with_guardrails(root : JsonataValue, max_depth? : Int, max_steps? : Int, max_sequence? : Int, depth_exceeded_code? : String, steps_exceeded_code? : String, sequence_exceeded_code? : String) -> EvalContext

    构造上下文并指定完整护栏配置（含序列长度与错误码）。

    用于 EvalOptions 启用 JSONata 官方 guardrails 语义：
    • stack 对应 max_depth，超限抛 D1011
    • timeout（毫秒）映射为 max_steps 的近似上限（MoonBit 当前无原生 wall-clock 超时支持，使用步数上限近似），超限抛 D1012
    • sequence 对应 max_sequence，超限抛 D2015

    EvalContext::new_with_limits

    source
    fn EvalContext::new_with_limits(root : JsonataValue, max_depth? : Int, max_steps? : Int) -> EvalContext

    构造上下文并指定护栏阈值。

    EvalContext::parent

    source
    fn EvalContext::parent(self : EvalContext) -> JsonataValue

    获取父级上下文（$$）。

    EvalContext::restore_bindings

    source
    fn EvalContext::restore_bindings(self : EvalContext, snapshot : Map[String, JsonataValue]) -> Unit

    恢复绑定的快照（用于块级作用域退出时）。

    EvalContext::root

    source

    获取根数据（$）。

    EvalContext::set_current

    source
    fn EvalContext::set_current(self : EvalContext, v : JsonataValue) -> JsonataValue

    设置当前项（@），返回旧值以便恢复。

    EvalContext::set_parent

    source
    fn EvalContext::set_parent(self : EvalContext, v : JsonataValue) -> JsonataValue

    设置父级上下文（$$），返回旧值以便恢复。

    EvalContext::sync_depth_from

    source
    fn EvalContext::sync_depth_from(self : EvalContext, other : EvalContext) -> Unit

    同步 caller 的递归深度到当前上下文（用于 Lambda invoke 跨上下文传播深度计数）。 Lambda 闭包捕获定义时的 depth，invoke 时若不与 caller 同步会导致护栏失效。

    EvalContext::tick

    source

    记录一步求值（护栏：超限抛 GuardrailError）。

    错误码：
    • 默认 U1001（对齐 jsonata-js test runner 的 timeboxExpression 超时语义， 使无限尾递归（如 tail-recursion/case006）在 TCO trampoline 下也能被拦截）
    • 通过 EvalOptions::timeout 启用时改用 D1012（对齐 JSONata guardrails 文档）

    EvalContext::with_binding

    source
    fn[T] EvalContext::with_binding(self : EvalContext, name : String, value : JsonataValue, f : () -> T raise 
    JsonataError    ) -> T raise 
    JsonataError

    在局部变量绑定下执行函数，结束后恢复旧绑定。

    EvalContext::with_context

    source

    在指定当前项与父级下执行函数，自动恢复（含异常路径）。

    EvalContext::with_depth

    source

    在递归层内执行函数，自动 enter/exit（含异常路径）。

    EvalContext::with_lineage

    source

    在指定当前项与完整父级链下执行函数，自动恢复。

    JsonataFunc

    source
    pub struct JsonataFunc {
      arity : Int
      signature : String?
      contextual : Bool
      invoke : (Array[JsonataValue], EvalContext) -> JsonataValue raise 
    JsonataError
      thunk_call : () -> (JsonataFunc, Array[JsonataValue]) raise 
    JsonataError    ?
    }

    函数值：持有元数与闭包。

    内建函数与用户 Lambda 统一为 JsonataFunc，闭包接收参数数组与上下文。 thunk_call 字段用于尾调用优化（TCO）：当 Lambda 被 parser 标记为 thunk 时， invoke 返回携带 thunk_call 的 Func，apply 通过 trampoline 循环展开， 使尾递归不增长调用栈。

    JsonataFunc::apply

    source

    带尾调用优化的函数应用（trampoline）。

    调用 invoke(args, ctx) 后，若返回值是携带 thunk_call 的 Func， 则通过 trampoline 循环展开：调用 thunk_call() 获取下一个 (func, args)， 验证签名后调用 next_func.invoke(next_args, ctx)，避免递归增长调用栈。

    对齐 jsonata-js apply() 的 while(isLambda(result) && result.thunk === true) 循环
    • applyInner 中的 validateArguments 调用。

    HOF（$map/$filter/$sift 等）通过此方法调用回调函数， 确保 lambda body 经 TCO 包装后返回的 thunk Func 被正确展开为最终值。

    JsonataFunc::check_args

    source

    按签名检查已提供参数。

    签名格式参见 JSONata parseSignature：
    • 简单签名（如 "sn"、"sss"）：仅基础类型字符，宽松校验。
    • 复杂签名（含 ?/+/-/:/</>/(/)）：严格校验参数数量、类型、 数组子类型、可选/可变/上下文修饰符，并按 JSONata 语义将标量提升为单元素数组。

    错误代码：T0410（数量/类型不匹配）、T0411（上下文值不兼容）、 T0412（数组元素类型不匹配）、S0401/S0402（签名语法错误）。

    JsonataFunc::new

    source
    fn JsonataFunc::new(arity~ : Int, signature? : String?, contextual? : Bool, invoke~ : (Array[JsonataValue], EvalContext) -> JsonataValue raise 
    JsonataError    , thunk_call? : () -> (JsonataFunc, Array[JsonataValue]) raise 
    JsonataError    ?) -> JsonataFunc

    构造函数值。

    JsonataFunc::validate_args

    source

    按签名检查参数并返回可能被包装（标量→单元素数组）后的参数列表。

    用于 Lambda 求值路径，使 a<s> 等数组参数能接收标量实参。

    JsonataValue

    source
    pub(all) enum JsonataValue {
      Json(Json)
      Sequence(Array[JsonataValue])
      Func(JsonataFunc)
      Object(Map[String, JsonataValue])
      Regex(pattern~ : String, flags~ : String)
      Undefined
    } derive(
    Debug    )

    JSONata 运行时值：四态 enum。

    • Json：单个 JSON 值（包装 prelude 的 Json）。
    • Sequence：平坦序列，元素恒为 Json（已展平）。
    • Func：函数值（内建函数与 Lambda 统一为一等公民）。
    • Object：对象字面量（保留 JsonataValue 字段，含 Func/Regex）。 仅在对象构造器遇到函数/正则值时使用；普通对象仍用 Json(Json::object)。 to_json/json_for_constructor 将其转换为 Json::object（Func → ""）。
    • Undefined：JSONata 语义一等值，参与传播，不等同于 null。

    JsonataValue::equal

    source
    fn JsonataValue::equal(self : JsonataValue, other : JsonataValue) -> Bool

    比较两个 JsonataValue 是否结构相等（用于测试）。

    函数值按元数比较；序列按元素递归比较。 Object 与 Json(Json::object) 通过 to_json 归一后比较，保证语义等价。

    JsonataValue::from_json

    source
    fn JsonataValue::from_json(json : Json) -> JsonataValue

    从 JSON 值构造 JsonataValue（单例）。

    JsonataValue::is_sequence

    source
    fn JsonataValue::is_sequence(self : JsonataValue) -> Bool

    是否为序列（长度 > 1）。

    JsonataValue::is_undefined

    source
    fn JsonataValue::is_undefined(self : JsonataValue) -> Bool

    是否为 undefined。

    JsonataValue::lift_singleton

    source
    fn JsonataValue::lift_singleton(self : JsonataValue) -> JsonataValue

    将序列提升为单例（标量上下文）。

    长度为 1 的序列提升为其唯一元素；其他原样返回。

    JsonataValue::sequence

    source
    fn JsonataValue::sequence(items : Array[JsonataValue]) -> JsonataValue

    构造序列：展平嵌套序列并过滤 Undefined。

    结果长度为 0 → Undefined；长度为 1 → 单例；否则 → Sequence。

    JsonataValue::to_array

    source
    fn JsonataValue::to_array(self : JsonataValue) -> Array[JsonataValue]

    将值规范为序列数组视图。

    • Sequence → 自身数组
    • Json(Array(...)) → 解包为元素数组
    • Undefined → 空数组
    • 其他 → 单元素数组

    JsonataValue::to_json

    source
    fn JsonataValue::to_json(self : JsonataValue) -> Json

    将 JsonataValue 转换为 JSON 值。

    • Undefined → Null（JSONata 语义：undefined 序列化为 null）
    • Sequence → 长度 0 转 null；长度 1 提升为单例；否则转数组
    • Func → Null
    • Object → Json::object（字段值递归 to_json，Func → Json::string("")）

    default_max_depth

    source
    let default_max_depth : Int

    默认最大递归深度。 设为 8000：覆盖 case007 的 6555 层互递归；同时较低以保证在 8MB native 栈耗尽前 触发 U1001 拦截无限递归（case005/case006）。

    default_max_sequence

    source
    let default_max_sequence : Int

    默认最大序列长度。-1 表示不限制。

    对应 JSONata guardrails 文档 sequence 选项（默认不开启）。 通过 EvalOptions::sequence 显式启用，超限抛 D2015。

    default_max_steps

    source
    let default_max_steps : Int

    默认最大求值步数。 设为 1000000：覆盖复杂表达式求值（如 performance/case001 的 256 项嵌套路径）。 无限尾递归（TCO trampoline）通过 per-trampoline 迭代计数器拦截， 不依赖全局 max_steps。

    flatten_sequence

    source
    fn flatten_sequence(items : Array[JsonataValue]) -> Array[JsonataValue]

    展平序列：递归展平嵌套序列并过滤 Undefined。

    validate_function_args

    source
    fn validate_function_args(signature : String, args : Array[JsonataValue], context : JsonataValue) -> Array[JsonataValue] raise 
    JsonataError

    对外入口：解析签名并校验参数。

    简单签名（仅基础类型字符）走宽松校验：仅检查 min(args, params) 个参数类型， 不强制参数数量；保持与历史内建函数签名兼容。 复杂签名走严格校验。

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io