Lumen: A Lisp for Lua and JavaScript
Right! I&#x27;ve been waiting a couple years for Lumen to get some traction. <i>cracks knuckles</i><p>Before I blather on about why it&#x27;s worth paying attention to, why don&#x27;t I just show you an implementation of the classic Trusting Trust paper:<p><a href="https:&#x2F;&#x2F;www.archive.ece.cmu.edu&#x2F;~ganger&#x2F;712.fall02&#x2F;papers&#x2F;p761-thompson.pdf" rel="nofollow">https:&#x2F;&#x2F;www.archive.ece.cmu.edu&#x2F;~ganger&#x2F;712.fall02&#x2F;papers&#x2F;p7...</a><p>We&#x27;ll implement this ourselves. Let&#x27;s dive right in. Start off by cloning Lumen.<p><pre><code>  $ git clone https:&#x2F;&#x2F;github.com&#x2F;sctb&#x2F;lumen
  $ cd lumen
  $ git checkout aedf2fd2c209bfc7926e0d4eae4becd8a647fb80
  $ vim main.l
</code></pre>
(Commit aedf2fd is just the latest commit at the time of this writing. I make it explicit here so that anyone can follow along in the future.)<p>Now that main.l is open, we begin by defining a global function `read-file` that simply returns a file as a string:<p><pre><code>  (define-global read-file (path)
    ((get system &#x27;read-file) path))
</code></pre>
If you run `make &amp;&amp; bin&#x2F;lumen`, you&#x27;ll see the function is now defined when Lumen starts:<p><pre><code>  &gt; read-file
  function

  &gt; (read-file &quot;README.md&quot;)
  &quot;Lumen\n=\nLumen is a very small, self-hosted Lisp for Lua and JavaScript. It provides a flexible compilation environment with an extensible reader, macros, and extensible special forms, but otherwise attempts...&quot;
</code></pre>
Now we define `read-from-file`, which reads Lumen source code and returns it as a form that can be evaluated:<p><pre><code>  (define-global read-from-file (path)
    (let (s ((get reader &#x27;stream) (read-file path))
          body ((get reader &#x27;read-all) s))
      `(do ,@body)))

  &gt; (read-from-file &quot;reader.l&quot;)
  (&quot;do&quot; (&quot;define&quot; &quot;delimiters&quot; (&quot;set-of&quot; &quot;\&quot;(\&quot;&quot; &quot;\&quot;)\&quot;&quot; &quot;\&quot;;\&quot;&quot; &quot;\&quot;\\r\&quot;&quot; &quot;\&quot;\\n\&quot;&quot;)) ...
</code></pre>
Those are the forms defined in reader.l: <a href="https:&#x2F;&#x2F;github.com&#x2F;sctb&#x2F;lumen&#x2F;blob&#x2F;aedf2fd2c209bfc7926e0d4eae4becd8a647fb80&#x2F;reader.l#L1" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;sctb&#x2F;lumen&#x2F;blob&#x2F;aedf2fd2c209bfc7926e0d4ea...</a><p>Let&#x27;s step through the forms and print them.<p><pre><code>  &gt; (step x (read-from-file &quot;reader.l&quot;)
      (print (str x)))
  &quot;do&quot;
  (&quot;define&quot; &quot;delimiters&quot; (&quot;set-of&quot; &quot;\&quot;(\&quot;&quot; &quot;\&quot;)\&quot;&quot; &quot;\&quot;;\&quot;&quot; &quot;\&quot;\\r\&quot;&quot; &quot;\&quot;\\n\&quot;&quot;))
  (&quot;define&quot; &quot;whitespace&quot; (&quot;set-of&quot; &quot;\&quot; \&quot;&quot; &quot;\&quot;\\t\&quot;&quot; &quot;\&quot;\\r\&quot;&quot; &quot;\&quot;\\n\&quot;&quot;))
  (&quot;define&quot; &quot;stream&quot; (&quot;str&quot; &quot;more&quot;) (&quot;obj&quot; more: &quot;more&quot; pos: 0 len: (&quot;#&quot; &quot;str&quot;) string: &quot;str&quot;))
  (&quot;define&quot; &quot;peek-char&quot; (&quot;s&quot;) (&quot;let&quot; ((pos: true len: true string: true) &quot;s&quot;) (&quot;when&quot; (&quot;&lt;&quot; &quot;pos&quot; &quot;len&quot;) (&quot;char&quot; &quot;string&quot; &quot;pos&quot;))))
  (&quot;define&quot; &quot;read-char&quot; (&quot;s&quot;) (&quot;let&quot; &quot;c&quot; (&quot;peek-char&quot; &quot;s&quot;) (&quot;if&quot; &quot;c&quot; (&quot;do&quot; (&quot;inc&quot; (&quot;get&quot; &quot;s&quot; (&quot;quote&quot; &quot;pos&quot;))) &quot;c&quot;))))
  ...
</code></pre>
Pretty good! We&#x27;re already doing some basic compiler-type stuff. That&#x27;s Lumen&#x27;s power: It&#x27;s a flexible compiler. (IMO one of the finest in the world due to its simplicity.)<p>Now, what can we do with these forms? Well, we can expand them:<p><pre><code>  &gt; (step x (expand (read-from-file &quot;reader.l&quot;))
      (print (str x)))
  &quot;do&quot;
  (&quot;%local&quot; &quot;delimiters&quot; (&quot;%object&quot; &quot;\&quot;(\&quot;&quot; true &quot;\&quot;)\&quot;&quot; true &quot;\&quot;;\&quot;&quot; true &quot;\&quot;\\n\&quot;&quot; true &quot;\&quot;\\r\&quot;&quot; true))
  (&quot;%local&quot; &quot;whitespace&quot; (&quot;%object&quot; &quot;\&quot;\\r\&quot;&quot; true &quot;\&quot; \&quot;&quot; true &quot;\&quot;\\n\&quot;&quot; true &quot;\&quot;\\t\&quot;&quot; true))
  (&quot;%local-function&quot; &quot;stream&quot; (&quot;str&quot; &quot;more&quot;) (&quot;return&quot; (&quot;%object&quot; &quot;\&quot;more\&quot;&quot; &quot;more&quot; &quot;\&quot;pos\&quot;&quot; 0 &quot;\&quot;len\&quot;&quot; (&quot;#&quot; &quot;str&quot;) &quot;\&quot;string\&quot;&quot; &quot;str&quot;)))
  (&quot;%local-function&quot; &quot;peek-char&quot; (&quot;s&quot;) (&quot;do&quot; (&quot;%local&quot; &quot;____id&quot; &quot;s&quot;) (&quot;%local&quot; &quot;__pos&quot; (&quot;get&quot; &quot;____id&quot; &quot;\&quot;pos\&quot;&quot;))
  ...
</code></pre>
We can compile them:<p><pre><code>  &gt; (print (compile (expand (read-from-file &quot;reader.l&quot;))))
  local delimiters = {[&quot;(&quot;] = true, [&quot;)&quot;] = true, [&quot;;&quot;] = true, [&quot;\n&quot;] = true, [&quot;\r&quot;] = true}
  local whitespace = {[&quot;\r&quot;] = true, [&quot; &quot;] = true, [&quot;\n&quot;] = true, [&quot;\t&quot;] = true}
  local function stream(str, more)
    return {more = more, pos = 0, len = _35(str), string = str}
  end
  local function peek_char(s)
    local ____id9 = s
    local __pos6 = ____id9.pos
    local __len3 = ____id9.len
    local __string3 = ____id9.string
    if __pos6 &lt; __len3 then
      return char(__string3, __pos6)
    end
  end
  local function read_char(s)
    local __c21 = peek_char(s)
    if __c21 then
      s.pos = s.pos + 1
      return __c21
    end
  end
  ...
</code></pre>
And we can switch languages:<p><pre><code>  &gt; (set target &#x27;js)
  &quot;js&quot;
  &gt; (print (compile (expand (read-from-file &quot;reader.l&quot;))))
  var delimiters = {&quot;(&quot;: true, &quot;)&quot;: true, &quot;;&quot;: true, &quot;\n&quot;: true, &quot;\r&quot;: true};
  var whitespace = {&quot;\r&quot;: true, &quot; &quot;: true, &quot;\n&quot;: true, &quot;\t&quot;: true};
  var stream = function (str, more) {
    return {more: more, pos: 0, len: _35(str), string: str};
  };
  var peek_char = function (s) {
    var ____id12 = s;
    var __pos8 = ____id12.pos;
    var __len4 = ____id12.len;
    var __string4 = ____id12.string;
    if (__pos8 &lt; __len4) {
      return char(__string4, __pos8);
    }
  };
  var read_char = function (s) {
    var __c28 = peek_char(s);
    if (__c28) {
      s.pos = s.pos + 1;
      return __c28;
    }
  };
  ...
</code></pre>
Ok, on to the cool stuff.<p>Make a file called lumen.l:<p><pre><code>  (when-compiling
    `(do ,(read-from-file &quot;runtime.l&quot;)
         ,(read-from-file &quot;macros.l&quot;)
         ,(read-from-file &quot;main.l&quot;)))
</code></pre>
English translation: &quot;When compiling, read the forms from runtime.l, macros.l, and main.l, join them together, then compile the result.&quot;<p>Let&#x27;s compile this file and see what happens:<p><pre><code>  $ bin&#x2F;lumen -c lumen.l
  environment = {{}}
  target = &quot;lua&quot;
  function nil63(x)
    return x == nil
  end
  function is63(x)
    return not nil63(x)
  end
  function no(x)
    return nil63(x) or x == false
  end
  function yes(x)
    return not no(x)
  end
  function either(x, y)
    if is63(x) then
      return x
    else
      return y
    end
  end
  ...
</code></pre>
Presto! We get bin&#x2F;lumen.lua: <a href="https:&#x2F;&#x2F;github.com&#x2F;sctb&#x2F;lumen&#x2F;blob&#x2F;aedf2fd2c209bfc7926e0d4eae4becd8a647fb80&#x2F;bin&#x2F;lumen.lua#L1" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;sctb&#x2F;lumen&#x2F;blob&#x2F;aedf2fd2c209bfc7926e0d4ea...</a><p>Why does it generate Lua? Because on my system, Lumen happens to default to running on LuaJIT, and the host language is the default. If Lua wasn&#x27;t installed on your system, you&#x27;d be seeing JS instead.<p>To get a specific language, pass the `-t` parameter:<p><pre><code>  $ bin&#x2F;lumen -c lumen.l -t js
  environment = [{}];
  target = &quot;js&quot;;
  nil63 = function (x) {
    return x === undefined || x === null;
  };
  is63 = function (x) {
    return ! nil63(x);
  };
  no = function (x) {
    return nil63(x) || x === false;
  };
  yes = function (x) {
    return ! no(x);
  };
  either = function (x, y) {
    if (is63(x)) {
      return x;
    } else {
      return y;
    }
  };
  ...
</code></pre>
That gives us bin&#x2F;lumen.js: <a href="https:&#x2F;&#x2F;github.com&#x2F;sctb&#x2F;lumen&#x2F;blob&#x2F;aedf2fd2c209bfc7926e0d4eae4becd8a647fb80&#x2F;bin&#x2F;lumen.js" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;sctb&#x2F;lumen&#x2F;blob&#x2F;aedf2fd2c209bfc7926e0d4ea...</a><p>Let&#x27;s simplify the makefile. Open makefile in your edior and replace it with this:<p><pre><code>  .PHONY: all clean test

  LUMEN_LUA  ?= lua
  LUMEN_NODE ?= node
  LUMEN_HOST ?= $(LUMEN_LUA)

  LUMEN := LUMEN_HOST=&quot;$(LUMEN_HOST)&quot; bin&#x2F;lumen

  MODS := bin&#x2F;lumen.x	\
    bin&#x2F;reader.x	\
    bin&#x2F;compiler.x	\
    bin&#x2F;system.x

  all: $(MODS:.x=.js) $(MODS:.x=.lua)

  clean:
    @git checkout bin&#x2F;*.js
    @git checkout bin&#x2F;*.lua
    @rm -f obj&#x2F;*

  bin&#x2F;%.js : %.l
    @echo $@
    @$(LUMEN) -c $&lt; -o $@ -t js

  bin&#x2F;%.lua : %.l
    @echo $@
    @$(LUMEN) -c $&lt; -o $@ -t lua

  test: all
    @echo js:
    @LUMEN_HOST=$(LUMEN_NODE) .&#x2F;test.l
    @echo lua:
    @LUMEN_HOST=$(LUMEN_LUA) .&#x2F;test.l
</code></pre>
Try it out:<p><pre><code>  $ make -B test
  bin&#x2F;lumen.js
  bin&#x2F;reader.js
  bin&#x2F;compiler.js
  bin&#x2F;system.js
  bin&#x2F;lumen.lua
  bin&#x2F;reader.lua
  bin&#x2F;compiler.lua
  bin&#x2F;system.lua
  js:
   647 passed, 0 failed
  lua:
   647 passed, 0 failed
</code></pre>
Perfect. Our new lumen.l file fits into the compiler pipeline nicely.<p>It may not seem like it, but we now have a tool of remarkable power. Let&#x27;s see why.<p>Open lumen.l back up. We recall it looks like this:<p><pre><code>  (when-compiling
    `(do ,(read-from-file &quot;runtime.l&quot;)
         ,(read-from-file &quot;macros.l&quot;)
         ,(read-from-file &quot;main.l&quot;)))
</code></pre>
Let me show you what makes Lumen special. Change lumen.l to this:<p><pre><code>  (define-global %lumen ()
    (when-compiling
      `&#x27;(do ,(read-from-file &quot;runtime.l&quot;)
            ,(read-from-file &quot;macros.l&quot;)
            ,(read-from-file &quot;main.l&quot;))))

  (when-compiling
    `(do ,(read-from-file &quot;runtime.l&quot;)
         ,(read-from-file &quot;macros.l&quot;)
         ,(read-from-file &quot;main.l&quot;)))
</code></pre>
then compile:<p><pre><code>  $ make
</code></pre>
Now change lumen.l to this:<p><pre><code>  (define-global %lumen ()
    (when-compiling
      `&#x27;(do ,(read-from-file &quot;runtime.l&quot;)
            ,(read-from-file &quot;macros.l&quot;)
            ,(read-from-file &quot;main.l&quot;))))
    
  (when-compiling
    (%lumen))
</code></pre>
and compile again:<p><pre><code>  $ make
</code></pre>
Here comes the surprise. Change lumen.l to this:<p><pre><code>  (define-global %lumen ()
    (when-compiling
      `&#x27;,(%lumen)))
    
  (when-compiling
    (%lumen))
</code></pre>
and compile:<p><pre><code>  $ make
</code></pre>
Now <i>delete the source code</i>:<p><pre><code>  $ rm runtime.l
</code></pre>
and compile:<p><pre><code>  $ make -B test
  make -B test
  bin&#x2F;lumen.js
  bin&#x2F;reader.js
  bin&#x2F;compiler.js
  bin&#x2F;system.js
  bin&#x2F;lumen.lua
  bin&#x2F;reader.lua
  bin&#x2F;compiler.lua
  bin&#x2F;system.lua
  js:
   647 passed, 0 failed
  lua:
   647 passed, 0 failed
</code></pre>
What happened to the source code? It&#x27;s gone!<p><a href="https:&#x2F;&#x2F;youtu.be&#x2F;TGwZVGKG30s?t=25" rel="nofollow">https:&#x2F;&#x2F;youtu.be&#x2F;TGwZVGKG30s?t=25</a><p>Gone? What do you mean gone? I had perfectly fine source code and you mean to tell me it&#x27;s gone?!<p>Not anymore you don&#x27;t. Poof.<p>Yet lumen remains:<p><pre><code>  $ make test
  js:
   647 passed, 0 failed
  lua:
   647 passed, 0 failed

</code></pre>
Last week I was trying to learn R, so I added a target for it: <a href="https:&#x2F;&#x2F;github.com&#x2F;sctb&#x2F;lumen&#x2F;pull&#x2F;193" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;sctb&#x2F;lumen&#x2F;pull&#x2F;193</a><p>Now I don&#x27;t have to write R.<p>Here&#x27;s a (now very-outdated) branch that has full support for Python: <a href="https:&#x2F;&#x2F;github.com&#x2F;shawwn&#x2F;lumen&#x2F;tree&#x2F;features&#x2F;python" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;shawwn&#x2F;lumen&#x2F;tree&#x2F;features&#x2F;python</a><p>Now I don&#x27;t have to write Python.<p>This has been a short tour of why Lumen has fascinated me for the last three years, and hope you find its mysteries delightful. It is only through abstraction that we can bend computers to our will, and Lumen is a decisive step forward.<p>Happy to answer any questions!