Forem: Hercules Lemke Merscher

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

Tsonnet #28 - Debugging gets pretty (printed)

Hercules Lemke Merscher — Thu, 11 Dec 2025 11:06:52 +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 reorganized function parameters and centralized error messages for consistency:

Hercules Lemke Merscher

Nov 3 '25

Tsonnet #27 - Consistency, consistency, consistency

#tsonnet #jsonnet #compiler

Comments

8 min read

The project is getting more complex and not having an option to debug the AST is becoming cumbersome. We'll quickly explore how to improve this.

deriving show

Sometimes we want to see a data type in the console in its raw form. We could implement a function to do that ourselves, but it's repetitive and boring. Enter ppx_deriving.show:

diff --git a/lib/dune b/lib/dune
index 75a7340..22e9961 100644
--- a/lib/dune
+++ b/lib/dune
@@ -4,7 +4,7 @@
   (backend bisect_ppx))
  (libraries yojson)
  (preprocess
-  (pps ppx_deriving_qcheck)))
+  (pps ppx_deriving.show ppx_deriving_qcheck)))

 (menhir
  (modules parser))

This saves you from manually writing boilerplate code to convert your types to strings.

Then we annotate the expr and other types, and it automatically generates the show and pp (pretty-printer) functions:

diff --git a/lib/ast.ml b/lib/ast.ml
index f7964a8..58c4439 100644
--- a/lib/ast.ml
+++ b/lib/ast.ml
@@ -5,25 +5,33 @@ type bin_op =
   | Subtract
   | Multiply
   | Divide
-  [@@deriving qcheck]
+  [@@deriving qcheck, show]

 type unary_op =
   | Plus
   | Minus
   | Not
   | BitwiseNot
-  [@@deriving qcheck]
+  [@@deriving qcheck, show]

 type number =
   | Int of int
   | Float of float
-  [@@deriving qcheck]
+  [@@deriving qcheck, show]

 type position = {
   startpos: Lexing.position;
   endpos: Lexing.position;
 }

+let pp_position fmt pos =
+  Format.fprintf fmt "%d:%d"
+    pos.startpos.pos_lnum
+    pos.endpos.pos_lnum
+
+let show_position pos =
+  Format.asprintf "%a" pp_position pos
+
 let dummy_pos = {
   startpos = Lexing.dummy_pos;
   endpos = Lexing.dummy_pos;
@@ -34,7 +42,16 @@ module StringSet = struct
   let compare = String.compare
 end

-module ObjectFields = Set.Make(StringSet)
+module ObjectFields = struct
+  include Set.Make(StringSet)
+
+  let pp fmt s =
+    Format.fprintf fmt "{%s}"
+      (String.concat ", " (to_list s))
+
+  let show s =
+    Format.asprintf "%a" pp s
+end

 type expr =
   | Unit
@@ -45,8 +62,8 @@ type expr =
   | Ident of position * string
   | Array of position * expr list
   | ParsedObject of position * object_entry list
-  | RuntimeObject of position * Env.env_id * ObjectFields.t
-  | ObjectPtr of Env.env_id * object_scope
+  | RuntimeObject of position * (Env.env_id [@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
   | UnaryOp of position * unary_op * expr
@@ -59,9 +76,15 @@ and object_entry =
 and object_scope =
   | Self
   | TopLevel
+[@@deriving show]

 let dummy_expr = Unit

+let debug (config : Config.t) (ast : expr) : (expr, string) result =
+  if config.debug_ast then
+    prerr_endline (show_expr ast);
+  Result.ok ast
+
 let pos_from_lexbuf (lexbuf : Lexing.lexbuf) : position =
   { startpos = lexbuf.lex_curr_p;
     endpos = lexbuf.lex_curr_p;

As you might have noticed, we can customize the functions for specific types. Neat!

This is required for our next step: printing the AST.

--debug-ast

We start by adding a new parameter:

diff --git a/bin/main.ml b/bin/main.ml
index e51d36b..64cf7b8 100644
--- a/bin/main.ml
+++ b/bin/main.ml
@@ -1,13 +1,17 @@
 let usage_msg = "tsonnet <file1> [<file2>] ..."
 let input_files = ref []
 let skip_typecheck = ref false
+let debug_ast = ref false
 let anonymous_fun filename = input_files := filename :: !input_files
 let spec_list = [
   ("--skip-typecheck", Arg.Set skip_typecheck, "Skip type checking step");
+  ("--debug-ast", Arg.Set debug_ast, "Print abstract syntax tree");
 ]

 let run_parser filename =
-  match Tsonnet.run ~skip_typecheck:!skip_typecheck filename with
+  let open Tsonnet in
+  let config = Config.make ~skip_typecheck:!skip_typecheck ~debug_ast:!debug_ast () in
+  match run config filename with
   | Ok stringified_json -> print_endline stringified_json
   | Error err -> prerr_endline err; exit 1

Instead of passing multiple options to the library, let's condense the configuration parameters in a Config module.

It has this interface:

type t = {
  skip_typecheck : bool;
  debug_ast : bool;
}

val default : t
val make : ?skip_typecheck:bool -> ?debug_ast:bool -> unit -> t

And this concrete implementation:

type t = {
  skip_typecheck : bool;
  debug_ast : bool;
}

let default = {
  skip_typecheck = false;
  debug_ast = false;
}

let make ?(skip_typecheck = false) ?(debug_ast = false) () = {
  skip_typecheck;
  debug_ast;
}

Now every function call has a clean config record to rely on:

diff --git a/lib/tsonnet.ml b/lib/tsonnet.ml
index 614b5ed..d142c9e 100644
--- a/lib/tsonnet.ml
+++ b/lib/tsonnet.ml
@@ -1,6 +1,8 @@
 open Result
 open Syntax_sugar

+module Config = Config
+
 (** [parse s] parses [s] into an AST. *)
 let parse (filename: string) =
   let input = open_in filename in
@@ -10,16 +12,15 @@ let parse (filename: string) =
     try ok (Parser.prog Lexer.read lexbuf)
     with
     | Lexer.SyntaxError err -> (Error.trace err (Ast.pos_from_lexbuf lexbuf)) >>= error
-    | Parser.Error -> (Error.trace "Invalid syntax" (Ast.pos_from_lexbuf lexbuf)) >>= error
-    | Failure err -> Error.trace ("Invalid token error: " ^ err) (Ast.pos_from_lexbuf lexbuf) >>= error
+    | Parser.Error -> (Error.trace Error.Msg.parse_error (Ast.pos_from_lexbuf lexbuf)) >>= error
+    | Failure err -> Error.trace (Error.Msg.parse_invalid_token err) (Ast.pos_from_lexbuf lexbuf) >>= error
   in
   close_in input;
   result

-let run ?(skip_typecheck = false) (filename: string) : (string, string) result =
-  if skip_typecheck then
-    prerr_endline "Warning: Type checking is skipped. This is not recommended as it may lead to runtime errors.\n";
+let run (config : Config.t) (filename: string) : (string, string) result =
   parse filename
-    >>= (if skip_typecheck then ok else Type.check)
+    >>= Ast.debug config
+    >>= Type.check config
     >>= Interpreter.eval
     >>= Json.expr_to_string
diff --git a/lib/type.ml b/lib/type.ml
index f1f30af..390313f 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -315,10 +315,12 @@ and translate_object_field_access venv pos scope chain_exprs =
     (ok (venv, obj))
     chain_exprs

-let check expr =
-  Scope.validate expr
-  >>= fun _ -> translate Env.empty expr
-  >>= fun _ ->
+let check (config : Config.t) expr  =
+  let* _ = Scope.validate expr in
+  if config.skip_typecheck then
+    (prerr_endline Error.Msg.warn_skip_typecheck;
+    ok expr)
+  else
+    let* _ = translate Env.empty expr in
     Env.Id.reset ();
     ok expr

As always, cram tests FTW--they function as automated tests with a nice touch of documentation:

diff --git a/bin/help.t b/bin/help.t
index dcf8e30..ebdd411 100644
--- a/bin/help.t
+++ b/bin/help.t
@@ -3,6 +3,7 @@ Display help message with -help flag:
   $ tsonnet -help
   tsonnet <file1> [<file2>] ...
     --skip-typecheck Skip type checking step
+    --debug-ast Print abstract syntax tree
     -help  Display this list of options
     --help  Display this list of options

@@ -11,6 +12,7 @@ Display help message with --help flag:
   $ tsonnet --help
   tsonnet <file1> [<file2>] ...
     --skip-typecheck Skip type checking step
+    --debug-ast Print abstract syntax tree
     -help  Display this list of options
     --help  Display this list of options

@@ -27,3 +29,45 @@ Run with type checking skipped using long flag:
   Warning: Type checking is skipped. This is not recommended as it may lead to runtime errors.

   42
+
+Testing the --debug-ast flag:
+
+Run with AST debugging enabled:
+
+  $ tsonnet --debug-ast ../samples/literals/object.jsonnet
+  (Ast.ParsedObject (1:8,
+     [(Ast.ObjectField ("int_attr", (Ast.Number (2:2, (Ast.Int 1)))));
+       (Ast.ObjectField ("float_attr", (Ast.Number (3:3, (Ast.Float 4.2)))));
+       (Ast.ObjectField ("string_attr", (Ast.String (4:4, "Hello, world!"))));
+       (Ast.ObjectField ("null_attr", (Ast.Null 5:5)));
+       (Ast.ObjectField ("array_attr",
+          (Ast.Array (6:6,
+             [(Ast.Number (6:6, (Ast.Int 1))); (Ast.Bool (6:6, false));
+               (Ast.ParsedObject (6:6, []))]
+             ))
+          ));
+       (Ast.ObjectField ("obj_attr",
+          (Ast.ParsedObject (7:7,
+             [(Ast.ObjectField ("a", (Ast.Bool (7:7, true))));
+               (Ast.ObjectField ("b", (Ast.Bool (7:7, false))));
+               (Ast.ObjectField ("c",
+                  (Ast.ParsedObject (7:7,
+                     [(Ast.ObjectField ("d",
+                         (Ast.Array (7:7, [(Ast.Number (7:7, (Ast.Int 42)))]))
+                         ))
+                       ]
+                     ))
+                  ))
+               ]
+             ))
+          ))
+       ]
+     ))
+  {
+    "array_attr": [ 1, false, {} ],
+    "float_attr": 4.2,
+    "int_attr": 1,
+    "null_attr": null,
+    "obj_attr": { "a": true, "b": false, "c": { "d": [ 42 ] } },
+    "string_attr": "Hello, world!"
+  }

Error messages

Some leftovers -- untamed error messages from previous changes:

diff --git a/lib/error.ml b/lib/error.ml
index e48ed89..cdbbada 100644
--- a/lib/error.ml
+++ b/lib/error.ml
@@ -3,6 +3,10 @@ open Result
 open Syntax_sugar

 module Msg = struct
+  (* Parameters configuration *)
+  let warn_skip_typecheck = "Warning: Type checking is skipped. This is not recommended as it may lead to runtime errors.\n"
+
+
   (* 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"
@@ -10,6 +14,10 @@ module Msg = struct
   let invalid_unary_op = "Invalid unary operation"
   let must_be_object = "Must be an object"

+  (* Parser messages *)
+  let parse_error = "Parsing error. Invalid syntax:"
+  let parse_invalid_token err = "Invalid token error: " ^ err
+
   (* Type checker messages *)
   let type_cyclic_reference varname = "Cyclic reference found for " ^ varname
   let type_non_indexable_value ty = ty ^ " is a non indexable value"
diff --git a/lib/error.mli b/lib/error.mli
index ddeb318..365af96 100644
--- a/lib/error.mli
+++ b/lib/error.mli
@@ -1,4 +1,7 @@
 module Msg : sig
+  (* Parameters configuration *)
+  val warn_skip_typecheck : string
+
   (* Scope-related messages *)
   val self_out_of_scope : string
   val no_toplevel_object : string
@@ -8,6 +11,10 @@ module Msg : sig
   val invalid_unary_op : string
   val must_be_object : string

+  (* Parser messages *)
+  val parse_error : string
+  val parse_invalid_token : string -> string
+
   (* Type checker messages *)
   val type_cyclic_reference : string -> string
   val type_non_indexable_value : string -> string

diff --git a/test/cram/errors.t b/test/cram/errors.t
index b70b266..7c117b8 100644
--- a/test/cram/errors.t
+++ b/test/cram/errors.t
@@ -45,7 +45,7 @@
   [1]

   $ tsonnet ../../samples/errors/unscoped_local.jsonnet
-  ../../samples/errors/unscoped_local.jsonnet:1:15 Invalid syntax
+  ../../samples/errors/unscoped_local.jsonnet:1:15 Parsing error. Invalid syntax:

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

Conclusion

With ppx_deriving.show and a new --debug-ast flag, debugging Tsonnet just got a whole lot easier. And consolidating configuration into a Config module keeps the API clean as more options get added.

The error message cleanup was long overdue. Having all error strings centralized in Error.Msg makes them easier to maintain and ensures consistency between the parser, type checker, and interpreter. One less thing to worry about when adding new features!

The entire diff can be seen here.

Thanks for reading Bit Maybe Wise! Subscribe to see what else I can get the compiler to write for me.

Photo by Timothy Dykes on Unsplash

ABEND dump #23

Hercules Lemke Merscher — Mon, 10 Nov 2025 21:56:52 +0000

Welcome to the ABEND dump #23.

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

Sep 24 '25

ABEND dump #22

#news #abenddump

Comments

2 min read

It's been a while since I sat down to curate another dump, but here we are: book reading philosophy, browser trust issues, career pendulums, and space BBQ. The usual eclectic mix that somehow makes sense (or probably not) when you're done reading. Let's go!

On reading books

If you don't enjoy it, don't do it.

I tend to agree. BUT, and there's a reason for it being a big "BUT" here, you must try hard when you're reading to acquire knowledge before dropping the book, and potentially returning to it later if you failed in the first try.

You can totally drop difficult and boring books if you're reading just for fun or curiosity, and I'd be the first one saying "don't do it". For knowledge acquisition, I'd stick to it a bit more, unless there's a better alternative available.

Gergely on AI browsers

I agree, except that I don't trust any browser with my passwords and credit cards. One more vector to leak important information. No thanks, I pass!

Speaking of which, I've been trying Zen Browser, and it is a refreshing version of Firefox.

Code Complete with Steve McConnell

That's an interesting interview:

I have this classic book on my list to read for a loooong time. Maybe it's about time to finally read it.

The Engineer/Manager Pendulum

This is a nice write-up from Charity Majors, that I like to read once a year and reflect whether I should try management or stay as an individual contributor.

I believe I had the luck of working in places where, in many occasions, I could be a manager of one -- myself. Which is nice. Because I'm not naturally inclined to do managerial work 100% of the time, at least, I don't feel like it full time yet, but still being a manager of one exposes you partially to many things that you should be aware of when coordinating work and expectations.

The Recovering Programmer

I realized I was looking at everything backward, from an implementation point of view, not from the perspective of a finished application, not considering the user first. And I realized that the inherent bitterness and negativity of programming arguments and technical defensiveness on the web were making me bitter and negative. I've consciously tried to rewind, to go back to when programming was a tool for implementing my visions, not its own end.

It's interesting how this thought can be flipped depending on the context and biases you're exposed to. I've definitely seen the lack of UX and software design together more often in the realm of web development, and sometimes caused by myself. The important point, IMO, is to be aware of your current context and do your best to assess the right trade-off -- easier said than done, but we can always get better with practice if we are attentive.

Chinese astronauts had BBQ in space

Ok, we can have BBQ in space. Now we are talking going to Mars XD

Thank you for reading the ABEND dump! Subscribe to Bit Maybe Wise -- there's no risk of prompt injection, just good, interesting, thoughtful, and fun links.

Tsonnet #27 - Consistency, consistency, consistency

Hercules Lemke Merscher — Mon, 03 Nov 2025 09:42:56 +0000

Welcome to the Tsonnet series!

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

In the previous post, I added comprehensive testing for object interpretation to prevent reference leaks:

Hercules Lemke Merscher

Oct 29 '25

Tsonnet #26 - Chain me maybe, part 2

#tsonnet #jsonnet #compiler

Comments

8 min read

This will be short and sweet post, so let's get to it.

When I first wrote the type checking function, I made an innocent mistake by having the environment parameter in a different order in the translate function compared to the interpreter. It's not a big deal, but consistency is important!

diff --git a/lib/type.ml b/lib/type.ml
index 99f11cc..1ece085 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -111,7 +111,7 @@ and check_object_field_chain_for_cycles venv (pos, scope, exprs) seen =
     (ok ())
     exprs

-let rec translate expr venv =
+let rec translate venv expr =
   match expr with
   | Unit -> ok (venv, Tunit)
   | Null _ -> ok (venv, Tnull)
@@ -122,7 +122,7 @@ let rec translate expr venv =
     Env.find_var varname venv
       ~succ:(fun venv ty ->
         match ty with
-        | Lazy expr -> translate expr venv
+        | Lazy expr -> translate venv expr
         | _ -> ok (venv, ty)
       )
       ~err:(Error.error_at pos)
@@ -168,26 +168,26 @@ let rec translate expr venv =
     in ok (venv', Tunit)
   | Seq exprs ->
     List.fold_left
-      (fun acc expr -> acc >>= fun (venv, _) -> translate expr venv)
+      (fun acc expr -> acc >>= fun (venv, _) -> translate venv expr)
       (ok (venv, Tunit))
       exprs
   | BinOp (pos, op, e1, e2) ->
-    (let* (venv', e1') = translate e1 venv in
-    let* (venv'', e2') = translate e2 venv' in
+    (let* (venv', e1') = translate venv e1 in
+    let* (venv'', e2') = translate venv' e2 in
     match op, e1', e2' with
     | _, Tnumber, Tnumber -> ok (venv'', Tnumber)
     | Add, _, Tstring | Add, Tstring, _ -> ok (venv'', Tstring)
     | _ -> Error.trace "Invalid binary operation" pos >>= error
     )
   | UnaryOp (pos, op, expr) ->
-    (let* (venv', expr') = translate expr venv in
+    (let* (venv', expr') = translate venv expr in
     match op, expr' with
     | Plus, Tnumber | Minus, Tnumber | BitwiseNot, Tnumber -> ok (venv', Tnumber)
     | Not, Tbool | BitwiseNot, Tbool -> ok (venv', Tbool)
     | _ -> Error.trace "Invalid unary operation" pos >>= error
     )
   | IndexedExpr (pos, varname, index_expr) ->
-    (let* (venv', index_expr') = translate index_expr venv in
+    (let* (venv', index_expr') = translate venv index_expr in
     match index_expr' with
     | Tnumber ->
       Env.find_var varname venv'
@@ -195,7 +195,7 @@ let rec translate expr venv =
           match expr' with
           | (Tarray _) as ty -> ok (venv', ty)
           | Tstring as ty -> ok (venv', ty)
-          | Lazy expr -> translate expr venv
+          | Lazy expr -> translate venv expr
           | ty -> error (to_string ty ^ " is a non indexable value")
         )
         ~err:(Error.error_at pos)
@@ -205,7 +205,7 @@ let rec translate expr venv =
     error ("Invalid type " ^ string_of_type expr')

 and translate_lazy venv = function
-  | Lazy expr -> translate expr venv
+  | Lazy expr -> translate venv expr
   | ty -> error ("Invalid type " ^ to_string ty)

 and translate_object venv pos entries =
@@ -222,7 +222,7 @@ and translate_object venv pos entries =
       let* venv = result in
       match entry with
       | ObjectExpr expr ->
-        let* (venv', _) = translate expr venv in (ok venv')
+        let* (venv', _) = translate venv expr in (ok venv')
       | ObjectField (attr, expr) ->
         ok (Env.add_obj_field attr (Lazy expr) obj_id venv)
     )
@@ -292,7 +292,7 @@ and translate_object_field_access venv pos scope chain_exprs =
           ~succ:translate_lazy
           ~err:(Error.error_at pos)
       | IndexedExpr (pos, field, index_expr) ->
-        let* (venv', index_expr_ty) = translate index_expr venv in
+        let* (venv', index_expr_ty) = translate venv index_expr in
         let* () =
           match index_expr_ty with
           | Tnumber | Tstring -> ok ()
@@ -317,7 +317,7 @@ and translate_object_field_access venv pos scope chain_exprs =

 let check expr =
   Scope.validate expr
-  >>= fun _ -> translate expr Env.empty
+  >>= fun _ -> translate Env.empty expr
   >>= fun _ ->
     Env.Id.reset ();
     ok expr

Yeah, I know what you're thinking: "Is this really worth a whole post?". We can argue that this is not a big deal, and in theory, it isn't, but in practice it's much more comfortable to work in a codebase where you get used to the pattern, and even better when they are replicated across multiple modules and functions. It just feels natural! Our brains just stop fighting the code.

Consistency, consistency, consistency!

Speaking of patterns -- this parameter ordering change is actually a small step toward a bigger goal. Eventually, I want to enforce better type checking in-between compiler phases: parsing -> scope validation -> type checking -> interpretation. As of now, we work with the same AST across multiple phases, but it would be nice to have intermediate representations between each step. This could help removing duplicated checks already present, and making invalid states unrepresentable.

But that's a story for another day. Before doing such big refactoring, there's something even more mundane that helps moving towards this goal: extracting error messages.

lib/error.ml:

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 invalid_binary_op = "Invalid binary operation"
  let invalid_unary_op = "Invalid unary operation"
  let must_be_object = "Must be an object"

  (* Type checker messages *)
  let type_cyclic_reference varname = "Cyclic reference found for " ^ 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
  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

  (* Interpreter messages *)
  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
end

See what I mean with the shared operation messages?! Those invalid_binary_op and invalid_unary_op strings appear in both the type checker and interpreter -- operations that should really only happen once, in a single compilation phase.

Now I can replace the hard-coded error messages everywhere:

diff --git a/lib/interpreter.ml b/lib/interpreter.ml
index fe7f1a7..77b3ac2 100644
--- a/lib/interpreter.ml
+++ b/lib/interpreter.ml
@@ -30,7 +30,7 @@ let interpret_concat_op env (e1 : expr) (e2 : expr) : (expr, string) result =
   | val1, String (_, s2) ->
     let* s1 = Json.expr_to_string (env, val1) in ok (String (dummy_pos, s1^s2))
   | _ ->
-    error "Invalid string concatenation operation"
+    error Error.Msg.interp_invalid_concat

 let interpret_unary_op (op: unary_op) (evaluated_expr: expr) =
   match op, evaluated_expr with
@@ -39,7 +39,7 @@ let interpret_unary_op (op: unary_op) (evaluated_expr: expr) =
   | Minus, Number (pos, Float f) -> ok (Number (pos, Float (-. f)))
   | Not, (Bool (pos, b)) -> ok (Bool (pos, not b))
   | BitwiseNot, Number (pos, Int i) -> ok (Number (pos, Int (lnot i)))
-  | _ -> error "Invalid unary operation"
+  | _ -> error Error.Msg.invalid_unary_op

 (** [interpret expr] interprets and reduce the intermediate AST [expr] into a result AST. *)
 let rec interpret env expr =
@@ -63,7 +63,7 @@ let rec interpret env expr =
     | _, Number (pos, v1), Number (_, v2) ->
       ok (env2, Number (pos, interpret_arith_op op v1 v2))
     | _ ->
-      Error.trace "Invalid binary operation" pos >>= error
+      Error.trace Error.Msg.invalid_binary_op pos >>= error
     )
   | UnaryOp (pos, op, expr) ->
     let* (env', expr') = interpret env expr in
@@ -91,7 +91,7 @@ let rec interpret env expr =
       )
       ~err:(Error.error_at pos)
     | expr ->
-      error (Printf.sprintf "Expression %s cannot be interpreted" (string_of_type expr))
+      error (Error.Msg.interp_cannot_interpret (string_of_type expr))

 and interpret_array env (pos, exprs) =
   let* (env', evaluated_exprs) = List.fold_left
@@ -159,8 +159,8 @@ and interpret_object_field_access env (pos, scope, chain_exprs) =
     | _ ->
       Error.error_at pos
         (match scope with
-        | Self -> Scope.self_out_of_scope
-        | TopLevel -> Scope.no_toplevel_object)
+        | Self -> Error.Msg.self_out_of_scope
+        | TopLevel -> Error.Msg.no_toplevel_object)
   in
   List.fold_left
     (fun acc field_expr ->
@@ -169,7 +169,7 @@ and interpret_object_field_access env (pos, scope, chain_exprs) =
         match prev_expr with
         | ObjectPtr (obj_id, _) -> ok obj_id
         | RuntimeObject (_, obj_id, _) -> ok obj_id
-        | _ -> Error.error_at pos "Must be an object"
+        | _ -> Error.error_at pos Error.Msg.must_be_object
       in

       match field_expr with
@@ -191,7 +191,7 @@ and interpret_object_field_access env (pos, scope, chain_exprs) =
             ~ok:(fun e -> interpret env' e)
             ~error:(Error.error_at pos)
       | _e ->
-        Error.error_at pos "Invalid object lookup"
+        Error.error_at pos Error.Msg.interp_invalid_lookup
     )
     (ok (env, obj))
     chain_exprs
diff --git a/lib/scope.ml b/lib/scope.ml
index d61a9c9..8846f39 100644
--- a/lib/scope.ml
+++ b/lib/scope.ml
@@ -12,9 +12,6 @@ type context = {
   current_locals: string list;
 }

-let self_out_of_scope = "Can't use self outside of an object"
-let no_toplevel_object = "No top-level object found"
-
 let empty_context = {
   in_object = false;
   object_depth = 0;
@@ -61,8 +58,8 @@ let rec _validate expr context =

 and validate_ident pos varname context =
   match (varname, context.in_object) with
-  | ("self", false) -> Error.trace self_out_of_scope pos >>= error
-  | ("$", false) -> Error.trace no_toplevel_object pos >>= error
+  | ("self", false) -> Error.trace Error.Msg.self_out_of_scope pos >>= error
+  | ("$", false) -> Error.trace Error.Msg.no_toplevel_object pos >>= error
   | _ -> ok ()

 and validate_expression_list exprs context =
@@ -109,8 +106,8 @@ and validate_object_field_access pos scope context =
   if not context.in_object
   then
     let with_error_msg = match scope with
-                        | Self -> self_out_of_scope
-                        | TopLevel -> no_toplevel_object
+                        | Self -> Error.Msg.self_out_of_scope
+                        | TopLevel -> Error.Msg.no_toplevel_object
     in
     Error.trace with_error_msg pos >>= error
   else ok ()
diff --git a/lib/type.ml b/lib/type.ml
index 1ece085..f1f30af 100644
--- a/lib/type.ml
+++ b/lib/type.ml
@@ -56,7 +56,7 @@ let rec to_string = function
 let rec check_cyclic_refs venv varname seen pos =
   if List.mem varname seen
   then
-    Error.trace ("Cyclic reference found for " ^ varname) pos >>= error
+    Error.trace (Error.Msg.type_cyclic_reference varname) pos >>= error
   else
     match Env.find_opt varname venv with
     | Some (Lazy expr) -> check_expr_for_cycles venv expr (varname :: seen)
@@ -177,14 +177,14 @@ let rec translate venv expr =
     match op, e1', e2' with
     | _, Tnumber, Tnumber -> ok (venv'', Tnumber)
     | Add, _, Tstring | Add, Tstring, _ -> ok (venv'', Tstring)
-    | _ -> Error.trace "Invalid binary operation" pos >>= error
+    | _ -> Error.trace Error.Msg.invalid_binary_op pos >>= error
     )
   | UnaryOp (pos, op, expr) ->
     (let* (venv', expr') = translate venv expr in
     match op, expr' with
     | Plus, Tnumber | Minus, Tnumber | BitwiseNot, Tnumber -> ok (venv', Tnumber)
     | Not, Tbool | BitwiseNot, Tbool -> ok (venv', Tbool)
-    | _ -> Error.trace "Invalid unary operation" pos >>= error
+    | _ -> Error.trace Error.Msg.invalid_unary_op pos >>= error
     )
   | IndexedExpr (pos, varname, index_expr) ->
     (let* (venv', index_expr') = translate venv index_expr in
@@ -196,17 +196,17 @@ let rec translate venv expr =
           | (Tarray _) as ty -> ok (venv', ty)
           | Tstring as ty -> ok (venv', ty)
           | Lazy expr -> translate venv expr
-          | ty -> error (to_string ty ^ " is a non indexable value")
+          | ty -> error (Error.Msg.type_non_indexable_value (to_string ty))
         )
         ~err:(Error.error_at pos)
-    | ty -> Error.trace ("Expected Integer index, got " ^ to_string ty) pos >>= error
+    | ty -> Error.trace (Error.Msg.type_expected_integer_index (to_string ty)) pos >>= error
     )
   | expr' ->
-    error ("Invalid type " ^ string_of_type expr')
+    error (Error.Msg.type_invalid_expr (string_of_type expr'))

 and translate_lazy venv = function
   | Lazy expr -> translate venv expr
-  | ty -> error ("Invalid type " ^ to_string ty)
+  | ty -> error (Error.Msg.type_invalid_expr (to_string ty))

 and translate_object venv pos entries =
   let* obj_id = Env.Id.generate () in
@@ -270,8 +270,8 @@ and translate_object_field_access venv pos scope chain_exprs =
     | _ ->
       Error.error_at pos
         (match scope with
-        | Self -> Scope.self_out_of_scope
-        | TopLevel -> Scope.no_toplevel_object)
+        | Self -> Error.Msg.self_out_of_scope
+        | TopLevel -> Error.Msg.no_toplevel_object)
   in

   List.fold_left
@@ -282,7 +282,7 @@ and translate_object_field_access venv pos scope chain_exprs =
         match prev_ty with
         | TobjectPtr (obj_id, _) -> ok obj_id
         | TruntimeObject (obj_id, _) -> ok obj_id
-        | _ -> Error.error_at pos "Must be an object"
+        | _ -> Error.error_at pos Error.Msg.must_be_object
       in

       match field_expr with
@@ -296,7 +296,7 @@ and translate_object_field_access venv pos scope chain_exprs =
         let* () =
           match index_expr_ty with
           | Tnumber | Tstring -> ok ()
-          | ty -> Error.error_at pos (to_string ty ^ " is a non-indexable type")
+          | 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) =
@@ -307,10 +307,10 @@ and translate_object_field_access venv pos scope chain_exprs =
         (match ty with
         | (Tarray _) as array_ty -> ok (venv', array_ty)
         | Tstring as ty -> ok (venv', ty)
-        | _ -> Error.error_at pos (field ^ " is a non-indexable value")
+        | _ -> Error.error_at pos (Error.Msg.type_non_indexable_field field)
         )
       | _ ->
-        Error.error_at pos ("Invalid object lookup key: " ^ string_of_type field_expr)
+        Error.error_at pos (Error.Msg.type_invalid_lookup_key (string_of_type field_expr))
     )
     (ok (venv, obj))
     chain_exprs

Conclusion

That's all for today! Nothing revolutionary, but these little improvements are making the codebase easier to navigate.

Now let me write down the ideas for a future refactoring.

The entire diff can be seen here.

Thanks for reading Bit Maybe Wise! Subscribe to watch me reorganize function parameters like I'm Marie Kondo-ing the compiler -- does it spark consistency? Then it stays!