fennel-tutorial - Man Page

A programming language is made up of syntax and semantics. The semantics of Fennel vary only in small ways from Lua (all noted below). The syntax of Fennel comes from the lisp family of languages. Lisps have syntax which is very uniform and predictable, which makes it easier to write code that operates on code (https://stopa.io/post/265) as well as structured editing (http://danmidwood.com/content/2014/11/21/animated-paredit.html).

If you know Lua and a lisp already, you'll feel right at home in Fennel. Even if not, Lua is one of the simplest programming languages in existence, so if you've programmed before you should be able to pick it up without too much trouble, especially if you've used another dynamic imperative language with closures. The Lua reference manual (https://www.lua.org/manual/5.4/) is a fine place to look for details, but Fennel's own Lua Primer (https://fennel-lang.org/lua-primer) is shorter and covers the highlights.

If you've already got some Lua example code and you just want to see how it would look in Fennel, you can learn a lot from putting it in antifennel (https://fennel-lang.org/see).

Strings that don't have spaces or reserved characters in them can use the :shorthand syntax instead, which is often used for table keys:

{:key value :number 531}

If a table has string keys like this, you can pull values out of it easily with a dot if the keys are known up front:

(let [tbl {:x 52 :y 91}]
  (+ tbl.x tbl.y)) ; -> 143

You can also use this syntax with set:

(let [tbl {}]
  (set tbl.one 1)
  (set tbl.two 2)
  tbl) ; -> {:one 1 :two 2}

If a table key has the same name as the variable you're setting it to, you can omit the key name and use : instead:

(let [one 1 two 2
      tbl {: one : two}]
  tbl) ; -> {:one 1 :two 2}

Finally, let can destructure a table into multiple locals.

There is positional destructuring:

(let [data [1 2 3]
      [fst snd thrd] data]
  (print fst snd thrd)) ; -> 1       2       3

And destructuring of tables via key:

(let [pos {:x 23 :y 42}
      {:x x-pos :y y-pos} pos]
  (print x-pos y-pos)) ; -> 23      42

As above, if a table key has the same name as the variable you're destructuring it to, you can omit the key name and use : instead:

(let [pos {:x 23 :y 42}
      {: x : y} pos]
  (print x y)) ; -> 23      42

This can nest and mix and match:

(let [f (fn [] ["abc" "def" {:x "xyz" :y "abc"}])
      [a d {:x x : y}] (f)]
  (print a d)
  (print x y))

If the size of the table doesn't match the number of binding locals, missing values are filled with nil and extra values are discarded. Note that unlike many languages, nil in Lua actually represents the absence of a value, and thus tables cannot contain nil. It is an error to try to use nil as a key, and using nil as a value removes whatever entry was at that key before.

Errors in Lua have two forms they can take. Functions in Lua can return any number of values, and most functions which can fail will indicate failure by using two return values: nil followed by a failure message string. You can interact with this style of function in Fennel by destructuring with parens instead of square brackets:

(case (io.open "file")
  ;; when io.open succeeds, it will return a file, but if it fails
  ;; it will return nil and an err-msg string describing why
  f (do (use-file-contents (f:read :*all))
        (f:close))
  (nil err-msg) (print "Could not open file:" err-msg))

You can write your own function which returns multiple values with values.

(fn use-file [filename]
  (if (valid-file-name? filename)
      (open-file filename)
      (values nil (.. "Invalid filename: " filename))))

Note: while errors are the most common reason to return multiple values from a function, it can be used in other cases as well. This is the most complex thing about Lua, and a full discussion is out of scope for this tutorial, but it's covered well elsewhere (https://benaiah.me/posts/everything-you-didnt-want-to-know-about-lua-multivals/).

The problem with this type of error is that it does not compose well; the error status must be propagated all the way along the call chain from inner to outer. To address this, you can use error. This will terminate the whole process unless it's within a protected call, similar to the way in other languages where throwing an exception will stop the program unless it is within a try/catch. You can make a protected call with pcall:

(let [(ok? val-or-msg) (pcall potentially-disastrous-call filename)]
  (if ok?
      (print "Got value" val-or-msg)
      (print "Could not get value:" val-or-msg)))

The pcall invocation there means you are running (potentially-disastrous-call filename) in protected mode. pcall takes an arbitrary number of arguments which are passed on to the function. You can see that pcall returns a boolean (ok? here) to let you know if the call succeeded or not, and a second value (val-or-msg) which is the actual value if it succeeded or an error message if it didn't.

The assert function takes a value and an error message; it calls error if the value is nil and returns it otherwise. This can be used to turn multiple-value failures into errors (kind of the inverse of pcall which turns errors into multiple-value failures):

(let [f (assert (io.open filename))
      contents (f.read f "*all")]
  (f.close f)
  contents)

In this example because io.open returns nil and an error message upon failure, a failure will trigger an error and halt execution.

Fennel supports variadic functions (in other words, functions which take any number of arguments) like many languages. The syntax for taking a variable number of arguments to a function is the ... symbol, which must be the last parameter to a function. This syntax is inherited from Lua rather than Lisp.

The ... form is not a list or first class value, it expands to multiple values inline. To access individual elements of the vararg, you can destructure with parentheses, or first wrap it in a table literal ([...]) and index like a normal table, or use the select function from Lua's core library. Often, the vararg can be passed directly to another function such as print without needing to bind it.

(fn print-each [...]
  (each [i v (ipairs [...])]
    (print (.. "Argument " i " is " v))))

(print-each :a :b :c)

(fn myprint [prefix ...]
  (io.write prefix)
  (io.write (.. (select "#" ...) " arguments given: "))
  (print ...))

(myprint ":D " :d :e :f)

Varargs are scoped differently than other variables as well - they are only accessible to the function in which they are created. Unlike normal values, functions cannot close over them. This means that the following code will NOT work, as the varargs in the inner function are out of scope.

(fn badcode [...]
  (fn []
    (print ...)))

If you get an error that says unknown global in strict mode it means that you're trying compile code that uses a global which the Fennel compiler doesn't know about. Most of the time, this is due to a coding mistake. However, in some cases you may get this error with a legitimate global reference. If this happens, it may be due to an inherent limitation of Fennel's strategy. You can use _G.myglobal to refer to it in a way that works around this check and calls attention to the fact that this is in fact a global.

Another possible cause for this error is a modified function environment (https://www.lua.org/pil/14.3.html). The solution depends on how you're using Fennel:

• Embedded Fennel can have its searcher modified to ignore certain (or all) globals via the allowedGlobals parameter. See the Lua API (https://fennel-lang.org/api) page for instructions.

• Fennel's CLI has the --globals parameter, which accepts a comma-separated list of globals to ignore. For example, to disable strict mode for globals x, y, and z:

  fennel --globals x,y,z yourfennelscript.fnl

There are a few surprises that might bite seasoned lispers. Most of these result necessarily from Fennel's insistence upon imposing zero runtime overhead over Lua.

• The arithmetic, comparison, and boolean operators are not first-class functions. They can behave in surprising ways with multiple-return-valued functions, because the number of arguments to them must be known at compile-time.
• There is no apply function; instead use table.unpack or unpack depending on your Lua version: (f 1 3 (table.unpack [4 9])).
• Tables are compared for equality by identity, not based on the value of their contents, as per Baker (https://p.hagelb.org/equal-rights-for-functional-objects.html).
• Return values in the repl will get pretty-printed, but calling (print tbl) will emit output like table: 0x55a3a8749ef0. If you don't already have one, it's recommended for debugging to define a printer function which calls fennel.view on its argument before printing it: (local fennel (require :fennel)) (fn _G.pp [x] (print (fennel.view x))). If you add this definition to your ~/.fennelrc file it will be available in the standard repl.
• Lua programmers should note Fennel functions cannot do early returns.

Note that built-in functions in Lua's standard library (https://www.lua.org/manual/5.4/manual.html#6) like math.random above can be called with no fuss and no overhead.

This includes features like coroutines, which are often implemented using special syntax in other languages. Coroutines let you express non-blocking operations without callbacks (https://leafo.net/posts/itchio-and-coroutines.html).

Tables in Lua may seem a bit limited, but metatables (https://www.lua.org/pil/13.html) allow a great deal more flexibility. All the features of metatables are accessible from Fennel code just the same as they would be from Lua.

You can use the require function to load code from other files.

(let [lume (require :lume)
      tbl [52 99 412 654]
      plus (fn [x y] (+ x y))]
  (lume.map tbl (partial plus 2))) ; -> [54 101 414 656]

Modules in Fennel and Lua are simply tables which contain functions and other values. The last value in a Fennel file will be used as the value of the whole module. Technically this can be any value, not just a table, but using a table is most common for good reason.

To require a module that's in a subdirectory, take the file name, replace the slashes with dots, and remove the extension, then pass that to require. For instance, a file called lib/ui/menu.lua would be read when loading the module lib.ui.menu.

When you run your program with the fennel command, you can call require to load Fennel or Lua modules. But in other contexts (such as compiling to Lua and then using the lua command, or in programs that embed Lua) it will not know about Fennel modules. You need to install the searcher that knows how to find .fnl files:

require("fennel").install()
local mylib = require("mylib") -- will compile and load code in mylib.fnl

Once you add this, require will work on Fennel files just like it does with Lua; for instance (require :mylib.parser) will look in "mylib/parser.fnl" on Fennel's search path (stored in fennel.path which is distinct from package.path used to find Lua modules). The path usually includes an entry to let you load things relative to the current directory by default.

There are several ways to write a library which uses modules. One of these is to rely on something like LuaRocks, to manage library installation and availability of it and its modules. Another way is to use the relative require style for loading nested modules. With relative require, libraries don't depend on the root directory name or its location when resolving inner module paths.

For example, here's a small example library, which contains an init.fnl file, and a module at the root directory:

;; file example/init.fnl:
(local a (require :example.module-a))

{:hello-a a.hello}

Here, the main module requires additional example.module-a module, which holds the implementation:

;; file example/module-a.fnl
(fn hello [] (print "hello from a"))
{:hello hello}

The main issue here is that the path to the library must be exactly example, e.g. library must be required as (require :example) for it to work, which can't be enforced on the library user. For example, if the library were moved into libs directory of the project to avoid cluttering, and required as (require :libs.example), there will be a runtime error. This happens because library itself will try to require :example.module-a and not :libs.example.module-a, which is now the correct module path:

runtime error: module 'example.module-a' not found:
        no field package.preload['example.module-a']
        ...
        no file './example/module-a.lua'
        ...
stack traceback:
  [C]: in function 'require'
  ./libs/example/init.fnl:2: in main chunk

LuaRocks addresses this problem by enforcing both the directory name and installation path, populating the LUA_PATH environment variable to make the library available. This, of course, can be done manually by setting LUA_PATH per project in the build pipeline, pointing it to the right directory. But this is not very transparent, and when requiring a project local library it's better to see the full path, that directly maps to the project's file structure, rather than looking up where the LUA_PATH is modified.

In the Fennel ecosystem we encourage a simpler way of managing project dependencies. Simply dropping a library into your project's tree or using git submodule is usually enough, and the require paths should be handled by the library itself.

Here's how a relative require path can be specified in the libs/example/init.fnl to make it name/path agnostic, assuming that we've moved our example library there:

;; file libs/example/init.fnl:
(local a (require (.. ... :.module-a)))

{:hello-a a.hello}

Now, it doesn't matter how library is named or where we put it - we can require it from anywhere. It works because when requiring the library with (require :lib.example), the first value in ... will hold the "lib.example" string. This string is then concatenated with the ".module-a", and require will properly find and load the nested module at runtime under the "lib.example.module-a" path. It's a Lua feature, and not something Fennel specific, and it will work the same when the library is AOT compiled to Lua.

(local current-module ...)
(require (.. current-module :.other-module))

(require (.. ... :.other-module))

package.preload["libs.example.module-a"] = package.preload["libs.example.module-a"] or function(...)
  local function hello()
    return print("hello from a")
  end
  return {hello = hello}
end

;; file libs/example/utils/greet.fnl:
(fn greet [who] (print (.. "hello " who)))

;; file libs/example/module-a.fnl
(local greet (require (.. (: ... :match "(.+)%.[^.]+") :.utils.greet)))

(fn hello [] (print "hello from a"))

{:hello hello :greet greet}

Fennel Maintainers.