
Lumen: A Lisp for Lua and JavaScript - tosh
https://github.com/sctb/lumen
======
d0m
I always find it cool to see the beginning of projects, but particularly lisp
projects where the boostrap language is replaced with the new one:
[https://github.com/sctb/lumen/commits/master?before=aedf2fd2...](https://github.com/sctb/lumen/commits/master?before=aedf2fd2c209bfc7926e0d4eae4becd8a647fb80+1271)

------
thecombjelly
Looking through the docs it seems a very nice lisp. Clean, simple, yet covers
all the basics without a lot of legacy warts. let with less parens and
limitless if branches are very nice. Definitely one of the nicer looking JS
lisps I've seen.

------
christophilus
This looks pretty darn nice. I’d be interested in hearing from anyone who’s
used it for anything. How was it?

~~~
shawn
It's the best! I learned R last week and added support for it:
[https://github.com/sctb/lumen/pull/193](https://github.com/sctb/lumen/pull/193)

There's an old version with Python support here:
[https://github.com/shawwn/lumen/tree/features/python/bin](https://github.com/shawwn/lumen/tree/features/python/bin)

------
d0m
That's great. I like the:

(get '(:a 5 :b 10) 'a)

How does it work in practice.. is '(:a 5) stored as an array or an object?

~~~
sctb
In JavaScript it's an array (which has limitations), and in Lua it's a table.

------
veli_joza
Looks great, I'll dig in. Two questions:

Does it generate code that can be optimized by luaJIT? (for example these
guidelines: [http://wiki.luajit.org/Numerical-Computing-Performance-
Guide](http://wiki.luajit.org/Numerical-Computing-Performance-Guide))

Can anyone compare to Urn? It's another active lisp-on-lua project that's at
the moment better documented than Lumen.

~~~
shawn
Yes, the performance is by far one of the best parts of Lumen.

Think of it this way. It generates exactly the code you write. It's nearly a
one-to-one translation between the input forms and output code. But that's why
it's fast.

If you want to see just how fast, try `time LUMEN_HOST=luajit make -B`

On my box, LuaJIT is able to recompile the entirety of Lumen _and_ run all the
tests in 1.3 seconds flat.

As for Urn, I'd be happy to answer specific comparison questions. I've been
putting together a little intro guide to Lumen, but for now the best way to
jump in is to study test.l and learn by example:
[https://github.com/sctb/lumen/blob/master/test.l](https://github.com/sctb/lumen/blob/master/test.l)

EDIT: By the way, Lumen runs on Torch too. If you want to do some hardcore
machine learning, it's as easy as installing torch and running `LUMEN_HOST=th
bin/lumen`.

[http://torch.ch/](http://torch.ch/)

Try evaluating `(require 'torch)` and `(require 'nn)`, then dive into the
Torch guides. You can bring Lumen's full macro system to bear on any ML
problem, which greatly simplifies the boilerplate generation involved with
standardizing datasets and such.

~~~
veli_joza
It's been few days since this post, don't know if you're still checking the
thread.

I'm really a beginner at lisp, so perhaps my questions won't make much sense?
I'd like to have Lua host application (in Love2d) with lisp-like runtime. The
lisp-like code is expected to be changed often during the runtime by
modifications of structure and constants in AST, so compile-time macros are
not useful to me.

On the other hand, the lisp-like code would not be written from scratch in
text form. It would be built by executing code-transformation functions that
would always construct a syntactically valid AST. For example, let's say there
is a function for drawing an arc of single color. Now user wants to draw a
rainbow. I would offer a function that could be executed to wrap existing
operation in a loop. In rainbow example the loop iteration would also modify a
vertical displacement and color hue shift.

My two questions - is lisp (and Lumen specifically) a good choice for self-
modifying live coding runtime? And is generated Lua source in Lumen project
suitable for embedding Lumen into Lua host application?

------
shove
I named my kid Lumen and today is his first birthday so I have to check this
out now

------
escherize
Looks cool! I wonder: what's the rationale for it exactly?

~~~
sctb
The core idea was to explore Lua's table-ness in a Lisp, with JavaScript along
for the ride for browser support. I think it was an interesting
experiment—interesting enough to possibly continue exploring in a more
“serious” implementation, if someone were so inclined.

------
eggy
How does it compare to Urn or Fennel first as a Lisp and second as a nice tool
alongside Lua?

------
jlarocco
As a Common Lisp user, I wish more of these one-off lisps would try to be
compatible with Common Lisp or Scheme.

Both CL and Scheme have pretty good library ecosystems, though realistically
not as rich as more popular languages. Coming out with a brand new,
incompatible, Lisp that has an even smaller community isn't very helpful, IMO.
Why not at least take advantage of the existing libraries and community?

~~~
shawn
Workin' on it!
[https://gist.github.com/shawwn/333540a1f0b02510d684394979d6b...](https://gist.github.com/shawwn/333540a1f0b02510d684394979d6b4bb)

Those member / assoc / rassoc / rassoc-if / etc definitions come straight out
of sbcl's lisp definition file.

I'm tellin' ya, Lumen is amazing. You can do everything you can imagine.
[https://www.youtube.com/watch?v=LIYNk4ARUR8](https://www.youtube.com/watch?v=LIYNk4ARUR8)

The best part is, it's additive work. The communities enhance and inform one
another.

------
shawn
Right! I've been waiting a couple years for Lumen to get some traction.
_cracks knuckles_

Before I blather on about why it's worth paying attention to, why don't I just
show you an implementation of the classic Trusting Trust paper:

[https://www.archive.ece.cmu.edu/~ganger/712.fall02/papers/p7...](https://www.archive.ece.cmu.edu/~ganger/712.fall02/papers/p761-thompson.pdf)

We'll implement this ourselves. Let's dive right in. Start off by cloning
Lumen.

    
    
      $ git clone https://github.com/sctb/lumen
      $ cd lumen
      $ git checkout aedf2fd2c209bfc7926e0d4eae4becd8a647fb80
      $ vim main.l
    

(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.)

Now that main.l is open, we begin by defining a global function `read-file`
that simply returns a file as a string:

    
    
      (define-global read-file (path)
        ((get system 'read-file) path))
    

If you run `make && bin/lumen`, you'll see the function is now defined when
Lumen starts:

    
    
      > read-file
      function
    
      > (read-file "README.md")
      "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..."
    

Now we define `read-from-file`, which reads Lumen source code and returns it
as a form that can be evaluated:

    
    
      (define-global read-from-file (path)
        (let (s ((get reader 'stream) (read-file path))
              body ((get reader 'read-all) s))
          `(do ,@body)))
    
      > (read-from-file "reader.l")
      ("do" ("define" "delimiters" ("set-of" "\"(\"" "\")\"" "\";\"" "\"\\r\"" "\"\\n\"")) ...
    

Those are the forms defined in reader.l:
[https://github.com/sctb/lumen/blob/aedf2fd2c209bfc7926e0d4ea...](https://github.com/sctb/lumen/blob/aedf2fd2c209bfc7926e0d4eae4becd8a647fb80/reader.l#L1)

Let's step through the forms and print them.

    
    
      > (step x (read-from-file "reader.l")
          (print (str x)))
      "do"
      ("define" "delimiters" ("set-of" "\"(\"" "\")\"" "\";\"" "\"\\r\"" "\"\\n\""))
      ("define" "whitespace" ("set-of" "\" \"" "\"\\t\"" "\"\\r\"" "\"\\n\""))
      ("define" "stream" ("str" "more") ("obj" more: "more" pos: 0 len: ("#" "str") string: "str"))
      ("define" "peek-char" ("s") ("let" ((pos: true len: true string: true) "s") ("when" ("<" "pos" "len") ("char" "string" "pos"))))
      ("define" "read-char" ("s") ("let" "c" ("peek-char" "s") ("if" "c" ("do" ("inc" ("get" "s" ("quote" "pos"))) "c"))))
      ...
    

Pretty good! We're already doing some basic compiler-type stuff. That's
Lumen's power: It's a flexible compiler. (IMO one of the finest in the world
due to its simplicity.)

Now, what can we do with these forms? Well, we can expand them:

    
    
      > (step x (expand (read-from-file "reader.l"))
          (print (str x)))
      "do"
      ("%local" "delimiters" ("%object" "\"(\"" true "\")\"" true "\";\"" true "\"\\n\"" true "\"\\r\"" true))
      ("%local" "whitespace" ("%object" "\"\\r\"" true "\" \"" true "\"\\n\"" true "\"\\t\"" true))
      ("%local-function" "stream" ("str" "more") ("return" ("%object" "\"more\"" "more" "\"pos\"" 0 "\"len\"" ("#" "str") "\"string\"" "str")))
      ("%local-function" "peek-char" ("s") ("do" ("%local" "____id" "s") ("%local" "__pos" ("get" "____id" "\"pos\""))
      ...
    

We can compile them:

    
    
      > (print (compile (expand (read-from-file "reader.l"))))
      local delimiters = {["("] = true, [")"] = true, [";"] = true, ["\n"] = true, ["\r"] = true}
      local whitespace = {["\r"] = true, [" "] = true, ["\n"] = true, ["\t"] = 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 < __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
      ...
    

And we can switch languages:

    
    
      > (set target 'js)
      "js"
      > (print (compile (expand (read-from-file "reader.l"))))
      var delimiters = {"(": true, ")": true, ";": true, "\n": true, "\r": true};
      var whitespace = {"\r": true, " ": true, "\n": true, "\t": 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 < __len4) {
          return char(__string4, __pos8);
        }
      };
      var read_char = function (s) {
        var __c28 = peek_char(s);
        if (__c28) {
          s.pos = s.pos + 1;
          return __c28;
        }
      };
      ...
    

Ok, on to the cool stuff.

Make a file called lumen.l:

    
    
      (when-compiling
        `(do ,(read-from-file "runtime.l")
             ,(read-from-file "macros.l")
             ,(read-from-file "main.l")))
    

English translation: "When compiling, read the forms from runtime.l, macros.l,
and main.l, join them together, then compile the result."

Let's compile this file and see what happens:

    
    
      $ bin/lumen -c lumen.l
      environment = {{}}
      target = "lua"
      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
      ...
    

Presto! We get bin/lumen.lua:
[https://github.com/sctb/lumen/blob/aedf2fd2c209bfc7926e0d4ea...](https://github.com/sctb/lumen/blob/aedf2fd2c209bfc7926e0d4eae4becd8a647fb80/bin/lumen.lua#L1)

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't
installed on your system, you'd be seeing JS instead.

To get a specific language, pass the `-t` parameter:

    
    
      $ bin/lumen -c lumen.l -t js
      environment = [{}];
      target = "js";
      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;
        }
      };
      ...
    

That gives us bin/lumen.js:
[https://github.com/sctb/lumen/blob/aedf2fd2c209bfc7926e0d4ea...](https://github.com/sctb/lumen/blob/aedf2fd2c209bfc7926e0d4eae4becd8a647fb80/bin/lumen.js)

Let's simplify the makefile. Open makefile in your edior and replace it with
this:

    
    
      .PHONY: all clean test
    
      LUMEN_LUA  ?= lua
      LUMEN_NODE ?= node
      LUMEN_HOST ?= $(LUMEN_LUA)
    
      LUMEN := LUMEN_HOST="$(LUMEN_HOST)" bin/lumen
    
      MODS := bin/lumen.x	\
        bin/reader.x	\
        bin/compiler.x	\
        bin/system.x
    
      all: $(MODS:.x=.js) $(MODS:.x=.lua)
    
      clean:
        @git checkout bin/*.js
        @git checkout bin/*.lua
        @rm -f obj/*
    
      bin/%.js : %.l
        @echo $@
        @$(LUMEN) -c $< -o $@ -t js
    
      bin/%.lua : %.l
        @echo $@
        @$(LUMEN) -c $< -o $@ -t lua
    
      test: all
        @echo js:
        @LUMEN_HOST=$(LUMEN_NODE) ./test.l
        @echo lua:
        @LUMEN_HOST=$(LUMEN_LUA) ./test.l
    

Try it out:

    
    
      $ make -B test
      bin/lumen.js
      bin/reader.js
      bin/compiler.js
      bin/system.js
      bin/lumen.lua
      bin/reader.lua
      bin/compiler.lua
      bin/system.lua
      js:
       647 passed, 0 failed
      lua:
       647 passed, 0 failed
    

Perfect. Our new lumen.l file fits into the compiler pipeline nicely.

It may not seem like it, but we now have a tool of remarkable power. Let's see
why.

Open lumen.l back up. We recall it looks like this:

    
    
      (when-compiling
        `(do ,(read-from-file "runtime.l")
             ,(read-from-file "macros.l")
             ,(read-from-file "main.l")))
    

Let me show you what makes Lumen special. Change lumen.l to this:

    
    
      (define-global %lumen ()
        (when-compiling
          `'(do ,(read-from-file "runtime.l")
                ,(read-from-file "macros.l")
                ,(read-from-file "main.l"))))
    
      (when-compiling
        `(do ,(read-from-file "runtime.l")
             ,(read-from-file "macros.l")
             ,(read-from-file "main.l")))
    

then compile:

    
    
      $ make
    

Now change lumen.l to this:

    
    
      (define-global %lumen ()
        (when-compiling
          `'(do ,(read-from-file "runtime.l")
                ,(read-from-file "macros.l")
                ,(read-from-file "main.l"))))
        
      (when-compiling
        (%lumen))
    

and compile again:

    
    
      $ make
    

Here comes the surprise. Change lumen.l to this:

    
    
      (define-global %lumen ()
        (when-compiling
          `',(%lumen)))
        
      (when-compiling
        (%lumen))
    

and compile:

    
    
      $ make
    

Now _delete the source code_ :

    
    
      $ rm runtime.l
    

and compile:

    
    
      $ make -B test
      make -B test
      bin/lumen.js
      bin/reader.js
      bin/compiler.js
      bin/system.js
      bin/lumen.lua
      bin/reader.lua
      bin/compiler.lua
      bin/system.lua
      js:
       647 passed, 0 failed
      lua:
       647 passed, 0 failed
    

What happened to the source code? It's gone!

[https://youtu.be/TGwZVGKG30s?t=25](https://youtu.be/TGwZVGKG30s?t=25)

Gone? What do you mean gone? I had perfectly fine source code and you mean to
tell me it's gone?!

Not anymore you don't. Poof.

Yet lumen remains:

    
    
      $ make test
      js:
       647 passed, 0 failed
      lua:
       647 passed, 0 failed
    
    

Last week I was trying to learn R, so I added a target for it:
[https://github.com/sctb/lumen/pull/193](https://github.com/sctb/lumen/pull/193)

Now I don't have to write R.

Here's a (now very-outdated) branch that has full support for Python:
[https://github.com/shawwn/lumen/tree/features/python](https://github.com/shawwn/lumen/tree/features/python)

Now I don't have to write Python.

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.

Happy to answer any questions!

~~~
alexisread
Very nice project - thanks for sharing! How would you say this compares to
maru, which does a similar thing? Maru uses gcc rather than Node.js or lua,
and compiles it's own (x86) binaries. It focusses on as minimal syntax as
possible, to expose new methods of composition:
[http://piumarta.com/software/maru/](http://piumarta.com/software/maru/)

If I've got this correct, lumen still relies on having the lua/Node/luaJIT
runtime underneath?

~~~
shawn
I didn’t want to give an answer till I spent some time picking apart Maru and
looking for similarities.

First, thanks for pointing out Maru. I’ve often wondered how to translate
Lumen into C, and this is an excellent guide.

Also, I’m not sure how to shoehorn this into the conversation, but:
[https://m.youtube.com/watch?v=2XID_W4neJo](https://m.youtube.com/watch?v=2XID_W4neJo)

Regarding Maru the Lisp, the goals are similar-ish to Lumen’s. Lumen started
life as an experiment: “what would a table-based Lisp look like?” Maru on the
other hand is a (very fine!) traditional Lisp. It has cons cells, for example,
and a GC. Lumen elides these features by virtue of running on a host that
already implements them.

You’ve got me excited to try writing a Lumen to C compiler now...

Actually, that highlights one interesting difference. It’s possible to
implement a C backend for Lumen relatively easily. It would just spit out C,
which is fed straight to gcc. The problem is self-hosting. It’s easy to emit
some C functions. It’s hard to emit code which is capable of compiling itself,
i.e. implementing Lumen’s runtime and compiler systems.

I would say that Lumen’s power is largely thanks to its brevity. In fact it’s
so small that I almost overlooked it, that first day many years ago. It didn’t
seem like something so small could be production-quality.

I’ll keep studying Maru and perhaps report back with more thoughts.

~~~
alexisread
The vid made me smile :) Yes, maru was conceived as part of the STEPS program,
to provide a minimal runtime base for an OS. As such it's focus was on being
able to produce DSLs for a higher level of abstraction, and hence needed to
provide the ability to extend composition
([http://piumarta.com/freeco11/freeco11-piumarta-
oecm.pdf](http://piumarta.com/freeco11/freeco11-piumarta-oecm.pdf)).

Personally I've been interested in replacing the GC part of maru with a
structural method of managing memory
([http://concurrency.ch/Content/publications/Blaeser_ETH_Diss_...](http://concurrency.ch/Content/publications/Blaeser_ETH_Diss_2007.pdf)),
this would require extending the language with the Composita primitives, but
not really sure how this'll go yet.

The Lumen-C compiler sounds good! Yes the tricky part is the self compilation,
I'm wondering if you'll just end up with a maru-like system if you follow this
down?

Alternatively the other way of doing this is via an explicitly generated
runtime as-per Ferret
([https://github.com/nakkaya/ferret](https://github.com/nakkaya/ferret))?

decisions decisions :)

------
motogpjimbo
You probably should have searched for the name Lumen before you chose it for
your project. Lumen is a framework for PHP:

[https://lumen.laravel.com/](https://lumen.laravel.com/)

~~~
dang
This Lumen predates that Lumen by a few years.

We did a search when we picked the name, and found
[https://github.com/xopxe/Lumen](https://github.com/xopxe/Lumen). I emailed
Jorge to ask if he was ok with us using the name for a Lisp-to-Lua project and
he sent a delightful reply that began "It's impossible to avoid conflicts with
such a cool name", and pointed out that there were other projects called lumen
that he discovered when he published on Github. Who knows how far back the
lumens go.

~~~
tosh
By now finding great names that aren't in use yet (let alone not in use in a
similar context) is almost impossible. Fast fwd 100 years from now & we'll
have way more artifacts with names. I think we'll be fine.

Reminds me a bit of Joe Armstrong's StrangeLoop talk from 2014: The Mess We're
In
[https://www.youtube.com/watch?v=lKXe3HUG2l4](https://www.youtube.com/watch?v=lKXe3HUG2l4)

