DEV Community: Hercules Lemke Merscher

Tsonnet #38 - Call me maybe, but make it typed, part 3

Hercules Lemke Merscher — Tue, 21 Apr 2026 07:00:00 +0000

Welcome to the Tsonnet series!

If you're not following along, check out how it all started in the first post of the series.

In the previous post, we implemented closures — both bound to locals and immediately invoked:

Hercules Lemke Merscher

Apr 19

Tsonnet #37 - Call me maybe, but make it typed, part 3

#tsonnet #jsonnet #compiler

Comments

8 min read

I was annoyed by the fact that function type variants were difficult to read, so went on an errand to make it simpler. We can do better!

Let's see how it turned out.

A makeover for the AST

diff --git a/lib/ast.ml b/lib/ast.ml
index e317b6e..4b1102e 100644
--- a/lib/ast.ml
+++ b/lib/ast.ml
@@ -90,10 +90,9 @@ type expr =
   | Local of position * (string * expr) list
   | Seq of expr list
   | IndexedExpr of position * string * expr
-  | FunctionDef of position * (string * (string * expr option) list * expr)
-  | FunctionCall of position * string * expr list
-  | Closure of position * ((string * expr option) list * expr)
-  | ClosureCall of position * (string * expr option) list * expr * expr list
+  | FunctionDef of position * function_def
+  | FunctionCall of position * function_call
+  | Closure of position * closure

 and object_entry =
   | ObjectField of string * expr

ClosureCall is gone. It's basically FunctionCall, so there's no need to have a duplicated type variant.

The type variants function_def, function_call, and closure are represented as records, which makes them much easier to reason about since we can have names to represent what they are holding:

@@ -102,6 +101,20 @@ and object_scope =
   | Self
   | TopLevel
   | ObjVarRef of string
+
+and function_def = {
+  name: string;
+  params: (string * expr option) list;
+  body: expr;
+}
+and function_call = {
+  callee: expr;
+  args: expr list;
+}
+and closure = {
+  params: (string * expr option) list;
+  body: expr;
+}
 [@@deriving show]

 let dummy_expr = Unit

With this AST change, it became easier to simplify the parsing rules:

diff --git a/lib/parser.mly b/lib/parser.mly
index 8b3821e..e7b7771 100644
--- a/lib/parser.mly
+++ b/lib/parser.mly
@@ -22,6 +22,7 @@
 %token DOT
 %token SELF TOP_LEVEL_OBJ
 %token PLUS MINUS MULTIPLY DIVIDE MODULO
+%nonassoc FUNCTION
 %left PLUS MINUS
 %left MULTIPLY DIVIDE MODULO
 %token <string> ID
@@ -43,13 +44,11 @@
 prog:
   | e = expr; EOF { e }
   | e = expr_seq; EOF { e }
-  | e = closure; EOF { e }
   ;

 expr:
   | e = assignable_expr { e }
   | e = vars { e }
-  | e = closure_call { e }
   ;

 expr_seq:
@@ -63,6 +62,7 @@ assignable_expr:
   | e = indexed_expr { e }
   | e = obj_field_access { e }
   | e = funcall { e }
+  | e = closure { e }
   ;

 indexed_expr:
@@ -175,7 +175,6 @@ obj_field_access:

 var:
   | varname = ID; ASSIGN; e = assignable_expr { (varname, e) }
-  | varname = ID; ASSIGN; e = closure { (varname, e) }
   ;

 vars:
@@ -196,7 +195,7 @@ fundef:
   | fname = ID;
     LEFT_PAREN; params = separated_nonempty_list(COMMA, fundef_param); RIGHT_PAREN;
     ASSIGN;
-    body = fundef_body { (fname, params, body) }
+    body = fundef_body { { name = fname; params = params; body = body } }
   ;

 fundef_body:
@@ -207,20 +206,23 @@ fundef_body:
 funcall:
   | fname = ID;
     LEFT_PAREN; params = separated_nonempty_list(COMMA, assignable_expr); RIGHT_PAREN
-    { FunctionCall (with_pos $startpos $endpos, fname, params) }
+    { FunctionCall
+      (with_pos $startpos $endpos, {
+        callee = Ident (with_pos $startpos(fname) $endpos(fname), fname);
+        args = params;
+      })
+    }
+  | callee = scoped_expr;
+    LEFT_PAREN; params = separated_nonempty_list(COMMA, assignable_expr); RIGHT_PAREN
+    { FunctionCall (with_pos $startpos $endpos, { callee = callee; args = params }) }
   ;

 closure:
   | FUNCTION;
     LEFT_PAREN; params = separated_nonempty_list(COMMA, fundef_param); RIGHT_PAREN;
-    body = assignable_expr { Closure (with_pos $startpos $endpos, (params, body)) }
-  ;
-
-closure_call:
-  | LEFT_PAREN; FUNCTION;
-    LEFT_PAREN; def_params = separated_nonempty_list(COMMA, fundef_param); RIGHT_PAREN;
-    body = assignable_expr;
-    RIGHT_PAREN;
-    LEFT_PAREN; call_params = separated_nonempty_list(COMMA, assignable_expr); RIGHT_PAREN;
-    { ClosureCall (with_pos $startpos $endpos, def_params, body, call_params) }
+    body = assignable_expr {
+      Closure (with_pos $startpos $endpos, { params = params; body = body })
+    }
+    (* precedence here will transform "function(x) x * x" into "function(x) (x * x)" *)
+    %prec FUNCTION
   ;

I could finally move closure out of prog and expr. It was never meant to be there. But part of the problem was not having FUNCTION flagged as non-associative.

The interpreter catches up

With ClosureCall gone and FunctionCall now carrying a callee: expr, the interpreter needed a bit more surgery -- resolving the callee before dispatching to apply_function:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index 7412fb9..15f9932 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -27,9 +27,8 @@ let rec interpret env expr =
   | Seq exprs -> interpret_seq env exprs
   | IndexedExpr (pos, varname, index_expr) -> interpret_indexed_expr env (pos, varname, index_expr)
   | FunctionDef (pos, def) -> interpret_function_def env (pos, def)
-  | FunctionCall (pos, fname, params) -> interpret_function_call env (pos, fname, params)
+  | FunctionCall (pos, call) -> interpret_function_call env (pos, call)
   | Closure _ -> ok (env, expr)
-  | ClosureCall (pos, def_params, body, params) -> interpret_closure_call env (pos, def_params, body, params)

 and interpret_indexed_expr env (pos, varname, index_expr) =
   let* (env', index_expr') = interpret env index_expr in
@@ -417,8 +416,8 @@ and interpret_ident env pos varname =
     result
   end

-and interpret_function_def env (pos, (fname, params, body)) =
-  let env' = Env.add_local fname (FunctionDef (pos, (fname, params, body))) env in
+and interpret_function_def env (pos, def) =
+  let env' = Env.add_local def.name (FunctionDef (pos, def)) env in
   ok (env', Unit)

 and apply_function env pos def_params body call_params =
@@ -468,16 +467,23 @@ and apply_function env pos def_params body call_params =
     in
     ok (env, result)

-and interpret_function_call env (pos, fname, call_params) =
-  match Env.find_opt fname env with
-  | Some (Closure (pos, (def_params, body)))
-  | Some (FunctionDef (pos, (_, def_params, body))) ->
-    apply_function env pos def_params body call_params
+and interpret_function_call env (pos, call) =
+  let* (env', callee_val) =
+    match call.callee with
+    | Ident (pos, name) ->
+      (match Env.find_opt name env with
+      | Some expr -> ok (env, expr)
+      | None -> Error.error_at pos (Error.Msg.var_not_found name)
+      )
+    | _ -> interpret env call.callee
+  in
+  match callee_val with
+  | Closure (_, closure) ->
+    apply_function env' pos closure.params closure.body call.args
+  | FunctionDef (_, def) ->
+    apply_function env' pos def.params def.body call.args
   | _ ->
-    Error.error_at pos (Error.Msg.var_not_found fname)
-
-and interpret_closure_call env (pos, def_params, body, call_params) =
-  apply_function env pos def_params body call_params
+    Error.error_at pos (Error.Msg.var_not_found (string_of_type call.callee))

 let rec deep_eval expr =
   match expr with

The type checker gets the memo

The type checker can also be improved by using the new type variants as records:

diff --git a/lib/type.ml b/lib/type.ml
index ee912b3..ad4f333 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -17,10 +17,10 @@ type tsonnet_type =
   | TobjectPtr of Env.env_id * t_object_scope
   | Lazy of expr
   | Tunresolved
-  | TfunctionDef of (string * tsonnet_type) list (* params: name * type *) * expr (* body *) * tsonnet_type (* return *)
-  | TfunctionCall of tsonnet_type list * tsonnet_type
-  | Tclosure of (string * tsonnet_type) list * expr
-  | TclosureCall of tsonnet_type list * tsonnet_type
+  | TfunctionDef of t_function_def
+  | TfunctionCall of t_function_call
+  | Tclosure of t_closure
+
 and t_object_entry =
   | TobjectField of string * tsonnet_type
   | TobjectExpr of tsonnet_type
@@ -28,6 +28,20 @@ and t_object_scope =
   | TobjectSelf
   | TobjectTopLevel

+and t_function_def = {
+  params: (string * tsonnet_type) list;
+  body: expr;
+  return: tsonnet_type;
+}
+and t_function_call = {
+  params: tsonnet_type list;
+  return: tsonnet_type;
+}
+and t_closure = {
+  params: (string * tsonnet_type) list;
+  body: expr;
+}
+
 let rec to_string = function
   | Tunit -> "()"
   | Tnull -> "Null"
@@ -59,25 +73,21 @@ let rec to_string = function
       | TobjectTopLevel -> "$"
     in Printf.sprintf "%s (%d)" s id
   | Lazy ty -> string_of_type ty
-  | TfunctionDef (params, _, return) ->
+  | TfunctionDef {params; return; _} ->
     Printf.sprintf "function(%s) -> %s"
       (List.map (fun (name, ty) -> name ^ ": " ^ to_string ty) params
       |> String.concat ", "
       )
       (to_string return)
-  | TfunctionCall (params_type, return) ->
+  | TfunctionCall {params=params_type; return} ->
     Printf.sprintf "function(%s) -> %s"
       (List.map to_string params_type |> String.concat ", ")
       (to_string return)
-  | Tclosure (params, _) ->
+  | Tclosure {params; _} ->
     Printf.sprintf "function(%s)"
       (List.map (fun (name, ty) -> name ^ ": " ^ to_string ty) params
       |> String.concat ", "
       )
-  | TclosureCall (params_type, return) ->
-    Printf.sprintf "function(%s) -> %s"
-      (List.map to_string params_type |> String.concat ", ")
-      (to_string return)
   | Tunresolved -> "<unresolved>"

 let rec collect_free_idents = function
@@ -95,10 +105,9 @@ let rec collect_free_idents = function
   | ObjectFieldAccess (_, _, exprs) -> List.concat_map collect_free_idents exprs
   | IndexedExpr (_, name, e) -> name :: collect_free_idents e
   | Local (_, vars) -> List.concat_map (fun (_, e) -> collect_free_idents e) vars
-  | FunctionCall (_, name, args) -> name :: List.concat_map collect_free_idents args
-  | Closure (_, (_, body)) -> collect_free_idents body
-  | ClosureCall (_, _, body, args) ->
-    collect_free_idents body @ List.concat_map collect_free_idents args
+  | FunctionCall (_, call) ->
+    collect_free_idents call.callee @ List.concat_map collect_free_idents call.args
+  | Closure (_, closure) -> collect_free_idents closure.body
   | _ -> []

 let reachable_bindings bindings initial_idents =
@@ -192,10 +201,8 @@ let rec translate venv expr =
   | UnaryOp (pos, op, expr) -> translate_unary_op venv (pos, op, expr)
   | IndexedExpr (pos, varname, index_expr) -> translate_indexed_expr venv (pos, varname, index_expr)
   | FunctionDef (pos, def) -> translate_function_def venv (pos, def)
-  | FunctionCall (pos, fname, params) -> translate_function_call venv (pos, fname, params)
-  | Closure (pos, (params, body)) -> translate_closure venv (pos, params, body)
-  | ClosureCall (pos, def_params, body, call_params) ->
-    translate_closure_call venv (pos, def_params, body, call_params)
+  | FunctionCall (pos, call) -> translate_function_call venv (pos, call)
+  | Closure (pos, closure) -> translate_closure venv (pos, closure)
   | expr' ->
     error (Error.Msg.type_invalid_expr (string_of_type expr')) 
@@ -493,7 +500,7 @@ and translate_bin_op venv pos op e1 e2 =
   | _, Tany, _ | _, _, Tany -> ok (venv'', Tany)
   | _ -> Error.error_at pos Error.Msg.invalid_binary_op

-and translate_function_def venv (pos, (fun_name, params, body)) =
+and translate_function_def venv (pos, def) =
   (* For params with defaults, we can infer the type from the default expression;
      params without defaults remain Tunresolved until the first call *)
   let* params_typed = List.fold_left
@@ -507,36 +514,57 @@ and translate_function_def venv (pos, (fun_name, params, body)) =
         ok (params' @ [(name, Tunresolved)])
     )
     (ok [])
-    params
+    def.params
+  in
+  let fun_def = TfunctionDef
+    { params = params_typed;
+      body = def.body;
+      return = Tunresolved;
+    }
   in
-  let fun_def = TfunctionDef (params_typed, body, Tunresolved) in
   (* So, function declaration will have an unresolved type definition,
      that only later it will be translated: before function call translation!
      After first function call, concrete types are set and subsequent calls will
      type check against the initial type assignment(s). *)
-  let venv' = Env.add_local fun_name fun_def venv in
+  let venv' = Env.add_local def.name fun_def venv in
   ok (venv', fun_def)

-and translate_function_call venv (pos, fname, call_params) =
-  (* 1. retrieve TfunctionDef from venv *)
-  match Env.find_opt fname venv with
-  | Some (TfunctionDef (def_params, body_expr, return_type)) ->
-    (* check arity: allow fewer args if defaults exist *)
-    let num_call = List.length call_params in
+and translate_function_call venv (pos, call) =
+  match call.callee with
+  | Ident (_, name) ->
+    translate_named_function_call venv (pos, name, call.args)
+  | Closure (_, closure) ->
+    translate_closure_call venv (pos, closure.params, closure.body, call.args)
+  | _ ->
+    let* (venv', callee_ty) = translate venv call.callee in
+    (match callee_ty with
+    | Tclosure { params = closure_params; body = body_expr } ->
+      let def_params = List.map (fun (name, _ty) -> (name, None)) closure_params in
+      translate_closure_call venv' (pos, def_params, body_expr, call.args)
+    | _ ->
+      Error.error_at pos (Error.Msg.type_invalid_expr (string_of_type call.callee))
+    )
+
+and translate_named_function_call venv (pos, name, args) =
+  match Env.find_opt name venv with
+  | Some (TfunctionDef { params = def_params;
+                         body = body_expr;
+                         return = return_type;
+                       }) ->
+    let num_call = List.length args in
     let num_def = List.length def_params in
     if num_call > num_def
     then
       Error.error_at pos
         (Error.Msg.wrong_number_of_params num_def num_call)
     else
-      (* 2. type check each positional parameter passed in the function call *)
       let* (venv', resolved_params) =
         List.fold_left
           (fun acc (index, (param_name, def_param_type)) ->
             let* (venv', params') = acc in
             if index < num_call
             then
-              let call_param = List.nth call_params index in
+              let call_param = List.nth args index in
               let* (venv'', call_param_type) = translate venv' call_param in
               match def_param_type with
               | Tunresolved ->
@@ -549,26 +577,22 @@ and translate_function_call venv (pos, fname, call_params) =
                     ~expected:(to_string expected)
                     ~got:(to_string call_param_type))
             else
-              (* default arg — resolve type from the original AST default expression *)
               ok (venv', params' @ [(param_name, def_param_type)])
           )
           (ok (venv, []))
           (List.mapi (fun i p -> (i, p)) def_params)
       in
-      (* 3. type check return *)
       let body_venv = List.fold_left
         (fun env (name, ty) -> Env.add_local name ty env)
         venv'
         resolved_params
       in
-      (* translate the body with resolved param types in scope *)
       let* (_, body_type) = translate body_venv body_expr in
-      let* resolved_return = match return_type with
+      let* resolved_return =
+        match return_type with
         | Tunresolved ->
-          (* 3a. first call: infer return type from body *)
           ok body_type
         | expected ->
-          (* 3b. subsequent calls: check body type matches *)
           if body_type = expected
           then ok expected
           else Error.error_at pos
@@ -576,23 +600,26 @@ and translate_function_call venv (pos, fname, call_params) =
               ~expected:(to_string expected)
               ~got:(to_string body_type))
       in
-      (* 4. update env with the now-resolved function type *)
-      let resolved_fun = TfunctionDef (resolved_params, body_expr, resolved_return) in
-      let venv_with_resolved_fun = Env.add_local fname resolved_fun venv' in
+      let resolved_fun =
+        TfunctionDef {
+          params = resolved_params;
+          body = body_expr;
+          return = resolved_return;
+        }
+      in
+      let venv_with_resolved_fun = Env.add_local name resolved_fun venv' in
       ok (venv_with_resolved_fun, resolved_return)
   | Some (Lazy expr) ->
     let* (venv', resolved) = translate venv expr in
-    (* Re-dispatch with the resolved type *)
-    let venv'' = Env.add_local fname resolved venv' in
-    translate_function_call venv'' (pos, fname, call_params)
-  | Some (Tclosure (def_params, body_expr)) ->
-    translate_closure_call venv (pos, 
-      List.map (fun (name, _ty) -> (name, None)) def_params,
-      body_expr, call_params)
+    let venv'' = Env.add_local name resolved venv' in
+    translate_named_function_call venv'' (pos, name, args)
+  | Some (Tclosure { params = closure_params; body = body_expr }) ->
+    let def_params = List.map (fun (name, _ty) -> (name, None)) closure_params in
+    translate_closure_call venv (pos, def_params, body_expr, args)
   | _ ->
-    Error.error_at pos (Error.Msg.var_not_found fname)
+    Error.error_at pos (Error.Msg.var_not_found name)

-and translate_closure venv (_pos, params, body) =
+and translate_closure venv (_pos, closure) =
   let* params_typed = List.fold_left
     (fun acc (name, default) ->
       let* params' = acc in
@@ -604,11 +631,11 @@ and translate_closure venv (_pos, params, body) =
         ok (params' @ [(name, Tunresolved)])
     )
     (ok [])
-    params
+    closure.params
   in
-  ok (venv, Tclosure (params_typed, body))
+  ok (venv, Tclosure { params = params_typed; body = closure.body })

-and translate_closure_call venv (pos, def_params, body_expr, call_params) =
+and translate_closure_call venv (pos, def_params, body, call_params) =
   let num_call = List.length call_params in
   let num_def = List.length def_params in
   let num_required =
@@ -641,7 +668,7 @@ and translate_closure_call venv (pos, def_params, body_expr, call_params) =
       venv'
       resolved_params
     in
-    let* (_, body_type) = translate body_venv body_expr in
+    let* (_, body_type) = translate body_venv body in
     ok (venv, body_type)

 let check (config : Config.t) expr  =

Conclusion

Switching from tuples to named records across the AST, type checker, and interpreter was one of those refactors that feels almost mechanical — until it isn't. The real win was collapsing ClosureCall into FunctionCall and generalising the callee to an arbitrary expression. The grammar conflict that made closure a second-class citizen in the previous post? Gone. A bit of precedence annotation and a small restructuring of funcall was all it took.

Here is the entire diff.

Next up, methods!

Thanks for reading Bit Maybe Wise! Tuples are out, records are in. Your inbox deserves named fields too — subscribe and stop guessing what position two holds.

Photo by Quino Al on Unsplash

Tsonnet #37 - Call me maybe, but make it typed, part 3

Hercules Lemke Merscher — Sun, 19 Apr 2026 10:40:23 +0000

Welcome to the Tsonnet series!

If you're not following along, check out how it all started in the first post of the series.

In the previous post, we added default function arguments:

Hercules Lemke Merscher

Apr 17

Tsonnet #36 — Call me maybe, but make it typed, part 2

#tsonnet #jsonnet #compiler

Comments

5 min read

Now let's implement closures.

Captured and ready to be called

We should accept a closure that is going to be assigned to a local, and immediately called closures:

// samples/functions/closure.jsonnet

// binding closure
local id = function(x) x;
// immediately called closure
(function(x) id(x) * id(x))(5)

Parsing: teaching the grammar new tricks

We need two new AST variants:

diff --git a/lib/ast.ml b/lib/ast.ml
index f4c1472..e317b6e 100644
--- a/lib/ast.ml
+++ b/lib/ast.ml
@@ -92,6 +92,8 @@ type expr =
   | IndexedExpr of position * string * expr
   | FunctionDef of position * (string * (string * expr option) list * expr)
   | FunctionCall of position * string * expr list
+  | Closure of position * ((string * expr option) list * expr)
+  | ClosureCall of position * (string * expr option) list * expr * expr list

 and object_entry =
   | ObjectField of string * expr

Then we update the lexer to recognise the new keyword:

diff --git a/lib/lexer.mll b/lib/lexer.mll
index a4c3745..4d65f55 100644
--- a/lib/lexer.mll
+++ b/lib/lexer.mll
@@ -80,6 +80,7 @@ rule read =
   | "self" { SELF }
   | "$" { TOP_LEVEL_OBJ }
   | "in" { IN }
+  | "function" { FUNCTION }
   | id { ID (Lexing.lexeme lexbuf) }
   | _ { raise (SyntaxError ("Unexpected char: " ^ Lexing.lexeme lexbuf)) }
   | eof { EOF }

And the parser:

diff --git a/lib/parser.mly b/lib/parser.mly
index 290b280..8b3821e 100644
--- a/lib/parser.mly
+++ b/lib/parser.mly
@@ -13,6 +13,7 @@
 %token NULL
 %token <bool> BOOL
 %token <string> STRING
+%token FUNCTION
 %token LEFT_SQR_BRACKET RIGHT_SQR_BRACKET
 %token LEFT_PAREN RIGHT_PAREN
 %token COMMA
@@ -42,11 +43,13 @@
 prog:
   | e = expr; EOF { e }
   | e = expr_seq; EOF { e }
+  | e = closure; EOF { e }
   ;

 expr:
   | e = assignable_expr { e }
   | e = vars { e }
+  | e = closure_call { e }
   ;

I stumbled upon a shift-reduce issue trying to make closure part of the assignable_expr parsing rule — it would make more semantic sense there, but the grammar conflicts beat me. I'll come back to fix it later.

Here's the short version of why it's not feasible as-is: if closure lives in assignable_expr, then (function(x) x) becomes reachable via two paths simultaneously — as a parenthesised closure via scoped_expr, and as the first half of a closure_call. When the parser sees ( function(x) body . ) and hits ), it can't decide whether to reduce into scoped_expr or shift ) as part of closure_call — that would require two tokens of lookahead, which LR(1) doesn't have. The only clean fix would be generalising funcall to accept any expression as the callee, so (function(x) x)(5) parses naturally as "call this expression with these args" — but that's a bigger refactor touching the AST, type checker, and interpreter.

Here's how the new closure and closure_call rules are implemented for now:

@@ -171,7 +174,9 @@ obj_field_access:
   ;

 var:
-  varname = ID; ASSIGN; e = assignable_expr { (varname, e) };
+  | varname = ID; ASSIGN; e = assignable_expr { (varname, e) }
+  | varname = ID; ASSIGN; e = closure { (varname, e) }
+  ;

 vars:
   | LOCAL; vars = separated_nonempty_list(COMMA, var) { Local (with_pos $startpos $endpos, vars) }
@@ -203,4 +208,19 @@ funcall:
   | fname = ID;
     LEFT_PAREN; params = separated_nonempty_list(COMMA, assignable_expr); RIGHT_PAREN
     { FunctionCall (with_pos $startpos $endpos, fname, params) }
+  ;
+
+closure:
+  | FUNCTION;
+    LEFT_PAREN; params = separated_nonempty_list(COMMA, fundef_param); RIGHT_PAREN;
+    body = assignable_expr { Closure (with_pos $startpos $endpos, (params, body)) }
+  ;
+
+closure_call:
+  | LEFT_PAREN; FUNCTION;
+    LEFT_PAREN; def_params = separated_nonempty_list(COMMA, fundef_param); RIGHT_PAREN;
+    body = assignable_expr;
+    RIGHT_PAREN;
+    LEFT_PAREN; call_params = separated_nonempty_list(COMMA, assignable_expr); RIGHT_PAREN;
+    { ClosureCall (with_pos $startpos $endpos, def_params, body, call_params) }
   ;

Type checking: the elephant in the room

The new type variants mirror the ones in ast.ml:

diff --git a/lib/type.ml b/lib/type.ml
index 05bc187..ee912b3 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -19,6 +19,8 @@ type tsonnet_type =
   | Tunresolved
   | TfunctionDef of (string * tsonnet_type) list (* params: name * type *) * expr (* body *) * tsonnet_type (* return *)
   | TfunctionCall of tsonnet_type list * tsonnet_type
+  | Tclosure of (string * tsonnet_type) list * expr
+  | TclosureCall of tsonnet_type list * tsonnet_type
 and t_object_entry =
   | TobjectField of string * tsonnet_type
   | TobjectExpr of tsonnet_type

The collect_free_idents function needs updating for the new variants — I also noticed I'd forgotten FunctionCall here earlier (oops!):

@@ -84,6 +95,10 @@ let rec collect_free_idents = function
   | ObjectFieldAccess (_, _, exprs) -> List.concat_map collect_free_idents exprs
   | IndexedExpr (_, name, e) -> name :: collect_free_idents e
   | Local (_, vars) -> List.concat_map (fun (_, e) -> collect_free_idents e) vars
+  | FunctionCall (_, name, args) -> name :: List.concat_map collect_free_idents args
+  | Closure (_, (_, body)) -> collect_free_idents body
+  | ClosureCall (_, _, body, args) ->
+    collect_free_idents body @ List.concat_map collect_free_idents args
   | _ -> []

Then we pattern-match on the new AST nodes in translate:

@@ -178,6 +193,9 @@ let rec translate venv expr =
   | IndexedExpr (pos, varname, index_expr) -> translate_indexed_expr venv (pos, varname, index_expr)
   | FunctionDef (pos, def) -> translate_function_def venv (pos, def)
   | FunctionCall (pos, fname, params) -> translate_function_call venv (pos, fname, params)
+  | Closure (pos, (params, body)) -> translate_closure venv (pos, params, body)
+  | ClosureCall (pos, def_params, body, call_params) ->
+    translate_closure_call venv (pos, def_params, body, call_params)
   | expr' ->
     error (Error.Msg.type_invalid_expr (string_of_type expr'))

I also added a catch-all for Tany in binary operations — if either side is Tany, we let it through rather than erroring:

@@ -472,6 +490,7 @@ and translate_bin_op venv pos op e1 e2 =
   | LessThan, Tstring, Tstring -> ok (venv'', Tbool)
   | LessThanOrEqual, Tstring, Tstring -> ok (venv'', Tbool)
   | In, Tstring, (Tobject _ | Tany | TruntimeObject _ | TobjectPtr _) -> ok (venv'', Tbool)
+  | _, Tany, _ | _, _, Tany -> ok (venv'', Tany)
   | _ -> Error.error_at pos Error.Msg.invalid_binary_op

translate_function_call also needs to handle Tclosure — if a bound name resolves to a closure, we re-dispatch to translate_closure_call:

@@ -561,9 +580,70 @@ and translate_function_call venv (pos, fname, call_params) =
       let resolved_fun = TfunctionDef (resolved_params, body_expr, resolved_return) in
       let venv_with_resolved_fun = Env.add_local fname resolved_fun venv' in
       ok (venv_with_resolved_fun, resolved_return)
+  | Some (Lazy expr) ->
+    let* (venv', resolved) = translate venv expr in
+    (* Re-dispatch with the resolved type *)
+    let venv'' = Env.add_local fname resolved venv' in
+    translate_function_call venv'' (pos, fname, call_params)
+  | Some (Tclosure (def_params, body_expr)) ->
+    translate_closure_call venv (pos, 
+      List.map (fun (name, _ty) -> (name, None)) def_params,
+      body_expr, call_params)
   | _ ->
     Error.error_at pos (Error.Msg.var_not_found fname)

translate_closure is pretty similar to translate_function_def:

and translate_closure venv (_pos, params, body) =
  let* params_typed = List.fold_left
    (fun acc (name, default) ->
      let* params' = acc in
      match default with
      | Some default_expr ->
        let* (_, default_ty) = translate venv default_expr in
        ok (params' @ [(name, default_ty)])
      | None ->
        ok (params' @ [(name, Tunresolved)])
    )
    (ok [])
    params
  in
  ok (venv, Tclosure (params_typed, body))

And translate_closure_call is pretty similar to translate_function_call:

and translate_closure_call venv (pos, def_params, body_expr, call_params) =
  let num_call = List.length call_params in
  let num_def = List.length def_params in
  let num_required =
    List.length (List.filter (fun (_, default) -> Option.is_none default) def_params)
  in
  if num_call < num_required || num_call > num_def
  then Error.error_at pos (Error.Msg.wrong_number_of_params num_def num_call)
  else
    let* (venv', resolved_params) =
      List.fold_left
        (fun acc (index, (param_name, default)) ->
          let* (venv', params') = acc in
          if index < num_call
          then
            let call_param = List.nth call_params index in
            let* (venv'', call_param_type) = translate venv' call_param in
            ok (venv'', params' @ [(param_name, call_param_type)])
          else
            match default with
            | Some default_expr ->
              let* (venv'', default_type) = translate venv' default_expr in
              ok (venv'', params' @ [(param_name, default_type)])
            | None -> Error.error_at pos (Error.Msg.wrong_number_of_params num_def num_call)
        )
        (ok (venv, []))
        (List.mapi (fun i p -> (i, p)) def_params)
    in
    let body_venv = List.fold_left
      (fun env (name, ty) -> Env.add_local name ty env)
      venv'
      resolved_params
    in
    let* (_, body_type) = translate body_venv body_expr in
    ok (venv, body_type)

There's room for simplification here, but let's move on for now.

It's worth pausing on a behaviour difference between Tsonnet and standard Jsonnet. Given this sample:

// samples/semantics/invalid_function_call_type.jsonnet
local my_function(x) = x * 2;
my_function(3) && my_function("oops")

Jsonnet fails at runtime after evaluating the first call, because && expects a boolean and gets a number first:

$ jsonnet samples/semantics/invalid_function_call_type.jsonnet
RUNTIME ERROR: Unexpected type number, expected boolean
    samples/semantics/invalid_function_call_type.jsonnet:2:1-38 $
    During evaluation

Tsonnet instead type-checks the function calls before even getting to the &&, and catches the type mismatch earlier:

dune exec -- tsonnet samples/semantics/invalid_function_call_type.jsonnet
ERROR: samples/semantics/invalid_function_call_type.jsonnet:2:18 Expected type Number, got String

2: my_function(3) && my_function("oops")
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

I think that's a more sensible error. Worth noting: I want to support polymorphic parameters and return types eventually, but for this prototype, this is enough.

Interpreting: where closures actually close over things

During interpretation, a closure definition is returned as-is — it just gets stored in the environment. The actual work happens at call time:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index 6ad259e..7412fb9 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -28,6 +28,8 @@ let rec interpret env expr =
   | IndexedExpr (pos, varname, index_expr) -> interpret_indexed_expr env (pos, varname, index_expr)
   | FunctionDef (pos, def) -> interpret_function_def env (pos, def)
   | FunctionCall (pos, fname, params) -> interpret_function_call env (pos, fname, params)
+  | Closure _ -> ok (env, expr)
+  | ClosureCall (pos, def_params, body, params) -> interpret_closure_call env (pos, def_params, body, params)

The function application logic was straightforward to generalise into apply_function, which both interpret_function_call and interpret_closure_call now share:

and apply_function env pos def_params body call_params =
  let num_call = List.length call_params in
  let num_def = List.length def_params in
  let num_required =
    List.length (
      List.filter (fun (_, default) -> Option.is_none default) def_params
    )
  in
  if num_call < num_required || num_call > num_def
  then
    Error.error_at pos (Error.Msg.wrong_number_of_params num_def num_call)
  else
    let* evaluated_call_params =
      List.fold_left
        (fun acc param ->
          let* params = acc in
          let* (_, v) = interpret env param in
          ok (params @ [v])
        )
        (ok [])
        call_params
    in
    let* bindings =
      List.fold_left
        (fun acc (index, (param_name, default)) ->
          let* bindings = acc in
          if index < num_call
          then
            ok (bindings @ [(param_name, List.nth evaluated_call_params index)])
          else
            match default with
            | Some default_expr -> ok (bindings @ [(param_name, default_expr)])
            | None -> Error.error_at pos (Error.Msg.wrong_number_of_params num_def num_call)
        )
        (ok [])
        (List.mapi (fun i p -> (i, p)) def_params)
    in
    let env' = List.fold_left
      (fun env (k, v) -> Env.add_local k v env)
      env
      bindings
    in
    let* (_, result) = with_fresh_evaluating_bindings
      (fun () -> interpret env' body)
    in
    ok (env, result)

interpret_function_call and interpret_closure_call now just delegate to it:

 and interpret_function_call env (pos, fname, call_params) =
   match Env.find_opt fname env with
+  | Some (Closure (pos, (def_params, body)))
   | Some (FunctionDef (pos, (_, def_params, body))) ->
-    ...
+    apply_function env pos def_params body call_params
   | _ ->
     Error.error_at pos (Error.Msg.var_not_found fname)

+and interpret_closure_call env (pos, def_params, body, call_params) =
+  apply_function env pos def_params body call_params

I also used this opportunity to fix a leftover hard-coded error string I'd missed during an earlier refactoring:

diff --git a/lib/error.ml b/lib/error.ml
-  let type_wrong_number_of_params expected got =
-    Printf.sprintf "Expected %d argument(s), got %d" expected got
+  let wrong_number_of_params expected got =
+    Printf.sprintf "Expected %d argument(s), got %d" expected got

The rename also moves the message out of the type_-prefixed block, since both the type checker and the interpreter now share it.

Does it work? (Yes it does)

$ dune exec -- tsonnet samples/functions/closure.jsonnet
25

And the cram test:

diff --git a/test/cram/functions.t b/test/cram/functions.t
index fa29868..5c77837 100644
--- a/test/cram/functions.t
+++ b/test/cram/functions.t
@@ -6,3 +6,6 @@

   $ tsonnet ../../samples/functions/default_args.jsonnet
   12
+
+  $ tsonnet ../../samples/functions/closure.jsonnet
+  25

Conclusion

Closures are in. Binding them to locals, calling them immediately, passing them around — it all works. The type checker was the trickier part, requiring extra plumbing to re-dispatch when a bound name turns out to be a closure, but the interpreter side practically wrote itself once apply_function was factored out. The shift-reduce issue in the parser is still there, nagging at me from the grammar file — but that's a problem for future me, probably involving a refactor to let funcall accept any expression as callee.

Here is the entire diff.

Next up, I think this can be simplified, and I will do so.

Thanks for reading Bit Maybe Wise! Closures capture their environment. This newsletter captures compilers being built in the open. Subscribe before the environment gets GC'd.

Photo by The Now Time on Unsplash

Tsonnet #36 — Call me maybe, but make it typed, part 2

Hercules Lemke Merscher — Fri, 17 Apr 2026 07:00:00 +0000

Welcome to the Tsonnet series!

If you're not following along, check out how it all started in the first post of the series.

In the previous post, we added basic function support — positional parameters, multiline bodies, and type inference that resolves at call time:

Hercules Lemke Merscher

Apr 15

Tsonnet #35 — Call me maybe, but make it typed, part 1

#tsonnet #jsonnet #compiler

Comments

8 min read

Now let's make functions a little more forgiving. In this post, we'll implement default function arguments.

What's on the menu?

// samples/functions/default_args.jsonnet
local my_function(x, y=10) = x + y;
my_function(2)

The call passes only one argument. y falls back to its default value of 10, so the result is 12.

Teaching the parser about optionals

The parser needs a small adjustment to accept an optional default expression per parameter. Previously, each parameter was just an ID. Now it can optionally include = <expr>:

diff --git a/lib/parser.mly b/lib/parser.mly
index 102d202..290b280 100644
--- a/lib/parser.mly
+++ b/lib/parser.mly
@@ -182,9 +182,14 @@ single_var:
   | LOCAL; var_expr = var { Local (with_pos $startpos $endpos, [var_expr]) }
   ;

+fundef_param:
+  | name = ID { (name, None) }
+  | name = ID; ASSIGN; default = assignable_expr { (name, Some default) }
+  ;
+
 fundef:
   | fname = ID;
-    LEFT_PAREN; params = separated_nonempty_list(COMMA, ID); RIGHT_PAREN;
+    LEFT_PAREN; params = separated_nonempty_list(COMMA, fundef_param); RIGHT_PAREN;
     ASSIGN;
     body = fundef_body { (fname, params, body) }
   ;

And the AST type updates to carry the optional default alongside the parameter name:

diff --git a/lib/ast.ml b/lib/ast.ml
index 106f37c..f4c1472 100644
--- a/lib/ast.ml
+++ b/lib/ast.ml
@@ -90,7 +90,7 @@ type expr =
   | Local of position * (string * expr) list
   | Seq of expr list
   | IndexedExpr of position * string * expr
-  | FunctionDef of position * (string * string list * expr)
+  | FunctionDef of position * (string * (string * expr option) list * expr)
   | FunctionCall of position * string * expr list

 and object_entry =

Each parameter goes from a plain string to a string * expr option — None for required, Some expr for optional with a default.

Filling in the blanks

The arity check is a bit more involved now, since we have to distinguish between required and optional parameters:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index d512c0f..6ad259e 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -422,16 +422,30 @@ and interpret_function_def env (pos, (fname, params, body)) =
 and interpret_function_call env (pos, fname, call_params) =
   match Env.find_opt fname env with
   | Some (FunctionDef (pos, (_, def_params, body))) ->
-    if List.compare_lengths call_params def_params <> 0
+    let num_call = List.length call_params in
+    let num_def = List.length def_params in
+    let num_required =
+      List.length (
+        List.filter (fun (_, default) -> Option.is_none default) def_params
+      )
+    in
+    if num_call < num_required || num_call > num_def
     then Error.error_at pos "wrong number of param(s)"
     else
-      let bindings =
-        List.mapi
-          (fun index value ->
-            let param_name = List.nth def_params index in
-            (param_name, value)
+      let* bindings =
+        List.fold_left
+          (fun acc (index, (param_name, default)) ->
+            let* bindings = acc in
+            if index < num_call
+            then
+              ok (bindings @ [(param_name, List.nth call_params index)])
+            else
+              match default with
+              | Some default_expr -> ok (bindings @ [(param_name, default_expr)])
+              | None -> Error.error_at pos "wrong number of param(s)"
           )
-          call_params
+          (ok [])
+          (List.mapi (fun i p -> (i, p)) def_params)
       in
       let env' = List.fold_left
         (fun env (k, v) -> Env.add_local k v env)

The key change: instead of checking for an exact match, we now compute both the total number of defined parameters (num_def) and the number of required ones (num_required). The call is valid if the number of supplied arguments falls anywhere in the range [num_required, num_def]. For arguments not supplied by the caller, we fall back to the default expression.

Knowing the type before the call

Default arguments give the type checker a nice bonus: when a parameter has a default value, we can infer its type right at declaration time instead of waiting for the first call.

diff --git a/lib/type.ml b/lib/type.ml
index bdbf357..05bc187 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -475,9 +475,21 @@ and translate_bin_op venv pos op e1 e2 =
   | _ -> Error.error_at pos Error.Msg.invalid_binary_op

 and translate_function_def venv (pos, (fun_name, params, body)) =
-  (* As of now, we don't know the input types at declaration *)
-  let params_typed = List.map (fun name -> (name, Tunresolved)) params in
-  (* We also don't know the result type *)
+  (* For params with defaults, we can infer the type from the default expression;
+     params without defaults remain Tunresolved until the first call *)
+  let* params_typed = List.fold_left
+    (fun acc (name, default) ->
+      let* params' = acc in
+      match default with
+      | Some default_expr ->
+        let* (_, default_ty) = translate venv default_expr in
+        ok (params' @ [(name, default_ty)])
+      | None ->
+        ok (params' @ [(name, Tunresolved)])
+    )
+    (ok [])
+    params
+  in
   let fun_def = TfunctionDef (params_typed, body, Tunresolved) in
   (* So, function declaration will have an unresolved type definition,
      that only later it will be translated: before function call translation!

Parameters without defaults stay Tunresolved and get resolved at the call site, same as before. Parameters with defaults get their type resolved immediately. In our example, y=10 means y is typed as Number from the moment the function is declared.

The arity check at the call site follows the same logic as the interpreter — allow fewer arguments than the total, as long as the mandatory ones are all there:

@@ -490,35 +502,39 @@ and translate_function_call venv (pos, fname, call_params) =
   (* 1. retrieve TfunctionDef from venv *)
   match Env.find_opt fname venv with
   | Some (TfunctionDef (def_params, body_expr, return_type)) ->
-    (* check arity *)
-    if List.compare_lengths call_params def_params <> 0
+    (* check arity: allow fewer args if defaults exist *)
+    let num_call = List.length call_params in
+    let num_def = List.length def_params in
+    if num_call > num_def
     then
       Error.error_at pos
-        (Error.Msg.type_wrong_number_of_params
-          (List.length def_params) (List.length call_params))
+        (Error.Msg.type_wrong_number_of_params num_def num_call)
     else
       (* 2. type check each positional parameter passed in the function call *)
       let* (venv', resolved_params) =
-        List.fold_left2
-          (fun acc call_param (param_name, def_param_type) ->
+        List.fold_left
+          (fun acc (index, (param_name, def_param_type)) ->
             let* (venv', params') = acc in
-            let* (venv'', call_param_type) = translate venv' call_param in
-            match def_param_type with
-            | Tunresolved ->
-              (* 2a. unresolved: accept and record the concrete type *)
-              ok (venv'', params' @ [(param_name, call_param_type)])
-            | expected ->
-              (* 2b. resolved: type check against the concrete type *)
-              if call_param_type = expected
-              then ok (venv'', params' @ [(param_name, expected)])
-              else Error.error_at pos
-                (Error.Msg.type_mismatch
-                  ~expected:(to_string expected)
-                  ~got:(to_string call_param_type))
+            if index < num_call
+            then
+              let call_param = List.nth call_params index in
+              let* (venv'', call_param_type) = translate venv' call_param in
+              match def_param_type with
+              | Tunresolved ->
+                ok (venv'', params' @ [(param_name, call_param_type)])
+              | expected ->
+                if call_param_type = expected
+                then ok (venv'', params' @ [(param_name, expected)])
+                else Error.error_at pos
+                  (Error.Msg.type_mismatch
+                    ~expected:(to_string expected)
+                    ~got:(to_string call_param_type))
+            else
+              (* default arg — resolve type from the original AST default expression *)
+              ok (venv', params' @ [(param_name, def_param_type)])
           )
           (ok (venv, []))
-          call_params
-          def_params
+          (List.mapi (fun i p -> (i, p)) def_params)
       in
       (* 3. type check return *)
       let body_venv = List.fold_left

When the caller omits an argument that has a default, we skip the type-checking step for that parameter and carry its already-resolved type forward. No extra work needed — the type was inferred when the function was declared.

The moment of truth

diff --git a/test/cram/functions.t b/test/cram/functions.t
index 0ad7e43..fa29868 100644
--- a/test/cram/functions.t
+++ b/test/cram/functions.t
@@ -3,3 +3,6 @@

   $ tsonnet ../../samples/functions/multiline.jsonnet
   [ 6, 7 ]
+
+  $ tsonnet ../../samples/functions/default_args.jsonnet
+  12

my_function(2) with y=10 gives 12. Working as expected.

Conclusion

Default arguments are in. With a surprisingly contained change across parser, AST, interpreter, and type checker, my_function(x, y=10) now works as you'd expect — and the type checker even gets to resolve y's type at declaration time rather than waiting for the first call.

Here is the entire diff.

Next up, functions get a serious upgrade: closures.

Thanks for reading Bit Maybe Wise! Default arguments are optional. Subscribing isn't — but I'd never force you. Subscribe

Photo by Compare Fibre on Unsplash

Tsonnet #35 — Call me maybe, but make it typed, part 1

Hercules Lemke Merscher — Wed, 15 Apr 2026 07:00:00 +0000

Welcome to the Tsonnet series!

If you're not following along, check out how it all started in the first post of the series.

In the previous post, we added warnings for unused variables and untouched bindings:

Hercules Lemke Merscher

Mar 15

Tsonnet #34 - Dabbling with untouched bindings

#tsonnet #jsonnet #compiler

Comments

14 min read

Now let's get to the most exciting feature in any programming language: functions!

What are we even working with here?

A simple inline function with a positional parameter:

// samples/functions/positional_params.jsonnet
local my_function(x) = x * 2;
my_function(3)

And a function with a multiline body:

// samples/functions/multiline.jsonnet
local simple_function(x, y) = x + y;

local multiline_function(x) =
  local temp = x * 2;
  [temp, temp + 1];

multiline_function(
  simple_function(1, 2)
)

Parsing (a.k.a. making sense of text)

We need two new AST variants -- one for function definition, one for function call:

diff --git a/lib/ast.ml b/lib/ast.ml
index ace6241..106f37c 100644
--- a/lib/ast.ml
+++ b/lib/ast.ml
@@ -90,6 +90,8 @@ type expr =
   | Local of position * (string * expr) list
   | Seq of expr list
   | IndexedExpr of position * string * expr
+  | FunctionDef of position * (string * string list * expr)
+  | FunctionCall of position * string * expr list

 and object_entry =
   | ObjectField of string * expr

And the parser rules to match:

diff --git a/lib/parser.mly b/lib/parser.mly
index 7adb1ee..102d202 100644
--- a/lib/parser.mly
+++ b/lib/parser.mly
@@ -59,6 +59,7 @@ assignable_expr:
   | op = unary_op; e = assignable_expr { UnaryOp (with_pos $startpos $endpos, op, e) }
   | e = indexed_expr { e }
   | e = obj_field_access { e }
+  | e = funcall { e }
   ;

 indexed_expr:
@@ -173,7 +174,28 @@ var:
   varname = ID; ASSIGN; e = assignable_expr { (varname, e) };

 vars:
-  LOCAL; vars = separated_nonempty_list(COMMA, var) { Local (with_pos $startpos $endpos, vars) };
+  | LOCAL; vars = separated_nonempty_list(COMMA, var) { Local (with_pos $startpos $endpos, vars) }
+  | LOCAL; def = fundef { FunctionDef (with_pos $startpos $endpos, def) }
+  ;

 single_var:
-  LOCAL; var_expr = var { Local (with_pos $startpos $endpos, [var_expr]) };
+  | LOCAL; var_expr = var { Local (with_pos $startpos $endpos, [var_expr]) }
+  ;
+
+fundef:
+  | fname = ID;
+    LEFT_PAREN; params = separated_nonempty_list(COMMA, ID); RIGHT_PAREN;
+    ASSIGN;
+    body = fundef_body { (fname, params, body) }
+  ;
+
+fundef_body:
+  | e = assignable_expr { e }
+  | local_bindings = vars; SEMICOLON; body = fundef_body { Seq [local_bindings; body] }
+  ;
+
+funcall:
+  | fname = ID;
+    LEFT_PAREN; params = separated_nonempty_list(COMMA, assignable_expr); RIGHT_PAREN
+    { FunctionCall (with_pos $startpos $endpos, fname, params) }
+  ;

fundef_body deserves a note: it lets us nest local bindings inside the function body, which is what makes multiline_function work. A function body is either a plain expression or a local binding followed by a semicolon and the rest of the body, recursively.

Interpreting: where things actually happen

While working on the interpreter, I noticed that evaluating_fields was a misleading name — interpret_ident handles not just object fields, but regular local bindings too. Renamed it to evaluating_bindings:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index c8755bc..d512c0f 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -2,7 +2,14 @@ open Ast
 open Result
 open Syntax_sugar

-let evaluating_fields = ref ObjectFields.empty
+let evaluating_bindings = ref ObjectFields.empty

I also needed a helper to run a function in a fresh evaluation environment, then restore the previous state afterwards:

let with_fresh_evaluating_bindings fn =
  let saved_evaluating_bindings = !evaluating_bindings in
  evaluating_bindings := ObjectFields.empty;
  let result = fn () in
  evaluating_bindings := saved_evaluating_bindings;
  result

This matters for function calls: we don't want the caller's evaluation state leaking into the function body.

The new pattern-matching cases route to their respective handlers:

 (** [interpret expr] interprets and reduce the intermediate AST [expr] into a result AST. *)
 let rec interpret env expr =
@@ -19,6 +26,8 @@ let rec interpret env expr =
   | Local (_, vars) -> interpret_local env vars
   | Seq exprs -> interpret_seq env exprs
   | IndexedExpr (pos, varname, index_expr) -> interpret_indexed_expr env (pos, varname, index_expr)
+  | FunctionDef (pos, def) -> interpret_function_def env (pos, def)
+  | FunctionCall (pos, fname, params) -> interpret_function_call env (pos, fname, params)

 and interpret_indexed_expr env (pos, varname, index_expr) =
   let* (env', index_expr') = interpret env index_expr in

Function definition just registers the function in the environment:

and interpret_function_def env (pos, (fname, params, body)) =
  let env' = Env.add_local fname (FunctionDef (pos, (fname, params, body))) env in
  ok (env', Unit)

Function call is where things get interesting:

and interpret_function_call env (pos, fname, call_params) =
  match Env.find_opt fname env with
  | Some (FunctionDef (pos, (_, def_params, body))) ->
    if List.compare_lengths call_params def_params <> 0
    then Error.error_at pos "wrong number of param(s)"
    else
      let bindings =
        List.mapi
          (fun index value ->
            let param_name = List.nth def_params index in
            (param_name, value)
          )
          call_params
      in
      let env' = List.fold_left
        (fun env (k, v) -> Env.add_local k v env)
        env
        bindings
      in
      let* (_, result) = with_fresh_evaluating_bindings
        (fun () -> interpret env' body)
      in
      ok (env, result)
  | _ ->
    Error.error_at pos (Error.Msg.var_not_found fname)

Step by step:

Check that the number of arguments matches the definition. I could skip this in the interpreter and rely on the type checker alone, but I'm keeping it in both for now -- type checking can be bypassed during development for faster iteration.
Pair up each call argument with its corresponding parameter name.
Add those bindings to the environment.
Interpret the function body in that environment, being careful to return the caller's environment, not the one modified inside the body.

Making sure this isn’t completely illegal

We don't have type annotations yet, so the type checker needs to infer parameter types and the return type. Here's the motivating example -- the first call is fine, the second should error:

// samples/semantics/invalid_function_call_type.jsonnet
local my_function(x) = x * 2;
my_function(3) && my_function("oops")

We need three new type variants:

diff --git a/lib/type.ml b/lib/type.ml
index cad9ad1..bdbf357 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -16,6 +16,9 @@ type tsonnet_type =
   | TruntimeObject of Env.env_id * t_object_entry list
   | TobjectPtr of Env.env_id * t_object_scope
   | Lazy of expr
+  | Tunresolved
+  | TfunctionDef of (string * tsonnet_type) list (* params: name * type *) * expr (* body *) * tsonnet_type (* return *)
+  | TfunctionCall of tsonnet_type list * tsonnet_type
 and t_object_entry =
   | TobjectField of string * tsonnet_type
   | TobjectExpr of tsonnet_type

@@ -54,6 +57,17 @@ let rec to_string = function
       | TobjectTopLevel -> "$"
     in Printf.sprintf "%s (%d)" s id
   | Lazy ty -> string_of_type ty
+  | TfunctionDef (params, _, return) ->
+    Printf.sprintf "function(%s) -> %s"
+      (List.map (fun (name, ty) -> name ^ ": " ^ to_string ty) params
+      |> String.concat ", "
+      )
+      (to_string return)
+  | TfunctionCall (params_type, return) ->
+    Printf.sprintf "function(%s) -> %s"
+      (List.map to_string params_type |> String.concat ", ")
+      (to_string return)
+  | Tunresolved -> "<unresolved>"

 let rec collect_free_idents = function
   | Unit | Null _ | Number _ | String _ | Bool _ -> []

Tunresolved is the key one. At declaration time, we don't know what types the parameters will have -- that only becomes clear at the call site. So we use Tunresolved as a placeholder and fill it in later.

Two new error messages to go with it:

diff --git a/lib/error.ml b/lib/error.ml
index e287af9..e08c670 100644
--- a/lib/error.ml
+++ b/lib/error.ml
@@ -28,6 +28,10 @@ module Msg = struct
   let type_non_indexable_type ty = ty ^ " is a non-indexable type"
   let type_non_indexable_field field = field ^ " is a non-indexable value"
   let type_invalid_lookup_key expr = "Invalid object lookup key: " ^ expr
+  let type_wrong_number_of_params expected got =
+    Printf.sprintf "Expected %d argument(s), got %d" expected got
+  let type_mismatch ~expected ~got =
+    Printf.sprintf "Expected type %s, got %s" expected got

   (* Interpreter messages *)
   let interp_division_by_zero = "Division by zero"

The new cases in translate forward to specialised functions, same pattern as always:

@@ -162,6 +176,8 @@ let rec translate venv expr =
   | BinOp (pos, op, e1, e2) -> translate_bin_op venv pos op e1 e2
   | UnaryOp (pos, op, expr) -> translate_unary_op venv (pos, op, expr)
   | IndexedExpr (pos, varname, index_expr) -> translate_indexed_expr venv (pos, varname, index_expr)
+  | FunctionDef (pos, def) -> translate_function_def venv (pos, def)
+  | FunctionCall (pos, fname, params) -> translate_function_call venv (pos, fname, params)
   | expr' ->
     error (Error.Msg.type_invalid_expr (string_of_type expr'))

At declaration time, all types are Tunresolved:

and translate_function_def venv (pos, (fun_name, params, body)) =
  (* As of now, we don't know the input types at declaration *)
  let params_typed = List.map (fun name -> (name, Tunresolved)) params in
  (* We also don't know the result type *)
  let fun_def = TfunctionDef (params_typed, body, Tunresolved) in
  (* So, function declaration will have an unresolved type definition,
     that only later it will be translated: before function call translation!
     After first function call, concrete types are set and subsequent calls will
     type check against the initial type assignment(s). *)
  let venv' = Env.add_local fun_name fun_def venv in
  ok (venv', fun_def)

At call time, Tunresolved gets replaced with concrete types -- and subsequent calls are checked against those:

and translate_function_call venv (pos, fname, call_params) =
  (* 1. retrieve TfunctionDef from venv *)
  match Env.find_opt fname venv with
  | Some (TfunctionDef (def_params, body_expr, return_type)) ->
    (* check arity *)
    if List.compare_lengths call_params def_params <> 0
    then
      Error.error_at pos
        (Error.Msg.type_wrong_number_of_params
          (List.length def_params) (List.length call_params))
    else
      (* 2. type check each positional parameter passed in the function call *)
      let* (venv', resolved_params) =
        List.fold_left2
          (fun acc call_param (param_name, def_param_type) ->
            let* (venv', params') = acc in
            let* (venv'', call_param_type) = translate venv' call_param in
            match def_param_type with
            | Tunresolved ->
              (* 2a. unresolved: accept and record the concrete type *)
              ok (venv'', params' @ [(param_name, call_param_type)])
            | expected ->
              (* 2b. resolved: type check against the concrete type *)
              if call_param_type = expected
              then ok (venv'', params' @ [(param_name, expected)])
              else Error.error_at pos
                (Error.Msg.type_mismatch
                  ~expected:(to_string expected)
                  ~got:(to_string call_param_type))
          )
          (ok (venv, []))
          call_params
          def_params
      in
      (* 3. type check return *)
      let body_venv = List.fold_left
        (fun env (name, ty) -> Env.add_local name ty env)
        venv'
        resolved_params
      in
      (* translate the body with resolved param types in scope *)
      let* (_, body_type) = translate body_venv body_expr in
      let* resolved_return = match return_type with
        | Tunresolved ->
          (* 3a. first call: infer return type from body *)
          ok body_type
        | expected ->
          (* 3b. subsequent calls: check body type matches *)
          if body_type = expected
          then ok expected
          else Error.error_at pos
            (Error.Msg.type_mismatch
              ~expected:(to_string expected)
              ~got:(to_string body_type))
      in
      (* 4. update env with the now-resolved function type *)
      let resolved_fun = TfunctionDef (resolved_params, body_expr, resolved_return) in
      let venv_with_resolved_fun = Env.add_local fname resolved_fun venv' in
      ok (venv_with_resolved_fun, resolved_return)
  | _ ->
    Error.error_at pos (Error.Msg.var_not_found fname)

One limitation worth mentioning: the first call wins. If the first call passes a value with the wrong type for the intended use, the type checker won't catch it -- that's what type annotations are for. They're coming once Tsonnet reaches a reasonable level of Jsonnet compliance.

Proof that it (mostly) works

Ta-da!

$ dune exec -- tsonnet samples/functions/positional_params.jsonnet
6

$ dune exec -- tsonnet samples/functions/multiline.jsonnet
[ 6, 7 ]

$ dune exec -- tsonnet samples/semantics/invalid_function_call_type.jsonnet
ERROR: samples/semantics/invalid_function_call_type.jsonnet:2:18 Expected type Number, got String

2: my_function(3) && my_function("oops")
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The error could be more precise -- ideally it would point at the offending argument rather than the entire expression. That's a detail I'll get to later; not something that adds much right now.

The cram tests:

diff --git a/test/cram/functions.t b/test/cram/functions.t
new file mode 100644
index 0000000..0ad7e43
--- /dev/null
+++ b/test/cram/functions.t
@@ -0,0 +1,5 @@
+  $ tsonnet ../../samples/functions/positional_params.jsonnet
+  6
+
+  $ tsonnet ../../samples/functions/multiline.jsonnet
+  [ 6, 7 ]
diff --git a/test/cram/semantics.t b/test/cram/semantics.t
index de60a1b..c9a790e 100644
--- a/test/cram/semantics.t
+++ b/test/cram/semantics.t
@@ -289,3 +322,16 @@
                  ^^
   ---
   1
+
+  $ tsonnet ../../samples/semantics/invalid_function_call_type.jsonnet
+  ERROR: ../../samples/semantics/invalid_function_call_type.jsonnet:2:18 Expected type Number, got String
+  
+  2: my_function(3) && my_function("oops")
+     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  [1]
+

Conclusion

Basic functions are in: positional parameters, multiline bodies, arity checks, and type inference that resolves on the first call. Not bad for a first round.

Here is the entire diff.

Next up, we make function calls a little more forgiving — default arguments are coming.

Thanks for reading Bit Maybe Wise! First caller wins the type. Subscribe to lock in yours.

Photo by Annie Spratt on Unsplash

ABEND dump #26

Hercules Lemke Merscher — Wed, 08 Apr 2026 21:27:00 +0000

Welcome to the ABEND dump #26!

Don't know what is an “ABEND dump”?! I'm glad you asked.

You can check the previous ABEND dump here:

Hercules Lemke Merscher

Feb 28

ABEND dump #25

#abenddump

Comments

2 min read

Tech boss uses AI and ChatGPT to create cancer vaccine for his dying dog

This is WILD! This is what I want AI for, a truly relevant use case. I feel like there's so much potential for applications in medicine. What a time to be alive!

I know, I know. There's plenty of reasons to be wary about AI, but let's be positive for a moment, this is truly good and magical!

And speaking of which...

Explore Sid's Data

Sid Sijbrandij, former GitLab CEO, is fighting an osteosarcoma (a rare bone cancer). He's open-sourcing his experimental treatment data to help advancing cancer research.

Sid rocks!

The internet was weeks away from disaster and no one knew

How Pokémon Go is giving delivery robots an inch-perfect view of the world

"When the product is free, you are the product" -- in the AI era, this sentence never made more sense than now.

Systems Thinking is Brain Rot for Analysts

This got me thinking.

Building a Second Brain

I forgot to recommend this book in the previous issue.

Last year I got hooked into the Zettelkasten system to organize my thoughts in a digital world, but it was simply too complex to grasp, and what really made it work for me was following the PARA Method presented by Tiago Forte in Building a Second Brain book.

I may write more about it here, eventually.

There's a version of this book written in portuguese too, which was the one I read.

Thanks for reading the ABEND dump! AI curing cancer, robots delivering pizza, open-source treatment data -- what a time to be alive. Subscribe and we'll keep marveling at it together.

Tsonnet #34 - Dabbling with untouched bindings

Hercules Lemke Merscher — Sun, 15 Mar 2026 16:26:39 +0000

Welcome to the Tsonnet series!

If you're not following along, check out how it all started in the first post of the series.

In the previous post, we wrapped up the arithmetic tutorial:

Tsonnet #33 - The arithmetic tutorial must go on

Hercules Lemke Merscher ・ Mar 13

#tsonnet #jsonnet #compiler

This time, before proceeding to cover the next tutorial, I'm going to revisit one laziness aspect: the evaluation (or no-evaluation) of untouched bindings.

Warnings, not errors

Up until now, Tsonnet would hard-error on cyclic references regardless of whether the offending variable was ever touched. That's a bit heavy-handed. Jsonnet is lazily evaluated -- if a variable has a cycle but is never used, the program should still run. We should warn, not panic. For example:

// samples/variables/untouched_variable.jsonnet
local a = 1, b = 42;
b

Jsonnet behaves like this:

$ jsonnet samples/variables/untouched_variable.jsonnet
42

Jsonnet does nothing to alert the programmer that something is unused. Maybe that belongs to a linter, but the compiler not even warning is a bad experience, IMHO.

The same logic applies to unused variables: they're suspicious, but they shouldn't crash anything.

// samples/objects/untouched_field.jsonnet
local result = {
    a: 1,
    b: 42,
};
result.b

$ jsonnet samples/objects/untouched_field.jsonnet
42

Let's work through each of these in order.

Warn on cyclic refs for unused variables

The first thing we need is a way to tell which variables are actually reachable from the body of a local expression. For that, I added collect_free_idents and reachable_bindings to the type checker:

let rec collect_free_idents = function
  | Unit | Null _ | Number _ | String _ | Bool _ -> []
  | Ident (_, name) -> [name]
  | Array (_, exprs) -> List.concat_map collect_free_idents exprs
  | BinOp (_, _, e1, e2) -> collect_free_idents e1 @ collect_free_idents e2
  | UnaryOp (_, _, e) -> collect_free_idents e
  | Seq exprs -> List.concat_map collect_free_idents exprs
  | ParsedObject (_, entries) ->
    List.concat_map (function
      | ObjectField (_, e) -> collect_free_idents e
      | ObjectExpr e -> collect_free_idents e
    ) entries
  | ObjectFieldAccess (_, _, exprs) -> List.concat_map collect_free_idents exprs
  | IndexedExpr (_, name, e) -> name :: collect_free_idents e
  | Local (_, vars) -> List.concat_map (fun (_, e) -> collect_free_idents e) vars
  | _ -> []

let reachable_bindings bindings initial_idents =
  let rec go visited = function
    | [] -> visited
    | name :: rest ->
      if List.mem name visited
      then go visited rest
      else
        let new_idents =
          match List.assoc_opt name bindings with
          | Some expr -> collect_free_idents expr
          | None -> []
        in
        go (name :: visited) (new_idents @ rest)
  in
  go [] initial_idents

collect_free_idents walks an expression and collects every identifier referenced. reachable_bindings does a simple graph traversal starting from the identifiers used in the body, following variable references transitively. If a binding is never reachable from the body, it's unused.

I'm delegating part of what used to be Local-processing into the translate_seq function, where the logic actually runs, to keep things tidy:

diff --git a/lib/type.ml b/lib/type.ml
index fbe68b1..2f4bf41 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -154,23 +187,15 @@ let rec translate venv expr =
     )
   | ParsedObject (pos, entries) -> translate_object venv pos entries
   | ObjectFieldAccess (pos, scope, chain) -> translate_object_field_access venv pos scope chain
-  | Local (pos, vars) ->
+  | Local (_pos, vars) ->
     let venv' = List.fold_left
       (* Adds an expr to the env to be evaluated at a later point in time (when required) *)
       (fun venv (varname, var_expr) -> Env.add_local varname (Lazy var_expr) venv)
       venv
       vars
-    in
-    let* _ = List.fold_left
-      (fun ok' (varname, _) -> ok' >>= fun _ -> check_cyclic_refs venv' varname [] pos)
-      (ok ())
-      vars
     in ok (venv', Tunit)
   | Seq exprs ->
-    List.fold_left
-      (fun acc expr -> acc >>= fun (venv, _) -> translate venv expr)
-      (ok (venv, Tunit))
-      exprs
+    translate_seq venv exprs
   | BinOp (pos, op, e1, e2) ->
     translate_bin_op venv pos op e1 e2
   | UnaryOp (pos, op, expr) ->

and translate_seq venv exprs =
  let rec collect_locals = function
    | Local (pos, vars) :: rest ->
      let (all_vars, body) = collect_locals rest in
      (List.map (fun v -> (pos, v)) vars @ all_vars, body)
    | rest -> ([], rest)
  in
  let rec go venv = function
    | [] -> ok (venv, Tunit)
    | [expr] -> translate venv expr
    | (Local _ :: _) as exprs ->
      let (all_pos_vars, body) = collect_locals exprs in
      let all_vars = List.map snd all_pos_vars in
      let venv' = List.fold_left
        (fun venv (varname, var_expr) ->
          Env.add_local varname (Lazy var_expr) venv
        )
        venv
        all_vars
      in
      let body_idents = List.concat_map collect_free_idents body in
      let reachable = reachable_bindings all_vars body_idents in
      let* () = List.fold_left
        (fun acc (pos, (varname, _)) -> acc >>= fun () ->
          match check_cyclic_refs venv' varname [] pos with
          | Ok () -> ok ()
          | Error msg ->
            if List.mem varname reachable
            then error msg
            else (Error.warn (Error.Msg.type_cyclic_reference varname) pos; ok ())
        )
        (ok ())
        all_pos_vars
      in
      go venv' body
    | expr :: rest ->
      let* (venv', _) = translate venv expr in
      go venv' rest
  in
  go venv exprs

The key part: if a cyclic reference involves a variable that's reachable from the body, we still error. If it's unreachable, we just warn and move on. Here's what it looks like in practice:

$ dune exec -- tsonnet samples/variables/untouched_invalid_variable.jsonnet
Warning: .../untouched_invalid_variable.jsonnet:1:31 Cyclic reference found for c

1: local a = 1, b = a, c = d, d = c;
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Warning: .../untouched_invalid_variable.jsonnet:1:24 Cyclic reference found for d

1: local a = 1, b = a, c = d, d = c;
   ^^^^^^^^^^^^^^^^^^^^^^^^^^
1

c and d have a cycle between them, but b is what the program actually evaluates. So we warn, and produce the result.

Warn on unused variables

With reachability analysis in place, unused variable warnings follow naturally. A variable is unused if it's not in the reachable set. Adding that to translate_seq:

diff --git a/lib/type.ml b/lib/type.ml
index 2f4bf41..0e7a680 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -247,6 +247,11 @@ and translate_seq venv exprs =
       (* Determine which vars are reachable from the body *)
       let body_idents = List.concat_map collect_free_idents body in
       let reachable = reachable_bindings all_vars body_idents in
+      (* Warn on unused variables *)
+      List.iter (fun (pos, (varname, _)) ->
+        if not (List.mem varname reachable)
+        then Error.warn (Error.Msg.type_unused_variable varname) pos
+      ) all_pos_vars;
       (* Check cycles: error for reachable, warn for unreachable *)
       let* () = List.fold_left
         (fun acc (pos, (varname, _)) -> acc >>= fun () ->
@@ -255,7 +260,7 @@ and translate_seq venv exprs =
           | Error msg ->
             if List.mem varname reachable
             then error msg
-            else (prerr_endline ("Warning: " ^ msg); ok ())
+            else (Error.warn (Error.Msg.type_cyclic_reference varname) pos; ok ())
         )
         (ok ())
         all_pos_vars

I also refactored the warning infrastructure a bit. Instead of calling prerr_endline inline, there's now a proper Error.warn function:

diff --git a/lib/error.ml b/lib/error.ml
index ac8ae48..508ae0c 100644
--- a/lib/error.ml
+++ b/lib/error.ml
@@ -21,6 +21,7 @@ module Msg = struct

   (* Type checker messages *)
   let type_cyclic_reference varname = "Cyclic reference found for " ^ varname
+  let type_unused_variable varname = "Unused variable " ^ varname
   let type_non_indexable_value ty = ty ^ " is a non indexable value"
   let type_expected_integer_index ty = "Expected Integer index, got " ^ ty
   let type_invalid_expr expr = "Invalid type " ^ expr
@@ -104,3 +105,8 @@ let trace (err: string) (pos: position) : (string, string) result =
     (fun content -> ok (Printf.sprintf "%s\n%s" (trace_file_position err pos) content))

 let error_at pos = fun msg -> trace msg pos >>= error
+
+let warn msg pos =
+  match trace msg pos with
+  | Ok formatted -> prerr_endline ("Warning: " ^ formatted)
+  | Error _ -> prerr_endline ("Warning: " ^ msg)
diff --git a/lib/error.mli b/lib/error.mli
index 0bdd708..c09b930 100644
--- a/lib/error.mli
+++ b/lib/error.mli
@@ -18,6 +18,7 @@ module Msg : sig

   (* Type checker messages *)
   val type_cyclic_reference : string -> string
+  val type_unused_variable : string -> string
   val type_non_indexable_value : string -> string
   val type_expected_integer_index : string -> string
   val type_invalid_expr : string -> string
@@ -37,3 +38,4 @@ end

 val trace : string -> Ast.position -> (string, string) result
 val error_at : Ast.position -> string -> ('a, string) result
+val warn : string -> Ast.position -> unit

Much cleaner. Let's see it in action:

$ dune exec -- tsonnet samples/variables/untouched_variable.jsonnet
Warning: .../untouched_variable.jsonnet:1:0 Unused variable a

1: local a = 1, b = 42;
   ^^^^^^^^^^^^^^^^^^^^
42

a is defined but never used. The program still returns 42.

Warn on untouched object fields

Variables were the easy part. Objects are more involved because we're dealing with two separate phases -- the type checker and the interpreter -- and both need to handle cyclic field references gracefully.

The approach is the same: if a cyclic object field is never accessed during evaluation, warn instead of error. The tricky bit is detecting "accessed during evaluation" correctly.

Both modules now track which fields are actively being evaluated using a mutable ObjectFields set:

(* In interpreter.ml *)
let evaluating_fields = ref ObjectFields.empty

(* In type.ml *)
let translating_fields = ref ObjectFields.empty

When we start evaluating a field, we add it to the set. When we're done (or on error), we remove it. If we try to evaluate a field already in the set -- cycle detected:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index fe248b9..391c1e2 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -21,9 +23,17 @@ let rec interpret env expr =
   | ObjectPtr _ as obj_ptr -> ok (env, obj_ptr)
   | ObjectFieldAccess (pos, scope, chain) -> interpret_object_field_access env (pos, scope, chain)
   | Ident (pos, varname) ->
-    Env.find_var varname env
-      ~succ:(fun env' expr -> interpret env' expr)
-      ~err:(Error.error_at pos)
+    if ObjectFields.mem varname !evaluating_fields then
+      Error.error_at pos (Error.Msg.type_cyclic_reference varname)
+    else begin
+      evaluating_fields := ObjectFields.add varname !evaluating_fields;
+      let result = Env.find_var varname env
+        ~succ:(fun env' expr -> interpret env' expr)
+        ~err:(Error.error_at pos)
+      in
+      evaluating_fields := ObjectFields.remove varname !evaluating_fields;
+      result
+    end
   | BinOp (pos, op, e1, e2) -> interpret_bin_op env (pos, op, e1, e2)
   | UnaryOp (pos, op, expr) ->
     let* (env', expr') = interpret env expr in
@@ -201,9 +211,18 @@ and interpret_object_field_access env (pos, scope, chain_exprs) =
       match field_expr with
       | String (pos, field) | Ident (pos, field) ->
         let* (obj_id, field_env) = get_obj_id in
-        Env.get_obj_field field obj_id field_env
-          ~succ:(interpret)
-          ~err:(Error.error_at pos)
+        let key = Env.uniq_field_ident obj_id field in
+        if ObjectFields.mem key !evaluating_fields then
+          Error.error_at pos (Error.Msg.type_cyclic_reference key)
+        else begin
+          evaluating_fields := ObjectFields.add key !evaluating_fields;
+          let result = Env.get_obj_field field obj_id field_env
+            ~succ:(interpret)
+            ~err:(Error.error_at pos)
+          in
+          evaluating_fields := ObjectFields.remove key !evaluating_fields;
+          result
+        end
       | Number _ as index_expr ->
         (* Handle array/string indexing: prev_expr[number] *)
         Result.fold
@@ -223,19 +242,27 @@ and interpret_runtime_object env (pos, obj_env, fields) =
 and interpret_runtime_object_fields obj_env fields =
   match Env.Map.find_opt "self" obj_env with
   | Some (ObjectPtr (obj_id, _)) ->
-    let* field_list =
+    let field_list =
       ObjectFields.fold
         (fun field acc ->
-          let* evaluated_fields = acc in
           let key = Env.uniq_field_ident obj_id field in
-          match Env.Map.find_opt key obj_env with
-          | Some expr ->
-            let* (_, evaluated) = interpret obj_env expr in
-            ok ((field, evaluated) :: evaluated_fields)
-          | None -> acc
+          if ObjectFields.mem key !evaluating_fields then
+            acc (* Skip: cyclic reference detected *)
+          else
+            match Env.Map.find_opt key obj_env with
+            | Some expr ->
+              evaluating_fields := ObjectFields.add key !evaluating_fields;
+              let result =
+                match interpret obj_env expr with
+                | Ok (_, evaluated) -> (field, evaluated) :: acc
+                | Error _ -> acc
+              in
+              evaluating_fields := ObjectFields.remove key !evaluating_fields;
+              result
+            | None -> acc
         )
         fields
-        (ok [])
+        []
     in ok (List.rev field_list)
   | _ -> ok []

For object fields that are never accessed, the type checker now warns instead of erroring. translate_object was changed to iterate over entries and emit warnings rather than propagate errors:

diff --git a/lib/type.ml b/lib/type.ml
index 0e7a680..8b41545 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -152,13 +154,21 @@ let rec translate venv expr =
   | Number _ -> ok (venv, Tnumber)
   | String _ -> ok (venv, Tstring)
   | Ident (pos, varname) ->
-    Env.find_var varname venv
-      ~succ:(fun venv ty ->
-        match ty with
-        | Lazy expr -> translate venv expr
-        | _ -> ok (venv, ty)
-      )
-      ~err:(Error.error_at pos)
+    if ObjectFields.mem varname !translating_fields then
+      Error.error_at pos (Error.Msg.type_cyclic_reference varname)
+    else begin
+      translating_fields := ObjectFields.add varname !translating_fields;
+      let result = Env.find_var varname venv
+        ~succ:(fun venv ty ->
+          match ty with
+          | Lazy expr -> translate venv expr
+          | _ -> ok (venv, ty)
+        )
+        ~err:(Error.error_at pos)
+      in
+      translating_fields := ObjectFields.remove varname !translating_fields;
+      result
+    end
   | Array (_pos, elems) ->
     (* As of now, we compare each element and if all have the same type,
       it is an array of this type, otherwise it will be an array of any.
@@ -298,32 +308,36 @@ and translate_object venv pos entries =
     entries
   in

-  (* Check for cyclical references among object fields *)
-  let* () = List.fold_left
-      (fun ok' entry -> ok' >>= fun _ ->
-        match entry with
-        | ObjectField (attr, _) ->
-          check_cyclic_refs venv (Env.uniq_field_ident obj_id attr) [] pos
-        | _ -> ok'
-      )
-      (ok ())
-      entries
-  in
+  (* Check for cyclical references among object fields
+    (warn, don't error when the reference is not part of
+    the evaluation tree)
+  *)
+  List.iter
+    (fun entry ->
+      match entry with
+      | ObjectField (attr, _) ->
+        (match check_cyclic_refs venv (Env.uniq_field_ident obj_id attr) [] pos with
+        | Ok () -> ()
+        | Error _ -> Error.warn (Error.Msg.type_cyclic_reference (Env.uniq_field_ident obj_id attr)) pos)
+      | _ -> ()
+    )
+    entries;

-  (* Then translate object fields *)
-  let* entry_types = List.fold_left
-    (fun result entry ->
-      let* entries' = result in
+  (* Translate object fields lazily: warn on errors, skip invalid fields *)
+  let entry_types = List.fold_left
+    (fun entries' entry ->
       match entry with
       | ObjectField (attr, _) ->
-        let* (_, entry_ty) = Env.get_obj_field attr obj_id venv
+        (match Env.get_obj_field attr obj_id venv
           ~succ:translate_lazy
           ~err:(Error.error_at pos)
-        in ok (entries' @ [TobjectField (attr, entry_ty)])
+        with
+        | Ok (_, entry_ty) -> entries' @ [TobjectField (attr, entry_ty)]
+        | Error _ -> entries')
       | _ ->
-        result
+        entries'
     )
-    (ok [])
+    []
     entries
   in
   (* Remove self and $ from the environment to prevent leaking *)
@@ -372,9 +386,18 @@ and translate_object_field_access venv pos scope chain_exprs =
       match field_expr with
       | String (_, field) | Ident (_, field) ->
         let* obj_id = get_obj_id in
-        Env.get_obj_field field obj_id venv
-          ~succ:translate_lazy
-          ~err:(Error.error_at pos)
+        let key = Env.uniq_field_ident obj_id field in
+        if ObjectFields.mem key !translating_fields then
+          Error.error_at pos (Error.Msg.type_cyclic_reference key)
+        else begin
+          translating_fields := ObjectFields.add key !translating_fields;
+          let result = Env.get_obj_field field obj_id venv
+            ~succ:translate_lazy
+            ~err:(Error.error_at pos)
+          in
+          translating_fields := ObjectFields.remove key !translating_fields;
+          result
+        end
       | Number (pos, _) ->
         (* Handle numeric indexing of strings and arrays *)
         (match prev_ty with
@@ -429,4 +452,5 @@ let check (config : Config.t) expr  =
   else
     let* _ = translate Env.empty expr in
     Env.Id.reset ();
+    translating_fields := ObjectFields.empty;
     ok expr

Here's a sample that demonstrates the distinction. When we only access result.b, the cyclic c/d pair just produces warnings:

// samples/objects/untouched_invalid_field.jsonnet
local result = {
    a: 1,
    b: self.a,
    c: self.d,
    d: self.c
};
result.b

$ dune exec -- tsonnet samples/objects/untouched_invalid_field.jsonnet
Warning: .../untouched_invalid_field.jsonnet:1:0 Unused variable result

...

Warning: .../untouched_invalid_field.jsonnet:1:15 Cyclic reference found for 1->c

...

Warning: .../untouched_invalid_field.jsonnet:1:15 Cyclic reference found for 1->d

...
1

Meanwhile, if a cyclic field is actually accessed at runtime, it still errors hard:

// samples/semantics/invalid_object_with_cyclic_field.jsonnet
{
    a: 1,
    b: self.c,
    c: self.b,
}

$ dune exec -- tsonnet samples/semantics/invalid_object_with_cyclic_field.jsonnet
Warning: .../invalid_object_with_cyclic_field.jsonnet:1:0 Cyclic reference found for 1->b
...
.../invalid_object_with_cyclic_field.jsonnet:3:12 Cyclic reference found for 1->c
...
[1]

The type checker warns (because it doesn't know at type-check time which fields will be accessed), but the interpreter finds the cycle at runtime and errors properly.

Warn on cyclic refs for untouched object fields

The previous changes got the type checker side right, but the interpreter was still getting it wrong. When rendering an object, interpret_runtime_object_fields was folding into a plain list and silently skipping any field that errored -- including cyclic ones. So if you did access a cyclic field at runtime, you'd get an empty result instead of an error. Not great.

The fix is straightforward: go back to a monadic fold and let errors propagate normally. The cycle detection in interpret_object_field_access already handles the "is this field in a cycle?" question via evaluating_fields -- interpret_runtime_object_fields doesn't need to second-guess it.

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index 391c1e2..60f8a72 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -242,27 +242,19 @@ and interpret_runtime_object env (pos, obj_env, fields) =
 and interpret_runtime_object_fields obj_env fields =
   match Env.Map.find_opt "self" obj_env with
   | Some (ObjectPtr (obj_id, _)) ->
-    let field_list =
+    let* field_list =
       ObjectFields.fold
         (fun field acc ->
+          let* evaluated_fields = acc in
           let key = Env.uniq_field_ident obj_id field in
-          if ObjectFields.mem key !evaluating_fields then
-            acc (* Skip: cyclic reference detected *)
-          else
-            match Env.Map.find_opt key obj_env with
-            | Some expr ->
-              evaluating_fields := ObjectFields.add key !evaluating_fields;
-              let result =
-                match interpret obj_env expr with
-                | Ok (_, evaluated) -> (field, evaluated) :: acc
-                | Error _ -> acc
-              in
-              evaluating_fields := ObjectFields.remove key !evaluating_fields;
-              result
-            | None -> acc
+          match Env.Map.find_opt key obj_env with
+          | Some expr ->
+            let* (_, evaluated) = interpret obj_env expr in
+            ok ((field, evaluated) :: evaluated_fields)
+          | None -> acc
         )
         fields
-        []
+        (ok [])
     in ok (List.rev field_list)
   | _ -> ok []

There's also a small fix in the type checker's translate_object_field_access. When chaining into a TruntimeObject, the field lookup was using the outer venv -- meaning self and $ weren't in scope. The fix builds a proper field_venv before looking up the field, the same way the interpreter does it:

diff --git a/lib/type.ml b/lib/type.ml
index 8b41545..200f533 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -376,22 +376,31 @@ and translate_object_field_access venv pos scope chain_exprs =
     (fun acc field_expr ->
       let* (venv, prev_ty) = acc in

-      let get_obj_id =
+      let get_obj_id_and_env =
         match prev_ty with
-        | TobjectPtr (obj_id, _) -> ok obj_id
-        | TruntimeObject (obj_id, _) -> ok obj_id
+        | TobjectPtr (obj_id, _) -> ok (obj_id, venv)
+        | TruntimeObject (obj_id, _) ->
+          (* TODO: we haven't included the environment in TruntimeObject yet.
+             It must be done such as Ast.RuntimeObject *)
+          let field_venv =
+            Env.add_local "self" (TobjectPtr (obj_id, TobjectSelf)) venv
+          in
+          let field_venv =
+            Env.add_local_when_not_present "$" (TobjectPtr (obj_id, TobjectTopLevel)) field_venv |> fst
+          in
+          ok (obj_id, field_venv)
         | _ -> Error.error_at pos Error.Msg.must_be_object
       in

       match field_expr with
       | String (_, field) | Ident (_, field) ->
-        let* obj_id = get_obj_id in
+        let* (obj_id, field_venv) = get_obj_id_and_env in
         let key = Env.uniq_field_ident obj_id field in
         if ObjectFields.mem key !translating_fields then
           Error.error_at pos (Error.Msg.type_cyclic_reference key)
         else begin
           translating_fields := ObjectFields.add key !translating_fields;
-          let result = Env.get_obj_field field obj_id venv
+          let result = Env.get_obj_field field obj_id field_venv
             ~succ:translate_lazy
             ~err:(Error.error_at pos)
           in

I sprinkled a TODO here because I don't want to do this refactoring now. XD

Everything is captured in the cram tests:

diff --git a/samples/semantics/valid_object_with_cyclic_field.jsonnet b/samples/semantics/invalid_object_with_cyclic_field.jsonnet
similarity index 100%
rename from samples/semantics/valid_object_with_cyclic_field.jsonnet
rename to samples/semantics/invalid_object_with_cyclic_field.jsonnet
diff --git a/test/cram/objects.t b/test/cram/objects.t
index b200032..e7ae092 100644
--- a/test/cram/objects.t
+++ b/test/cram/objects.t
@@ -24,7 +24,7 @@

   $ tsonnet ../../samples/objects/untouched_field.jsonnet
   Warning: ../../samples/objects/untouched_field.jsonnet:1:0 Unused variable result
-  
+
   1: local result = {
      ^^^^^^^^^^^^^^^^
   2:     a: 1,
@@ -32,3 +32,39 @@
   3:     b: 42,
      ^^^^^^^^^^
   42
+
+
+  $ tsonnet ../../samples/objects/untouched_invalid_field.jsonnet
+  Warning: ../../samples/objects/untouched_invalid_field.jsonnet:1:0 Unused variable result
+
+  1: local result = {
+     ^^^^^^^^^^^^^^^^
+  2:     a: 1,
+     ^^^^^^^^^
+  3:     b: self.a,
+     ^^^^^^^^^^^^^^
+  4:     c: self.d,
+     ^^^^^^^^^^^^^^
+  5:     d: self.c
+     ^^^^^^^^^^^^^
+  Warning: ../../samples/objects/untouched_invalid_field.jsonnet:1:15 Cyclic reference found for 1->c
+
+  1: local result = {
+     ^^^^^^^^^^^^^^^^
+  2:     a: 1,
+
+  3:     b: self.a,
+
+  4:     c: self.d,
+
+  Warning: ../../samples/objects/untouched_invalid_field.jsonnet:1:15 Cyclic reference found for 1->d
+
+  1: local result = {
+     ^^^^^^^^^^^^^^^^
+  2:     a: 1,
+
+  3:     b: self.a,
+
+  4:     c: self.d,
+
+  1
diff --git a/test/cram/semantics.t b/test/cram/semantics.t
index 4513915..c98851d 100644
--- a/test/cram/semantics.t
+++ b/test/cram/semantics.t
@@ -52,7 +52,11 @@
      ^^^^^^^^^^^^^^^^
   4:     local c = b,
      ^^^^^^^^^^^^^^^^
-  {}
+  ../../samples/semantics/invalid_binding_cycle_object_locals.jsonnet:4:14 Cyclic reference found for b
+  
+  4:     local c = b,
+     ^^^^^^^^^^^^^^^^
+  [1]

   $ tsonnet ../../samples/semantics/invalid_binding_cycle_binop.jsonnet
   ../../samples/semantics/invalid_binding_cycle_binop.jsonnet:2:10 Cyclic reference found for a
@@ -92,7 +96,11 @@
      ^^^^^^^^^^^^^^
   3:     b: self.a,
      ^^^^^^^^^^^^^^
-  {}
+  ../../samples/semantics/invalid_binding_cycle_object_fields.jsonnet:2:12 Cyclic reference found for 1->b
+  
+  2:     a: self.b,
+     ^^^^^^^^^^^^^^
+  [1]

   $ tsonnet ../../samples/semantics/invalid_binding_cycle_object_nested_field.jsonnet
   Warning: ../../samples/semantics/invalid_binding_cycle_object_nested_field.jsonnet:1:0 Cyclic reference found for 1->a
@@ -135,7 +143,11 @@
               ^^^^^^^^^
   4:     },

-  { "a": {} }
+  ../../samples/semantics/invalid_binding_cycle_object_nested_field.jsonnet:3:17 Cyclic reference found for 1->b
+  
+  3:         value: $.b
+     ^^^^^^^^^^^^^^^^^^
+  [1]

   $ tsonnet ../../samples/semantics/invalid_binding_cycle_outer_object_fields.jsonnet
   Warning: ../../samples/semantics/invalid_binding_cycle_outer_object_fields.jsonnet:1:0 Cyclic reference found for 1->a
@@ -154,7 +166,11 @@
      ^^^^^^^^^^^
   3:     b: $.a,
      ^^^^^^^^^^^
-  {}
+  ../../samples/semantics/invalid_binding_cycle_outer_object_fields.jsonnet:2:9 Cyclic reference found for 1->b
+  
+  2:     a: $.b,
+     ^^^^^^^^^^^
+  [1]

   $ tsonnet ../../samples/semantics/invalid_binding_cycle_object_field_and_local.jsonnet
   Warning: ../../samples/semantics/invalid_binding_cycle_object_field_and_local.jsonnet:1:0 Cyclic reference found for 1->b
@@ -165,7 +181,11 @@
      ^^^^^^^^^^^^^^^^^^^^^
   3:     b: a,
      ^^^^^^^^^
-  {}
+  ../../samples/semantics/invalid_binding_cycle_object_field_and_local.jsonnet:3:7 Cyclic reference found for a
+  
+  3:     b: a,
+     ^^^^^^^^^
+  [1]

   $ tsonnet ../../samples/semantics/invalid_binding_cycle_indexed_field.jsonnet
   Warning: ../../samples/semantics/invalid_binding_cycle_indexed_field.jsonnet:1:0 Cyclic reference found for 1->arr
@@ -184,10 +204,14 @@
      ^^^^^^^^^^^^^^^^^^^^^^
   3:     first: self.arr[0]
      ^^^^^^^^^^^^^^^^^^^^^^
-  {}
+  ../../samples/semantics/invalid_binding_cycle_indexed_field.jsonnet:2:15 Cyclic reference found for 1->first
+  
+  2:     arr: [self.first],
+     ^^^^^^^^^^^^^^^^^^^^^^
+  [1]

-  $ tsonnet ../../samples/semantics/valid_object_with_cyclic_field.jsonnet
-  Warning: ../../samples/semantics/valid_object_with_cyclic_field.jsonnet:1:0 Cyclic reference found for 1->b
+  $ tsonnet ../../samples/semantics/invalid_object_with_cyclic_field.jsonnet
+  Warning: ../../samples/semantics/invalid_object_with_cyclic_field.jsonnet:1:0 Cyclic reference found for 1->b

   1: {
      ^
@@ -197,7 +221,7 @@
      ^^^^^^^^^^^^^^
   4:     c: self.b,
      ^^^^^^^^^^^^^^
-  Warning: ../../samples/semantics/valid_object_with_cyclic_field.jsonnet:1:0 Cyclic reference found for 1->c
+  Warning: ../../samples/semantics/invalid_object_with_cyclic_field.jsonnet:1:0 Cyclic reference found for 1->c

   1: {
      ^
@@ -207,7 +231,11 @@
      ^^^^^^^^^^^^^^
   4:     c: self.b,
      ^^^^^^^^^^^^^^
-  { "a": 1 }
+  ../../samples/semantics/invalid_object_with_cyclic_field.jsonnet:3:12 Cyclic reference found for 1->c
+  
+  3:     b: self.c,
+     ^^^^^^^^^^^^^^
+  [1]

   $ tsonnet ../../samples/semantics/valid_object_access_non_cyclic_field.jsonnet
   Warning: ../../samples/semantics/valid_object_access_non_cyclic_field.jsonnet:1:0 Unused variable obj

One thing I noticed while working through the test cases: the sample that used to be called valid_object_with_cyclic_field.jsonnet is not actually valid -- it errors when the cyclic fields are accessed. Renamed it to invalid_object_with_cyclic_field.jsonnet. These things happen when you're naming files before you've implemented the feature that would tell you whether they're valid or not.

Conclusion

The reachability analysis for variables and the evaluating_fields tracking for objects both push in the same direction -- lean on lazy evaluation instead of fighting it. This is the nature of Jsonnet, and Tsonnet should embrace it.

You can check the entire diff here.

I think, after that, we can start playing with much more fun things: functions!

Thanks for reading Bit Maybe Wise! If you too believe a cycle you never touch shouldn't ruin your day, subscribe and let's keep being reasonably lenient together.

Photo by Sebastian Unrau on Unsplash

Tsonnet #33 - The arithmetic tutorial must go on

Hercules Lemke Merscher — Fri, 13 Mar 2026 10:04:57 +0000

Welcome to the Tsonnet series!

If you're not following along, check out how it all started in the first post of the series.

In the previous post, we added a full set of binary operators:

Hercules Lemke Merscher

Mar 5

Tsonnet #32 - != done, but getting there

#tsonnet #jsonnet #compiler

Comments

11 min read

We were almost done with the arithmetic tutorial. Two pieces were still missing: object merging, and division by zero error handling. Let's wrap those up.

Merging objects

The + operator is overloaded to act as an operator to merge two objects.

This sample file:

// samples/objects/merge.jsonnet
{ a: 1, b: 2 } + { b: 3, c: 4 }

Results in:

{ "a": 1, "b": 3, "c": 4 }

The right-hand side overrides the left-hand side fields.

The cram test looks like this:

diff --git a/test/cram/objects.t b/test/cram/objects.t
index 9c12260..bfb25bd 100644
--- a/test/cram/objects.t
+++ b/test/cram/objects.t
@@ -18,3 +18,6 @@

   $ tsonnet ../../samples/objects/toplevel_field_lookup_chain.jsonnet
   { "answer": { "value": 42 }, "answer_to_the_ultimate_question": 42 }
+
+  $ tsonnet ../../samples/objects/merge.jsonnet
+  { "a": 1, "b": 3, "c": 4 }

I'm adding a helper function in the Ast module to merge two lists of fields:

module Object = struct
  let merge_fields fields1 fields2 =
    (* fields2 comes after and has preference over fields1 *)
    let updated = List.map
      (fun (k, v) ->
        match List.assoc_opt k fields2 with
        | Some v' -> (k, v')
        | None -> (k, v)
      )
      fields1
    in
    (* (k,v) in fields2 not present in fields1 *)
    let new_fields = List.filter
      (fun (k, _) -> not (List.mem_assoc k fields1))
      fields2
    in
    (* then we merge *)
    updated @ new_fields
end

The type checker only needs to include the overloaded operation:

diff --git a/lib/type.ml b/lib/type.ml
index d553f5c..fbe68b1 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -321,6 +321,8 @@ and translate_bin_op venv pos op e1 e2 =
   | Add, _, Tstring | Add, Tstring, _ -> ok (venv'', Tstring)
   | Add, Tnumber, Tnumber -> ok (venv'', Tnumber)
   | Add, (Tarray _), (Tarray _) -> ok (venv'', Tarray Tany)
+  | Add, (Tobject _ | TruntimeObject _ | TobjectPtr _), (Tobject _ | TruntimeObject _ | TobjectPtr _) ->
+    ok (venv'', Tany)
   | Subtract, Tnumber, Tnumber -> ok (venv'', Tnumber)
   | Multiply, Tnumber, Tnumber -> ok (venv'', Tnumber)
   | Divide, Tnumber, Tnumber -> ok (venv'', Tnumber)

The interpreter implements the new interpret_object_merge_op function to deal with that, and we pattern-match in the interpret_bin_op function to add it:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index ddc8041..24f0595 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -66,6 +66,19 @@ and interpret_array_concat_op env e1 e2 =
   | _ ->
     error Error.Msg.interp_invalid_concat

+and interpret_object_merge_op env pos e1 e2 =
+  let eval_object = function
+    | EvaluatedObject _ as obj -> ok (env, obj)
+    | RuntimeObject _ as obj -> interpret env obj
+    | _ -> error Error.Msg.invalid_binary_op
+  in
+  let* (_, e1') = eval_object e1 in
+  let* (_, e2') = eval_object e2 in
+  match e1', e2' with
+  | EvaluatedObject (_, fields1), EvaluatedObject (_, fields2) ->
+    ok (env, EvaluatedObject (pos, Object.merge_fields fields1 fields2))
+  | _ -> error Error.Msg.invalid_binary_op
+
 and interpret_array env (pos, exprs) =
   let* (env', evaluated_exprs) = List.fold_left
     (fun result expr ->
@@ -234,6 +247,8 @@ and interpret_bin_op env (pos, op, e1, e2) =
    | Add, (Array _ as v1), (Array _ as v2)  ->
      interpret_array_concat_op env2 v1 v2
+   | Add, (EvaluatedObject _ | RuntimeObject _ as v1), (EvaluatedObject _ | RuntimeObject _ as v2) ->
+     interpret_object_merge_op env2 pos v1 v2
    | In, (String _ | Ident _ as field), (EvaluatedObject _ | RuntimeObject (_, _, _) as obj) ->
      interpret_in_op env2 pos field obj
    | _, v1, v2 ->

Done!

dune exec -- tsonnet samples/objects/merge.jsonnet
{ "a": 1, "b": 3, "c": 4 }

Division by zero

Next we should deal with the division by zero error.

Here's how Jsonnet handles it:

$ jsonnet samples/errors/divide_by_zero.jsonnet
RUNTIME ERROR: Division by zero.
    samples/errors/divide_by_zero.jsonnet:1:1-6 $
    During evaluation

And here are the sample files and how I want it to look in Tsonnet:

diff --git a/samples/errors/divide_by_zero.jsonnet b/samples/errors/divide_by_zero.jsonnet
new file mode 100644
index 0000000..59a5d52
--- /dev/null
+++ b/samples/errors/divide_by_zero.jsonnet
@@ -0,0 +1 @@
+5 / 0
diff --git a/samples/errors/divide_by_zero_float.jsonnet b/samples/errors/divide_by_zero_float.jsonnet
new file mode 100644
index 0000000..20f3764
--- /dev/null
+++ b/samples/errors/divide_by_zero_float.jsonnet
@@ -0,0 +1 @@
+5 / 0.0
diff --git a/samples/errors/modulo_by_zero.jsonnet b/samples/errors/modulo_by_zero.jsonnet
new file mode 100644
index 0000000..be4046b
--- /dev/null
+++ b/samples/errors/modulo_by_zero.jsonnet
@@ -0,0 +1 @@
+5 % 0
diff --git a/samples/errors/modulo_by_zero_float.jsonnet b/samples/errors/modulo_by_zero_float.jsonnet
new file mode 100644
index 0000000..8f666b8
--- /dev/null
+++ b/samples/errors/modulo_by_zero_float.jsonnet
@@ -0,0 +1 @@
+5 % 0.0
diff --git a/test/cram/errors.t b/test/cram/errors.t
index 7c117b8..dfcac7e 100644
--- a/test/cram/errors.t
+++ b/test/cram/errors.t
@@ -93,9 +105,43 @@
   $ tsonnet ../../samples/errors/object_outer_most_ref_out_of_scope.jsonnet
   ../../samples/errors/object_outer_most_ref_out_of_scope.jsonnet:2:13 No top-level object found

   2: local _two = $.one + 1;
      ^^^^^^^^^^^^^^^^^^^^^^^
   [1]
+
+
+  $ tsonnet ../../samples/errors/divide_by_zero.jsonnet
+  ../../samples/errors/divide_by_zero.jsonnet:1:0 Division by zero
+  
+  1: 5 / 0
+     ^^^^^
+  [1]
+
+
+  $ tsonnet ../../samples/errors/divide_by_zero_float.jsonnet
+  ../../samples/errors/divide_by_zero_float.jsonnet:1:0 Division by zero
+  
+  1: 5 / 0.0
+     ^^^^^^^
+  [1]
+
+
+  $ tsonnet ../../samples/errors/modulo_by_zero.jsonnet
+  ../../samples/errors/modulo_by_zero.jsonnet:1:0 Division by zero
+  
+  1: 5 % 0
+     ^^^^^
+  [1]
+
+
+  $ tsonnet ../../samples/errors/modulo_by_zero_float.jsonnet
+  ../../samples/errors/modulo_by_zero_float.jsonnet:1:0 Division by zero
+  
+  1: 5 % 0.0
+     ^^^^^^^
+  [1]
+

Not a huge difference from the reference implementation, but I like seeing the faulty operation highlighted in the source — much easier to spot and fix.

Let's add the error message:

diff --git a/lib/error.ml b/lib/error.ml
index 8c6b53f..ac8ae48 100644
--- a/lib/error.ml
+++ b/lib/error.ml
@@ -29,6 +29,7 @@ module Msg = struct
   let type_invalid_lookup_key expr = "Invalid object lookup key: " ^ expr

   (* Interpreter messages *)
+  let interp_division_by_zero = "Division by zero"
   let interp_invalid_concat = "Invalid concatenation operation"
   let interp_invalid_lookup = "Invalid object lookup"
   let interp_cannot_interpret expr = Printf.sprintf "Expression %s cannot be interpreted" expr
diff --git a/lib/error.mli b/lib/error.mli
index 58d7e8e..0bdd708 100644
--- a/lib/error.mli
+++ b/lib/error.mli
@@ -26,6 +26,7 @@ module Msg : sig
   val type_invalid_lookup_key : string -> string

   (* Interpreter messages *)
+  val interp_division_by_zero : string
   val interp_invalid_concat : string
   val interp_invalid_lookup : string
   val interp_cannot_interpret : string -> string

The interpret_arith_op function only needs to pattern-match on Int and Float zero before the division — pretty simple. Have I mentioned how much I enjoy pattern matching?

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index 24f0595..fe248b9 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -280,6 +280,8 @@ and interpret_arith_op env (pos, bin_op, n1, n2) =
     ok (env, Number (pos, Float ((float_of_int a) *. b)))
   | Multiply, Number (_, Float a), Number (_, Float b) ->
     ok (env, Number (pos, Float (a *. b)))
+  | Divide, _, Number (_, n) when n = Int 0 || n = Float 0.0 ->
+    Error.error_at pos Error.Msg.interp_division_by_zero
   | Divide, Number (_, Int a), Number (_, Int b) ->
     ok (env, Number (pos, Float ((float_of_int a) /. (float_of_int b))))
   | Divide, Number (_, Float a), Number (_, Int b) ->
@@ -288,6 +290,8 @@ and interpret_arith_op env (pos, bin_op, n1, n2) =
     ok (env, Number (pos, Float ((float_of_int a) /. b)))
   | Divide, Number (_, Float a), Number (_, Float b) ->
     ok (env, Number (pos, Float (a /. b)))
+  | Modulo, _, Number (_, n) when n = Int 0 || n = Float 0.0 ->
+    Error.error_at pos Error.Msg.interp_division_by_zero
   | Modulo, Number (_, Int a), Number (_, Int b) ->
     ok (env, Number (pos, Int (a mod b)))
   | Modulo, Number (_, Float a), Number (_, Int b) ->

The guard clauses (when n = Int 0 || n = Float 0.0) catch both integer and float zero before the division cases get a chance to run.

Completing the tutorial

With those two additions in place, samples/tutorials/arith.jsonnet is now fully supported -- minus the string formatting bits I'm deliberately setting aside for later. Here's the file with those commented out:

{
  concat_array: [1, 2, 3] + [4],
  concat_string: '123' + 4,
  equality1: 1 == '1',
  equality2: [{}, { x: 3 - 1 }]
             == [{}, { x: 2 }],
  ex1: 1 + 2 * 3 / (4 + 5),
  // Bitwise operations first cast to int.
  ex2: self.ex1 | 3,
  // Modulo operator.
  ex3: self.ex1 % 2,
  // Boolean logic
  ex4: (4 > 3) && (1 <= 3) || false,
  // Mixing objects together
  obj: { a: 1, b: 2 } + { b: 3, c: 4 },
  // Test if a field is in an object
  obj_member: 'foo' in { foo: 1 },
//   // String formatting
//   str1: 'The value of self.ex2 is '
//         + self.ex2 + '.',
//   str2: 'The value of self.ex2 is %g.'
//         % self.ex2,
//   str3: 'ex1=%0.2f, ex2=%0.2f'
//         % [self.ex1, self.ex2],
//   // By passing self, we allow ex1 and ex2 to
//   // be extracted internally.
//   str4: 'ex1=%(ex1)0.2f, ex2=%(ex2)0.2f'
//         % self,
//   // Do textual templating of entire files:
//   str5: |||
//     ex1=%(ex1)0.2f
//     ex2=%(ex2)0.2f
//   ||| % self,
}

Running it:

dune exec -- tsonnet samples/tutorials/arith.jsonnet
{
  "concat_array": [ 1, 2, 3, 4 ],
  "concat_string": "1234",
  "equality1": false,
  "equality2": true,
  "ex1": 1.6666666666666665,
  "ex2": 3,
  "ex3": 1.6666666666666665,
  "ex4": true,
  "obj": { "a": 1, "b": 3, "c": 4 },
  "obj_member": true
}

String formatting is next on the list -- but there are more interesting features to tackle first, so I'm parking it for now.

Conclusion

Two small additions -- object merging and division by zero -- and the arithmetic tutorial is effectively done. The pattern-matching guard clauses made the zero-division check almost embarrassingly straightforward, and the merge_fields helper slotted in without touching anything else.

You can check the entire diff here.

If you, too, believe dividing by zero should be an error and not a NaN, subscribe and let's keep each other honest.

Photo by Lance Grandahl on Unsplash

Tsonnet #32 - != done, but getting there

Hercules Lemke Merscher — Thu, 05 Mar 2026 08:56:22 +0000

Welcome to the Tsonnet series!

If you're not following along, check out how it all started in the first post of the series.

In the previous post, the equality operation was simplified:

Hercules Lemke Merscher

Mar 2

Tsonnet #31 - Taking back control of equality

#tsonnet #jsonnet #compiler

Comments

9 min read

Now, in order to complete the arithmetic tutorial, there's a myriad of operations still left to be implemented. They are quite simple to add actually, so let's do this ASAP!

Operations everywhere!

Here are all the operations we are going to add to the lexer:

diff --git a/lib/lexer.mll b/lib/lexer.mll
index 6f51b6f..a4c3745 100644
--- a/lib/lexer.mll
+++ b/lib/lexer.mll
@@ -46,6 +46,13 @@ rule read =
   | "@\"" { read_single_line_verbatim_double_quoted_string (Buffer.create 16) lexbuf }
   | "@'" { read_single_line_verbatim_single_quoted_string (Buffer.create 16) lexbuf }
   | "==" { EQUALITY }
+  | "!=" { INEQUALITY }
+  | ">=" { GREATER_EQUAL }
+  | "<=" { LESS_EQUAL }
+  | "<<" { SHIFT_LEFT }
+  | ">>" { SHIFT_RIGHT }
+  | '>' { GREATER }
+  | '<' { LESS }
   | '[' { LEFT_SQR_BRACKET }
   | ']' { RIGHT_SQR_BRACKET }
   | '{' { LEFT_CURLY_BRACKET }
@@ -58,14 +65,21 @@ rule read =
   | '-' { MINUS }
   | '*' { MULTIPLY }
   | '/' { DIVIDE }
+  | '%' { MODULO }
   | '!' { NOT }
   | '~' { BITWISE_NOT }
+  | "||" { LOGICAL_OR }
+  | '|' { BITWISE_OR }
+  | "&&" { LOGICAL_AND }
+  | "&" { BITWISE_AND }
+  | '^' { BITWISE_XOR }
   | '=' { ASSIGN }
   | ';' { SEMICOLON }
   | '.' { DOT }
   | "local" { LOCAL }
   | "self" { SELF }
   | "$" { TOP_LEVEL_OBJ }
+  | "in" { IN }
   | id { ID (Lexing.lexeme lexbuf) }
   | _ { raise (SyntaxError ("Unexpected char: " ^ Lexing.lexeme lexbuf)) }
   | eof { EOF }

The parser changes are quite straightforward too:

diff --git a/lib/parser.mly b/lib/parser.mly
index 456e33e..7adb1ee 100644
--- a/lib/parser.mly
+++ b/lib/parser.mly
@@ -20,17 +20,19 @@
 %token COLON
 %token DOT
 %token SELF TOP_LEVEL_OBJ
-%token PLUS MINUS MULTIPLY DIVIDE
+%token PLUS MINUS MULTIPLY DIVIDE MODULO
 %left PLUS MINUS
-%left MULTIPLY DIVIDE
+%left MULTIPLY DIVIDE MODULO
 %token <string> ID
-%token NOT BITWISE_NOT
-%left NOT BITWISE_NOT
+%token NOT BITWISE_NOT BITWISE_OR BITWISE_AND BITWISE_XOR LOGICAL_AND LOGICAL_OR
+%left  NOT BITWISE_NOT BITWISE_OR BITWISE_AND BITWISE_XOR LOGICAL_AND LOGICAL_OR
 %token SEMICOLON
 %token LOCAL
 %token ASSIGN
-%token EQUALITY
-%left EQUALITY
+%token EQUALITY INEQUALITY GREATER GREATER_EQUAL LESS LESS_EQUAL IN
+%left EQUALITY INEQUALITY GREATER GREATER_EQUAL LESS LESS_EQUAL IN
+%token SHIFT_LEFT SHIFT_RIGHT
+%left SHIFT_LEFT SHIFT_RIGHT
 %token EOF

 %start <Ast.expr> prog
@@ -139,12 +141,26 @@ obj_field_access:
   ;

 %inline bin_op:
-  | PLUS { Add }
-  | MINUS { Subtract }
-  | MULTIPLY { Multiply }
-  | DIVIDE { Divide }
-  | EQUALITY { Equality }
-  ;
+     | PLUS { Add }
+     | MINUS { Subtract }
+     | MULTIPLY { Multiply }
+     | DIVIDE { Divide }
+     | MODULO { Modulo }
+     | EQUALITY { Equality }
+     | INEQUALITY { Inequality }
+     | GREATER { GreaterThan }
+     | GREATER_EQUAL { GreaterThanOrEqual }
+     | LESS { LessThan }
+     | LESS_EQUAL { LessThanOrEqual }
+     | BITWISE_OR { BitwiseOr }
+     | BITWISE_AND { BitwiseAnd }
+     | BITWISE_XOR { BitwiseXor }
+     | LOGICAL_AND { LogicalAnd }
+     | LOGICAL_OR { LogicalOr }
+     | IN { In }
+     | SHIFT_LEFT { ShiftLeft }
+     | SHIFT_RIGHT { ShiftRight }
+     ;

 %inline unary_op:
   | PLUS { Plus }

I only had to introduce the new symbols we'd use for each operation.

The new AST variants:

diff --git a/lib/ast.ml b/lib/ast.ml
index 03f413e..5111806 100644
--- a/lib/ast.ml
+++ b/lib/ast.ml
@@ -5,7 +5,21 @@ type bin_op =
   | Subtract
   | Multiply
   | Divide
+  | Modulo
   | Equality
+  | Inequality
+  | GreaterThan
+  | GreaterThanOrEqual
+  | LessThan
+  | LessThanOrEqual
+  | BitwiseOr
+  | BitwiseAnd
+  | BitwiseXor
+  | LogicalAnd
+  | LogicalOr
+  | In
+  | ShiftLeft
+  | ShiftRight
   [@@deriving qcheck, show]

 type unary_op =
@@ -160,7 +174,21 @@ let rec string_of_type = function
     | Subtract -> "-"
     | Multiply -> "*"
     | Divide -> "/"
+    | Modulo -> "%"
     | Equality -> "=="
+    | Inequality -> "!="
+    | GreaterThan -> ">"
+    | GreaterThanOrEqual -> ">="
+    | LessThan -> "<"
+    | LessThanOrEqual -> "<="
+    | BitwiseOr -> "|"
+    | BitwiseAnd -> "&"
+    | BitwiseXor -> "^"
+    | LogicalAnd -> "&&"
+    | LogicalOr -> "||"
+    | In -> "in"
+    | ShiftLeft -> "<<"
+    | ShiftRight -> ">>"
     in prefix ^ " " ^ bin_op
   | UnaryOp (_, unary_op, _) ->
     let prefix = "Unary Operation" in

The type checker changes are also straightforward:

diff --git a/lib/type.ml b/lib/type.ml
index 5de3c4c..d553f5c 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -320,10 +320,29 @@ and translate_bin_op venv pos op e1 e2 =
   match op, e1', e2' with
   | Add, _, Tstring | Add, Tstring, _ -> ok (venv'', Tstring)
   | Add, Tnumber, Tnumber -> ok (venv'', Tnumber)
+  | Add, (Tarray _), (Tarray _) -> ok (venv'', Tarray Tany)
   | Subtract, Tnumber, Tnumber -> ok (venv'', Tnumber)
   | Multiply, Tnumber, Tnumber -> ok (venv'', Tnumber)
   | Divide, Tnumber, Tnumber -> ok (venv'', Tnumber)
+  | Modulo, Tnumber, Tnumber -> ok (venv'', Tnumber)
+  | BitwiseOr, Tnumber, Tnumber -> ok (venv'', Tnumber)
+  | BitwiseAnd, Tnumber, Tnumber -> ok (venv'', Tnumber)
+  | BitwiseXor, Tnumber, Tnumber -> ok (venv'', Tnumber)
+  | ShiftLeft, Tnumber, Tnumber -> ok (venv'', Tnumber)
+  | ShiftRight, Tnumber, Tnumber -> ok (venv'', Tnumber)
+  | LogicalAnd, Tbool, Tbool -> ok (venv'', Tbool)
+  | LogicalOr, Tbool, Tbool -> ok (venv'', Tbool)
   | Equality, _, _ -> ok (venv'', Tbool)
+  | Inequality, _, _ -> ok (venv'', Tbool)
+  | GreaterThan, Tnumber, Tnumber -> ok (venv'', Tbool)
+  | GreaterThanOrEqual, Tnumber, Tnumber -> ok (venv'', Tbool)
+  | LessThan, Tnumber, Tnumber -> ok (venv'', Tbool)
+  | LessThanOrEqual, Tnumber, Tnumber -> ok (venv'', Tbool)
+  | GreaterThan, Tstring, Tstring -> ok (venv'', Tbool)
+  | GreaterThanOrEqual, Tstring, Tstring -> ok (venv'', Tbool)
+  | LessThan, Tstring, Tstring -> ok (venv'', Tbool)
+  | LessThanOrEqual, Tstring, Tstring -> ok (venv'', Tbool)
+  | In, Tstring, (Tobject _ | Tany | TruntimeObject _ | TobjectPtr _) -> ok (venv'', Tbool)
   | _ -> Error.trace Error.Msg.invalid_binary_op pos >>= error

 let check (config : Config.t) expr  =

What changes on evaluation?

The array concatenation was missing, so I added that:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index 0b522f2..689e786 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -44,7 +44,7 @@ let rec interpret env expr =
       )
       ~err:(Error.error_at pos)

-and interpret_concat_op env e1 e2 =
+and interpret_string_concat_op env e1 e2 =
     match e1, e2 with
     | String (_, s1), String (_, s2) ->
       ok (env, String (dummy_pos, s1^s2))
@@ -59,6 +59,13 @@ and interpret_concat_op env e1 e2 =
     | _ ->
       error Error.Msg.interp_invalid_concat

+and interpret_array_concat_op env e1 e2 =
+    match e1, e2 with
+    | Array (pos, exprs1), Array (_, exprs2) ->
+      ok (env, Array (pos, List.append exprs1 exprs2))
+    | _ ->
+      error Error.Msg.interp_invalid_concat
+
 and interpret_array env (pos, exprs) =
   let* (env', evaluated_exprs) = List.fold_left
     (fun result expr ->

@@ -220,16 +227,20 @@ and interpret_runtime_object_fields obj_env fields =
   | _ -> ok []

 and interpret_bin_op env (pos, op, e1, e2) =
-  let* (env1, e1') = interpret env e1 in
-  let* (env2, e2') = interpret env1 e2 in
-  match op, e1', e2' with
-  | Add, (String _ as v1), (_ as v2) | Add, (_ as v1), (String _ as v2) ->
-    interpret_concat_op env2 v1 v2
-  | _, v1, v2 ->
-    interpret_arith_op env2 (pos, op, v1, v2)
+   let* (env1, e1') = interpret env e1 in
+   let* (env2, e2') = interpret env1 e2 in
+   match op, e1', e2' with
+   | Add, (String _ as v1), (_ as v2) | Add, (_ as v1), (String _ as v2) ->
+     interpret_string_concat_op env2 v1 v2
+   | Add, (Array _ as v1), (Array _ as v2)  ->
+     interpret_array_concat_op env2 v1 v2
+   | In, (String _ | Ident _ as field), (EvaluatedObject _ | RuntimeObject (_, _, _) as obj) ->
+     interpret_in_op env2 pos field obj
+   | _, v1, v2 ->
+     interpret_arith_op env2 (pos, op, v1, v2)

The previous interpret_concat_op was renamed to be more specific: interpret_string_concat_op. A new function was added to handle the concatenation of arrays: interpret_array_concat_op.

We still don't have one for objects, but we'll get there eventually.

interpret_arith_op grew into a large matching function. It's a lot of lines, but it's easy to follow:

and interpret_arith_op env (pos, bin_op, n1, n2) =
   match bin_op, n1, n2 with
  | Add, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Int (a + b)))
  | Add, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Float (a +. (float_of_int b))))
  | Add, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Float ((float_of_int a) +. b)))
  | Add, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Float (a +. b)))
  | Subtract, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Int (a - b)))
  | Subtract, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Float (a -. (float_of_int b))))
  | Subtract, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Float ((float_of_int a) -. b)))
  | Subtract, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Float (a -. b)))
  | Multiply, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Int (a * b)))
  | Multiply, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Float (a *. (float_of_int b))))
  | Multiply, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Float ((float_of_int a) *. b)))
  | Multiply, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Float (a *. b)))
  | Divide, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Float ((float_of_int a) /. (float_of_int b))))
  | Divide, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Float (a /. (float_of_int b))))
  | Divide, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Float ((float_of_int a) /. b)))
  | Divide, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Float (a /. b)))
  | Modulo, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Int (a mod b)))
  | Modulo, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Float (Float.rem a (float_of_int b))))
  | Modulo, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Float (Float.rem (float_of_int a) b)))
  | Modulo, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Float (Float.rem a b)))
  | BitwiseOr, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Int (a lor b)))
  | BitwiseOr, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Int (int_of_float a lor b)))
  | BitwiseOr, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Int (a lor int_of_float b)))
  | BitwiseOr, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Int (int_of_float a lor int_of_float b)))
  | BitwiseAnd, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Int (a land b)))
  | BitwiseAnd, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Int (int_of_float a land b)))
  | BitwiseAnd, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Int (a land int_of_float b)))
  | BitwiseAnd, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Int (int_of_float a land int_of_float b)))
  | BitwiseXor, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Int (a lxor b)))
  | BitwiseXor, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Int (int_of_float a lxor b)))
  | BitwiseXor, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Int (a lxor int_of_float b)))
  | BitwiseXor, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Int (int_of_float a lxor int_of_float b)))
  | ShiftLeft, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Int (a lsl b)))
  | ShiftLeft, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Int (int_of_float a lsl b)))
  | ShiftLeft, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Int (a lsl int_of_float b)))
  | ShiftLeft, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Int (int_of_float a lsl int_of_float b)))
  | ShiftRight, Number (_, Int a), Number (_, Int b) ->
    ok (env, Number (pos, Int (a lsr b)))
  | ShiftRight, Number (_, Float a), Number (_, Int b) ->
    ok (env, Number (pos, Int (int_of_float a lsr b)))
  | ShiftRight, Number (_, Int a), Number (_, Float b) ->
    ok (env, Number (pos, Int (a lsr int_of_float b)))
  | ShiftRight, Number (_, Float a), Number (_, Float b) ->
    ok (env, Number (pos, Int (int_of_float a lsr int_of_float b)))
  | LogicalAnd, Bool (_, a), Bool (_, b) ->
    ok (env, Bool (pos, a && b))
  | LogicalOr, Bool (_, a), Bool (_, b) ->
    ok (env, Bool (pos, a || b))
  | Equality, Array (_, items1), Array (_, items2) ->
    (* Early exit: skip evaluation if lengths differ for efficiency *)
    if List.length items1 <> List.length items2 then
      ok (env, Bool (pos, false))
    else
      let* (_, evaluated1) = interpret_array env (pos, items1) in
      let* (_, evaluated2) = interpret_array env (pos, items2) in
      ok (env, Bool (pos, evaluated1 =~ evaluated2))
  | Equality, v1, v2 ->
    let* (_, eval_expr1) = interpret env v1 in
    let* (_, eval_expr2) = interpret env v2 in
    ok (env, Bool (pos, eval_expr1 =~ eval_expr2))
  | Inequality, v1, v2 ->
    (* Inequality is, simply put, negation of equality *)
    let* (_, expr) = interpret_arith_op env (pos, Equality, v1, v2) in
    (match expr with
    | Bool (_, value) -> ok (env, Bool (pos, not value))
    | _ -> Error.trace Error.Msg.invalid_binary_op pos >>= error
    )
  | GreaterThan, v1, v2 ->
   ok (env, Bool (pos, Compare.gt v1 v2))
  | GreaterThanOrEqual, v1, v2 ->
   ok (env, Bool (pos, Compare.gte v1 v2))
  | LessThan, v1, v2 ->
   ok (env, Bool (pos, Compare.lt v1 v2))
  | LessThanOrEqual, v1, v2 ->
   ok (env, Bool (pos, Compare.lte v1 v2))
  | _ ->
    Error.trace Error.Msg.invalid_binary_op pos >>= error

Most operations map directly to their OCaml equivalents. Equality we took care in the previous post. The exception is the comparison operators -- I had to abstract those under the Ast.Compare module:

module Compare = struct
  let _cmp_num n1 n2 =
    let to_float = function Int i -> float_of_int i | Float f -> f in
    Float.compare (to_float n1) (to_float n2)

  let _cmp_str s1 s2 = String.compare s1 s2

  let _compare op v1 v2 =
    match v1, v2 with
    | Number (_, n1), Number (_, n2) -> op (_cmp_num n1 n2) 0
    | String (_, s1), String (_, s2) -> op (_cmp_str s1 s2) 0
    | _ ->
      (* unreachable: the type checker rejects comparisons on
         non-numeric/non-string types before evaluation *)
      false

  let gt v1 v2 = _compare (>) v1 v2
  let gte v1 v2 = _compare (>=) v1 v2
  let lt v1 v2 = _compare (<) v1 v2
  let lte v1 v2 = _compare (<=) v1 v2
end

Number comparisons work as you'd expect. Strings are compared by unicode codepoint order, which OCaml's String.compare handles out of the box.

There's also a new interpret_in_op that checks if a field is present in an object:

// samples/operations/in.jsonnet
{
    has_field: 'foo' in { foo: 1 },
    has_no_field: 'xyz' in { foo: 1 },

    local field_name = 'bar',
    has_field_bar: field_name in { bar: 2 },
    has_no_field_bar: field_name in { baz: 3 },
}

And the implementation:

and interpret_in_op env pos field obj =
  match field, obj with
  | String (_, field_str), EvaluatedObject (_, fields)
  | Ident (_, field_str), EvaluatedObject (_, fields) ->
    let field_exists = List.exists (fun (name, _) -> name = field_str) fields in
    ok (env, Bool (pos, field_exists))
  | String (_, field_str), RuntimeObject (_, _, fields)
  | Ident (_, field_str), RuntimeObject (_, _, fields) ->
    let field_exists = ObjectFields.exists (fun name -> name = field_str) fields in
    ok (env, Bool (pos, field_exists))
  | _ ->
    Error.trace Error.Msg.invalid_binary_op pos >>= error

We must pattern match on both String and Ident -- these are the two variants we use to define field names in objects, e.g. { a: 42 } or { "a": 42 }.

Verifying

New sample files:

//samples/arrays/concat.jsonnet
[1, 2, 3] + [4]

// samples/operations/modulo.jsonnet
10 % 3

// samples/operations/shift_left.jsonnet
1 << 1

// samples/operations/shift_right.jsonnet
4 >> 1

// samples/operations/bitwise.jsonnet
{
    or: 1.6 | 3,
    xor: 1 ^ 3,
    and: 5 & 3
}

// samples/operations/gt_gte_lt_lte.jsonnet
{
    gt_true: 2 > 1,
    gt_false: 1 > 2,

    gte_true: 2 >= 2,
    gte_false: 1 >= 2,

    lt_true: 1 < 2,
    lt_false: 2 < 1,

    lte_true: 2 <= 2,
    lte_false: 2 <= 1,
}

// samples/operations/in.jsonnet
{
    has_field: 'foo' in { foo: 1 },
    has_no_field: 'xyz' in { foo: 1 },

    local field_name = 'bar',
    has_field_bar: field_name in { bar: 2 },
    has_no_field_bar: field_name in { baz: 3 },
}

// samples/operations/inequality.jsonnet
{
    eq_number_number: 1 != 1,
    dif_number_number: 1 != 2,
    dif_number_str: "1" != 1,

    eq_str_str: "42" != "42",
    dif_str_str: "42" != "0",

    eq_array_array: [1,2,3] != [1,2,3],
    dif_array_array: [1,2,3] != [3,2,1],

    eq_obj_obj: {x: 1, y: 2, z: 3} != {z: 3, x: 1, y: 2},
    dif_obj_obj: {a: 1, b: 2} != {b: 2, c: 3},

    eq_complex_obj_complex_obj: [{}, { x: 3 - 1 }] != [{}, { x: 2 }],
    dif_complex_obj_complex_obj: [{ a: 1 }, { b: 2 }] != [{ b: 2 }, { a: 1 }],
}

// samples/operations/logical.jsonnet
{
    and_true: true && true,
    and_false: true && false,
    or_true: false || true,
    or_false: false || false
}

// samples/strings/comparison.jsonnet
{
    // Two strings can be compared with `<` (unicode codepoint order).
    gt_true: "é" > "e",
    gte_true: "é" >= "e",
    lt_true: "e" < "é",
    lte_true: "e" <= "é",

    gt_false: "é" < "e",
    gte_false: "é" <= "e",
    lt_false: "e" > "é",
    lte_false: "e" >= "é",

    ordered: std.sort(["b", "a", "é", "A"])
}

// samples/operations/in.jsonnet
{
    has_field: 'foo' in { foo: 1 },
    has_no_field: 'xyz' in { foo: 1 },

    local field_name = 'bar',
    has_field_bar: field_name in { bar: 2 },
    has_no_field_bar: field_name in { baz: 3 },
}

Of course, I match each one with a cram test:

diff --git a/test/cram/arrays.t b/test/cram/arrays.t
new file mode 100644
index 0000000..b840584
--- /dev/null
+++ b/test/cram/arrays.t
@@ -0,0 +1,2 @@
+  $ tsonnet ../../samples/arrays/concat.jsonnet
+  [ 1, 2, 3, 4 ]
diff --git a/test/cram/operations.t b/test/cram/operations.t
index bb1c93a..503084f 100644
--- a/test/cram/operations.t
+++ b/test/cram/operations.t
@@ -1,22 +1,25 @@

-  $ tsonnet ../../samples/equality.jsonnet
+  $ tsonnet ../../samples/operations/modulo.jsonnet
+  1
+
+  $ tsonnet ../../samples/operations/equality.jsonnet
   {
     "dif_array_array": false,
     "dif_complex_obj_complex_obj": false,
@@ -30,3 +33,23 @@
     "eq_obj_obj": true,
     "eq_str_str": true
   }
+
+  $ tsonnet ../../samples/operations/bitwise.jsonnet
+  { "and": 1, "or": 3, "xor": 2 }
+
+  $ tsonnet ../../samples/operations/logical.jsonnet
+  { "and_false": false, "and_true": true, "or_false": false, "or_true": true }
+
+  $ tsonnet ../../samples/operations/in.jsonnet
+  {
+    "has_field": true,
+    "has_field_bar": true,
+    "has_no_field": false,
+    "has_no_field_bar": false
+  }
+
+  $ tsonnet ../../samples/operations/shift_left.jsonnet
+  2
+
+  $ tsonnet ../../samples/operations/shift_right.jsonnet
+  2

Conclusion

What looked like a mountain of work turned out to be quite mechanical -- once the scaffolding is in place, each new operator slotted in with minimal friction.

You can check the entire diff here.

Thanks for reading Bit Maybe Wise! If 'foo' in { foo: 1 } returns true for you too, subscribe.

Photo by Joachim Schnürle on Unsplash

Tsonnet #31 - Taking back control of equality

Hercules Lemke Merscher — Mon, 02 Mar 2026 20:40:42 +0000

Welcome to the Tsonnet series!

If you're not following along, check out how it all started in the first post of the series.

In the previous post, I implemented the equality operator:

Hercules Lemke Merscher

Jan 30 '25

Tsonnet #30 - Dabbling with equality

#tsonnet #jsonnet #compiler

Comments

10 min read

In a messy way, I should say. So, let's take back control.

Encoding the compiler phases as phantom types

In the previous post I mentioned this, and it was my initial idea. The premise has its merit. We encode each compiler phase in the type system, as each phase will only deal with AST variants that matter in that stage. I still believe this should be the end state of the compiler, but I played with it, and decided not to pursue this path. At least, not yet.

I made a quick and dirty attempt, you can see the diff here, but in the end, I was not satisfied with how it turned out.

Why? Because it introduced too much noise, and made the code brittle, IMO. I don't want to enforce too much strictness at this point while the compiler is still changing. Though I still believe this is going to be valuable eventually.

For now, I chose a different and simpler path.

A new variant

EvaluatedObject comes into play:

diff --git a/lib/ast.ml b/lib/ast.ml
index ab91d6f..03f413e 100644
--- a/lib/ast.ml
+++ b/lib/ast.ml
@@ -55,11 +55,16 @@ module ObjectFields = struct
 end

 type expr =
+  (* terminal variants can appear in any stage, representable in the final JSON *)
   | Unit
   | Null of position
   | Number of position * number
   | Bool of position * bool
   | String of position * string
+  | EvaluatedObject of position * (string * expr) list
+
+  (* interpreted variants were parsed, interpreted and transformed,
+    but are not terminal, and are waiting to be transformed into terminal variants *)
   | Ident of position * string
   | Array of position * expr list
   | ParsedObject of position * object_entry list
@@ -71,6 +76,7 @@ type expr =
   | Local of position * (string * expr) list
   | Seq of expr list
   | IndexedExpr of position * string * expr
+
 and object_entry =
   | ObjectField of string * expr
   | ObjectExpr of expr

Here we'll draw a line between the type variants that are terminal (can be representable as JSON), and those that are merely there for intermediate steps (used by the interpreter).

This gives us the power to simplify our workflow, starting with the semantic_equal function:

@@ -100,11 +106,12 @@ let rec semantic_equal evaluated_expr1 evaluated_expr2 =
   | Array (_, items1), Array (_, items2) ->
     List.length items1 = List.length items2
     && List.for_all2 semantic_equal items1 items2
-  | ParsedObject (_, entries1), ParsedObject (_, entries2) ->
-    List.length entries1 = List.length entries2
-    && List.for_all2 object_entry_semantic_equal entries1 entries2
-  | RuntimeObject (_, env1, fields1), RuntimeObject (_, env2, fields2) ->
-    runtime_object_semantic_equal (env1, fields1) (env2, fields2)
+  | EvaluatedObject (_, fields1), EvaluatedObject (_, fields2) ->
+    List.length fields1 = List.length fields2
+    && List.for_all2
+      (fun (k1, v1) (k2, v2) -> k1 = k2 && semantic_equal v1 v2)
+      fields1
+      fields2
   | ObjectPtr (id1, scope1), ObjectPtr (id2, scope2) ->
     id1 = id2 && scope1 = scope2
   | _, _ ->
@@ -112,36 +119,6 @@ let rec semantic_equal evaluated_expr1 evaluated_expr2 =
       just representable values such as number, boolean, string, object, array *)
     false

Intermediate object variants are not relevant in this function anymore.

We can remove some ugly code now:

-and object_entry_semantic_equal entry1 entry2 =
-  match (entry1, entry2) with
-  | ObjectField (name1, e1), ObjectField (name2, e2) ->
-    name1 = name2 && semantic_equal e1 e2
-  | ObjectExpr e1, ObjectExpr e2 ->
-    semantic_equal e1 e2
-  | _, _ -> false
-
-and runtime_object_semantic_equal (env1, fields1) (env2, fields2) =
-  (* RuntimeObjects contain lazy (unevaluated) fields.
-    Full semantic comparison of field values requires
-    evaluation, which must be done in the interpreter. *)
-  let get_obj_id env =
-    match Env.Map.find_opt "self" env with
-    | Some (ObjectPtr (obj_id, _)) -> Some obj_id
-    | _ -> None
-  in
-  (match (get_obj_id env1, get_obj_id env2) with
-  | Some obj_id1, Some obj_id2 ->
-    ObjectFields.equal fields1 fields2
-    && ObjectFields.for_all (fun field ->
-      let key1 = Env.uniq_field_ident obj_id1 field in
-      let key2 = Env.uniq_field_ident obj_id2 field in
-      match (Env.Map.find_opt key1 env1, Env.Map.find_opt key2 env2) with
-      | Some v1, Some v2 -> semantic_equal v1 v2
-      | _, _ -> false
-    ) fields1
-  | _, _ -> false
-  )
-
 let ( =~ ) = semantic_equal

 let debug (config : Config.t) (ast : expr) : (expr, string) result =

By accepting only EvaluatedObject in the semantic_equal function, we invert the control of who evaluates the AST, leaving the responsibility for the interpreter.

The interpreter owns the evaluation

Before the evaluation changes, let's make sure parsing equality has the right associativity:

diff --git a/lib/parser.mly b/lib/parser.mly
index 158e4ab..456e33e 100644
--- a/lib/parser.mly
+++ b/lib/parser.mly
@@ -30,6 +30,7 @@
 %token LOCAL
 %token ASSIGN
 %token EQUALITY
+%left EQUALITY
 %token EOF

 %start <Ast.expr> prog

EvaluatedObject will be returned as-is by interpret function, and the pattern match that used to return RuntimeObject as-is will call interpret_runtime_object from now on:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index de0dd80..0b522f2 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -14,10 +14,10 @@ let interpret_unary_op (op: unary_op) (evaluated_expr: expr) =
 (** [interpret expr] interprets and reduce the intermediate AST [expr] into a result AST. *)
 let rec interpret env expr =
   match expr with
-  | Null _ | Bool _ | String _ | Number _ -> ok (env, expr)
+  | Null _ | Bool _ | String _ | Number _ | EvaluatedObject _ -> ok (env, expr)
   | Array (pos, exprs) -> interpret_array env (pos, exprs)
   | ParsedObject (pos, entries) -> interpret_object env (pos, entries)
-  | RuntimeObject _ as runtime_obj -> ok (env, runtime_obj)
+  | RuntimeObject (pos, obj_env, fields) -> interpret_runtime_object env (pos, obj_env, fields)
   | ObjectPtr _ as obj_ptr -> ok (env, obj_ptr)
   | ObjectFieldAccess (pos, scope, chain) -> interpret_object_field_access env (pos, scope, chain)
   | Ident (pos, varname) ->

The recursive nature of interpret is extremely flexible and elegant to reduce AST variants. Don't you think?

The Json module can be simplified a lot with this change too. Here's a sneak peek of its usage from now on:

@@ -49,10 +49,12 @@ and interpret_concat_op env e1 e2 =
     | String (_, s1), String (_, s2) ->
       ok (env, String (dummy_pos, s1^s2))
     | String (_, s1), val2 ->
-      let* s2 = Json.expr_to_string ~eval:interpret (env, val2) in
+      let* (_, val2) = interpret env val2 in
+      let* s2 = Json.expr_to_string val2 in
       ok (env, String (dummy_pos, s1^s2))
     | val1, String (_, s2) ->
-      let* s1 = Json.expr_to_string ~eval:interpret (env, val1) in
+      let* (_, val1) = interpret env val1 in
+      let* s1 = Json.expr_to_string val1 in
       ok (env, String (dummy_pos, s1^s2))
     | _ ->
       error Error.Msg.interp_invalid_concat

We'll get back to it. Let's get back to interpret_runtime_object:

@@ -97,25 +99,6 @@ and interpret_seq env exprs =
     interpret env expr >>= fun (env', _) ->
     interpret env' (Seq exprs')

-and fully_evaluate_obj_fields obj_env fields =
-  let get_obj_id env =
-    match Env.Map.find_opt "self" env with
-    | Some (ObjectPtr (obj_id, _)) -> Some obj_id
-    | _ -> None
-  in
-  match get_obj_id obj_env with
-  | None -> ok Env.Map.empty
-  | Some obj_id ->
-    ObjectFields.fold (fun field acc ->
-      let* evaluated_fields = acc in
-      let key = Env.uniq_field_ident obj_id field in
-      match Env.Map.find_opt key obj_env with
-      | Some expr ->
-        let* (_, evaluated) = interpret obj_env expr in
-        ok (Env.Map.add field evaluated evaluated_fields)
-      | None -> acc
-    ) fields (ok Env.Map.empty)
-
 and interpret_object env (pos, entries) =
   let* obj_id = Env.Id.generate () in
   let obj_env = Env.add_local "self" (ObjectPtr (obj_id, Self)) env in
@@ -213,6 +196,29 @@ and interpret_object_field_access env (pos, scope, chain_exprs) =
     (ok (env', obj))
     chain_exprs

+and interpret_runtime_object env (pos, obj_env, fields) =
+  let* evaluated_fields = interpret_runtime_object_fields obj_env fields in
+  ok (env, EvaluatedObject (pos, evaluated_fields))
+
+and interpret_runtime_object_fields obj_env fields =
+  match Env.Map.find_opt "self" obj_env with
+  | Some (ObjectPtr (obj_id, _)) ->
+    let* field_list =
+      ObjectFields.fold
+        (fun field acc ->
+          let* evaluated_fields = acc in
+          let key = Env.uniq_field_ident obj_id field in
+          match Env.Map.find_opt key obj_env with
+          | Some expr ->
+            let* (_, evaluated) = interpret obj_env expr in
+            ok ((field, evaluated) :: evaluated_fields)
+          | None -> acc
+        )
+        fields
+        (ok [])
+    in ok (List.rev field_list)
+  | _ -> ok []
+
 and interpret_bin_op env (pos, op, e1, e2) =
   let* (env1, e1') = interpret env e1 in
   let* (env2, e2') = interpret env1 e2 in

And the equality operation becomes much more manageable:

@@ -256,37 +262,54 @@ and interpret_arith_op env (pos, bin_op, n1, n2) =
     ok (env, Number (pos, Float ((float_of_int a) /. b)))
   | Divide, Number (_, Float a), Number (_, Float b) ->
     ok (env, Number (pos, Float (a /. b)))
-  | Equality, RuntimeObject (_, env1, fields1), RuntimeObject (_, env2, fields2) ->
-    if not (ObjectFields.equal fields1 fields2) then
-      ok (env, Bool (pos, false))
-    else
-      let* evaluated1 = fully_evaluate_obj_fields env1 fields1 in
-      let* evaluated2 = fully_evaluate_obj_fields env2 fields2 in
-      let* are_equal = ObjectFields.fold (fun field acc ->
-        let* all_equal = acc in
-        if not all_equal then ok false
-        else
-          match (Env.Map.find_opt field evaluated1, Env.Map.find_opt field evaluated2) with
-          | Some v1, Some v2 -> ok (v1 =~ v2)
-          | _, _ -> ok false
-      ) fields1 (ok true) in
-      ok (env, Bool (pos, are_equal))
   | Equality, Array (_, items1), Array (_, items2) ->
+    (* Early exit: skip evaluation if lengths differ for efficiency *)
     if List.length items1 <> List.length items2 then
       ok (env, Bool (pos, false))
     else
-      let* are_equal = List.fold_left2 (fun acc item1 item2 ->
-        let* all_equal = acc in
-        if not all_equal then ok false
-        else
-          match interpret_bin_op env (pos, Equality, item1, item2) with
-          | Ok (_, Bool (_, eq)) -> ok eq
-          | _ -> ok false
-      ) (ok true) items1 items2 in
-      ok (env, Bool (pos, are_equal))
+      let* (_, evaluated1) = interpret_array env (pos, items1) in
+      let* (_, evaluated2) = interpret_array env (pos, items2) in
+      ok (env, Bool (pos, evaluated1 =~ evaluated2))
   | Equality, v1, v2 ->
-    ok (env, Bool (pos, v1 =~ v2))
+    let* (_, eval_expr1) = interpret env v1 in
+    let* (_, eval_expr2) = interpret env v2 in
+    ok (env, Bool (pos, eval_expr1 =~ eval_expr2))
   | _ ->
     Error.trace Error.Msg.invalid_binary_op pos >>= error

Before handing over the interpretation phase to the serialization phase, now that we delineated the terminal variants, let's deep evaluate the AST expression:

let rec deep_eval expr =
  match expr with
  | Null _ | Bool _ | String _ | Number _ -> ok expr
  | Array (pos, items) ->
    let* evaluated_items = List.fold_left
      (fun acc item ->
        let* list = acc in
        let* evaluated = deep_eval item in
        ok (evaluated :: list)
      )
      (ok [])
      items
    in
    ok (Array (pos, List.rev evaluated_items))
  | EvaluatedObject (pos, fields) ->
    let* evaluated_fields = List.fold_left
      (fun acc (name, expr) ->
        let* list = acc in
        let* evaluated = deep_eval expr in
        ok ((name, evaluated) :: list)
      )
      (ok [])
      fields
    in
    ok (EvaluatedObject (pos, List.rev evaluated_fields))
  | RuntimeObject _ ->
    let* (_, evaluated) = interpret Env.empty expr in
    deep_eval evaluated
  | expr ->
    let* (_, evaluated) = interpret Env.empty expr in
    deep_eval evaluated

The deep_eval function guarantees that we have only terminal values before serializing.

The eval function now works with a 2 step interpretation. First the interpret that will evaluate the AST expressions lazily, and the deep_eval that will walk down the AST transforming the variants into terminal variants:

let eval expr =
  let* (_, expr) = interpret Env.empty expr in
  let* expr = deep_eval expr in
  ok expr

Do you know what we can do now? Simplify the JSON rendering!

JSON is finally free from the evaluation bad smell

Look how simple the Json module became -- simple like in the very early stages of Tsonnet:

diff --git a/lib/json.ml b/lib/json.ml
index c8e2159..a40cea6 100644
--- a/lib/json.ml
+++ b/lib/json.ml
@@ -2,15 +2,7 @@ open Ast
 open Result
 open Syntax_sugar

-(* The interpreter type allows us to break the circular dependency
-   between Json and Interpreter modules.
-   Ideally, the Json module does not need to know anything about the
-   previous step.
-   TODO: Json module fuctions should not receive unevaluated values.
-   Guarantee Interpreter generates a new and evaluated AST. *)
-type interpreter = expr Env.Map.t -> expr -> ((expr Env.Map.t * expr), string) result
-
-let rec value_to_yojson ~(eval: interpreter) (env : expr Env.Map.t) (expr : Ast.expr) : (Yojson.t, string) result =
+let rec value_to_yojson (expr : Ast.expr) : (Yojson.t, string) result =
   match expr with
   | Number (_, n) ->
     ok (match n with
@@ -20,31 +12,29 @@ let rec value_to_yojson ~(eval: interpreter) (env : expr Env.Map.t) (expr : Ast.
   | Bool (_, b) -> ok (`Bool b)
   | String (_, s) -> ok (`String s)
   | Array (_, values) ->
-    let expr_to_list expr' = to_list (value_to_yojson ~eval env expr') in
-    let results = values |> List.map expr_to_list |> List.concat in
-    ok (`List results)
-  | RuntimeObject (pos, obj_env, fieldset) -> obj_to_yojson ~eval env (pos, obj_env, fieldset)
-  | expr -> error (Error.Msg.value_not_represetable_as_json (string_of_type expr))
-
-and obj_to_yojson ~(eval: interpreter) _env (pos, obj_env, fieldset) =
-  let* fields =
-    ObjectFields.fold
-      (fun field acc ->
-        let* obj_id = match Env.find_opt "self" obj_env with
-        | Some (Ast.ObjectPtr (obj_id, _)) -> ok obj_id
-        | _ -> error Error.Msg.must_be_object
-        in
-        let* (env', expr) =
-          Env.get_obj_field field obj_id obj_env ~succ:eval ~err:(Error.error_at pos)
-        in
-        let* yo_value = value_to_yojson ~eval env' expr in
-        let* fields = acc in
-        ok ((field, yo_value) :: fields)
+    let* results = List.fold_left
+      (fun acc v ->
+        let* list = acc in
+        let* json = value_to_yojson v in
+        ok (json :: list)
       )
-      fieldset
       (ok [])
-  in ok (`Assoc (List.rev fields))
+      values
+    in
+    ok (`List (List.rev results))
+  | EvaluatedObject (_, fields) ->
+    let* json_fields = List.fold_left
+      (fun acc (name, expr) ->
+        let* list = acc in
+        let* json = value_to_yojson expr in
+        ok ((name, json) :: list)
+      )
+      (ok [])
+      fields
+    in
+    ok (`Assoc (List.rev json_fields))
+  | expr -> error (Error.Msg.value_not_represetable_as_json (string_of_type expr))

-let expr_to_string ~(eval: interpreter) (env, expr) =
-  let yojson = value_to_yojson ~eval env expr
+let expr_to_string expr =
+  let yojson = value_to_yojson expr
   in Result.map Yojson.pretty_to_string yojson

It doesn't need to care about how expr is interpreted anymore -- single responsibility:

diff --git a/lib/tsonnet.ml b/lib/tsonnet.ml
index 6913295..d142c9e 100644
--- a/lib/tsonnet.ml
+++ b/lib/tsonnet.ml
@@ -23,4 +23,4 @@ let run (config : Config.t) (filename: string) : (string, string) result =
     >>= Ast.debug config
     >>= Type.check config
     >>= Interpreter.eval
-    >>= Json.expr_to_string ~eval:Interpreter.interpret
+    >>= Json.expr_to_string

Conclusion

The EvaluatedObject variant did a lot of heavy lifting here. By drawing a clear line between terminal and intermediate AST variants, we were able to push the responsibility for evaluation squarely back onto the interpreter, simplify semantic_equal into something I'm no longer embarrassed to look at, and let the Json module be blissfully ignorant of how things got evaluated. That TODO comment in the previous post aged well — sometimes the cleanest solutions come from just letting a problem sleep on it.

The entire diff can be seen here.

Thanks for reading Bit Maybe Wise! Subscribe to follow along as I convince OCaml's type system to do my job for me.

Photo by JESHOOTS.COM on Unsplash

ABEND dump #25

Hercules Lemke Merscher — Sat, 28 Feb 2026 18:14:27 +0000

Welcome to the ABEND dump #25!

Don't know what is an “ABEND dump”?! I'm glad you asked.

You can check the previous ABEND dump here:

Hercules Lemke Merscher

Dec 31 '25

ABEND dump #24

#abenddump

Comments

3 min read

Everybody is talking about AI lately, so inevitably I'd share the drama in the ABEND dump eventually, and here we are.

Sam Altman (OpenAI) and Dario Amodei (Anthropic) refuse to hold hands

WTF with these guys?! Are they in the first grade yet? ¬¬

Which lead us to...

Claude and Ads

I feel like I'm living in a Black Mirror episode now.

You don't know what I'm talking about? Go watch this:

At least, it is doing work for us, and reducing our burden. Or, isn't it?

AI doesn't reduce work, it intensifies it

While some programmers were freaking out, fearing being replace by AI. Well, now there's some proof that it is not robing us the work, but in fact creating more work for us. Not exactly what we were expecting, right?

Joy & Curiosity #75

And Thorsten's Substack is my favorite source of AI related stuff these days. Like this quote from Chris Lattner:

Lower barriers to implementation do not reduce the importance of engineers; instead, they elevate the importance of vision, judgment, and taste. When creation becomes easier, deciding what is worth creating becomes the harder problem. AI accelerates execution, but meaning, direction, and responsibility remain fundamentally human.

Long live to tasteful software!

Speaking of which...

Stop babysitting your terminal

I can't believe I used opencode all this time without this!

I never played WoW, so I tweaked peonping to have Bender from Futurama telling me things have completed. It's so useful, and so much fun XD

Thanks for reading the ABEND dump! Where the content is curated by a human, for humans, with the occasional Bender GIF. That's a feature, not a bug.

ABEND dump #24

Hercules Lemke Merscher — Wed, 31 Dec 2025 08:00:00 +0000

Welcome to ABEND dump #24!

If you wanna know what is the "ABEND dump", I've got you covered.

You can check the previous ABEND dump here:

Hercules Lemke Merscher

Nov 10 '25

ABEND dump #23

#abenddump

Comments

3 min read

Yeah, I know, I missed the opportunity to release this on Christmas eve. I've been unplugged from the usual tech content treadmill -- less blog reading, less social media doom-scrolling. Turns out playing "Clair Obscur: Expedition 33" and hanging out with family is way more interesting than doomscrolling through yet another AI hot take. Who knew?

This one's lighter than usual, but sometimes that's exactly what we need.

AWS re:Invent 2025 - Keynote with Dr. Werner Vogels

The first 5 minutes of this keynote captures something I've been thinking about the AI trend: we're treating it like it's unprecedented, but software development has always evolved. Remember when everyone said the web would replace desktop apps? Or mobile would kill the web? Or cloud would eliminate sysadmins?

AI-assisted development might seem revolutionary because of the pace, but ultimately it's another tool in the toolbox. People will adapt, integrate it into their workflows, and move on to worrying about the next thing. The hype cycle is exhausting, but the underlying truth remains: good engineering principles outlast trendy tools.

What's new in Ruby 4.0

Ruby turned 30 this Christmas, and as tradition demands, dropped a new version. Ruby 4.0 brings some interesting changes, though honestly, I haven't dug deep enough to have strong opinions yet.

Ruby::Box stands out as potentially game-changing -- it's essentially a way to box values for safe mutation tracking, which could help with some gnarly concurrency patterns. I'm curious to see how the community adopts it. Will it become ubiquitous like blocks and procs, or will it be one of those features that everyone acknowledges is cool but rarely uses?

The official announcement is here if you want the full details.

Advent of Compiler Optimisations

Matt Goldbolt's Advent of Compiler Optimisations is a phenomenal series breaking down compiler quirks and optimizations. Fair warning: I'm still working through it -- my assembly knowledge isn't where I'd like it to be, so some episodes require multiple rewatches.

But that's exactly why it's valuable. Seeing how seemingly innocent code changes can trigger wildly different compiler behaviors is eye-opening. It's the kind of series that makes you question every performance assumption you've ever made.

If you're into compilers, low-level programming, or just enjoy having your mind bent by optimization strategies, this is worth your time.

And, speaking of compilers...

Tsonnet series - Table of contents

I put together an index of all my Tsonnet posts so far. If you've been following along, now you have one place to reference everything. If you haven't, you can skim through and see if anything catches your interest.

Building a compiler from scratch has been educational (and occasionally maddening) side projects I've taken on. The table of contents makes it easier to follow the journey from "what is Tsonnet?" to "oh god, self-referential objects are a nightmare."

Thanks for reading the ABEND dump! May your holidays be free of production incidents and full of whatever brings you joy -- whether that's diving into compiler optimizations or finally beating that video game.

Photo by Thanh Tran on Unsplash

Tsonnet #29 - Making inner references work

Hercules Lemke Merscher — Sat, 13 Dec 2025 10:15:21 +0000

Welcome to the Tsonnet series!

If you're not following along, check out how it all started in the first post of the series.

In the previous post, I added ppx_deriving.show to help debug the AST and centralized configuration:

Hercules Lemke Merscher

Dec 11 '25

Tsonnet #28 - Debugging gets pretty (printed)

#jsonnet #tsonnet #compiler

Comments

6 min read

Time to tackle another piece of the Jsonnet tutorial: inner references. This is the second part of working with object references, and it gets... interesting.

What we're building

Here's the sample file we need to handle:

// samples/tutorials/inner-reference.jsonnet
{
  Martini: {
    local drink = self,
    ingredients: [
      { kind: "Farmer's Gin", qty: 1 },
      {
        kind: 'Dry White Vermouth',
        qty: drink.ingredients[0].qty,
      },
    ],
    garnish: 'Olive',
    served: 'Straight Up',
  },
}

The tricky bit? That local drink = self inside the Martini object. The variable drink holds a reference to the object itself, and then we use it to access drink.ingredients[0].qty. This is self-reference through an intermediate variable.

The expected output (as a cram test):

diff --git a/test/cram/tutorials.t b/test/cram/tutorials.t
index b9c1f6f..9fe544c 100644
--- a/test/cram/tutorials.t
+++ b/test/cram/tutorials.t
@@ -79,3 +79,15 @@
       "served": "Tall"
     }
   }
+
+  $ tsonnet ../../samples/tutorials/inner-reference.jsonnet
+  {
+    "Martini": {
+      "garnish": "Olive",
+      "ingredients": [
+        { "kind": "Farmer's Gin", "qty": 1 },
+        { "kind": "Dry White Vermouth", "qty": 1 }
+      ],
+      "served": "Straight Up"
+    }
+  }

Extending the AST with variable references

We already have Self and TopLevel for object scopes. Now we need a way to reference objects through variables:

@@ -76,6 +76,7 @@ and object_entry =
 and object_scope =
   | Self
   | TopLevel
+  | ObjVarRef of string
 [@@deriving show]

 let dummy_expr = Unit

Objects also need their own environment. Before, we were storing just an env_id in RuntimeObject, but now we need the full environment to properly resolve these variable references:

@@ -62,7 +62,7 @@ type expr =
   | Ident of position * string
   | Array of position * expr list
   | ParsedObject of position * object_entry list
-  | RuntimeObject of position * (Env.env_id [@opaque]) * ObjectFields.t
+  | RuntimeObject of position * (expr Env.Map.t [@opaque]) * ObjectFields.t
   | ObjectPtr of (Env.env_id [@opaque]) * object_scope
   | ObjectFieldAccess of position * object_scope * expr list
   | BinOp of position * bin_op * expr * expr
@@ -109,9 +111,8 @@ let rec string_of_type = function
   | ParsedObject (_, fields) ->
     Printf.sprintf "PlainObject{%s}"
       (String.concat ", " (List.map string_of_object_entry fields))
-  | RuntimeObject (_, (Env.EnvId id), fields) ->
-    Printf.sprintf "obj<%d>{%s}" id
-      (String.concat ", " (ObjectFields.to_list fields))
+  | RuntimeObject (_, _env, fields) ->
+    Printf.sprintf "obj{%s}" (String.concat ", " (ObjectFields.to_list fields))
   | BinOp (_, bin_op, _, _) ->
     let prefix = "Binary Operation" in
     let bin_op = match bin_op with

Wrestling with the parser

The parser changes are where things get hairy. We need to handle three cases:

self.field or $.field (with optional chains)
drink.field (variable reference requiring at least one field access)
drink[expr] (variable reference with bracket notation)

The second case is crucial for interpreting the inner reference sample file.

Here's the updated grammar:

diff --git a/lib/parser.mly b/lib/parser.mly
index 9d4ca52..6a5b704 100644
--- a/lib/parser.mly
+++ b/lib/parser.mly
@@ -103,38 +103,38 @@ obj_field_list:
   ;

 obj_field_expr:
-  | DOT; e = indexed_expr { e }
+  | DOT; LEFT_SQR_BRACKET; e = assignable_expr; RIGHT_SQR_BRACKET { e }
   | DOT; id = identifier { id }
   ;

+obj_field_chain_item:
+  | e = obj_field_expr { e }
+  | LEFT_SQR_BRACKET; e = assignable_expr; RIGHT_SQR_BRACKET { e }
+  ;
+
 obj_field_chain:
   | { [] }
-  | id = obj_field_expr; ids = obj_field_chain { id :: ids }
+  | id = obj_field_chain_item; ids = obj_field_chain { id :: ids }
+  ;
+
+obj_field_chain_nonempty:
+  | id = obj_field_chain_item { [id] }
+  | id = obj_field_chain_item; ids = obj_field_chain_nonempty { id :: ids }
   ;

 obj_scope:
   | SELF { Self }
   | TOP_LEVEL_OBJ { TopLevel }
+  | id = ID { ObjVarRef id }
   ;

 obj_field_access:
-  | scope = obj_scope; chain = obj_field_chain { ObjectFieldAccess (with_pos $startpos $endpos, scope, chain) }
-  (* The first bracketed expr when accessing an object field
-     must be explicitly declared here, instead of being part
-     of `object_field_expr`.
-
-     Adding the bracketed expr there will make the grammar unclear
-     since Menhir will need to decide between parsing one of the options:
-     1) .identifier
-     2) .identifier[expr]
-
-     By tying to the scope, such as $[expr], the grammar is now clear
-     and Menhir doesn't need to decide on its own.
-  *)
-  | scope = obj_scope;
-    LEFT_SQR_BRACKET; e = assignable_expr; RIGHT_SQR_BRACKET;
-    chain = obj_field_chain
-    { ObjectFieldAccess (with_pos $startpos $endpos, scope, e :: chain) }
+  (* For self and $, allow empty chain *)
+  | SELF; chain = obj_field_chain { ObjectFieldAccess (with_pos $startpos $endpos, Self, chain) }
+  | TOP_LEVEL_OBJ; chain = obj_field_chain { ObjectFieldAccess (with_pos $startpos $endpos, TopLevel, chain) }
+  (* For ID-based scope, only match if there's a dot (obj_field_expr) or multiple bracket accesses *)
+  | id = ID; field = obj_field_expr; chain = obj_field_chain { ObjectFieldAccess (with_pos $startpos $endpos, ObjVarRef id, field :: chain) }
+  | id = ID; LEFT_SQR_BRACKET; e = assignable_expr; RIGHT_SQR_BRACKET; rest = obj_field_chain_nonempty { ObjectFieldAccess (with_pos $startpos $endpos, ObjVarRef id, e :: rest) }
   ;

 %inline number:

The comments in the original code explain it well, but the key insight is: we need separate rules for self/$ (which can stand alone or have chains) versus variable references (which must have at least one field access to be meaningful).

If you're fuzzy on shift/reduce conflicts, I wrote about debugging them here.

Scope validation

The Scope module needs a small update to handle ObjVarRef:

diff --git a/lib/scope.ml b/lib/scope.ml
index 8846f39..ecbf17c 100644
--- a/lib/scope.ml
+++ b/lib/scope.ml
@@ -103,14 +103,19 @@ and validate_object_field_access pos scope context =
     local x = self.field;
     local x = $.field;
     outside of objects *)
-  if not context.in_object
-  then
-    let with_error_msg = match scope with
-                        | Self -> Error.Msg.self_out_of_scope
-                        | TopLevel -> Error.Msg.no_toplevel_object
-    in
-    Error.trace with_error_msg pos >>= error
-  else ok ()
+  match scope with
+  | Self | TopLevel ->
+    if not context.in_object then
+      let with_error_msg = match scope with
+        | Self -> Error.Msg.self_out_of_scope
+        | TopLevel -> Error.Msg.no_toplevel_object
+        | ObjVarRef _ -> "" (* unreachable *)
+      in
+      Error.trace with_error_msg pos >>= error
+    else ok ()
+  | ObjVarRef _ ->
+    (* Variable references are allowed anywhere *)
+    ok ()

 and validate_locals vars context =
   (* This is crucial - it catches: local x = self.field; outside objects *)

Variable references don't have the same scoping restrictions as self and $ -- they're just regular identifiers that happen to point to objects.

Before we proceed to the relevant part

The interpreter went through a more than trivial refactoring.

The interpret_concat_op moved below to be part of the recursive definition of interpret:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index 77b3ac2..ca33fd6 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -21,17 +21,6 @@ let interpret_arith_op (op: bin_op) (n1: number) (n2: number) =
   | Divide, (Int a), (Float b) -> Float ((float_of_int a) /. b)
   | Divide, (Float a), (Float b) -> Float (a /. b)

-let interpret_concat_op env (e1 : expr) (e2 : expr) : (expr, string) result =
-  match e1, e2 with
-  | String (_, s1), String (_, s2) ->
-    ok (String (dummy_pos, s1^s2))
-  | String (_, s1), val2 ->
-    let* s2 = Json.expr_to_string (env, val2) in ok (String (dummy_pos, s1^s2))
-  | val1, String (_, s2) ->
-    let* s1 = Json.expr_to_string (env, val1) in ok (String (dummy_pos, s1^s2))
-  | _ ->
-    error Error.Msg.interp_invalid_concat
-

The same has been done with interpret_local and interpret_seq -- it's cleaner to read now:

 let interpret_unary_op (op: unary_op) (evaluated_expr: expr) =
   match op, evaluated_expr with
   | Plus, number -> ok number
@@ -48,6 +37,7 @@ let rec interpret env expr =
   | Array (pos, exprs) -> interpret_array env (pos, exprs)
   | ParsedObject (pos, entries) -> interpret_object env (pos, entries)
   | RuntimeObject _ as runtime_obj -> ok (env, runtime_obj)
+  | ObjectPtr _ as obj_ptr -> ok (env, obj_ptr)
   | ObjectFieldAccess (pos, scope, chain) -> interpret_object_field_access env (pos, scope, chain)
   | Ident (pos, varname) ->
     Env.find_var varname env
@@ -70,16 +60,9 @@ let rec interpret env expr =
     Result.fold (interpret_unary_op op expr')
       ~ok:(fun expr' -> ok (env', expr'))
       ~error:(Error.error_at pos)
-  | Local (_, vars) ->
-    let acc_fun env (varname, expr) = Env.add_local varname expr env in
-    let env' = List.fold_left acc_fun env vars
-    in ok (env', Unit)
+  | Local (_, vars) -> interpret_local env vars
   | Unit -> ok (env, Unit)
-  | Seq exprs ->
-    (match exprs with
-    | [] -> ok (env, Unit)
-    | [expr] -> interpret env expr
-    | (expr :: exprs) -> interpret env expr >>= fun (env', _) -> interpret env' (Seq exprs))
+  | Seq exprs -> interpret_seq env exprs
   | IndexedExpr (pos, varname, index_expr) ->
     let* (env', index_expr') = interpret env index_expr in
     Env.find_var varname env'
@@ -90,8 +73,17 @@ let rec interpret env expr =
           ~error:(Error.error_at pos)
       )
       ~err:(Error.error_at pos)
-    | expr ->
-      error (Error.Msg.interp_cannot_interpret (string_of_type expr))

The only difference in interpret_concat_op is the new eval parameter passed to Json.expr_to_string -- we'll come to it in a bit:

+
+and interpret_concat_op env (e1 : expr) (e2 : expr) : (expr, string) result =
+    match e1, e2 with
+    | String (_, s1), String (_, s2) ->
+      ok (String (dummy_pos, s1^s2))
+    | String (_, s1), val2 ->
+      let* s2 = Json.expr_to_string ~eval:interpret (env, val2) in ok (String (dummy_pos, s1^s2))
+    | val1, String (_, s2) ->
+      let* s1 = Json.expr_to_string ~eval:interpret (env, val1) in ok (String (dummy_pos, s1^s2))
+    | _ ->
+      error Error.Msg.interp_invalid_concat

 and interpret_array env (pos, exprs) =
   let* (env', evaluated_exprs) = List.fold_left
@@ -104,14 +96,44 @@ and interpret_array env (pos, exprs) =
     exprs
   in ok (env', Array (pos, evaluated_exprs))

And interpret_seq did not change a thing, it's just wrapped in its own function now:

+and interpret_seq env exprs =
+  match exprs with
+  | [] -> ok (env, Unit)
+  | [expr] -> interpret env expr
+  | (expr :: exprs') ->
+    interpret env expr >>= fun (env', _) ->
+    interpret env' (Seq exprs')
+

Lazy evaluation arrives

This is where the interpreter changes get substantial. Up until now, we were eagerly evaluating in multiple parts of the code. But with inner references, we need proper lazy evaluation to avoid infinite loops.

Consider this pathological case:

{
  local drink = self,
  x: drink.x
}

If we evaluate drink.x eagerly, we'd recurse infinitely. The solution is to only evaluate object fields when they're actually accessed.

Here's the new interpret_local:

and interpret_local env vars =
  let* env' =
    List.fold_left
      (fun acc (varname, expr) ->
        let* env = acc in
        match expr with
        | ObjectFieldAccess (_, (Self | TopLevel), []) ->
          (* Eagerly evaluate unchained self/$ references to capture the current object.
            AST example:
            (Ast.Local (3:3, [("drink", (Ast.ObjectFieldAccess (3:3, Ast.Self, [])))])));
          *)
          let* (env', evaluated_expr) = interpret env expr in
          ok (Env.add_local varname evaluated_expr env')
        | _ ->
          (* Other expressions remain lazy *)
          ok (Env.add_local varname expr env)
      )
      (ok env)
      vars
  in ok (env', Unit)

The exception is self and $ with no field chain -- we need to evaluate those immediately to capture the concrete object ID. For everything else, we store the unevaluated expression.

I'm pretty sure there's some edge cases hiding in this part as we progress in the implementation, but this is enough to make the current tests to pass--baby steps is my mantra.

Simplifying object interpretation

The interpret_object function actually got simpler:

 and interpret_object env (pos, entries) =
   let* obj_id = Env.Id.generate () in
-  let had_toplevel = Option.is_some (Env.find_opt "$" env) in
-  let self_expr = ObjectPtr (obj_id, Self) in
-  let env' = Env.add_local "self" self_expr env in
-  let env', toplevel_expr = Env.add_local_when_not_present "$" (ObjectPtr (obj_id, TopLevel)) env' in
+  let obj_env = Env.add_local "self" (ObjectPtr (obj_id, Self)) env in
+  let obj_env, _ = Env.add_local_when_not_present "$" (ObjectPtr (obj_id, TopLevel)) obj_env in
+
   (* First add locals and object fields to env *)
-  let* (env', fields) = List.fold_left
+  let* (obj_env, fields) = List.fold_left
     (fun result entry ->
       let* (env', fields) = result in
       match entry with
@@ -120,80 +142,87 @@ and interpret_object env (pos, entries) =
           it will add the expr to the environment *)
         let* (env', _) = interpret env' expr in ok (env', fields)
       | ObjectField (name, expr) ->
+        (* Object fields are kept lazy -- they will be evaluated only when accessed.
+           This prevents infinite loops from circular references. *)
         let env' = Env.add_obj_field name expr obj_id env' in
         ok (env', ObjectFields.add name fields)
     )
-    (ok (env', ObjectFields.empty))
+    (ok (obj_env, ObjectFields.empty))
     entries
   in
-  (* Then interpret object fields after env is populated *)
-  let* env' = ObjectFields.fold
-    (fun field acc ->
-      let* env' = acc in
-      let* (env', _expr) =
-        Env.get_obj_field field obj_id env'
-          ~succ:(interpret)
-          ~err:(Error.error_at pos)
-      in
-      (* self is removed by object evaluation, for this reason
-         we re-add self and $ to env' on each iteration here *)
-      let env' = Env.add_local "self" self_expr env' in
-      let env' = Env.add_local "$" toplevel_expr env' in
-      ok env'
-    )
-    fields
-    (ok env')
-  in
-
-  (* Remove self and $ from the resulting environment.
-     Posterior interpretations shouldn't have references to them. *)
-  let env' = Env.Map.remove "self" env' in
-  let env' = if had_toplevel then env' else Env.Map.remove "$" env' in
-
-  ok (env', RuntimeObject (pos, obj_id, fields))
+  (* We return env unchanged. RuntimeObject holds its own scoped env. *)
+  ok (env, RuntimeObject (pos, obj_env, fields))

Instead of evaluating all fields immediately and carefully removing self and $ references afterward, we just keep the object's environment inside RuntimeObject. Much cleaner!

The complexity moved to interpret_object_field_access, which now handles the actual evaluation when fields are accessed.

The gnarly field access logic

This function got... lengthy. The core challenge is handling three different types of scopes:

 and interpret_object_field_access env (pos, scope, chain_exprs) =
-  let* obj =
-    match Env.find_opt (string_of_object_scope scope) env with
-    | Some (ObjectPtr _ as obj) -> ok obj
-    | _ ->
-      Error.error_at pos
-        (match scope with
-        | Self -> Error.Msg.self_out_of_scope
-        | TopLevel -> Error.Msg.no_toplevel_object)
+  let* (env', obj) =
+    (* Special case: if this is just `self` or `$` with no field chain,
+     return the ObjectPtr directly. This ensures that when stored in variables,
+     they capture the concrete object ID, not a dynamic scope reference. *)
+    match scope with
+    | Self | TopLevel ->
+      (* For self and $, look them up as scopes in the environment *)
+      (match Env.find_opt (string_of_object_scope scope) env with
+      | Some (ObjectPtr _ as obj) -> ok (env, obj)
+      | Some (RuntimeObject _ as obj) -> ok (env, obj)
+      | _ ->
+        Error.error_at pos
+          (match scope with
+          | Self -> Error.Msg.self_out_of_scope
+          | TopLevel -> Error.Msg.no_toplevel_object
+          | ObjVarRef _ -> Error.Msg.var_not_found "" (* unreachable -- should never happen, TODO: make this unrepresentable *)
+          )
+      )
+    | ObjVarRef varname ->
+      (* For variable references, look up and evaluate the variable *)
+      let* (env', expr) =
+        Env.find_var varname env ~succ:(interpret) ~err:(Error.error_at pos)
+      in
+      match expr with
+      | ObjectPtr (obj_id, (Self | TopLevel)) ->
+        (* If the variable holds a Self/TopLevel reference, the obj_id
+           already captures which object it refers to. We don't need to
+           re-resolve Self/TopLevel in the current environment. *)
+        ok (env', ObjectPtr (obj_id, ObjVarRef varname))
+      | ObjectPtr _ as obj -> ok (env', obj)
+      | RuntimeObject _ as obj -> ok (env', obj)
+      | _ -> Error.error_at pos Error.Msg.must_be_object
   in
+

The tricky part is when a variable holds a Self or TopLevel reference -- we need to preserve the object ID that was captured when the variable was bound, not re-resolve it in the current environment.

Processing the chain involves lazily evaluating fields:

   List.fold_left
     (fun acc field_expr ->
       let* (env', prev_expr) = acc in
       let get_obj_id =
         match prev_expr with
-        | ObjectPtr (obj_id, _) -> ok obj_id
-        | RuntimeObject (_, obj_id, _) -> ok obj_id
+        | ObjectPtr (obj_id, _) ->
+          (* Temporarily add self and $ to env for lazy field evaluation *)
+          let field_env = Env.add_local "self" (ObjectPtr (obj_id, Self)) env' in
+          let field_env = Env.add_local_when_not_present "$" (ObjectPtr (obj_id, TopLevel)) field_env |> fst in
+          ok (obj_id, field_env)
+        | RuntimeObject (_, obj_env, _) ->
+          (match Env.find_opt "self" obj_env with
+          | Some (ObjectPtr (obj_id, _)) -> ok (obj_id, obj_env)
+          | _ -> error Error.Msg.must_be_object
+          )
         | _ -> Error.error_at pos Error.Msg.must_be_object
       in

       match field_expr with
       | String (pos, field) | Ident (pos, field) ->
-        let* obj_id = get_obj_id in
-        Env.get_obj_field field obj_id env'
+        let* (obj_id, field_env) = get_obj_id in
+        Env.get_obj_field field obj_id field_env
           ~succ:(interpret)
           ~err:(Error.error_at pos)
-      | IndexedExpr (pos, field, index_expr) ->
-        let* obj_id = get_obj_id in
-        let* (env', index_expr') = interpret env' index_expr in
-        let* (env', indexable_expr) =
-          Env.get_obj_field field obj_id env'
-            ~succ:(interpret)
-            ~err:(Error.error_at pos)
-        in
-          Result.fold
-            (Indexable.get index_expr' indexable_expr)
-            ~ok:(fun e -> interpret env' e)
-            ~error:(Error.error_at pos)
+      | Number _ as index_expr ->
+        (* Handle array/string indexing: prev_expr[number] *)
+        Result.fold
+          (Indexable.get index_expr prev_expr)
+          ~ok:(fun e -> ok (env', e))
+          ~error:(Error.error_at pos)
       | _e ->
         Error.error_at pos Error.Msg.interp_invalid_lookup
     )
-    (ok (env, obj))
+    (ok (env', obj))
     chain_exprs

 let eval expr = interpret Env.empty expr

This code needs to be simplified to avoid unreachable cases, such as the ObjVarRef. By leveraging the type system, we can encode this in the types, but this would require a big refactoring. The comments explaining the reason are trade-offs that I accept for the time being.

I also had to change how the bracketed expressions were being interpreted. This part got simpler and became more readable.

Breaking circular dependencies

The Json module now needs to actually interpret expressions, which creates a circular dependency. The quick fix is to pass the interpreter function as a parameter:

diff --git a/lib/json.ml b/lib/json.ml
index 57a3be6..c8e2159 100644
--- a/lib/json.ml
+++ b/lib/json.ml
@@ -2,7 +2,15 @@ open Ast
 open Result
 open Syntax_sugar

-let rec value_to_yojson (env : expr Env.Map.t) (expr : Ast.expr) : (Yojson.t, string) result =
+(* The interpreter type allows us to break the circular dependency
+   between Json and Interpreter modules.
+   Ideally, the Json module does not need to know anything about the
+   previous step.
+   TODO: Json module fuctions should not receive unevaluated values.
+   Guarantee Interpreter generates a new and evaluated AST. *)
+type interpreter = expr Env.Map.t -> expr -> ((expr Env.Map.t * expr), string) result
+
+let rec value_to_yojson ~(eval: interpreter) (env : expr Env.Map.t) (expr : Ast.expr) : (Yojson.t, string) result =
   match expr with
   | Number (_, n) ->
     ok (match n with
@@ -12,22 +20,24 @@ let rec value_to_yojson (env : expr Env.Map.t) (expr : Ast.expr) : (Yojson.t, st
   | Bool (_, b) -> ok (`Bool b)
   | String (_, s) -> ok (`String s)
   | Array (_, values) ->
-    let expr_to_list expr' = to_list (value_to_yojson env expr') in
+    let expr_to_list expr' = to_list (value_to_yojson ~eval env expr') in
     let results = values |> List.map expr_to_list |> List.concat in
     ok (`List results)
-  | RuntimeObject (pos, context, fieldset) -> obj_to_yojson env (pos, context, fieldset)
-  | expr -> error ("value type not representable as JSON: " ^ string_of_type expr)
+  | RuntimeObject (pos, obj_env, fieldset) -> obj_to_yojson ~eval env (pos, obj_env, fieldset)
+  | expr -> error (Error.Msg.value_not_represetable_as_json (string_of_type expr))

-and obj_to_yojson env (pos, obj_id, fieldset) =
+and obj_to_yojson ~(eval: interpreter) _env (pos, obj_env, fieldset) =
   let* fields =
     ObjectFields.fold
       (fun field acc ->
-        let* (_, expr) =
-          Env.get_obj_field field obj_id env
-            ~succ:(fun _ expr -> ok (env, expr))
-            ~err:(Error.error_at pos)
+        let* obj_id = match Env.find_opt "self" obj_env with
+        | Some (Ast.ObjectPtr (obj_id, _)) -> ok obj_id
+        | _ -> error Error.Msg.must_be_object
+        in
+        let* (env', expr) =
+          Env.get_obj_field field obj_id obj_env ~succ:eval ~err:(Error.error_at pos)
         in
-        let* yo_value = value_to_yojson env expr in
+        let* yo_value = value_to_yojson ~eval env' expr in
         let* fields = acc in
         ok ((field, yo_value) :: fields)
       )
@@ -35,6 +45,6 @@ and obj_to_yojson env (pos, obj_id, fieldset) =
       (ok [])
   in ok (`Assoc (List.rev fields))

-let expr_to_string (env, expr) =
-  let yojson = value_to_yojson env expr
+let expr_to_string ~(eval: interpreter) (env, expr) =
+  let yojson = value_to_yojson ~eval env expr
   in Result.map Yojson.pretty_to_string yojson

diff --git a/lib/tsonnet.ml b/lib/tsonnet.ml
index d142c9e..6913295 100644
--- a/lib/tsonnet.ml
+++ b/lib/tsonnet.ml
@@ -23,4 +23,4 @@ let run (config : Config.t) (filename: string) : (string, string) result =
     >>= Ast.debug config
     >>= Type.check config
     >>= Interpreter.eval
-    >>= Json.expr_to_string
+    >>= Json.expr_to_string ~eval:Interpreter.interpret

This isn't ideal -- the Json module shouldn't need to know about interpretation. Ideally, we'd have separate AST types for each compiler phase, with the JSON serializer only receiving fully-evaluated expressions. But that's a big refactoring, and for now this works.

Type checker follows suit

The type checker needs similar changes to track variable references:

diff --git a/lib/type.ml b/lib/type.ml
index 390313f..6334c27 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -264,14 +264,30 @@ and translate_object venv pos entries =
   ok (venv, TruntimeObject (obj_id, entry_types))

 and translate_object_field_access venv pos scope chain_exprs =
-  let* obj =
-    match Env.find_opt (string_of_object_scope scope) venv with
-    | Some (TobjectPtr _ as obj) -> ok obj
-    | _ ->
-      Error.error_at pos
-        (match scope with
-        | Self -> Error.Msg.self_out_of_scope
-        | TopLevel -> Error.Msg.no_toplevel_object)
+  let* (venv, obj) =
+    match scope with
+    | Self | TopLevel ->
+      (* For self and $, look them up directly *)
+      (match Env.find_opt (string_of_object_scope scope) venv with
+      | Some (TobjectPtr _ as obj) -> ok (venv, obj)
+      | _ ->
+        Error.error_at pos
+          (match scope with
+          | Self -> Error.Msg.self_out_of_scope
+          | TopLevel -> Error.Msg.no_toplevel_object
+          | ObjVarRef _ -> "" (* unreachable *)
+          )
+      )
+    | ObjVarRef varname ->
+      (* For variable references, look up and translate the variable *)
+      Env.find_var varname venv
+        ~succ:(fun venv ty ->
+          match ty with
+          | TobjectPtr _ | TruntimeObject _ as obj -> ok (venv, obj)
+          | Lazy expr -> translate venv expr
+          | _ -> Error.error_at pos Error.Msg.must_be_object
+        )
+        ~err:(Error.error_at pos)
   in

   List.fold_left
@@ -291,23 +307,12 @@ and translate_object_field_access venv pos scope chain_exprs =
         Env.get_obj_field field obj_id venv
           ~succ:translate_lazy
           ~err:(Error.error_at pos)
-      | IndexedExpr (pos, field, index_expr) ->
-        let* (venv', index_expr_ty) = translate venv index_expr in
-        let* () =
-          match index_expr_ty with
-          | Tnumber | Tstring -> ok ()
-          | ty -> Error.error_at pos (Error.Msg.type_non_indexable_type (to_string ty))
-        in
-        let* obj_id = get_obj_id in
-        let* (venv', ty) =
-          Env.get_obj_field field obj_id venv'
-            ~succ:translate_lazy
-            ~err:(Error.error_at pos)
-        in
-        (match ty with
-        | (Tarray _) as array_ty -> ok (venv', array_ty)
-        | Tstring as ty -> ok (venv', ty)
-        | _ -> Error.error_at pos (Error.Msg.type_non_indexable_field field)
+      | Number (pos, _) ->
+        (* Handle numeric indexing of strings and arrays *)
+        (match prev_ty with
+        | Tstring -> ok (venv, Tstring)
+        | Tarray elem_ty -> ok (venv, elem_ty)
+        | _ -> Error.error_at pos (Error.Msg.type_non_indexable_type (to_string prev_ty))
         )
       | _ ->
         Error.error_at pos (Error.Msg.type_invalid_lookup_key (string_of_type field_expr))

The field chain processing also simplifies since we don't need the IndexedExpr case anymore -- bracket notation is now just numeric indexing.

Taming more error messages

Found a couple more error messages that needed centralization:

diff --git a/lib/error.ml b/lib/error.ml
index cdbbada..b518608 100644
--- a/lib/error.ml
+++ b/lib/error.ml
@@ -10,6 +10,7 @@ module Msg = struct
   (* Shared operation messages *)
   let self_out_of_scope = "Can't use self outside of an object"
   let no_toplevel_object = "No top-level object found"
+  let var_not_found varname = varname ^ " not found"
   let invalid_binary_op = "Invalid binary operation"
   let invalid_unary_op = "Invalid unary operation"
   let must_be_object = "Must be an object"
@@ -31,6 +32,9 @@ module Msg = struct
   let interp_invalid_concat = "Invalid string concatenation operation"
   let interp_invalid_lookup = "Invalid object lookup"
   let interp_cannot_interpret expr = Printf.sprintf "Expression %s cannot be interpreted" expr
+
+  (* Others messages *)
+  let value_not_represetable_as_json value = "value type not representable as JSON: " ^ value
 end

 let enumerate_error_lines filename position ~highlight_error =
diff --git a/lib/error.mli b/lib/error.mli
index 365af96..58d7e8e 100644
--- a/lib/error.mli
+++ b/lib/error.mli
@@ -5,6 +5,7 @@ module Msg : sig
   (* Scope-related messages *)
   val self_out_of_scope : string
   val no_toplevel_object : string
+  val var_not_found : string -> string

   (* Shared operation messages *)
   val invalid_binary_op : string
@@ -28,6 +29,9 @@ module Msg : sig
   val interp_invalid_concat : string
   val interp_invalid_lookup : string
   val interp_cannot_interpret : string -> string
+
+  (* Other messages *)
+  val value_not_represetable_as_json : string -> string
 end

 val trace : string -> Ast.position -> (string, string) result

And voilà

$ dune exec -- tsonnet samples/tutorials/inner-reference.jsonnet
{
  "Martini": {
    "garnish": "Olive",
    "ingredients": [
      { "kind": "Farmer's Gin", "qty": 1 },
      { "kind": "Dry White Vermouth", "qty": 1 }
    ],
    "served": "Straight Up"
  }
}

Conclusion

Inner references required introducing proper lazy evaluation for objects, which turned out to be a bigger change than I expected. The interpreter now properly handles self-references through variables, and objects carry their own environments.

There are definitely some rough edges -- the unreachable cases in pattern matches, the circular dependency between Json and Interpreter, the lengthy field access function. These are all candidates for future refactoring, but they're manageable trade-offs for now. The tests pass, and that's what matters.

The entire diff can be seen here.

Thanks for reading Bit Maybe Wise! Subscribe for more compiler complexity that's definitely not a circular dependency (it totally is).

Photo by Didssph on Unsplash