to_number in doc topics

.gitignore

@@ -33,3 +33,4 @@ target/repl-port
 .repl-buffer.janet
 .env
 src/jpm_tree
+.zig-cache

README.md

@@ -2,48 +2,37 @@
 ## Ludus: A friendly, dynamic, functional language
 Ludus is a scripting programming language that is designed to be friendly, dynamic, and functional.
 
-This repo currently contains an in-progress reference implementation of an interpreter for the Ludus programming language, using Clojure as a host language.
-
-Ludus is part of the [_Thinking with Computers_ project](https://thinking-with-computers.github.io), run by Scott Richmond at the University of Toronto, with collaborator Matt Nish-Lapidus; Bree Lohman and Mynt Marsellus are the RAs for the project. Ludus is our research language, which aspires to be a free translation of Logo for the 2020s.
+This repo currently contains a work-in-progress implementation of an interpreter for the Ludus programming language, using [Janet](https://janet-lang.org) as a host language.
+Ludus is part of the [_Thinking with Computers_ project](https://alea.ludus.dev/twc/), run by Scott Richmond at the University of Toronto, with collaborator Matt Nish-Lapidus; Bree Lohman and Mynt Marsellus are the RAs for the project. Ludus is our research language, which aspires to be a free translation of Logo for the 2020s.
 
 Here are our design goals:
 
 #### Friendly
-Ludus, like Logo, is meant to be a teaching language, often for students who don't think of themselves as "computer people." Our intended audience are humanities and art people at the University level (undergrads, grads, faculty). Everything is kept as simple as possible, but no simpler. Everything is consistent as possible. We aspire to the best error messages we can muster, which is important for a language to be teachable. That means being as strict as we can muster, _in order to be friendlier_.
+Ludus, like Logo, is meant to be a teaching language, often for students who don't think of themselves as "computer people." Our intended audience are humanities and art people at the university level (undergrads, grads, faculty). Everything is kept as simple as possible, but no simpler. Everything is consistent as possible. We aspire to the best error messages we can muster, which is important for a language to be teachable. That means being as strict as we can muster, _in order to be friendlier_.
 
-Our current development target is Ludus on the web: https://thinking-with-computers/ludus-web. That wires what we do on the langauge interpreter (here in this repo) to a web frontent.
+Our current development target is Ludus on the web: https://web.ludus.dev. That wires what we do on the langauge interpreter (here in this repo) to a web frontend.
 
 Naturally, it starts with Logo's famed turtle graphics.
 
 #### Dynamic
-Statically typed programming languages generally give more helpful error messages than dynamic ones, but learning a type system (even one with robust type inference) requires learning two parallel systems: the type system and the expression system. Type systems only really make sense once you've learned why they're necessary. And their benefits seem (to us, anyway) to be largely necessary when writing long-lived, maintainable, multiauthor code. Ludus code is likely to be one-off, expressive, and single-authored.
+Statically typed programming languages generally give more helpful error messages than dynamic ones, but learning a type system (even one with robust type inference) requires learning two parallel systems: the type system and the expression system (well, and the pattern system). Type systems only really make sense once you've learned why they're necessary. And their benefits seem (to us, anyway) to be largely necessary when writing long-lived, maintainable, multi-author code. Ludus code is likely to be one-off, expressive, and single-authored.
 
 To stay friendly, Ludus is dynamic. But: despite the dynamism, we aim to be as strict as possible. Certainly, we want to avoid the type conversion shenanigans of a language like JavaScript.
 
 #### Functional
 Ludus is emphatically functional: it uses functions for just about everything. This is both because your humble PI had his world reordered when he learned his first functional language (Elixir), and because the research into Logo and the programming cultures of MIT in the 1970s revolve around extremely functional Lisp code (i.e., Scheme). Logo is a weird little language, but it is a descendant of Lisp. So is Ludus.
 
-Also, we believe that Ludus's immutable bindings and persistent or immutable data structures and careful approach to manipulating state lead to a lot of good pedagogical results. Learning a programming language involves learning how to model what's going on inside the computer; Ludus, we think, makes that simpler and easier.
+Also, we believe that Ludus's immutable bindings and persistent or immutable data structures and careful approach to manipulating state lead to a lot of good pedagogical results. Learning a programming language involves learning how to model what's going on inside the computer; Ludus, we think, makes that both simpler and easier.
 
-If you're looking for cognate languages, Ludus takes a _lot_ of design inspiration from Clojure and Elixir (which itself took a lot from Clojure). (The current--quick, dirty, and slow--version of LUdus written in Clojure, in no small part to have access to persistent data structures that compile to JS.) Clojure and Elixir are great! If you're asking why you should use Ludus instead of them, you're already at the point where you should be using them. Ludus is, maybe, for the people whom you'd like to work with in 5 years at your Pheonix shop.
+If you're looking for cognate languages, Ludus takes a _lot_ of design inspiration from Clojure and Elixir (which itself took a lot from Clojure). (The current--quick, dirty, and slow--version of Ludus is written in [Janet](https://janet-lang.org).) Clojure and Elixir are great! If you're asking why you should use Ludus instead of them, you're already at the point where you should be using them. Ludus is, maybe, for the people whom you'd like to work with in 5 years at your Pheonix shop (but even then, probably not).
 
 ### Status
-Pre-alpha, still under active development. Lots of things change all the time. See [the ludus-spec repo for progress notes and additional documentation](https://github.com/thinking-with-computers/ludus-spec/blob/main/todo.md).
+Pre-alpha, still under active development. Lots of things change all the time.
 
-The current version of Ludus is a pure function that runs in JavaScript. We have plans for more and better things.
+The current version of Ludus is a pure function that runs in JavaScript as a WASM blob. We have plans for more and better things.
 
 ### Use
-Current emphasis is on the web version: see https://github.com/thinking-with-computers/ludus-web/.
-
-Or, if you're on a Mac and want to open a terminal:
-* Clone this repo.
-	- `git clone https://github.com/thinking-with-computers/ludus`
-* Have Clojure and Leiningen installed.
-	- On a Mac: `brew install clojure leiningen`
-* `lein run {script}`, it runs your script.
-* `lein run`, it runs a REPL.
-
-~Or, download a binary on the [releases page](https://github.com/thinking-with-computers/ludus/releases). (At current: M1 Mac only.)~
+Current emphasis is on the web version: https://web.ludus.dev.
 
 ### Main features
 * Expression-oriented: everything returns a value
@@ -52,17 +41,14 @@ Or, if you're on a Mac and want to open a terminal:
 * Easy-peasy partial application with placeholders
 * Function pipelines
 * Persistent or immutable data structures
-* Careful, explicit state management using `ref`erences
+* Careful, explicit state management using `box`es
 * Clean, concise, expressive syntax
 * Value-based equality; only functions are reference types
 
 #### Under construction
-* Tail call optimization
-* Actor model style concurrency?
-* ~Strong nominal data typing, including tagged unions~
-	- ~Exhaustiveness-checking in `match` expressions in dynamically-typed code~
-* Faster, bytecode-based VM written in a systems language, compiled to WASM for web use.
-* Recursive descent parser with excellent parsing error message, just as soon as the syntax is fully stabilized.
+* Actor-model style concurrency.
+* Faster, bytecode-based VM written in a systems language, for better performance.
+* Performant persistent, immutable data structures, à la Clojure.
 
 ### `Hello, world!`
 Ludus is a scripting language. At current it does not have a good REPL. Our aim is to get interactive coding absolutely correct, and our efforts in [ludus-web](https://github.com/thinking-with-computers/ludus-web) are currently under way to surface the right interactivity models for Ludus.
@@ -84,7 +70,7 @@ print! ("Hello, world!")
 => :ok
 ```
 
-Or, you can use a the `print!` function, which sends a string to a console (`stdout` on Unix, or a little console box on the web). Because `print!` returns the keyword `:ok` when it completes, that is the result of the last expression in the script--and so Ludus also prints this.
+Here, we use the `print!` function, which sends a string to a console (`stdout` on Unix, or a little console box on the web). Because `print!` returns the keyword `:ok` when it completes, that is the result of the last expression in the script--and so Ludus also prints this.
 
 ### Some code
 Fibonacci numbers:
@@ -104,4 +90,4 @@ fib (10) &=> 55
 ```
 
 ### More on Ludus
-See the [language reference](/language.md) and [the documentation for the prelude](/prelude.md).
+See the [language reference](language.md) and [the documentation for the prelude](prelude.md).

build/driver.cpp

@@ -9,7 +9,6 @@ using std::string;
 
 // set all our exported Janet functions as null pointers
 static JanetFunction *janet_ludus = NULL;
-static JanetFunction *janet_hello = NULL;
 
 // these let us look up functions
 Janet env_lookup(JanetTable *env, const char *name) {
@@ -65,14 +64,6 @@ unsigned char *read_file(const char *filename, size_t *length) {
   return src;
 }
 
-// these are the C++ functions that wrap our Janet functions
-// simplest case: takes nothing, returns nothing
-void hello() {
-  Janet result; // we need a place to put the result
-  // args are: fn ptr, argc, argv, result
-  call_fn(janet_hello, 0, {}, &result);
-}
-
 // finally, getting a string back
 // this is our result type
 struct StringResult {
@@ -123,9 +114,6 @@ int main() {
   // no namespacing
   janet_ludus = env_lookup_function(janet_unwrap_table(env), "ludus");
   janet_gcroot(janet_wrap_function(janet_ludus));
-
-  janet_hello = env_lookup_function(janet_unwrap_table(env), "hello");
-  janet_gcroot(janet_wrap_function(janet_hello));
 }
 
 // these bindings are exported into javascript
@@ -134,7 +122,6 @@ EMSCRIPTEN_BINDINGS(module) {
 
   // these are the functions that will be available
   function("ludus", &ludus, allow_raw_pointers());
-  function("hello", &hello, allow_raw_pointers());
 
   // we also want a wrapper for our StringResult
   // we won't access it directly, but emcc makes it nice

build/justfile

@@ -1,6 +1,4 @@
 build:
-    # compile the janet into an image
-    # janet -c src/ludus.janet build/ludus.jimage
     # the complex emscripten invocation
     # note we have the stack size set to 1024*1024 (1 MB)
     emcc \

build/ludus.mjs

@@ -2,7 +2,369 @@ import init from "./out.mjs"
 
 const mod = await init()
 
+let res = null
+
+let code = null
+
 export function run (source) {
-  const result = mod.ludus(source).value
-  return JSON.parse(result)
+  code = source
+  const output = mod.ludus(source).value
+  res = JSON.parse(output)
+  return res
 }
+
+export function stdout () {
+  if (!res) return ""
+  return res.io.stdout.data
+}
+
+export function turtle_commands () {
+  if (!res) return []
+  return res.io.turtle.data
+}
+
+export function result () {
+  return res
+}
+
+const turtle_init = {
+  position: [0, 0],
+  heading: 0,
+  pendown: true,
+  pencolor: "white",
+  penwidth: 1,
+  visible: true
+}
+
+const colors = {
+	black: [0, 0, 0, 255],
+	silver: [192, 192, 192, 255],
+	gray: [128, 128, 128, 255],
+	white: [255, 255, 255, 255],
+	maroon: [128, 0, 0, 255],
+	red: [255, 0, 0, 255],
+	purple: [128, 0, 128, 255],
+	fuchsia: [255, 0, 255, 255],
+	green: [0, 128, 0, 255],
+	lime: [0, 255, 0, 255],
+	olive: [128, 128, 0, 255],
+	yellow: [255, 255, 0, 255],
+	navy: [0, 0, 128, 255],
+	blue: [0, 0, 255, 255],
+	teal: [0, 128, 128, 255],
+	aqua: [0, 255, 25, 255],
+}
+
+function resolve_color (color) {
+  if (typeof color === 'string') return colors[color]
+  if (typeof color === 'number') return [color, color, color, 255]
+  if (Array.isArray(color)) return color
+  return [0, 0, 0, 255] // default to black?
+}
+
+let background_color = "black"
+
+function add (v1, v2) {
+  const [x1, y1] = v1
+  const [x2, y2] = v2
+  return [x1 + x2, y1 + y2]
+}
+
+function mult (vector, scalar) {
+  const [x, y] = vector
+  return [x * scalar, y * scalar]
+}
+
+function unit_of (heading) {
+  const turns = -heading + 0.25
+  const radians = turn_to_rad(turns)
+  return [Math.cos(radians), Math.sin(radians)]
+}
+
+function command_to_state (prev_state, curr_command) {
+  const verb = curr_command[0]
+  switch (verb) {
+    case "goto": {
+      const [_, x, y] = curr_command
+      return {...prev_state, position: [x, y]}
+    }
+    case "home": {
+      return {...prev_state, position: [0, 0], heading: 0}
+    }
+    case "right": {
+      const [_, angle] = curr_command
+      const {heading} = prev_state
+      return {...prev_state, heading: heading + angle}
+    }
+    case "left": {
+      const [_, angle] = curr_command
+      const {heading} = prev_state
+      return {...prev_state, heading: heading - angle}
+    }
+    case "forward": {
+      const [_, steps] = curr_command
+      const {heading, position} = prev_state
+      const unit = unit_of(heading)
+      const move = mult(unit, steps)
+      return {...prev_state, position: add(position, move)}
+    }
+    case "back": {
+      const [_, steps] = curr_command
+      const {heading, position} = prev_state
+      const unit = unit_of(heading)
+      const move = mult(unit, -steps)
+      return {...prev_state, position: add(position, move)}
+    }
+    case "penup": {
+      return {...prev_state, pendown: false}
+    }
+    case "pendown": {
+      return {...prev_state, pendown: true}
+    }
+    case "penwidth": {
+      const [_, width] = curr_command
+      return {...prev_state, penwidth: width}
+    }
+    case "pencolor": {
+      const [_, color] = curr_command
+      return {...prev_state, pencolor: color}
+    }
+    case "setheading": {
+      const [_, heading] = curr_command
+      return {...prev_state, heading: heading}
+    }
+    case "loadstate": {
+      // console.log("LOADSTATE: ", curr_command)
+      const [_, [x, y], heading, visible, pendown, penwidth, pencolor] = curr_command
+      return {position: [x, y], heading, visible, pendown, penwidth, pencolor}
+    }
+    case "show": {
+      return {...prev_state, visible: true}
+    }
+    case "hide": {
+      return {...prev_state, visible: false}
+    }
+    case "background": {
+      background_color = curr_command[1]
+      return prev_state
+    }
+  }
+}
+
+function eq_vect (v1, v2) {
+  const [x1, y1] = v1
+  const [x2, y2] = v2
+  return (x1 === x2) && (y1 === y2)
+}
+
+function eq_color (c1, c2) {
+  if (c1 === c2) return true
+  const res1 = resolve_color(c1)
+  const res2 = resolve_color(c2)
+  for (let i = 0; i < res1.length; ++i) {
+    if (res1[i] !== res2[i]) return false
+  }
+  return true
+}
+
+function states_to_call (prev, curr) {
+  const calls = []
+  // whose state should we use?
+  // pen states will only differ on more than one property
+  // if we use `loadstate`
+  // my sense is `prev`, but that may change
+  if (prev.pendown && !eq_vect(prev.position, curr.position)) {
+    calls.push(["line", prev.position[0], prev.position[1], curr.position[0], curr.position[1]])
+  }
+  if (!eq_color(curr.pencolor, prev.pencolor)) {
+    calls.push(["stroke", ...resolve_color(curr.pencolor)])
+  }
+  if (curr.penwidth !== prev.penwidth) {
+    calls.push(["strokeWeight", curr.penwidth])
+  }
+  return calls
+}
+
+const turtle_radius = 20
+
+const turtle_angle = 0.385
+
+const turtle_color = [255, 255, 255, 150]
+
+const p5_call_root = [
+  ["background", ...resolve_color(background_color)],
+  ["push"],
+  ["rotate", Math.PI],
+  ["scale", -1, 1],
+  ["stroke", ...resolve_color(turtle_init.pencolor)],
+]
+
+function rotate (vector, heading) {
+  const radians = turn_to_rad(heading)
+  const [x, y] = vector
+  return [
+    (x * Math.cos (radians)) - (y * Math.sin (radians)),
+    (x * Math.sin (radians)) + (y * Math.cos (radians))
+  ]
+}
+
+function turn_to_rad (heading) {
+  return (heading % 1) * 2 * Math.PI
+}
+
+function turn_to_deg (heading) {
+  return (heading % 1) * 360
+}
+
+function svg_render_line (prev, curr) {
+  if (!prev.pendown) return ""
+  if (eq_vect(prev.position, curr.position)) return ""
+  const {position: [x1, y1], pencolor, penwidth} = prev
+  const {position: [x2, y2]} = curr
+  const [r, g, b, a] = resolve_color(pencolor)
+  return `
+    <line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" stroke="rgb(${r} ${g} ${b})" stroke-opacity="${a/255}" stroke-width="${penwidth}"/>
+    `
+}
+
+function escape_svg (svg) {
+  return svg
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;")
+}
+
+export function extract_ludus (svg) {
+  const code = svg.split("<ludus>")[1]?.split("</ludus>")[0] ?? ""
+  return code 
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, `"`)
+    .replace(/&apos;/g, `'`)
+}
+
+function svg_render_path (states) {
+  const path = []
+  for (let i = 1; i < states.length; ++i) {
+    const prev = states[i - 1]
+    const curr = states[i]
+    path.push(svg_render_line(prev, curr))
+  }
+  return path.join("")
+}
+
+function svg_render_turtle (state) {
+  if (!state.visible) return ""
+  const [fr, fg, fb, fa] = turtle_color
+  const fill_alpha = fa/255
+  const {heading, pencolor, position: [x, y], pendown, penwidth} = state
+  const origin = [0, turtle_radius]
+  const [x1, y1] = origin
+  const [x2, y2] = rotate(origin, turtle_angle)
+  const [x3, y3] = rotate(origin, -turtle_angle)
+  const [pr, pg, pb, pa] = resolve_color(pencolor)
+  const pen_alpha = pa/255
+  const ink = pendown ? `<line x1="${x1}" y1="${y1}" x2="0" y2="0" stroke="rgb(${pr} ${pg} ${pb})" stroke-opacity="${pen_alpha}" stroke-width="${penwidth}" />` : ""
+  return `
+    <g transform="translate(${x}, ${y})rotate(${-turn_to_deg(heading)})">
+      <polygon points="${x1} ${y1} ${x2} ${y2} ${x3} ${y3}" stroke="none" fill="rgb(${fr} ${fg} ${fb})" fill-opacity="${fill_alpha}"/>
+      ${ink}
+    </g>
+    `
+}
+
+export function svg (commands) {
+  // console.log(commands)
+  const states = [turtle_init]
+  commands.reduce((prev_state, command) => {
+    const new_state = command_to_state(prev_state, command)
+    states.push(new_state)
+    return new_state
+  }, turtle_init)
+  // console.log(states)
+  const {maxX, maxY, minX, minY} = states.reduce((accum, {position: [x, y]}) => {
+    accum.maxX = Math.max(accum.maxX, x)
+    accum.maxY = Math.max(accum.maxY, y)
+    accum.minX = Math.min(accum.minX, x)
+    accum.minY = Math.min(accum.minY, y)
+    return accum
+    
+  }, {maxX: 0, maxY: 0, minX: 0, minY: 0})
+  const [r, g, b, a] = resolve_color(background_color)
+  const view_width = (maxX - minX) * 1.2
+  const view_height = (maxY - minY) * 1.2
+  const margin = Math.max(view_width, view_height) * 0.1
+  const x1 = minX - margin
+  // don't actually need these:
+  // const y1 = minY - margin
+  // const x2 = maxX + margin
+  const y2 = maxY + margin
+  const path = svg_render_path(states)
+  const turtle = svg_render_turtle(states[states.length - 1])
+  return `<?xml version="1.0" standalone="no"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" style="background-color:rgb(${r} ${g} ${b}); background-opacity: ${a/255}" viewBox="${x1} ${-y2} ${view_width} ${view_height}">
+
+  <g transform="scale(-1, 1) rotate(180)">
+    ${path}
+    ${turtle}
+  </g>
+
+<ludus>
+${escape_svg(code)}
+</ludus>
+</svg>
+  `
+}
+
+function p5_render_turtle (state, calls) {
+  if (!state.visible) return
+  calls.push(["push"])
+  const [r, g, b, a] = turtle_color
+  calls.push(["fill", r, g, b, a])
+  const {heading, pencolor, position: [x, y], pendown, penwidth} = state
+  const origin = [0, turtle_radius]
+  const [x1, y1] = origin
+  const [x2, y2] = rotate(origin, turtle_angle)
+  const [x3, y3] = rotate(origin, -turtle_angle)
+  calls.push(["translate", x, y])
+  // need negative turtle rotation with the other p5 translations
+  calls.push(["rotate", -turn_to_rad(heading)])
+  calls.push(["noStroke"])
+  calls.push(["beginShape"])
+  calls.push(["vertex", x1, y1])
+  calls.push(["vertex", x2, y2])
+  calls.push(["vertex", x3, y3])
+  calls.push(["endShape"])
+  calls.push(["strokeWeight", penwidth])
+  calls.push(["stroke", ...resolve_color(pencolor)])
+  if (pendown) calls.push(["line", 0, 0, x1, y1])
+  calls.push(["pop"])
+  return calls
+}
+
+export function p5 (commands) {
+  const states = [turtle_init]
+  commands.reduce((prev_state, command) => {
+    const new_state = command_to_state(prev_state, command)
+    states.push(new_state)
+    return new_state
+  }, turtle_init)
+  // console.log(states)
+  const p5_calls = [...p5_call_root]
+  for (let i = 1; i < states.length; ++i) {
+    const prev = states[i - 1]
+    const curr = states[i]
+    const calls = states_to_call(prev, curr)
+    for (const call of calls) {
+      p5_calls.push(call)
+    }
+  }
+  p5_calls[0] = ["background", ...resolve_color(background_color)]
+  p5_render_turtle(states[states.length - 1], p5_calls)
+  p5_calls.push(["pop"])
+  return p5_calls
+}
+

build/out.mjs

@@ -6489,7 +6489,7 @@ var __emscripten_stack_alloc = (a0) => (__emscripten_stack_alloc = wasmExports['
 var _emscripten_stack_get_current = () => (_emscripten_stack_get_current = wasmExports['emscripten_stack_get_current'])();
 var ___cxa_is_pointer_type = createExportWrapper('__cxa_is_pointer_type', 1);
 var dynCall_jiji = Module['dynCall_jiji'] = createExportWrapper('dynCall_jiji', 5);
-var ___emscripten_embedded_file_data = Module['___emscripten_embedded_file_data'] = 1783292;
+var ___emscripten_embedded_file_data = Module['___emscripten_embedded_file_data'] = 1819972;
 function invoke_i(index) {
   var sp = stackSave();
   try {

build/p5_test.mjs

@@ -0,0 +1,13 @@
+import {run, p5} from "./ludus.mjs"
+
+const code = `
+print! ("Hello, world!")
+pencolor! (colors :white)
+fd! (50)
+pw! (3)
+`
+
+const result = run(code)
+
+console.log(result.io.stdout.data)
+console.log(p5(result.io.turtle.data))

build/svg_test.mjs

@@ -0,0 +1,22 @@
+import {run, svg, stdout} from "./ludus.mjs"
+
+const code = `
+let start = unbox (turtle_state)
+fd! (100)
+rt! (0.25)
+fd! (100) 
+
+loadstate! (start)
+& home! ()
+
+rt! (0.25)
+fd! (100)
+lt! (0.25)
+
+`
+
+const result = run(code)
+
+// console.log(stdout(result))
+
+console.log(svg(result.io.turtle.data))

build/svg_test.svg

@@ -0,0 +1,37 @@
+<?xml version="1.0" standalone="no"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" style="background-color:rgb(0 0 0); background-opacity: 1" viewBox="-12 -112 120 120">
+
+  <g transform="scale(-1, 1) rotate(180)">
+    
+    <line x1="0" y1="0" x2="6.123233995736766e-15" y2="100" stroke="rgb(255 255 255)" stroke-opacity="1" stroke-width="1"/>
+    
+    <line x1="6.123233995736766e-15" y1="100" x2="0" y2="0" stroke="rgb(255 255 255)" stroke-opacity="1" stroke-width="1"/>
+    
+    <line x1="0" y1="0" x2="100" y2="0" stroke="rgb(255 255 255)" stroke-opacity="1" stroke-width="1"/>
+    
+    
+    <g transform="translate(100, 0)rotate(90)">
+      <polygon points="0 20 -13.226237306473037 -15.00222139260919 13.226237306473037 -15.00222139260919" stroke="none" fill="rgb(255 255 255)" fill-opacity="0.5882352941176471"/>
+      <line x1="0" y1="20" x2="0" y2="0" stroke="rgb(255 255 255)" stroke-opacity="1" stroke-width="1" />
+    </g>
+    
+  </g>
+
+<ludus>
+
+
+let home = unbox (turtle_state)
+
+fd! (100)
+
+loadstate! (home)
+
+rt! (0.25)
+fd! (100)
+
+do turtle_state &gt; unbox
+
+
+</ludus>
+</svg>
+  

build/test.mjs

@@ -1,11 +1,9 @@
-console.log("Starting wasm test run.")
+import {run} from "./ludus.mjs"
 
-import init from "./out.mjs"
+console.log(run(`
 
-console.log("Imported module")
+forward! (100)
+right! (0.25)
+print! ("foobar")
     
-const mod = await init()
-
-console.log("Initted module")
-
-console.log(mod.ludus(":hello_from_ludus").value)
+`))

doc/intro.md

@@ -1,3 +0,0 @@
-# Introduction to cludus
-
-TODO: write [great documentation](http://jacobian.org/writing/what-to-write/)

justfile

@@ -3,6 +3,7 @@ repl:
 	kitten @ launch --type=os-window --allow-remote-control --cwd=current --title=hx_repl:ludus --keep-focus
 	kitten @ send-text -m "title:hx_repl:ludus" "janet -s\n"
 
+# restart the repl server
 restart:
 	kitten @ send-text -m "title:hx_repl:ludus" "\04"
 	kitten @ send-text -m "title:hx_repl:ludus" "janet -s\n"
@@ -11,10 +12,20 @@ restart:
 eval:
 	sd "$" "\n" | sd "\n\n" "\n" | kitten @ send-text -m "title:hx_repl:ludus" --stdin
 
-# send what's selected to a buffer, and then evaluate what's in the buffer
-buffer:
-	sd "$" "\n" | sd "\n\n" "\n" > .repl-buffer.janet
-	kitten @ send-text -m "title:hx_repl:ludus" "(import ./.repl-buffer :prefix \"\")"
-
+# get documentation for a symbol in janet/clojure
 doc:
 	sd "$" "\n" | sd "\n\n" "\n" | xargs -I _ echo "(doc " _ ")" | kitten @ send-text -m "title:hx_repl:ludus" --stdin
+
+# publish to npm (did you build things first?)
+publish:
+	npm version patch
+	npm publish
+
+# build the ludus jimage
+build:
+	rm -f build/out.mjs
+	rm -f build/out.wasm
+	rm -f build/ludus.jimage
+	janet -c src/ludus.janet build/ludus.jimage
+	cd build && just build
+	git commit -am "build"

language.md

@@ -1,6 +1,6 @@
 # Ludus language reference
 
-This is not intended for beginners, but to be a language overview for experienced users. That said, it may help beginners orient themselves in the language.
+This is not intended for beginners, but to be a language overview for experienced programmers. That said, it may help beginners orient themselves in the language.
 
 ## Comments
 Ludus's comment character is `&`. Anything after an ampersand on a line is ignored. There are no multiline comments.
@@ -9,15 +9,15 @@ Ludus's comment character is `&`. Anything after an ampersand on a line is ignor
 Ludus has four types of atomic values.
 
 ### `nil`
-`nil` is Ludus's representation of nothing. In the grand Lisp tradition, Ludus can, and frequently does, use `nil`-punning. Its type is `:nil`.
+`nil` is Ludus's representation of nothing. In the grand Lisp tradition, Ludus can, and occasionally does, use `nil`-punning. Its type is `:nil`.
 
 ### Booleans
 `true` and `false`. That said, in all conditional constructs, `nil` and `false` are "falsy," and everything else is "truthy." Their type is `:boolean`.
 
 ### Numbers
-Ludus has numbers. At current, they rely on underlying number types. When Ludus runs in the browser, numbers are Javascript 64-bit floats. When Ludus runs at the command line in JVM-based Clojure, Ludus numbers could be ints, floats, or ratios, depending. Numbers are more complicated than you think.
+Ludus has numbers, which are IEEE-754 64-bit floats. Numbers are more complicated than you think, probably.
 
-Number literals in Ludus are either integers or decimal floating point numbers. 
+Number literals in Ludus are either integers or decimal floating point numbers, e.g. `32.34`, `42`, `-0.23`. Underscores in numbers are ignored, and can be used to separate long numbers, e.g. `1_234_567_890`.
 
 Numbers' type is `:number`.
 
@@ -27,21 +27,42 @@ Ludus keywords begin with a colon and a letter, e.g. `:keyword`. Types are repre
 Keywords must begin with an ASCII upper- or lower-case letter, and can then include any letter character, as well as `_`, `/`, `!`, `?`, and `*`.
 
 ## Strings
-Ludus strings are dependent on the host platform. Given that Ludus either runs in Javascript or the JVM, strings are UTF-16 strings. Eventually, Ludus will use UTF-8 strings. Strings are much more complicated than you think. Strings are emphatically not a collection type.
+Ludus strings are UTF-8 strings, and only use double quotes. Strings may be multiline. For example, this is a string: `"foo"`. So is this:
+
+```
+"foo
+
+
+bar baz"
+```
+Strings use backslashes for escapes, including `\n` for newline, `\t` for tab, `\"` for a double quote, and `\{` for an open curly brace (see below on interpolation).
 
 Strings' type is `:string`.
 
-## Collections
-Ludus has a few different types of collections, in increasing order of complexity: tuples, lists, sets, dicts, and namespaces.
+### String interpolation
+Strings may also insert a string representation of any Ludus value that is bound to a name, by inserting that name in curly braces. To wit,
+```
+let foo = :foo
+let bar = 42
+let baz = [1, 2, 3]
+"{foo} {bar} {baz}" &=> ":foo 42 1, 2, 3"
+```
+Interpolations may _not_ be arbitrary expressions: only bound names may be used in interpolations.
 
-### Separators
+## Collections
+Ludus has a few different types of collections, in increasing order of complexity: tuples, lists, sets, dicts, and packages. All collections are immutable.
+
+#### Separators
 In all collection literals, members are written with a separator between them. On the same line, use a comma; or a newline will also separate elements. You may use as many separators as you wish at any point inside a collection or pattern. `(,,,,,,,3,,4,,,,,,)` and `(3, 4)` are the same value.
 
+#### Efficiency
+At the current moment, Ludus collections are all copy-on-write; this means that Ludus is _not_ performant with large collections. Eventually, Ludus will have Clojure-style persistent, immutable collections.
+
 ### Tuples
 Tuples are fully-immutable, ordered collections of any kinds of values, delimited by parentheses, e.g. `(1, :a, "foo")`. At current, they have no length limit (although they eventually will). Unlike in some languages, tuples can be empty or contain a single element: `()` and `(:foo)` are both just fine. Tuples largely cannot be manipulated functionally; they must be written as literals and unpacked using pattern matching. They can, however, be converted to lists, either through pattern matching or the `list` function. Their type is `:tuple`.
 
 ### Lists
-Lists are persistent and immutable ordered collections of any kinds of values, delimited by square braces, e.g. `[1, :a, "foo"]`. They are currently implemented using Clojure's persistent vectors. Their type is `:list`.
+Lists are persistent and immutable ordered collections of any kinds of values, delimited by square braces, e.g. `[1, :a, "foo"]`. Their type is `:list`.
 
 Lists may be combined using splats, written with ellipses, e.g., `[...foo, ...bar]`.
 
@@ -51,13 +72,13 @@ Sets are persistent and immutable unordered collections of any kinds of values,
 ### Dictionaries, or dicts
 Dicts are persistent and immutable associative collections of any kinds of values. Dicts use keywords as keys (and cannot use any other kind of Ludus value as a key, not even strings), but can store any values. Dict literals are written as keyword-value pairs: `#{:a 1, :b false}`. Single words may be used as a shorthand for a key-value pair. Accessing a key that holds no value returns `nil`. Their type is `:dict`.
 
-### Namespaces
-Namespaces are immutable collections of bindings. They may only be described at the top level of a script. Accessing a key that has no value on a namepsace results in a panic. Their type is `:ns`.
+### Packages
+Packages are immutable collections of bindings. They may only be described at the top level of a script, and their names must begin with a capital letter. Accessing a key that has no value on a package results in a validation error. They may not be accessed using functions, but only direct keyword access. Their type is `:pkg`.
 
-They are written with the form `ns`, then a word that will be bound as their name, and then an associative structure (pairs or word shorthands), delimited by `{}`, e.g.:
+They are written with the form `pkg`, then a package name, beginning with a capital letter, that will be bound as their name, and then an associative structure (pairs or word shorthands), delimited by `{}`, e.g.:
 
 ```
-ns foo {
+pkg Foo {
   :bar "bar"
   :baz 42
   quux
@@ -65,28 +86,33 @@ ns foo {
 ```
 
 ### Working with collections
-Ludus names are bound permanently and immutably. How do you add something to a list or a dict? How do you get things out of them?
+Ludus names are bound permanently and immutably. Collections are immutable. How do you add something to a list or a dict? How do you get things out of them?
 
-Ludus provides functions that allow working with persistent collections. They're detailed in [the Prelude](/prelude.md). That said, all functions that modify collections take a collection and produce the modified collection _as a return value_, without changing the original collection. E.g., `append ([1, 2, 3], 4)` will produce `[1, 2, 3, 4]`. (For dicts, the equivalent is `assoc`.)
+Ludus provides functions that allow working with persistent collections. They're detailed in [the Prelude](prelude.md). That said, all functions that modify collections take a collection and produce the modified collection _as a return value_, without changing the original collection. E.g., `append ([1, 2, 3], 4)` will produce `[1, 2, 3, 4]`, but the original list is unchanged. (For dicts, the equivalent is `assoc`.)
 
 ## Expressions
 Ludus is an expression-based language: all forms in the language are expressions and return values, except `panic!`. That said, not all expressions may be used everywhere.
 
+### Terminating expressions
+Expressions in scripts and blocks are terminated by a newline or a semicolon. In compound forms, like, `if`, the terminator comes after the `else` expression.
+
+In forms with multiple clauses surrounded by curly braces (i.e., function bodies, `match`, `when`, etc.), you may separate clauses with semicolons as well as newlines.
+
 ### Toplevel expressions
-Some expressions may only be used in the "top level" of a script. Because they are the toplevel, they are assured to be statically knowable. These include: `ns`, `use`, `import`, and `test`.
+Some expressions may only be used in the "top level" of a script. Because they are the toplevel, they are assured to be statically knowable. These include: `pkg`, `ns`, `use`, `import`, and `test`. (NB: not all of these are yet implemented.)
 
 ### Non-binding expressions
-Some forms may take any expression that does _not_ [bind a name](#Words-and-bindings), for example, any entry in a collection, or the right-hand side of a `let` binding. This is because binding a name in some positions is ambiguous, or nonsensical, or leads to unwarranted complications.
+Some forms may take any expression that does _not_ [bind a name](#words-and-bindings), for example, any entry in a collection, or the right-hand side of a `let` binding. This is because binding a name in some positions is ambiguous, or nonsensical, or leads to unwarranted complications.
 
 ### Simple expressions
-Many complex forms will only accept "simple" expressions. Formally, simple expressions are either literal (atomic, string, or collection literals) or synthetic expressions. They are expressions which do not take sub-expressions: no `if`, `when`, `match`, etc. (`do` expressions are currently not simple, but that may be revised.)
+Many compound forms will only accept "simple" expressions. Formally, simple expressions are either literal (atomic, string, or collection literals) or synthetic expressions. They are expressions which do not take sub-expressions: no `if`, `when`, `match`, etc. (`do` expressions are currently not simple, but that may be revised.)
 
 ## Words and bindings
 Ludus uses _words_ to bind values to names. Words must start with a lower case ASCII letter, and can subsequently include any letter character (modulo backing character encoding), as well as , `_`, `/`, `?`, `!`, and `*`.
 
-Ludus binds values to names immutably and permanently: no name in the same scope may ever be re-bound to a different value. (Although see [refs](#references-and-state), below.
+Ludus binds values to names immutably and permanently: no name in the same scope may ever be re-bound to a different value. (Although see [boxes](#boxes-and-state), below.
 
-Attempting to use an unbound name (a word that has not had a value bound to it) will result in a panic.
+Attempting to use an unbound name (a word that has not had a value bound to it) will result in a validation error, and the script will not run.
 
 ### `let` bindings: a very short introduction
 Ludus's basic binding form is `let`:
@@ -94,7 +120,7 @@ Ludus's basic binding form is `let`:
 ```
 let foo = :bar & `foo` is now bound to `bar` for the rest of the scope.
 
-let foo = :baz & panic!
+let foo = :baz & Validation error: name foo was bound in line 1
 ```
 
 `let` bindings are more complex; we will return to these below.
@@ -106,10 +132,10 @@ Ludus makes extensive use of pattern-matching. Patterns do two jobs at once: the
 The simplest pattern is the placeholder: it matches against anything, and does not bind a name. It is written as a single underscore: `_`, e.g., `let _ = :foo`.
 
 #### Ignored names
-If you wish to be a bit more explict than using a placeholder, you can use an ignored name, which is a name that starts with an underscore: `_foo`. This is not bound, is not a valid name, and can be used however much you wish, even multiple times in the same pattern. It's a placeholder, plus a reader-facing description.
+If you wish to be a bit more explict than using a placeholder, you can use an ignored name, which is a name that starts with an underscore: `_foo`. This is not bound, is not a valid name, and can be used however much you wish, even multiple times in the same pattern. It is, in fact, a placeholder, plus a reader-facing description.
 
 ### Literal patterns
-Patterns can be literal atomic values or strings: `0`, `false`, `nil`, `"foo"`, etc. That means you can write `let 0 = 0` or `let :foo = :foo`, and everything will be jsut fine.
+Patterns can be literal atomic values or strings: `0`, `false`, `nil`, `:foo`, etc. That means you can write `let 0 = 0` or `let :foo = :foo`, and, while nothing will happen, everything will be just fine.
 
 Literals match against, well, literal values: if the pattern and the value are the same, they match! If not, they don't match.
 
@@ -121,6 +147,24 @@ Word patterns match against any value, and bind that value to the word as a name
 #### Typed patterns
 Word patterns can, optionally, take a type, using the `as` reserved word, and the keyword representing the desired type: `let foo as :number = 42`.
 
+### String patterns
+Ludus has a simple but powerful form of string pattern matching that mirrors string interpolation. Any word inside curly braces in a string will match against a substring of a string passed into a pattern.
+
+```
+let i_am = "I am the walrus"
+
+let "I {verb} the {noun}" = i_am
+(verb, noun) &=> ("am", "walrus")
+```
+
+Note that such names may well be bound to empty strings: a match does not guarantee that there will be anything in the string. This is particularly relevant at the beginning and end of string patterns:
+
+```
+let we_are = "We are the eggmen"
+let "{first}We {what}" = we_are
+(first, what) &=> ("", "are the eggmen")
+```
+
 ### Collection patterns
 Tuples, lists, and dicts can be destructured using patterns. They are written nearly identically to their literal counterparts. Collection patterns are composed of any number of simpler patterns or other collection patterns. They bind any names nested in them, match literals in them, etc.
 
@@ -141,11 +185,15 @@ let () = () & empty tuples are also patterns
 #### List patterns
 List patterns are identical to tuple patterns, but they are written using square braces. They also match against a specific number of members, and may take a splat in the last position, e.g. `let [first, ...rest] = [1, 2, 3]`.
 
+Note that list patterns, like tuple patterns, match on explicit length. That means that if you are matching only the first items of a list, you must explicitly include a splat pattern, e.g. `let [first, second, ...] = [1, 2, 3, 4]`.
+
 #### Dict patterns
 Dict patterns are written either with shorthand words, or keyword-pattern pairs. Consider: `let #{:a foo, :b 12, c} = #{:a 1, :b 12, :c 4}`. `foo` is now 1; `b` is now 12, `c` is now 4. If a dict does not hold a value at a particular key, there is no match.
 
 Dict patterns may also use a splat as their last member: `let #{:a 1, ...b} = #{:a 1, :b 2, :c 3}` will bind `b` to `#{:b 2, :c 3}`.
 
+Like tuple and list patterns, dict patterns without a splat at the end match only on exact equivalence on all keys.
+
 ## `let` bindings
 `let` bindings are the basic form of matching and binding in Ludus. It is written `let {pattern} = {non-binding expression}`. The pattern can be arbitrarily complex. If the left-hand side of a `let` binding does not match, Ludus will raise a panic, halting evaluation of the script.
 
@@ -162,7 +210,7 @@ let first = {
   add (outer, inner)
 } & first is now bound to 65
 
-inner & panic! unbound name inner
+inner & Validation error: unbound name inner
 
 ```
 
@@ -182,37 +230,28 @@ let y = {
 ```
 
 ## Conditional forms
-Ludus has a robust set of conditionoal forms, all of which are expressions and resolve to a single value.
+Ludus has a robust set of conditional forms, all of which are expressions and resolve to a single value.
 
 ### `if`
 `if` evaluates a condition; if the result of the condition is truthy, it evaluates is `then` branch; if the condition is falsy, it evaluates its `else` branch. Both branches must always be present. Newlines may come before `then` and `else`.
 
 `if {simple expression} then {non-binding expression} else {non-binding expression}`
 
-#### `if let`
-There is one exception to the above: a single `let` form can be used as the condition. In that case, if the `let` binding is successful--the pattern matches--the `then` branch is evaluated with any resulting bindings. If the pattern does not match, in place of a panic, the `else` branch is evaluated. Note that if the right-hand value of the `let` expression is falsy, the `else` branch will also be evaluated.
-
-```
-if let (:ok, value) = might_fail ()
-  then do_something_with (value)
-  else recover
-```
-
 ### `when`
 `when` is like Lisp's `cond`: it takes a series of clauses, separated by semicolons or newlines, delimited by curly braces. Clauses are written `lhs -> rhs`. `when` expressions are extremely useful for avoiding nested `if`s. 
 
-The left hand of a clause is a simple expression; the right hand of a clause is any expression. When the left hand is truthy, the right hand is evaluated, and the result of that evaluation is returned; no further clauses are evaluated. If no clause has a truthy left-hand value, then a panic is raised. `else` and `_` are valid left-hand expressions, which are always truthy in this context.
+The left hand of a clause is a simple expression; the right hand of a clause is any expression. When the left hand is truthy, the right hand is evaluated, and the result of that evaluation is returned; no further clauses are evaluated. If no clause has a truthy left-hand value, then a panic is raised. In the example below, not the use of literal `true` as an always-matching clause.
 
 ```
 when {
   maybe () -> :something
   mabye_not () -> :something_else
-  else -> :always
+  true -> :always
 }
 ```
 
 ### `match`
-A `match` form is the most powerful conditional form in Ludus (for now). It consists of a test expression, and a series of clauses. The test expression must be a simple expression, followed by `with`, and then a series of clauses separated by a semicolon or newline, delimited by curly braces.
+A `match` form is the most powerful conditional form in Ludus. It consists of a test expression, and a series of clauses. The test expression must be a simple expression, followed by `with`, and then a series of clauses separated by a semicolon or newline, delimited by curly braces.
 
 ```
 match may_fail () with {
@@ -223,9 +262,20 @@ match may_fail () with {
 
 The left hand of a match clause is a pattern; the right hand is an expression: `pattern -> expression`. If the pattern matches the test expression of a clause, the expression is evaluated with any bindings from the pattern, and `match` form evaluates to the result of that expression.
 
-If a test expression does not match against any clause's pattern, a panic is raised. As with `when` expressions, `_` and `else` always match.
+If a test expression does not match against any clause's pattern, a panic is raised.
 
-Ludus does not attempt to do any exhaustiveness checking on match forms. 
+Ludus does not attempt to do any exhaustiveness checking on match forms; match errors are always runtime errors.
+
+#### Guards
+`match` clauses may have a _guard expression_, which allows a clause only to match if the expression's result is truthy. In the previous example, consider that we might want different behaviour depending on the value of the number:
+```
+match may_fail () with {
+  (:ok, value) if pos? (value) -> calculate_positive_result (value)
+  (:ok, value) if neg? (value) -> calculate_negative_result (value)
+  (:ok, 0) -> do_something_with_zero ()
+  (:err, msg) -> { log! (msg); recover_somehow () }
+}
+```
 
 ## Functions
 Ludus is an emphatically functional language. Almost everything in Ludus is accomplished by applying functions to values, or calling functions with arguments. (These are precise synonyms.)
@@ -247,7 +297,7 @@ A named function is identical to a lambda, with the one change that a word follo
 #### Compound functions
 Compound functions are functions that have multiple clauses. They must be named, and in place of a single clause after a name, they consist in one or more clauses, separated by semicolons or newlines, delimited by curly braces. Optionally, compound functions may have a docstring as their first element after the opening curly brace. The docstring explains the function's purpose and use, before any of the function clauses.
 
-An exampele from Ludus's Prelude:
+An example from Ludus's Prelude:
 
 ```
 fn some {
@@ -258,10 +308,29 @@ fn some {
 ```
 
 ### Closures
-Functions in Ludus are closures: function bodies have access not only to their specific scope, but any enclosing scope. Note that function bodies may have access to names bound after them in their scope, so long as the function is _called_ after any names it accesses are bound.
+Functions in Ludus are closures: function bodies have access not only to their specific scope, but any enclosing scope. That said, functions only have access to names bound _before_ they are defined; nothing is hoisted in Ludus.
+
+### Mutual recursion and forward declaration
+If you try the following, you'll get a validation error:
+
+```
+fn stupid_odd? {
+  (0) -> false
+  (x) -> supid_even? (dec (x)) & Validation error: unbound name stupid_even?
+}
+
+fn stupid_even? {
+  (0) -> true
+  (x) -> stupid_odd? (dec (x))
+}
+```
+
+To allow for mutual recursion, Ludus allows forward declarations, which are written `fn name` without any clauses. In the example above, we would simply put `fn stupid_even?` before we define `stupid_odd?`. 
+
+If you declare a function without defining it, however, Ludus will raise a validation error.
 
 ### The Prelude
-The Prelude is a substantial set of functions that is available in any given Ludus script. (It is, itself, just a Ludus file that has special access to host functions.) Because of that, a large number of functions are always available. The prelude documentation is [here](/prelude.md).
+The Prelude is a substantial set of functions that is available in any given Ludus script. (It is, itself, just a Ludus file that has special access to host functions.) Because of that, a large number of functions are always available. The prelude documentation is [here](prelude.md).
 
 ### Partial application
 Functions in Ludus can be partially applied by using a placeholder in the arguments. Partial application may only use a single placeholder (partially applied functions are always unary), but it can be anywhere in the arguments: `let add_1 = add(1, _)` or `let double = mult(_, 2)`.
@@ -274,11 +343,11 @@ Because of "partial application," Ludus has a concept of an "argument tuple" (wh
 In place of nesting function calls inside other function calls, Ludus allows for a more streamlined version of function application: the `do` form or function pipeline. `do` is followed by an initial expression. `do` expressions use `>` as an operator: whatever is on the left hand side of the `>` is passed in as a single argument to whatever is on its right hand side. For example:
 
 ```
-let silly_result = do 23
-  > mult (_, 2) > add (1, _)
-  > sub (_, 2) > div (_, 9) & silly_result is 5
+let silly_result = do 23 > 
+  mult (_, 2) > add (1, _) > 
+  sub (_, 2) > div (_, 9) & silly_result is 5
 ```
-Newlines may appear before any instance of `>` in a `do` expression.
+Newlines may appear after any instance of `>` in a `do` expression. That does, however, mean that you must be careful not to accidentally include any trailing `>`s.
 
 ### Called keywords
 Keywords may be called as functions, in which case they extract the value stored at that key in the value passed in:
@@ -290,8 +359,16 @@ let bar = :a (foo) & `bar` is now 1
 
 Called keywords can be used in pipelines.
 
+In addition, keywords may be called when they are bound to names:
+
+```
+let foo = #{:a 1, :b 2}
+let bar = :a
+bar (foo) & => 1 
+```
+
 ## Synthetic expressions
-Synthetic expressions are valid combinations of words, keywords, and argument tuples which allow for calling functions and extracting values from associative collections. The root--first term--of a synthetic expression must be a word or a keyword; subsequent terms must be either argument tuples or keywords.
+Synthetic expressions are valid combinations of words, keywords, package names, and argument tuples which allow for calling functions and extracting values from associative collections. The root--first term--of a synthetic expression must be a word or a keyword; subsequent terms must be either argument tuples or keywords.
 
 ```
 let foo = #{:a 1, :b #{:c "bar" :d "baz"}}
@@ -303,7 +380,7 @@ let baz = :b (foo) :d & `baz` is now "baz"
 ```
 
 ## Looping forms
-Ludus will have optimized tail calls--the most straightforward way to accomplish repeating behaviour is function recursion. There are two additional looping forms, `repeat` and `loop`.
+Ludus has optimized tail calls--the most straightforward way to accomplish repeating behaviour is function recursion. There are two additional looping forms, `repeat` and `loop`.
 
 ### `repeat`
 `repeat` is a help to learners, and is useful for executing side effects multiple times. It is written `repeat {number|word} { {exprs} }`. From turtle graphics:
@@ -316,8 +393,8 @@ repeat 4 {
 ```
 Note that `repeat` does two interesting things:
 
-1. It never returns a value other than `nil`. If it's in the block, it disappears.
-2. Unlike everything else in Ludus, it requires a block. You cannot write `repeat 4 forward! (100)`. (But: watch this space.)
+1. It never returns a value other than `nil`. If it's in the block, it disappears. This is a unique (and frankly, undesirable) property in Ludus.
+2. Unlike everything else in Ludus, repeate _requires_ a block, and not simply an expression. You cannot write `repeat 4 forward! (100)`.
 
 ### `loop`/`recur`
 `loop` and `recur` are largely identical to recursive functions for repetition, but use a special form to allow an anonymous construction and a few guard rails.
@@ -332,7 +409,9 @@ loop (xs, 0) with {
 } &=> 10
 ```
 
-`recur` is the recursive call. It must be in tail position--`recur` must be the root of a synthetic expression, in return position. (At present, this is not checked. It will be statically verified, eventually.)
+`recur` is the recursive call. It must be in tail position--`recur` must be the root of a synthetic expression, in return position. If `recur` is not in tail position, a validation error will be raised.
+
+In addition, `recur` calls must have the same number of arguments as the original tuple passed to `loop`. While Ludus will allow you to write clauses in `loop` forms with a different arity than the original tuple, those will never match. 
 
 `recur` calls return to the nearest `loop`. Nested `loop`s are probably a bad idea and should be avoided when possible.
 
@@ -342,14 +421,18 @@ The "toplevel" of a script are the expressions that are not embedded in other ex
 ### `import`
 `import` allows for the evaluation of other Ludus scripts: `import "path/to/file" as name`. `import` just evaluates that file, and then binds a name to the result of evaluating that script. This, right now, is quite basic: circular imports are currently allowed but will lead to endless recursion; results are not cached, so each `import` in a chain re-evaluates the file; and so on.
 
+Status: not yet implemented.
+
 ### `use`
 `use` loads the contents of a namespace into a script's context. To ensure that this is statically checkable, this must be at the toplevel. 
 
-### `ns`
-Namespaces, `ns`es, may only be described at the toplevel of a script. This is to ensure they can be statically evaluatable.
+Status: not yet implemented.
+
+### `pkg`
+Packages, `pkg`es, may only be described at the toplevel of a script. This is to ensure they can be statically evaluatable.
 
 ### `test`
-A `test` expression (currently not working!--it will blow up your script, although it parses properly) is a way of ensuring things behave the way you want them to. Run the script in test mode (how?--that doesn't exist yet), and these are evaluated. If the expression under `test` returns a truthy value, you're all good! If the expression under `test` returns a falsy value or raises a panic, then Ludus will report which test(s) failed.
+A `test` expression is a way of ensuring things behave the way you want them to. Run the script in test mode, and these are evaluated. If the expression under `test` returns a truthy value, you're all good! If the expression under `test` returns a falsy value or raises a panic, then Ludus will report which test(s) failed.
 
 ```
 test "something goes right" eq? (:foo, :foo)
@@ -365,26 +448,32 @@ test "something goes wrong" {
 
 Formally: `test <string> <expression>`.
 
-## Changing things: `ref`s
-Ludus does not let you re-bind names. It does, however, have a type that allows for changing values over time: `ref` (short for reference--they are references to values). `ref`s are straightforward, but do require a bit more overhead than `let` bindings. The idea is that Ludus makes it obvious where mutable state is in a program, as well as where that mutable state may change. It does so elegantly, but with some guardrails that may take a little getting used to.
+Status: not yet implemented.
 
-The type of a `ref` is, predictably, `:ref`.
+## Changing things: `box`es
+Ludus does not let you re-bind names. It does, however, have a type that allows for changing values over time: `box`. A box is a place to put things, it has its own identity, it can store whatever you put in it, but to get what's in it, you have to `unbox` it. 
+
+Syntactically and semantically, `box`es are straightforward, but do require a bit more overhead than `let` bindings. The idea is that Ludus makes it obvious where mutable state is in a program, as well as where that mutable state may change. It does so elegantly, but with some guardrails that may take a little getting used to.
+
+The type of a `box` is, predictably, `:box`.
 
 ```
-ref foo = 42 & foo is now bound to a _ref that contains 42_
+box foo = 42 & foo is now bound to a _box that contains 42_
 add (1, foo) & panic! no match: foo is _not_ a number
-make! (foo, 23) & foo is now a ref containing 23
+store! (foo, 23) & foo is now a box containing 23
 update! (foo, inc) & foo is now a ref containing 24
-value_of (foo) &=> 23; use value_of to get the value contained in a ref
+unbox (foo) &=> 23; use unbox to get the value contained in a box
 ```
 
 ### Ending with a bang!
-Ludus has a strong naming convention that functions that change state or could cause an explicit panic end in an exclamation point (or, in computer nerd parlance, a "bang"). So anything function that mutates the value held in a reference ends with a bang: `make!` and `update!` take bangs; `value_of` does not.
+Ludus has a strong naming convention that functions that change state or could cause an explicit panic end in an exclamation point (or, in computer nerd parlance, a "bang"). So anything function that mutates the value held in a reference ends with a bang: `store!` and `update!` take bangs; `unbox` does not.
 
-This convention also includes anything that prints to the console: `print!`, `report!`, `doc!`, `update!`, `make!`, etc.
+This convention also includes anything that prints to the console: `print!`, `report!`, `doc!`, `update!`, `store!`, etc.
+
+(Note that there are a few counter-examples to this: math functions that could cause a panic [in place of returning NaN] do not end with bangs: `div`, `inv`, and `mod`; each of these has variants that allow for more graceful error handling).
 
 ### Ending with a whimper?
-Relatedly, just about any function that returns a boolean value is a predicate function--and has a name that ends with a question mark: `eq?` tests for equality; `ref?` tells you if something is a ref or not; `lte?` is less-than-or-equal.
+Relatedly, just about any function that returns a boolean value is a predicate function--and has a name that ends with a question mark: `eq?` tests for equality; `box?` tells you if something is a ref or not; `lte?` is less-than-or-equal.
 
 ## Errors: panic! in the Ludus script
 A special form, `panic!`, halts script execution with the expression that follows as an error message. 
@@ -401,13 +490,14 @@ Panics also happen in the following cases:
 * a function is called with arguments that do not match any of its clauses
 * something that is not a function or keyword is called as a function
 * a called keyword is partially applied
-* `div` divides by zero
+* `div`, `inv`, or `mod` divides by zero
+* `sqrt` takes the square root of a negative number
 * certain error handling functions, like `unwrap!` or `assert!`, are invoked on values that cause them to panic
 
-In fact, the only functions in the Prelude which can cause panics are, at current, `div`, `unwrap!`, and `assert!`.
+In fact, the only functions in the Prelude which explicitly cause panics are, at current, `div`, `inv`, `mod`, `sqrt`, `unwrap!`, and `assert!`.
 
 ### `nil`s, not errors
-Ludus, however, tries to return `nil` instead of panicking a lot of the time. So, for example, attempting to get access a value at a keyword off a number, while nonsensical, will return `nil` rather than panicking:
+Ludus, however, tries to return `nil` instead of panicking where it seems prudent. So, for example, attempting to get access a value at a keyword off a number or `nil`, while nonsensical, will return `nil` rather than panicking:
 
 ```
 let a = true
@@ -418,6 +508,6 @@ at (b, 12) &=> nil
 ```
 
 ### Result tuples
-Operations that could fail--especially when you want some information about why--don't always return `nil` on failures. Instead of exceptions or special error values, recoverable errors in Ludus are handled instead by result tuples: `(:ok, value)` and `(:err, msg)`. So, for example, `unwrap!` takes a result tuple and either returns the value in the `:ok` case, or panics in the `:err` case. Or `assert!` will panic on a falsy value; `assert`, instead, returns a result tuple.
+Operations that could fail--especially when you want some information about why--don't always return `nil` on failures. Instead of exceptions or special error values, recoverable errors in Ludus are handled instead by result tuples: `(:ok, value)` and `(:err, msg)`. So, for example, `unwrap!` takes a result tuple and either returns the value in the `:ok` case, or panics in the `:err` case.
 
-Variants of some functions that may have undesirably inexplicit behaviour are written as `{name}/safe`. So, for example, you can get a variant of `div` that returns a result tuple in `div/safe`, which returns `(:ok, result)` when everything's good; and `(:err, "division by zero")` when the divisor is 0. Or, `get/safe` will give you a result rather than returning `nil`. (Althougn `nil` punning makes this mostly unncessary. Mostly.)
+Variants of some functions that may have undesirably inexplicit behaviour are written as `{name}/safe`. So, for example, you can get a variant of `div` that returns a result tuple in `div/safe`, which returns `(:ok, result)` when everything's good; and `(:err, "division by zero")` when the divisor is 0.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@ludus/ludus-js-pure",
-  "version": "0.1.0-alpha.7.9",
+  "version": "0.1.36",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ludus/ludus-js-pure",
-      "version": "0.1.0-alpha.7.9",
+      "version": "0.1.36",
       "license": "GPL-3.0",
       "devDependencies": {
         "shadow-cljs": "^2.26.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludus/ludus-js-pure",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.36",
   "description": "A Ludus interpreter in a pure JS function.",
   "type": "module",
   "main": "build/ludus.mjs",
@@ -11,6 +11,7 @@
   "files": [
     "build/out.wasm",
     "build/out.mjs",
-    "build/ludus.mjs"],
+    "build/ludus.mjs"
+  ],
   "devDependencies": {}
 }

postlude.ld

@@ -3,23 +3,5 @@
 & the goal is to output any global state held in Ludus
 & this does not have base loaded into it, only prelude: must be pure Ludus
 
-if turtle_state () :visible? then render_turtle! () else nil
-
-reset_turtle! ()
-
-& let console_msgs = flush! ()
-
-let (r, g, b, a) = unbox (bgcolor)
-store! (bgcolor, colors :black)
-
-let draw_calls = unbox (p5_calls)
-store! (p5_calls, [])
-
-#{
-	& :result result is provided elsewhere
-	& :errors [] & if we get here there are no errors
-	& :console console_msgs
-	:draw concat (
-		[(:background, r, g, b, a), (:stroke, 255, 255, 255, 255)]
-		draw_calls)
-}
+store! (turtle_state, turtle_init)
+store! (turtle_commands, [])

sandbox.ld

@@ -0,0 +1,285 @@
+let input = "I remember my mother"
+
+print! ("DOCTOR")
+
+print! ("> ", input)
+
+let sanitized = do input > trim > downcase
+
+& ensuring we have spaces at the beginning and end
+& this lets us match patterns as written below
+let padded = join ([" ", sanitized, " "])
+
+fn switch_persons {
+ ("i") -> "you"
+ ("you") -> "i"
+ ("am") -> "are"
+ ("me") -> "you"
+ ("my") -> "your"
+ (x) -> x
+}
+
+fn repersonalize (x) -> do x > 
+    trim > 
+    split (_, " ") > 
+    map (switch_persons, _) > 
+    join (_, " ")
+
+fn one_of {
+ (str as :string) -> str
+ (strs as :list) -> random (strs)
+}
+
+let output = match padded with {
+ "{x} hello {y}" -> "How do you do. Please state your problem"
+ "{x} hi {y}" -> "How do you do. Please state your problem"
+ "{x} computer {y}" -> [
+   "Do computers worry you"
+   "What do you think about machines"
+   "Why do you mention computers"
+   "What do you think machines have to do with your problem"
+ ]
+ "{x} name {y}" -> "I am not interested in names"
+ "{x} sorry {y}" -> [
+   "Please don't apologize"
+   "Apologies are not necessary"
+   "What feelings do you have when you apologize"
+ ]
+ "{x} i remember {y}" -> { 
+   let switched = repersonalize (y)
+   [
+     "Do you often think of {switched}"
+     "Does thinking of {switched} bring anything else to mind"
+     "What else do you remember"
+     "Why do you recall {switched} right now"
+     "What in the present situation reminds you of {switched}"
+     "What is the connection between me and {switched}"
+   ]
+  } 
+ "{x} do you remember {y}" -> {
+  let switched = repersonalize (y)
+  [
+    "Did you think I would forget {switched}"
+    "Why do you think I should recall {switched} now"
+    "What about {switched}"
+    "You mentioned {switched}"
+  ]
+ }
+ "{x} if {y}" -> {
+  let switched = repersonalize (y)
+  [
+    "Do you reall think that its likely that {switched}"
+    "Do you wish that {switched}"
+    "What do you think about {switched}"
+    "Really--if {switched}"
+  ]
+ }
+ "{x} i dreamt {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "Really--{y}"
+   "Have you ever fantasized {y} while you were awake"
+   "Have you dreamt {y} before"
+  ]
+ }
+ "{x} dream about {y}" -> {
+  let switched = repersonalize (y)
+  "How do you feel about {switched} in reality"
+ }
+ "{x} dream {y}" -> [
+   "What does this dream suggest to you"
+   "Do you dream often"
+   "What persons appear in your dreams"
+   "Don't you believe that dream has to do with your problem"
+ ]
+ "{x} my mother {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "Who else in your family {y}"
+   "Tell me more about your family"
+  ]
+ }
+ "{x} my father {y}" -> [
+   "Your father"
+   "Does he influence you strongly"
+   "What else comes to mind when you think of your father"
+ ]
+ "{x} i want {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "What would it mean if you got {y}"
+   "Why do you want {y}"
+   "Suppose you got {y} soon"
+  ]
+ }
+ "{x} i am glad {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "How have I helped you to be {y}"
+   "What makes you happy just now"
+   "Can you explain why you are suddenly {y}"
+  ]
+ }
+ "{x} i am sad {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "I am sorry to hear you are depressed"
+   "I'm sure it's not pleasant to be sad"
+  ]
+ }
+ "{x} are like {y}" -> {
+  let switched_x = repersonalize (x)
+  let switched_y = repersonalize (y)
+  "What resemblance to you see between {switched_x} and {switched_y}"
+ }
+  "{x} is like {y}" -> {
+   let switched_x = repersonalize (x)
+   let switched_y = repersonalize (y)
+   [
+    "In what way is it that {switched_x} is like {switched_y}"
+    "What resemblance do you see"
+    "Could there really be some connection"
+    "How"
+   ]
+  }
+ "{x} alike {y}" -> [
+  "In what way"
+  "What similarities are there"
+ ]
+ "{x} same {y}" -> "What other connections do you see"
+ "{x} i was {y}" -> {
+  let switched = repersonalize (y) 
+  [
+   "Were you really"
+   "Perhaps I already knew you were {switched}"
+   "Why do you tell me you were {switched} now"
+  ]
+ }
+ "{x} was i {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "What if you were {switched}"
+   "Do you think you were {switched}"
+   "What wouuld it mean if you were {switched}"
+  ]
+ }
+ "{x} i am {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "In what way are you {switched}"
+   "Do you want to be {switched}"
+  ]
+ }
+ "{x} am i {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "Do you believe you are {switched}"
+   "Would you want to be {switched}"
+   "You wish I would tell you you are {switched}"
+   "What would it mean if you were {switched}"
+  ] 
+ }
+ "{x} am {y}" -> [
+  "Why do you say *AM*"
+  "I don't understand that"
+ ]
+ "{x} are you {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "Why are you interested in whether I am {switched} or not"
+   "Would you prefer if I weren't {switched}"
+   "Perhaps I am {switched} in your fantasies"
+  ]
+ }
+ "{x} you are {y}" -> {
+  let switched = repersonalize (y)
+  "What makes you think I am {y}"
+ }
+ "{x} because {y}" -> [
+  "Is that the real reason"
+  "What other reasons might there be"
+  "Does that reason seem to explain anything else"
+ ]
+ "{x} were you {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "Perhaps I was {switched}"
+   "What od you think"
+   "What if I had been {switched}"
+  ]
+ }
+ "{x} i can't {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "Maybe you could {switched} now"
+   "What if you could {switched}"
+  ]
+ }
+ "{x} i feel {y}" -> {
+  let switched = repersonalize (y)
+  "Do you often feel {switched}"
+ }
+ "{x} i felt {y}" -> "What other feelings do you have"
+ "{x} i {y} you {z}" -> {
+  let switched = repersonalize (y)
+  "Perhaps in your fantasy we {switched} each other"
+ }
+ "{x} why don't you {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "Should you {y} yourself"
+   "Do you believe I don't {y}"
+   "Perhaps I will {y} in good time"
+  ]
+ }
+ "{x} yes {y}" -> [
+  "You seem quite positive"
+  "You are sure"
+  "I understand"
+ ]
+ "{x} no {y}" -> [
+  "Why not"
+  "You are being a bit negative"
+  "Are you saying *NO* just to be negative"
+ ]
+ "{x} someone {y}" -> "Can you be more specific"
+ "{x} everyone {y}" -> [
+  "Surely not everyone"
+  "Can you think of anyone in particular"
+  "Who for example"
+  "You are thinking of a special person"
+ ]
+ "{x} always {y}" -> [
+  "Can you think of a specific example"
+  "When"
+  "What incident are you thinking of"
+  "Really--always"
+ ]
+ "{x} what {y}" -> [
+  "Why do you ask"
+  "Does that question interest you"
+  "What is it you really want to know"
+  "What do you think"
+  "What comes to your mind when you ask that"
+ ]
+ "{x} perhaps {y}" -> "You do not seem quite certain"
+ "{x} are {y}" -> {
+  let switched = repersonalize (y)
+  [
+   "Did you think they might not be {switched}"
+   "Possibly they are {switched}"
+  ]
+ }
+ _ -> [
+   "Very interesting"
+   "I am not sure I understand you fully"
+   "What does that suggest to you"
+   "Please continue"
+   "Go on"
+   "Do you feel strongly about discussing such things"
+ ] 
+}
+
+print! (">>> ", do output > one_of > upcase)
+
+

src/base.janet

@@ -1,6 +1,8 @@
 # A base library for Ludus
 # Only loaded in the prelude
 
+(import /src/scanner :as s)
+
 (defn bool [x] (if (= :^nil x) nil x))
 
 (defn ludus/and [& args] (every? (map bool args)))
@@ -8,6 +10,7 @@
 (defn ludus/or [& args] (some bool args))
 
 (defn ludus/type [value]
+  (when (= :^nil value) (break :nil))
   (def typed? (when (dictionary? value) (value :^type)))
   (def the-type (if typed? typed? (type value)))
   (case the-type
@@ -52,6 +55,8 @@
 
 (set stringify stringify*)
 
+(var show nil)
+
 (defn- show-pkg [x]
   (def tab (struct/to-table x))
   (set (tab :^name) nil)
@@ -59,41 +64,57 @@
   (string "pkg " (x :^name) " {" (stringify tab) "}")
 )
 
-(defn show [x]
-  (case (ludus/type x)
-    :nil "nil"
-    :string (string "\"" x "\"")
-    :tuple (string "(" (stringify x) ")")
-    :list (string "[" (stringify x) "]")
-    :dict (string "#{" (stringify x) "}")
-    :set (string "${" (stringify x) "}")
-    :box (string "box " (x :name) " [ " (stringify x) " ]")
-    :pkg (show-pkg x)
-    (stringify x)))
-
-(var json nil)
-
-(defn- dict-json [dict]
+(defn- dict-show [dict]
   (string/join 
     (map 
-      (fn [[k v]] (string (json k) ": " (json v))) 
+      (fn [[k v]] (string (show k) " " (show v))) 
       (pairs dict))
     ", "))
 
-(defn- json* [x]
-  (case (ludus/type x)
-    :nil "null"
-    :number (string x)
-    :bool (if true "true" "false")
-    :string (string "\"" x "\"")
-    :keyword (string "\"" x "\"")
-    :tuple (string "[" (string/join (map json x) ", ") "]")
-    :list (string "["  (string/join (map json x) ", ")"]")
-    :dict (string "{" (dict-json x) "}")
-    :set (string "["  (string/join (map json (keys x)) ", ") "]")
-    (show x)))
+(defn- set-show [sett]
+  (def prepped (merge sett))
+  (set (prepped :^type) nil)
+  (def shown (map show (keys prepped)))
+  (string/join shown ", ")
+)
 
-(set json json*)
+(defn- show* [x]
+  (case (ludus/type x)
+    :nil "nil"
+    :string (string "\"" x "\"")
+    :tuple (string "(" (string/join (map show x) ", ") ")")
+    :list (string "[" (string/join (map show x) ", ") "]")
+    :dict (string "#{" (dict-show x) "}")
+    :set (string "${" (set-show x) "}")
+    :box (string "box " (x :name) " [ " (show (x :^value)) " ]")
+    :pkg (show-pkg x)
+    (stringify x)))
+
+(set show show*)
+
+# (var json nil)
+
+# (defn- dict-json [dict]
+#   (string/join 
+#     (map 
+#       (fn [[k v]] (string (json k) ": " (json v))) 
+#       (pairs dict))
+#     ", "))
+
+# (defn- json* [x]
+#   (case (ludus/type x)
+#     :nil "\"null\""
+#     :number (string x)
+#     :bool (if true "\"true\"" "\"false\"")
+#     :string (string "\"" x "\"")
+#     :keyword (string "\"" x "\"")
+#     :tuple (string "[" (string/join (map json x) ", ") "]")
+#     :list (string "["  (string/join (map json x) ", ")"]")
+#     :dict (string "{" (dict-json x) "}")
+#     :set (string "["  (string/join (map json (keys x)) ", ") "]")
+#     (show x)))
+
+# (set json json*)
 
 (defn show-patt [x]
   (case (x :type)
@@ -110,16 +131,20 @@
     :typed (string (show-patt (get-in x [:data 1])) " as " (show-patt (get-in x [:data 0])))
     :interpolated (get-in x [:token :lexeme])
     :string (get-in x [:token :lexeme])
-    :splat (string "..." (when (x :splatted) (show-patt (x :splatted))))
+    :splat (string "..." (when (x :data) (show-patt (x :data))))
     (error (string "cannot show pattern of unknown type " (x :type)))))
 
 (defn pretty-patterns [fnn]
   (def {:body clauses} fnn)
-  (string/join (map (fn [x] (-> x first show-patt)) clauses) " "))
+  (string/join (map (fn [x] (-> x first show-patt)) clauses) "\n"))
 
 (defn doc [fnn]
-  (def {:name name :doc doc} fnn)
-  (string/join [name (pretty-patterns fnn) doc] "\n"))
+  (when (not= :fn (ludus/type fnn)) (break "No documentation available."))
+  (def {:name name :doc docstring} fnn)
+  (string/join [name 
+                (pretty-patterns fnn) 
+                (if docstring docstring "No docstring available.")] 
+    "\n"))
 
 (defn- conj!-set [sett value]
   (set (sett value) true)
@@ -187,8 +212,13 @@
     :set (-> x (dissoc :^type) keys)
     @[x]))
 
+(defn showprint [x]
+  (if (= :string (ludus/type x))
+    x
+    (show x)))
+
 (defn print! [args]
-  (print ;(map show args)))
+  (print ;(map showprint args)))
 
 (defn prn [x]
   (pp x)
@@ -204,66 +234,104 @@
 
 (defn store! [b x] (set (b :^value) x))
 
+(defn mod [x y] 
+  (% x y))
+
+(defn- byte->ascii [c i]
+  (if (< c 128) 
+    (string/from-bytes c)
+    (error (string "non-ASCII character at index" i))))
+
+(defn chars [str]
+  (def out @[])
+  (try 
+    (for i 0 (length str)
+      (array/push out (byte->ascii (str i) i)))
+    ([e] (break [:err e])))
+  [:ok out])
+
+(defn to_number [str]
+  (when (string/find "&" str)
+    (break [:err (string "Could not parse `" str "` as a number")]))
+  (def scanned (s/scan (string/trim str)))
+  (when (< 0 (length (scanned :errors)))
+    (break [:err (string "Could not parse `" str "` as a number")]))
+  (def tokens (scanned :tokens))
+  (when (< 3 (length tokens))
+    (break [:err (string "Could not parse `" str "` as a number")]))
+  (def fst (first tokens))
+  (when (not= :number (fst :type))
+    (break [:err (string "Could not parse `" str "` as a number")]))
+  [:ok (fst :literal)])
+
 (def ctx {
-  "print!" print!
-  "prn" prn
-  "eq?" deep=
-  "bool" bool
-  "and" ludus/and
-  "or" ludus/or
   "add" +
-  "sub" -
-  "mult" *
+  "and" ludus/and
+  "assoc!" assoc!
+  "assoc" assoc
+  "atan_2" math/atan2
+  "bool" bool
+  "ceil" math/ceil
+  "chars" chars
+  "concat" concat
+  "conj!" conj!
+  "conj" conj
+  "cos" math/cos
+  "count" length
+  "dec" dec
+  "disj!" disj!
+  "disj" disj
+  "dissoc!" dissoc!
+  "dissoc" dissoc
   "div" /
-  "mod" %
+  "doc" doc
+  "downcase" string/ascii-lower
+  "eq?" deep=
+  "first" first
+  "floor" math/floor
+  "get" ludus/get
   "gt" >
   "gte" >=
+  "inc" inc
+  "last" last
   "lt" <
   "lte" <=
-  "inc" inc
-  "dec" dec
+  "mod" mod
+  "mult" *
   "not" not
-  "type" ludus/type
-  "stringify" stringify
-  "show" show
-  "doc" doc
-  "concat" concat
-  "conj" conj
-  "conj!" conj!
-  "disj" disj
-  "disj!" disj!
-  "push" array/push
-  "assoc" assoc
-  "assoc!" assoc!
-  "dissoc" dissoc
-  "dissoc!" dissoc!
-  "get" ludus/get
   "nth" ludus/get
-  "first" first
-  "rest" rest
-  "last" last
-  "slice" slice
-  "to_list" to_list
-  "count" length
+  "or" ludus/or
   "pi" math/pi
-  "sin" math/sin
-  "cos" math/cos
-  "tan" math/tan
-  "atan_2" math/atan2
-  "sqrt" math/sqrt
+  "print!" print!
+  "prn" prn
+  "push" array/push
   "random" math/random
-  "floor" math/floor
-  "ceil" math/ceil
-  "round" math/round
   "range" range
-  "unbox" unbox
+  "rest" rest
+  "round" math/round
+  "show" show
+  "sin" math/sin
+  "slice" array/slice
+  "split" string/split
+  "sqrt" math/sqrt
   "store!" store!
+  "str_slice" string/slice
+  "stringify" stringify
+  "sub" -
+  "tan" math/tan
+  "to_list" to_list
+  "to_number" to_number
+  "trim" string/trim
+  "triml" string/triml
+  "trimr" string/trimr
+  "type" ludus/type
+  "unbox" unbox
+  "upcase" string/ascii-upper
 })
 
-(def base (let [b @{}]
+(def base (let [b @{:^type :dict}]
   (each [k v] (pairs ctx)
     (set (b (keyword k)) v))
   b))
 
-(set (base :^type) :dict)
-
+(to_number "     123  a  ")

src/doc.janet

@@ -0,0 +1,131 @@
+(import /src/base :as base)
+(import /src/prelude :as prelude)
+
+(defn map-values [f dict] 
+ (from-pairs (map (fn [[k v]] [k (f v)]) (pairs dict))))
+
+(def with-docs (map-values base/doc prelude/ctx))
+
+(def sorted-names (-> with-docs keys sort))
+
+(defn escape-underscores [str] (string/replace  "_" "\\_" str))
+
+(defn escape-punctuation [str] (->> str
+ (string/replace "?" "")
+ (string/replace "!" "")
+ (string/replace "/" "")))
+
+(defn toc-entry [name] 
+ (def escaped (escape-underscores name)) 
+ (string "[" escaped "](#" (escape-punctuation escaped) ")"))
+
+(def alphabetical-list
+ (string/join (map toc-entry sorted-names) "    "))
+
+(def topics {
+ "math" ["abs" "add" "angle" "atan/2" "between?" "ceil" "cos" "dec" "deg/rad" "deg/turn" "dist" "div" "div/0" "div/safe" "even?" "floor" "gt?" "gte?" "heading/vector" "inc" "inv" "inv/0" "inv/safe" "lt?" "lte?" "max" "min" "mod" "mod/0" "mod/safe" "mult" "neg" "neg?" "odd?" "pi" "pos?" "rad/deg" "rad/turn" "random" "random_int" "range" "round" "sin" "sqrt" "sqrt/safe" "square" "sub" "sum_of_squares" "tan" "tau" "to_number" "turn/deg" "turn/rad" "zero?"]
+ "boolean" ["and" "bool" "bool?" "false?" "not" "or" "true?"]
+ "dicts" ["any?" "assoc" "assoc?" "coll?" "count" "dict" "dict?" "diff" "dissoc" "empty?" "get" "keys" "random" "update" "values"]
+ "lists" ["any?" "append" "at" "butlast" "coll?" "concat" "count" "each!" "empty?" "filter" "first" "fold" "join" "keep" "last" "list" "list?" "map" "ordered?" "random" "range" "rest" "second" "sentence" "slice"]
+ "sets" ["any?" "append" "coll?" "concat" "contains?" "count" "empty?" "omit" "random" "set" "set?"]
+ "tuples" ["any?" "at" "coll?" "count" "empty?" "first" "last" "ordered?" "rest" "second" "tuple?"]
+ "strings" ["any?" "chars" "chars/safe" "concat" "count" "downcase" "empty?" "join" "sentence" "show" "slice" "split" "string" "string?" "strip" "to_number" "trim" "upcase" "words"]
+ "types and values" ["assoc?" "bool?" "box?" "coll?" "dict?" "eq?" "fn?" "keyword?" "list?" "neq?" "nil?" "number?" "ordered?" "set?" "show" "some" "some?" "string?" "tuple?" "type"]
+ "boxes and state" ["box?" "unbox" "store!" "update!"]
+ "results" ["err" "err?" "ok" "ok?" "unwrap!" "unwrap_or"]
+ "errors" ["assert!"]
+ "turtle graphics" ["back!" "background!" "bk!" "clear!" "colors" "fd!" "forward!" "goto!" "heading" "heading/vector" "hideturtle!" "home!" "left!" "loadstate!" "lt!" "pc!" "pd!" "pencolor" "pencolor!" "pendown!" "pendown?" "penup!" "penwidth" "penwidth!" "position" "pu!" "pw!" "render_turtle!" "reset_turtle!" "right!" "rt!" "setheading!" "showturtle!" "turtle_state"]
+ "environment and i/o" ["doc!" "print!" "report!" "state"]
+ })
+
+(defn capitalize [str]
+ (def fst (slice str 0 1))
+ (def rest (slice str 1))
+ (def init_cap (string/ascii-upper fst))
+ (def lower_rest (string/ascii-lower rest))
+ (string init_cap lower_rest))
+
+(defn topic-entry [topic] 
+ (string "### " (capitalize topic) "\n" 
+  (as-> topic _ (topics _) (array/slice _) (sort _) (map toc-entry _) 
+   (string/join _ "    "))
+  "\n"))
+
+(def by-topic (let [the-topics (-> topics keys sort)
+                    topics-entries (map topic-entry the-topics)]
+                (string/join topics-entries "\n")))
+
+(defn compose-entry [name]
+ 	(def header (string "\n### " name "\n"))   	
+ 	(def the-doc (get with-docs name))
+  (when (= "No documentation available." the-doc)
+   (break (string header the-doc "\n")))
+  (def lines (string/split "\n" the-doc))
+	(def description (last lines))
+  (def patterns (string/join (slice lines 1 (-> lines length dec)) "\n"))
+  (def backto "[Back to top.](#ludus-prelude-documentation)\n")
+ 	(string header description "\n```\n" patterns "\n```\n" backto))
+
+(compose-entry "update")
+
+(def entries (string/join (map compose-entry sorted-names) "\n---"))
+
+(def doc-file (string 
+```
+# Ludus prelude documentation
+These functions are available in every Ludus script.
+The documentation for any function can be found within Ludus by passing the function to `doc!`, 
+e.g., running `doc! (add)` will send the documentation for `add` to the console.
+
+For more information on the syntax & semantics of the Ludus language, see [language.md](./language.md).
+
+The prelude itself is just a Ludus file, which you can see at [prelude.ld](./prelude.ld).
+
+## A few notes
+**Naming conventions.** Functions whose name ends with a question mark, e.g., `eq?`, return booleans.
+Functions whose name ends with an exclamation point, e.g., `make!`, change state in some way.
+In other words, they _do things_ rather than _calculating values_. 
+Functions whose name includes a slash either convert from one value to another, e.g. `deg/rad`,
+or they are variations on a function, e.g. `div/0` as a variation on `div`.
+
+**How entries are formatted.** Each entry has a brief (sometimes too brief!) description of what it does.
+It is followed by the patterns for each of its function clauses.
+This should be enough to indicate order of arguments, types, and so on.
+
+**Patterns often, but do not always, indicate types.** Typed patterns are written as `foo as :bar`,
+where the type is indicated by the keyword. 
+Possible ludus types are: `:nil`, `:boolean`, `:number`, `:keyword` (atomic values);
+`:string` (strings are their own beast); `:tuple` and `:list` (ordered collections), `:set`s, and `:dict`ionaries (the other collection types); `:pkg` (packages, which are quasi-collections); `:fn` (functions); and `:box`es.
+
+**Conventional types.** Ludus has two types based on conventions.
+* _Result tuples._ Results are a way of modeling the result of a calculation that might fail.
+The two possible values are `(:ok, value)` and `(:err, msg)`.
+`msg` is usually a string describing what went wrong.
+To work with result tuples, see [`unwrap!`](#unwrap) and [`unwrap_or`](#unwrap_or).
+That said, usually you work with these using pattern matching.
+
+* _Vectors._ Vectors are 2-element tuples of x and y coordinates.
+The origin is `(0, 0)`. 
+Many math functions take vectors as well as numbers, e.g., `add` and `mult`.
+You will see vectors indicated in patterns by an `(x, y)` tuple.
+You can see what this looks like in the last clause of `add`: `((x1, y1), (x2, y2))`.
+
+## Functions by topic
+
+```
+by-topic
+```
+    
+## All functions, alphabetically
+
+```
+alphabetical-list
+```
+
+## Function documentation
+
+```
+entries
+))
+
+(spit "prelude.md" doc-file)

src/errors.janet

@@ -3,78 +3,138 @@
 (defn- get-line [source line]
  ((string/split "\n" source) (dec line)))
 
-(defn scan-error [e] (pp e) e)
+(defn- caret [source line start]
+ (def lines (string/split "\n" source))
+ (def the-line (lines (dec line)))
+ (def prev-lines (slice lines 0 (dec line)))
+ (def char-counts (map (fn [x] (-> x length inc)) prev-lines))
+ (def prev-line-chars (sum char-counts))
+ (def offset (- start prev-line-chars))
+ (def indent (string/repeat "." (+ 6 offset)))
+ (string indent "^")
+)
+
+
+(defn scan-error [e] 
+ (def {:line line-num :input input :source source :start start :msg msg} e)
+ (print "Syntax error: " msg)
+ (print "  on line " line-num " in " input ":")
+ (def source-line (get-line source line-num))
+ (print "  >>> " source-line)
+ (print (caret source line-num start))
+ e)
 
 (defn parse-error [e] 
  (def msg (e :msg))
- (def {:line line-num :input input :soure source} (e :token))
+ (def {:line line-num :input input :source source :start start} (e :token))
  (def source-line (get-line source line-num))
- (print "Parsing error: " msg)
- (print "On line " line-num " in " input)
- (print source-line)
+ (print "Syntax error: " msg)
+ (print "  on line " line-num " in " input ":")
+ (print "  >>> " source-line)
+ (print (caret source line-num start))
  e)
 
-
 (defn validation-error [e]
  (def msg (e :msg))
- (def {:line line-num :input input :source source} (get-in e [:node :token]))
+ (def {:line line-num :input input :source source :start start} (get-in e [:node :token]))
  (def source-line (get-line source line-num))
  (case msg
   "unbound name"
   (do
    (print "Validation error: " msg " " (get-in e [:node :data]))
-   (print "on line " line-num " in " input)
-   (print source-line))
+   (print "  on line " line-num " in " input ":")
+   (print "  >>> " source-line)
+   (print (caret source line-num start)))
   (do
    (print "Validation error: " msg)
-   (print "on line " line-num)
-   (print source-line)))
+   (print "  on line " line-num " in " input ":")
+   (print "  >>> " source-line)
+   (print (caret source line-num start))))
  e)
 
 (defn- fn-no-match [e]
  (print "Ludus panicked! no match")
- (def {:line line-num :source source :input input} (get-in e [:node :token]))
+ (def {:line line-num :source source :input input :start start} (get-in e [:node :token]))
  (def source-line (get-line source line-num))
- (print "on line " line-num " in " input)
+ (print "  on line " line-num " in " input ", ")
  (def called (e :called))
- (print "calling " (b/show called))
+ (print "  calling: " (slice (b/show called) 3))
  (def value (e :value))
- (print "with " (b/show value))
- (print "expecting to match one of")
- (print (b/pretty-patterns called))
- (print source-line))
+ (print "  with arguments: " (b/show value))
+ (print "  expected match with one of:")
+ (def patterns (b/pretty-patterns called))
+ (def fmt-patt (do
+  (def lines (string/split "\n" patterns))
+  (def indented (map (fn [x] (string "    " x)) lines))
+  (string/join indented "\n")
+  ))
+ (print fmt-patt)
+ (print "  >>> " source-line)
+ (print (caret source line-num start))
+ )
 
 (defn- let-no-match [e]
  (print "Ludus panicked! no match")
- (def {:line line-num :source source :input input} (get-in e [:node :token]))
+ (def {:line line-num :source source :input input :start start} (get-in e [:node :token]))
  (def source-line (get-line source line-num))
- (print "on line " line-num " in " input)
- (print "binding " (b/show (e :value)))
+ (print "  on line " line-num " in " input ", ")
+ (print "  matching: " (b/show (e :value)))
  (def pattern (get-in e [:node :data 0]))
- (print "to " (b/show-patt pattern))
- (print source-line))
+ (print "  with pattern: " (b/show-patt pattern))
+ (print "  >>> " source-line)
+ (print (caret source line-num start))
+ e)
+
+(defn- match-no-match [e]
+ (print "Ludus panicked! no match")
+ (def {:line line-num :source source :input input :start start} (get-in e [:node :token]))
+ (print "  on line " line-num " in " input ", ")
+ (def value (e :value))
+ (print "  matching: " (b/show value))
+ (print "  with patterns:")
+ (def clauses (get-in e [:node :data 1]))
+ (def patterns (b/pretty-patterns {:body clauses}))
+ (def fmt-patt (do
+  (def lines (string/split "\n" patterns))
+  (def indented (map (fn [x] (string "    " x)) lines))
+  (string/join indented "\n")
+  ))
+ (print fmt-patt)
+ (def source-line (get-line source line-num))
+ (print "  >>> " source-line)
+ (print (caret source line-num start))
+ e)
 
 (defn- generic-panic [e]
  (def msg (e :msg))
- (def {:line line-num :source source :input input} (get-in e [:node :token]))
+ (def {:line line-num :source source :input input :start start} (get-in e [:node :token]))
  (def source-line (get-line source line-num))
  (print "Ludus panicked! " msg)
- (print "on line " line-num " in " input)
- (print source-line))
+ (print "  on line " line-num " in " input ":")
+ (print "  >>> " source-line)
+ (print (caret source line-num start))
+ e)
 
 (defn- unbound-name [e]
- (def {:line line-num :source source :lexeme name :input input} (get-in e [:node :token]))
+ (def {:line line-num :source source :lexeme name :input input :start start} (get-in e [:node :token]))
  (def source-line (get-line source line-num))
  (print "Ludus panicked! unbound name " name)
- (print "on line " line-num " in " input)
- (print source-line))
+ (print "  on line " line-num " in " input ":")
+ (print "  >>> " source-line)
+ (print (caret source line-num start))
+ e)
 
 (defn runtime-error [e]
- (when (= :string (type e)) (print e) (break e))
+ (when (= :string (type e)) 
+  (print (string "Internal Ludus error: " e)) 
+  (print "Please file an issue at https://alea.ludus.dev/twc/ludus/issues")
+  (break e))
  (def msg (e :msg))
  (case msg
   "no match: function call" (fn-no-match e)
   "no match: let binding" (let-no-match e)
+  "no match: match form" (match-no-match e)
+  "no match: when form" (generic-panic e)
   "unbound name" (unbound-name e)
   (generic-panic e))
  e)

src/interpreter.janet

@@ -183,7 +183,7 @@
     :word (match-word pattern value ctx)
 
     # match on equality
-    :nil {:success (nil? value) :ctx ctx}
+    :nil {:success (= :^nil value) :ctx ctx}
     :bool {:success (= data value) :ctx ctx}
     :number {:success (= data value) :ctx ctx}
     :string {:success (= data value) :ctx ctx}
@@ -251,7 +251,9 @@
   (interpret last-line ctx))
 
 (defn- to_string [ctx] (fn [x] 
-  (b/stringify (interpret x ctx))))
+  (if (buffer? x) 
+    (string x)
+    (b/stringify (interpret x ctx)))))
 
 (defn- interpolated [ast ctx]
   (def terms (ast :data))
@@ -343,7 +345,7 @@
         (set (the-dict key) value))))
   the-dict)
 
-(defn- ref [ast ctx]
+(defn- box [ast ctx]
   (def {:data value-ast :name name} ast)
   (def value (interpret value-ast ctx))
   (def box @{:^type :box :^value value :name name})
@@ -421,8 +423,8 @@
   (when (= :function (type clauses))
     (break (clauses root-ast ;args)))
   (def len (length clauses))
-  (when (the-fn :match) (break ((the-fn :match) 0 args)))
-  (defn match-fn [i args]
+  (when (the-fn :match) (break ((the-fn :match) root-ast 0 args)))
+  (defn match-fn [root-ast i args]
     (when (= len i)
       (error {:node root-ast :called the-fn :value args :msg "no match: function call"}))
     (def clause (clauses i))
@@ -430,17 +432,17 @@
     (def match?
       (match-pattern patt args @{:^parent (the-fn :ctx)}))
     (when (not (match? :success)) 
-      (break (match-fn (inc i) args)))
+      (break (match-fn root-ast (inc i) args)))
   #   (print "matched!")
     (def body-ctx (match? :ctx))
     (def guard? (if guard
       (b/bool (interpret guard body-ctx)) true))
   #   (print "passed guard")
     (when (not guard?) 
-      (break (match-fn (inc i) args)))
+      (break (match-fn root-ast (inc i) args)))
     (interpret expr body-ctx))
   (set (the-fn :match) match-fn)
-  (match-fn 0 args))
+  (match-fn root-ast 0 args))
 
 (set call-fn call-fn*)
 
@@ -458,10 +460,12 @@
     [:function :tuple] (call-fn root-ast prev curr)
     # [:applied :tuple] (call-partial root-ast prev curr)
     [:keyword :args] (get (first curr) prev :^nil)
+    [:keyword :tuple] (get (first curr) prev :^nil)
     [:dict :keyword] (get prev curr :^nil)
     [:nil :keyword] :^nil
     [:pkg :keyword] (get prev curr :^nil)
-    [:pkg :pkg-kw] (get prev curr :^nil)))
+    [:pkg :pkg-kw] (get prev curr :^nil)
+    (error (string "cannot call " (b/ludus/type prev) " `" (b/show prev) "`"))))
 
 (defn- synthetic [ast ctx]
   (def terms (ast :data))
@@ -486,9 +490,9 @@
   (def last-term (last terms))
   (for i 1 (-> terms length dec)
     (def curr (interpret (terms i) ctx))
-    (set prev (call-fn (first terms) curr [prev])))
+    (set prev (apply-synth-term (first terms) curr [prev])))
   (def last-fn (interpret last-term ctx))
-  (call-fn (first terms) last-fn [prev]))
+  (apply-synth-term (first terms) last-fn [prev]))
 
 (defn- pkg [ast ctx] 
   (def members (ast :data))
@@ -591,7 +595,7 @@
     # named/naming forms
     :word (word ast ctx)
     :interpolated (interpolated ast ctx)
-    :ref (ref ast ctx)
+    :box (box ast ctx)
     :pkg (pkg ast ctx)
     :pkg-name (word ast ctx)
 
@@ -620,9 +624,9 @@
 (set interpret interpret*)
 
 # # repl
-# (import ./scanner :as s)
-# (import ./parser :as p)
-# (import ./validate :as v) 
+# (import /src/scanner :as s)
+# (import /src/parser :as p)
+# (import /src/validate :as v) 
 
 # (var source nil)
 
@@ -637,14 +641,16 @@
 #   # (when (has-errors? validated) (break (validated :errors)))
 #   # (def cleaned (get-in parsed [:ast :data 1]))
 #   # # (pp cleaned)
-#   # (interpret (parsed :ast) @{:^parent b/ctx})
-#   (try (interpret (parsed :ast) @{:^parent b/ctx})
-#     ([e] (if (struct? e) (error (e :msg)) (error e)))))
+#   (interpret (parsed :ast) @{:^parent b/lett})
+#   # (try (interpret (parsed :ast) @{:^parent b/ctx})
+#   #   ([e] (if (struct? e) (error (e :msg)) (error e))))
+#   )
 
 # # (do 
 # (comment
 # (set source `
-
+# let foo = 42
+# "{foo} bar baz"
 # `)
 # (def result (run))
 # )

src/json.janet

@@ -0,0 +1,131 @@
+# pulled from cfiggers/jayson
+
+(defmacro- letv [bindings & body]
+  ~(do ,;(seq [[k v] :in (partition 2 bindings)] ['var k v]) ,;body))
+
+(defn- read-hex [n] 
+    (scan-number (string "0x" n)))
+
+(defn- check-utf-16 [capture]
+  (let [u (read-hex capture)]
+    (if (and (>= u 0xD800)
+             (<= u 0xDBFF))
+      capture 
+      false)))
+
+(def- utf-8->bytes 
+  (peg/compile
+   ~{:double-u-esc (/ (* "\\u" (cmt (<- 4) ,|(check-utf-16 $)) "\\u" (<- 4))
+                      ,|(+ (blshift (- (read-hex $0) 0xD800) 10)
+                           (- (read-hex $1) 0xDC00) 0x10000))
+     :single-u-esc (/ (* "\\u" (<- 4)) ,|(read-hex $))
+     :unicode-esc  (/ (+ :double-u-esc :single-u-esc)
+                      ,|(string/from-bytes
+                         ;(cond
+                           (<= $ 0x7f) [$]
+                           (<= $ 0x7ff)
+                           [(bor (band (brshift $  6) 0x1F) 0xC0)
+                            (bor (band (brshift $  0) 0x3F) 0x80)]
+                           (<= $ 0xffff)
+                           [(bor (band (brshift $ 12) 0x0F) 0xE0)
+                            (bor (band (brshift $  6) 0x3F) 0x80)
+                            (bor (band (brshift $  0) 0x3F) 0x80)]
+                             # Otherwise
+                           [(bor (band (brshift $ 18) 0x07) 0xF0)
+                            (bor (band (brshift $ 12) 0x3F) 0x80)
+                            (bor (band (brshift $  6) 0x3F) 0x80)
+                            (bor (band (brshift $  0) 0x3F) 0x80)])))
+     :escape       (/ (* "\\" (<- (set "avbnfrt\"\\/")))
+                      ,|(get {"a" "\a" "v" "\v" "b" "\b"
+                              "n" "\n" "f" "\f" "r" "\r"
+                              "t" "\t"} $ $))
+     :main         (+ (some (+ :unicode-esc :escape (<- 1))) -1)}))
+
+(defn decode 
+  ``
+  Returns a janet object after parsing JSON. If `keywords` is truthy,
+  string keys will be converted to keywords. If `nils` is truthy, `null`
+  will become `nil` instead of the keyword `:json/null`.
+  ``
+  [json-source &opt keywords nils] 
+
+  (def json-parser 
+    {:null (if nils
+             ~(/ (<- (+ "null" "Null")) nil)
+             ~(/ (<- (+ "null" "Null")) :json/null))
+     :bool-t ~(/ (<- (+ "true")) true)
+     :bool-f ~(/ (<- (+ "false")) false)
+     :number ~(/ (<- (* (? "-") :d+ (? (* "." :d+)))) ,|(scan-number $))
+     :string ~(/ (* "\"" (<- (to (* (> -1 (not "\\")) "\"")))
+                    (* (> -1 (not "\\")) "\""))
+                 ,|(string/join (peg/match utf-8->bytes $))) 
+     :array ~(/ (* "[" :s* (? (* :value (any (* :s* "," :value)))) "]") ,|(array ;$&))
+     :key-value (if keywords
+                  ~(* :s* (/ :string ,|(keyword $)) :s* ":" :value)
+                  ~(* :s* :string :s* ":" :value))
+     :object ~(/ (* "{" :s* (? (* :key-value (any (* :s* "," :key-value)))) "}")
+                 ,|(from-pairs (partition 2 $&)))
+     :value ~(* :s* (+ :null :bool-t :bool-f :number :string :array :object) :s*)
+     :unmatched ~(/ (<- (to (+ :value -1))) ,|[:unmatched $])
+     :main ~(some (+ :value "\n" :unmatched))})
+  
+  (first (peg/match (peg/compile json-parser) json-source)))
+
+(def- bytes->utf-8
+  (peg/compile
+   ~{:four-byte  (/ (* (<- (range "\xf0\xff")) (<- 1) (<- 1) (<- 1))
+                    ,|(bor (blshift (band (first $0) 0x07) 18)
+                           (blshift (band (first $1) 0x3F) 12)
+                           (blshift (band (first $2) 0x3F) 6)
+                           (blshift (band (first $3) 0x3F) 0)))
+     :three-byte (/ (* (<- (range "\xe0\xef")) (<- 1) (<- 1))
+                    ,|(bor (blshift (band (first $0) 0x0F) 12)
+                           (blshift (band (first $1) 0x3F) 6)
+                           (blshift (band (first $2) 0x3F) 0)))
+     :two-byte   (/ (* (<- (range "\x80\xdf")) (<- 1))
+                    ,|(bor (blshift (band (first $0) 0x1F) 6)
+                           (blshift (band (first $1) 0x3F) 0)))
+     :multi-byte (/ (+ :two-byte :three-byte :four-byte)
+                    ,|(if (< $ 0x10000) 
+                        (string/format "\\u%04X" $)
+                        (string/format "\\u%04X\\u%04X" 
+                                       (+ (brshift (- $ 0x10000) 10) 0xD800) 
+                                       (+ (band (- $ 0x10000) 0x3FF) 0xDC00))))
+     :one-byte   (<- (range "\x20\x7f"))
+     :0to31      (/ (<- (range "\0\x1F"))
+                    ,|(or ({"\a" "\\u0007" "\b" "\\u0008"
+                            "\t" "\\u0009" "\n" "\\u000A"
+                            "\v" "\\u000B" "\f" "\\u000C"
+                            "\r" "\\u000D"} $)
+                          (string/format "\\u%04X" (first $))))
+     :backslash  (/ (<- "\\") "\\\\")
+     :quote      (/ (<- "\"") "\\\"")
+     :main       (+ (some (+ :0to31 :backslash :quote :one-byte :multi-byte)) -1)}))
+
+(defn- encodeone [x depth]
+  (if (> depth 1024) (error "recurred too deeply"))
+  (cond
+    (= x :json/null) "null"
+    (= x nil) "null"
+    (bytes? x) (string "\"" (string/join (peg/match bytes->utf-8 x)) "\"")
+    (indexed? x) (string "[" (string/join (map |(encodeone $ (inc depth)) x) ",") "]")
+    (dictionary? x) (string "{" (string/join
+                                 (seq [[k v] :in (pairs x)]
+                                   (string "\"" (string/join (peg/match bytes->utf-8 k)) "\"" ":" (encodeone v (inc depth)))) ",") "}")
+    (case (type x)
+      :nil "null"
+      :boolean (string x)
+      :number (string x)
+      (error "type not supported"))))
+
+(defn encode 
+  `` 
+  Encodes a janet value in JSON (utf-8). If `buf` is provided, the formated 
+  JSON is append to `buf` instead of a new buffer. Returns the modifed buffer.
+  ``
+  [x &opt buf]
+  
+  (letv [ret (encodeone x 0)]
+        (if (and buf (buffer? buf))
+          (buffer/push ret)
+          (thaw ret))))

src/judge

@@ -1 +0,0 @@
-./jpm_tree/bin/judge

src/ludus.janet

@@ -9,48 +9,98 @@
 (import /src/errors :as e)
 (import /src/base :as b)
 (import /src/prelude :as prelude)
+(import /src/json :as j)
 
 (defn ludus [source]
+ # if we can't load prelude, bail
  (when (= :error prelude/pkg) (error "could not load prelude"))
+
+ # get us a clean working slate
  (def ctx @{:^parent prelude/ctx})
  (def errors @[])
- (def draw @[])
  (var result @"")
  (def console @"")
- (def out @{:errors errors :draw draw :result result :console console})
+
+ # capture all `print`s
+ (setdyn :out console)
+
+ # an output table
+ # this will change: the shape of our output
+ # at the moment, there's only one stack of turtle graphics
+ # we will be getting more
+ (def out @{:errors errors :result result 
+  :io @{
+   :stdout @{:proto [:text-stream "0.1.0"] :data console} 
+   :turtle @{:proto [:turtle-graphics "0.1.0"] :data @[]}}})
+
+ ### start the program
+ # first, scanning
  (def scanned (s/scan source))
  (when (any? (scanned :errors))
-   (set (out :errors) (scanned :errors))
    (each err (scanned :errors)
     (e/scan-error err))
-   (break out))
+   (break (-> out j/encode string)))
+ # then, parsing
  (def parsed (p/parse scanned))
  (when (any? (parsed :errors))
-  (set (out :errors) (parsed :errors))
   (each err (parsed :errors)
    (e/parse-error err))
-  (break out))
+  (break (-> out j/encode string)))
+ # then, validation
  (def validated (v/valid parsed ctx))
  (when (any? (validated :errors))
-  (set (out :errors) (validated :errors))
   (each err (validated :errors)
    (e/validation-error err))
-  (break out))
- (setdyn :out console)
- (try
-  (set result (i/interpret (parsed :ast) ctx))
+  (break (-> out j/encode string)))
+ # and, finally, try interpreting the program
+ (try (do
+  # we need to do this every run or we get the very same sequence of "random" numbers every time we run a program
+  (math/seedrandom (os/cryptorand 8))
+  (set result (i/interpret (parsed :ast) ctx)))
   ([err] 
    (e/runtime-error err)
-   (set (out :errors) [err])
-   (break out)))
+   (break (-> out j/encode string))))
+
+ # stop capturing output
  (setdyn :out stdout)
+
+ # update our output table with our output
  (set (out :result) (b/show result))
- (var post @{})
+ (set (((out :io) :turtle) :data) (get-in prelude/pkg [:turtle_commands :^value]))
+
+ # run the "postlude": any Ludus code that needs to run after each program
+ # right now this is just resetting the boxes that hold turtle commands and state
  (try
-  (set post (i/interpret prelude/post/ast ctx))
+  (i/interpret prelude/post/ast ctx)
   ([err] (e/runtime-error err)))
- (set (out :draw) (post :draw))
- (b/json out))
 
-(defn hello [] (print "hello"))
+ # json-encode our output table, and convert it from a buffer to a string (which we require for playing nice with WASM/C)
+ (-> out j/encode string))
+
+#### REPL
+(comment
+# (do
+ # (def start (os/clock))
+ (def source `
+fd! (100)
+rt! (0.25)
+fd! (100)
+lt! (0.25)
+fd! (100)
+setheading! (0.75)
+unbox (turtle_state)
+ `)
+ (def out (-> source 
+  ludus
+  j/decode
+  ))
+ # (def end (os/clock))
+ (setdyn :out stdout)
+ (pp out)
+ (def console (out "console"))
+ (print console)
+ (def result (out "result"))
+ (print result)
+ # (print (- end start))
+)
 

src/parser.janet

@@ -3,6 +3,9 @@
 ### We still need to scan some things
 (import /src/scanner :as s)
 
+# stash janet type
+(def janet-type type)
+
 (defmacro declare
  "Forward-declares a function name, so that it can be called in a mutually recursive manner."
  [& names]
@@ -18,6 +21,26 @@
   (if-not (dyn name) (error "recursive functions must be declared before they are defined"))
   ~(set ,name (defn- ,name ,;forms)))
 
+### Some more human-readable formatting
+(defn- pp-tok [token]
+ (if (not token) (break "nil"))
+ (def {:line line :lexeme lex :type type :start start} token)
+ (string "<" line "[" start "]" ": " type ": " lex ">"))
+
+(defn- pp-ast [ast &opt indent]
+ (default indent 0)
+ (def {:token token :data data :type type} ast)
+ (def pretty-tok (pp-tok token))
+ (def data-rep (if (= :array (janet-type data))
+  (string "[\n"  
+   (string/join (map (fn [x] (pp-ast x (inc indent))) data) 
+    (string (string/repeat "   " indent) "\n"))
+   "\n" (string/repeat "   " indent) "]")
+  data
+ ))
+ (string (string/repeat "   " indent) type ": " pretty-tok " " data-rep)
+)
+
 ### Next: a data structure for a parser
 (defn- new-parser 
  "Creates a new parser data structure to pass around"
@@ -75,7 +98,9 @@
  (has-value? terminators ttype))
 
 # breakers are what terminate panics
-(def breaking [:break :newline :semicolon :comma :eof :then :else])
+(def breaking [:break :newline :semicolon :comma :eof 
+# :then :else :arrow
+])
 
 (defn- breaks? 
  "Returns true if the current token in the parser should break a panic"
@@ -89,12 +114,12 @@
  [parser message]
 #  (print "Panic in the parser: " message)
  (def origin (current parser))
- (advance parser)
- (def skipped @[origin])
+ (def skipped @[])
  (while (not (breaks? parser))
   (array/push skipped (current parser))
   (advance parser))
  (array/push skipped (current parser))
+ # (advance parser)
  (def err {:type :error :data skipped :token origin :msg message})
  (update parser :errors array/push err)
  (error err))
@@ -279,8 +304,10 @@
  (def origin (current parser))
  (advance parser) # consume the :lparen
  (def ast @{:type :args :data @[] :token origin :partial false})
- (while (separates? parser) (advance parser)) # consume any separators
  (while (not (check parser :rparen))
+  (accept-many parser :newline :comma)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
   (when (check parser :eof)
    (def err {:type :error :token origin :msg "unclosed paren"})
    (array/push (parser :errors) err)
@@ -299,8 +326,7 @@
      {:type :placeholder :token origin}))
    (capture nonbinding parser)))
   (array/push (ast :data) term)
-  (try (separators parser) 
-   ([e] (array/push (ast :data) e))))
+  (capture separators parser))
  (advance parser)
  ast)
 
@@ -333,20 +359,26 @@
  {:type :synthetic :data [;terms] :token origin})
 
 # collections
+### XXX: the current panic/capture structure in this, script, etc. is blowing up when the LAST element (line, tuple member, etc.) has an error
+# it does, however, work perfectly well when there isn't one
+# there's something about advancing past the breaking token, or not
+# aslo, I removed the captures here around nonbinding and separators, and we got into a loop with a panic
+# oy
 (defn- tup [parser]
  (def origin (current parser))
  (advance parser) # consume the :lparen
  (def ast {:type :tuple :data @[] :token origin})
- (while (separates? parser) (advance parser)) # consume any separators
  (while (not (check parser :rparen))
+  (accept-many parser :newline :comma)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
   (when (check parser :eof)
    (def err {:type :error :token origin :msg "unclosed paren"})
    (array/push (parser :errors) err)
    (error err))
   (def term (capture nonbinding parser))
   (array/push (ast :data) term)
-  (try (separators parser) 
-   ([e] (array/push (ast :data) e))))
+  (capture separators parser))
  (advance parser)
  ast)
 
@@ -354,8 +386,10 @@
  (def origin (current parser))
  (advance parser)
  (def ast {:type :list :data @[] :token origin})
- (while (separates? parser) (advance parser))
  (while (not (check parser :rbracket))
+  (accept-many parser :newline :comma)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
   (when (check parser :eof)
    (def err {:type :error :token origin :msg "unclosed bracket"})
    (array/push (parser :errors) err)
@@ -369,8 +403,7 @@
    )
    (capture nonbinding parser)))
   (array/push (ast :data) term)
-  (try (separators parser)
-   ([e] (array/push (ast :data) e))))
+  (capture separators parser))
  (advance parser)
  ast)
 
@@ -378,8 +411,10 @@
  (def origin (current parser))
  (advance parser)
  (def ast {:type :set :data @[] :token origin})
- (while (separates? parser) (advance parser))
  (while (not (check parser :rbrace))
+  (accept-many parser :newline :comma)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
   (when (check parser :eof)
    (def err {:type :error :token origin :msg "unclosed brace"})
    (array/push (parser :errors) err)
@@ -393,8 +428,7 @@
    )
    (capture nonbinding parser)))
   (array/push (ast :data) term)
-  (try (separators parser)
-   ([e] (array/push (ast :data) e))))
+  (capture separators parser))
  (advance parser)
  ast)
 
@@ -402,8 +436,10 @@
  (def origin (current parser))
  (advance parser)
  (def ast {:type :dict :data @[] :token origin})
- (while (separates? parser) (advance parser))
  (while (not (check parser :rbrace))
+  (accept-many parser :newline :comma)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
   (when (check parser :eof)
    (def err {:type :error :token origin :msg "unclosed brace"})
    (array/push (parser :errors) err)
@@ -423,7 +459,7 @@
    (try (panic parser (string "expected dict term, got " (type origin))) ([e] e))
   ))
   (array/push (ast :data) term)
-  (try (separators parser) ([e] (array/push (ast :data) e))))
+  (capture separators parser))
  (advance parser)
  ast)
 
@@ -452,8 +488,10 @@
  (def origin (current parser))
  (advance parser) # consume the :lparen
  (def ast {:type :tuple :data @[] :token origin})
- (while (separates? parser) (advance parser)) # consume any separators
  (while (not (check parser :rparen))
+  (accept-many parser :newline :comma)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
   (when (check parser :eof)
    (def err {:type :error :token origin :msg "unclosed paren"})
    (array/push (parser :errors) err)
@@ -466,8 +504,7 @@
     {:type :splat :data splatted :token origin})
    (capture pattern parser)))
   (array/push (ast :data) term)
-  (try (separators parser) 
-   ([e] (array/push (ast :data) e))))
+  (capture separators parser))
  (advance parser)
  ast)
 
@@ -475,8 +512,10 @@
  (def origin (current parser))
  (advance parser)
  (def ast {:type :list :data @[] :token origin})
- (while (separates? parser) (advance parser))
  (while (not (check parser :rbracket))
+  (accept-many parser :newline :comma)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
   (when (check parser :eof)
    (def err {:type :error :token origin :msg "unclosed bracket"})
    (array/push (parser :errors) err)
@@ -489,8 +528,7 @@
     {:type :splat :data splatted :token origin})
    (capture pattern parser)))
   (array/push (ast :data) term)
-  (try (separators parser)
-   ([e] (array/push (ast :data) e))))
+  (capture separators parser))
  (advance parser)
  ast)
 
@@ -498,8 +536,10 @@
  (def origin (current parser))
  (advance parser)
  (def ast {:type :dict :data @[] :token origin})
- (while (separates? parser) (advance parser))
  (while (not (check parser :rbrace))
+  (accept-many parser :newline :comma)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
   (when (check parser :eof)
    (def err {:type :error :token origin :msg "unclosed brace"})
    (array/push (parser :errors) err)
@@ -519,7 +559,7 @@
    (try (panic parser (string "expected dict term, got " (type origin))) ([e] e))
   ))
   (array/push (ast :data) term)
-  (try (separators parser) ([e] (array/push (ast :data) e))))
+  (capture separators parser))
  (advance parser)
  ast)
  
@@ -560,22 +600,25 @@
 (defn- iff [parser]
  (def ast {:type :if :data @[] :token (current parser)})
  (advance parser) #consume the if
- (array/push (ast :data) (capture simple parser))
+ (array/push (ast :data) (simple parser))
  (accept-many parser :newline)
  (if-let [err (expect-ret parser :then)] 
   (array/push (ast :data) err) 
   (advance parser))
- (array/push (ast :data) (capture nonbinding parser))
+ (array/push (ast :data) (nonbinding parser))
  (accept-many parser :newline)
  (if-let [err (expect-ret parser :else)] 
   (array/push (ast :data) err)
   (advance parser))
- (array/push (ast :data) (capture nonbinding parser))
+ (array/push (ast :data) (nonbinding parser))
  ast)
 
+(defn- literal-terminator? [token]
+ (def tok-type (token :type))
+ (or (= :newline tok-type) (= :semicolon tok-type)))
+
 (defn- terminator [parser]
  (if-not (terminates? parser) 
-  # this line panics, captures the panic, advances the parser, and re-throws the error; solves an off-by-one error
   (panic parser "expected terminator"))
  (advance parser)
  (while (terminates? parser) (advance parser)))
@@ -798,13 +841,15 @@
 (defn- block [parser]
  (def origin (current parser))
  (expect parser :lbrace) (advance parser)
- (accept-many parser ;terminators)
  (def data @[])
  (while (not (check parser :rbrace))
+  (accept-many parser :newline :semicolon)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
   (if (check parser :eof)
    (error {:type :error :token origin :data data :msg "unclosed brace"}))
   (array/push data (capture expr parser))
-  (terminator parser))
+  (capture terminator parser))
  (advance parser)
  {:type :block :data data :token origin})
 
@@ -826,16 +871,16 @@
   (array/push data (capture simple parser)))
  {:type :do :data data :token origin})
 
-### refs, pkgs, nses, etc.
-(defn- ref [parser]
+### boxs, pkgs, nses, etc.
+(defn- box [parser]
  (def origin (current parser))
- (expect parser :ref) (advance parser)
+ (expect parser :box) (advance parser)
  (try
   (do
    (def name (-> parser word-only (get :data)))
    (expect parser :equals) (advance parser)
    (def value (nonbinding parser))
-   {:type :ref :data value :name name :token origin})
+   {:type :box :data value :name name :token origin})
   ([err] err)))
 
 (defn- pkg-name [parser]
@@ -966,7 +1011,7 @@
 ### expressions
 # four levels of expression complexity:
 # simple (atoms, collections, synthetic expressions; no conditionals or binding or blocks)
-# nonbinding (excludes let, ref, named fn: what is allowed inside collections)
+# nonbinding (excludes let, box, named fn: what is allowed inside collections)
 # plain old exprs (anything but toplevel)
 # toplevel (exprs + ns, pkg, test, import, use)
 
@@ -1054,7 +1099,7 @@
   # binding forms
   :let (lett parser)
   :fn (fnn parser)
-  :ref (ref parser)
+  :box (box parser)
 
   # nonbinding forms
   :nil (nill parser)
@@ -1103,8 +1148,12 @@
  (def origin (current parser))
  (def lines @[])
  (while (not (check parser :eof))
-  (accept-many parser :newline)
-  (array/push lines (capture toplevel parser))
+  # (print "starting script loop with " (pp-tok origin))
+  (accept-many parser :newline :semicolon)
+  (when (= :break ((current parser) :type))
+   (break (advance parser)))
+  (def term (capture toplevel parser))
+  (array/push lines term)
   (capture terminator parser))
  {:type :script :data lines :token origin})
 
@@ -1116,10 +1165,17 @@
 
 # (do
 (comment
-(def source `...
+(def source `
+{
+ foo bar
+ quux frobulate
+ baz
+ 12 23 42
+}
 `)
 (def scanned (s/scan source))
 # (print "\n***NEW PARSE***\n")
-(def a-parser (new-parser scanned))
-(def parsed (splat a-parser))
+(def parsed (parse scanned)) 
+(pp (map (fn [err] (err :msg)) (parsed :errors)))
+(print (pp-ast (parsed :ast)))
 )

src/prelude.janet

@@ -39,3 +39,4 @@
   (def validation-errors (post-validated :errors))
   (when (any? validation-errors) (each err validation-errors (e/validation-error err)) (break :error))
   (post-parsed :ast)))
+

src/scanner.janet

@@ -1,8 +1,9 @@
 (def reserved-words
   "List of Ludus reserved words."
   ## see ludus-spec repo for more info
-  {"as" :as ## impl
-   "box" :ref
+  {
+   "as" :as ## impl
+   "box" :box
    "do" :do ## impl
    "else" :else ## impl
    "false" :false ## impl -> literal word
@@ -17,13 +18,13 @@
    "panic!" :panic ## impl (should _not_ be a function)
    "pkg" :pkg
    "recur" :recur ## impl   
+   "repeat" :repeat ## impl
+   "test" :test
    "then" :then ## impl
    "true" :true ## impl -> literal word
    "use" :use ## wip
-   "with" :with ## impl
    "when" :when ## impl, replaces cond
-   "repeat" :repeat ## syntax sugar over "loop": still unclear what this syntax could be
-   "test" :test
+   "with" :with ## impl  
   })
 
 (def literal-words {"true" true
@@ -154,7 +155,7 @@
                :start (get scanner :start)
                :source (get scanner :source)
                :input (get scanner :input)
-               :message msg}]
+               :msg msg}]
     (-> scanner
       (update :errors array/push token)
       (update :tokens array/push token))))
@@ -194,6 +195,15 @@
         :else (add-error scanner (string "Unexpected " curr " after number " num ".")))))
   (recur scanner (buffer char) false))
 
+(def escape {
+  "\"" "\""
+  "n" "\n"
+  "{" "{"
+  "t" "\t"
+  "r" "\r"
+  "\\" "\\"
+})
+
 (defn- add-string
   [scanner]
   (defn recur [scanner buff interpolate?]
@@ -204,12 +214,10 @@
         "\n" (recur (update (advance scanner) :line inc) (buffer/push buff char) interpolate?)
         "\"" (add-token (advance scanner) (if interpolate? :interpolated :string) (string buff))
         "\\" (let [next (next-char scanner)]
-                (if (= next "{") 
-                  (do
-                    (buffer/push buff char)
-                    (buffer/push buff next)
-                    (recur (advance (advance scanner)) buff interpolate?))
-                  (recur (advance scanner) (buffer/push buff char) interpolate?))) 
+                (recur 
+                  (advance (advance scanner)) 
+                  (buffer/push buff (get escape next next))
+                  interpolate?))
         (if (at-end? scanner)
           (add-error scanner "Unterminated string.")
           (recur (advance scanner) (buffer/push buff char) interpolate?)))))
@@ -341,3 +349,7 @@
       (recur (-> scanner (scan-token) (next-token)))))
   (recur (new-scanner source input)))
 
+# (comment
+(do
+  (def source "    -123  ")
+  (length ((scan source) :tokens)))

src/validate.janet

@@ -74,6 +74,10 @@ Deferred until a later iteration of Ludus:
 (defn- block [validator]
  (def ast (validator :ast))
  (def data (ast :data))
+ (when (= 0 (length data))
+  (array/push (validator :errors)
+   {:node ast :msg "blocks may not be empty"})
+  (break validator))
  (def status (validator :status))
  (set (status :toplevel) nil)
  (def tail? (status :tail))
@@ -98,6 +102,11 @@ Deferred until a later iteration of Ludus:
  (def node (get ctx name))
  (if node node (resolve-name (get ctx :^parent) name)))
 
+(defn- resolve-name-in-script [ctx name]
+ (when (ctx :^toplevel) (break nil))
+ (def node (ctx name))
+ (if node node (resolve-name-in-script (ctx :^parent) name)))
+
 (defn- word [validator]
  (def ast (validator :ast))
  (def name (ast :data))
@@ -153,10 +162,12 @@ Deferred until a later iteration of Ludus:
  (def ast (validator :ast))
  (def name (ast :data))
  (def ctx (validator :ctx))
- (when (has-key? ctx name)
-  (def {:line line :input input} (get-in ctx [name :token]))
+ ### XXX TODO: this resolution should ONLY be for userspace, NOT prelude
+ (def resolved (resolve-name-in-script ctx name))
+ (when resolved
+  (def {:line line :input input} resolved)
   (array/push (validator :errors)
-   {:node ast :msg (string "name is already bound on line "
+   {:node ast :msg (string "name " name " is already bound on line "
     line " of " input)}))
  (set (ctx name) ast)
  # (pp ctx)
@@ -332,7 +343,7 @@ Deferred until a later iteration of Ludus:
  (set (ast :arities) arities)
  validator)
 
-(defn- ref [validator]
+(defn- box [validator]
  (def ast (validator :ast))
  (def ctx (validator :ctx))
  (def expr (ast :data))
@@ -431,12 +442,12 @@ Deferred until a later iteration of Ludus:
  (def rest-arities (keys (arities :rest)))
  (when (empty? rest-arities)
   (array/push (validator :errors)
-   {:node ast :msg "mismatched arity"})
+   {:node ast :msg "wrong number of arguments"})
   (break validator))
  (def rest-min (min ;rest-arities))
  (when (< num-args rest-min)
   (array/push (validator :errors)
-   {:node ast :msg "mismatched arity"}))
+   {:node ast :msg "wrong number of arguments"}))
  validator)
 
 (defn- kw-root [validator]
@@ -746,7 +757,7 @@ Deferred until a later iteration of Ludus:
    :use (usee validator)
    :loop (loopp validator)
    :recur (recur validator)
-   :ref (ref validator)
+   :box (box validator)
    (error (string "unknown node type " type)))))
 
 (set validate validate*)
@@ -754,12 +765,13 @@ Deferred until a later iteration of Ludus:
 (defn- cleanup [validator]
  (def declared (get-in validator [:status :declared] {}))
  (when (any? declared)
-  (each declaration declared
+  (each declaration (keys declared)
    (array/push (validator :errors) {:node declaration :msg "declared fn, but not defined"})))
  validator)
 
 (defn valid [ast &opt ctx]
  (default ctx @{})
+ (set (ctx :^toplevel) true)
  (def validator (new-validator ast))
  (def base-ctx @{:^parent ctx})
  (set (validator :ctx) base-ctx)

turtle-graphics.md

@@ -0,0 +1,92 @@
+# Turtle Graphics protocol
+
+name: "turtle-graphics"
+
+version: 0.1.0
+
+### Description
+Turtle graphics describe the movements and drawing behaviours of screen, robot, and print "turtles."
+* `proto`: `["turtle-graphics", "{version number}"]`
+* `data`: an array of arrays; each array represents a turtle command; the first element of a command array is the verb; any subsequent items are the arguments to the verbs.
+* Valid arguments are numbers, strings, and booleans.
+* Depending on what we end up doing, we may add arrays of these, representing tuples or lists, and/or objects with string keys whose text are well-formed keywords in Ludus. For now, however, arguments must be atomic values.
+* E.g., `["forward", 100]`
+* Each turtle has its own stream.
+* At current, this protocol describes the behaviour of turtle-like objects, all of which "live" in the same "world"; there is not yet a provision for multiple canvases/worlds. That said, an additional field for "world" in at the top level may well be added in the future to allow for multiple worlds to unfold at the same time.
+
+### Verbs and arguments
+* `forward`, steps: number
+  - Moves the turtle forward by the number of steps/pixels.
+* `back`, steps: number
+  - Moves the turtle backwards by the number of steps/pixels.
+* `right`, turns: number
+  - Turns the turtle right by the number of turns. (1 turn = 360 degrees.)
+* `left`, turns: number
+  - Turns the turtle to the left by the number of turns. (1 turn = 360 degrees.)
+* `penup`, no arguments
+  - "Lifts" the turtle's pen, keeping it from drawing.
+* `pendown`, no arguments
+  - "Lowers" the turtle's pen, starting it drawing a path.
+* `pencolor`, red: number, green: number, blue: number, alpha: number, OR: color: string
+  - Sets the turtle's pen's color to the specified RGBA color.
+* `penwidth`, width: number
+  - Sets the width of the turtle's pen, in pixels (or some other metric).
+* `home`, no arguments
+  - Sends the turtle back to its starting point, with a heading of 0.
+* `goto`, x: number, y: number
+  - Sends the turtle to the specified Cartesian coordinates, where the origin is the turtle's starting position.
+* `setheading`, heading: number
+  - Sets the turtle's heading. 0 is the turtle's starting heading, with increasing numbers turning to the right.
+* `show`, no arguments
+  - Shows the turtle.
+* `hide`, no arguments
+  - Hides the turtle.
+* `loadstate`, x: number, y: number, heading: number, visible: boolean, pendown: boolean, width: number, color: string OR r: number, g: number, b: number, a: number
+  - Loads a turtle state.
+* `clear`, no arguments
+  - Erases any paths drawn and sets the background color to the default.
+* `background`, red: number, green: number, blue: number, alpha: number
+  - Sets the background color to the specified RGBA color, OR: color: string
+
+These last two feel a little weird to me, since the background color is more the property of the **world** the turtle is in, not the turtle itself. Worlds with multiple turtles will be set up so that _any_ turtle will be able to change the background, and erase all paths.
+
+That said, since we don't yet have a world abstraction/entity, then there's no other place to put them. This will likely be shifted around in later versions of the protocol.
+
+### Other considerations
+**Not all turtles will know how to do all these things.**
+The idea is that this single abstraction will talk to all the turtle-like things we eventually use.
+That means that some turtles won't be able to do all the things; that's fine! 
+They just won't do things they can't do; but warnings should go to `stderr`.
+
+**Errors are not passed back to Ludus.** 
+These are fire-off commands.
+Errors should be _reported_ to `stderr` or equivalent.
+But Ludus sending things to its output streams should only cause Ludus panics when there's an issue in Ludus.
+
+**Colors aren't always RGBA.**
+For pen-and-paper turtles, we don't have RGBA colors.
+Colors should also be specifiable with strings corresponding to CSS basic colors: black, silver, gray, white, maroon, red, purple, fuchsia, green, lime, olive, yellow, navy, blue, teal, and aqua.
+
+**Turtles should communicate states.** 
+Ludus should have access to turtle states.
+This is important for push/pop situations that we use for L-systems.
+There are two ways to do this: Ludus does its own bookkeeping for turtle states, or it has a way to get the state from a turtle.
+
+The latter has the value of being instantaneous, and gives us an _expected_ state of the turtle after the commands are all processed.
+In particular, this will be necessary for the recursive L-systems that require pushing and popping turtle state.
+The latter has the drawback of potentially allowing the turtle state and expected turtle state to fall out of synch.
+
+The former has the value of always giving us the correct, actual state of the turtle.
+It has the drawback of requiring such state reporting to be asynchronous, and perhaps wildly asynchronous, as things like moving robots and plotters will take quite some time to actually draw what Ludus tells it to.
+(Being able to wait until `eq? (expected, actual)` to do anything else may well be extremely useful.)
+
+That suggests, then, that both forms of turtle state are desirable and necessary.
+Thus: turtles should communicate states (and thus there ought to be a protocol for communicating state back to Ludus) and Ludus should always do the bookkeeping of calculating the expected state.
+
+**Turtles use Cartesian, rather than screen, coordinates.** 
+The starting position of the turtle is `(0, 0)`, which is the origin, and _centred_ in the field of view. 
+Increasing the x-coordinate moves the turtle to the right; increasing the y-coordinate moves the turtle _up_.
+
+**Turtles use compass headings, not mathematical angles.**
+Turtles start pointing vertially, at heading `0`.
+Turning right _increases_ the heading; pointing due "east" is `0.25`; south `0.5`, and west, `0.75`.