Fennel takes a lot of inspiration from Clojure. If you already know Clojure, then you'll have a good head start on Fennel. However, there are still a lot of differences! This document will guide you thru those differences and get you up to speed from the perspective of someone who already knows Clojure.
Fennel and Lua are minimalist languages, and Clojure is not. So it may take some getting used to when you make assumptions about what should be included in a language and find that it's not. There's almost always still a good way to do what you want; you just need to get used to looking somewhere different. With that said, Fennel is easier to learn since the conceptual surface area is much smaller.
Clojure and Fennel are both languages which have very close integration with their host runtime. In the case of Clojure it's Java, and in the case of Fennel it's Lua. However, Fennel's symbiosis goes beyond that of Clojure. In Clojure, every function implements the interfaces needed to be callable from Java, but Clojure functions are distinct from Java methods. Clojure namespaces are related to Java packages, but namespaces still exist as a distinct concept from packages. In Fennel you don't have such distinctions. Every Fennel function is indistinguishable from a Lua function, and every Fennel module is indistinguishable from a Lua module.
Clojure runs on the JVM, but it also has its own standard library:
the clojure.core namespace as well as supplemental ones
like clojure.set or clojure.java.io provide
more functions. In Fennel, there are no functions whatsoever provided by
the language; it only provides macros and special forms. Since the Lua
standard library is quite minimal, it's common to pull in 3rd-party
things like Lume, LuaFun, or Penlight for things
you might expect to be built-in to the language, like merge
or keys. There's also an experimental Cljlib library,
that implements a lot of functions from clojure.core
namespace, and has a set of macros to make writing code more familiar to
Clojure programmers, like adding syntax for defining multi-arity
functions, or multimethods, also providing deep comparison semantics,
sequence abstraction, and some addition data structures, like sets.
In Clojure it's typical to bring in libraries using a tool like Leiningen. In Fennel you can use LuaRocks for dependencies, but it's often overkill. Usually it's better to just check your dependencies into your source repository. Deep dependency trees are very rare in Fennel and Lua. Even tho Lua's standard library is very small, adding a single file for a 3rd-party library into your repo is very cheap. Checking a jar into a git repository in Clojure is strongly discouraged (for good reasons) but those reasons usually don't apply with Lua libraries.
Deploying Clojure usually means creating an uberjar that you launch using an existing JVM installation, because the JVM is a pretty large piece of software. Fennel deployments are much more varied; you can easily create self-contained standalone executables that are under a megabyte, or you can create scripts which rely on an existing Lua install, or code which gets embedded inside a larger application where the VM is already present.
Clojure has two types of scoping: locals and vars. Fennel uses
lexical scope for everything. (Globals exist, but they're mostly used
for debugging and repl purposes; you don't use them in normal code.)
This means that the "unit of reloading" is not the
clojure.lang.Var, but the module. Fennel's repl includes a
,reload module-name command for this. Inside functions,
let is used to introduce new locals just like in Clojure.
But at the top-level, local is used, which declares a local
which is valid for the entire remaining chunk instead of just for the
body of the let.
Like Clojure, Fennel uses the fn form to create
functions. However, giving it a name will also declare it as a local
rather than having the name be purely internal, allowing it to be used
more like defn. Functions declared with fn
have no arity checking; you can call them with any number of arguments.
If you declare with lambda instead, it will throw an
exception when you provide too few arguments.
Fennel supports destructuring similarly to Clojure. The main
difference is that rather than using :keys Fennel has a
notation where a bare : is followed by a symbol naming the
key. One main advantage of this notation is that unlike
:keys, the same notation is used for constructing and
destructuring.
;; clojure
(defn my-function [{:keys [msg abc def]}]
(println msg)
(+ abc def))
(my-function {:msg "hacasb" :abc 99 :def 523});; fennel
(fn my-function [{: msg : abc : def}]
(print msg)
(+ abc def))
(my-function {:msg "hacasb" :abc 99 :def 523})Like Clojure, normal locals cannot be given new values. However,
Fennel has a special var form that will allow you to
declare a special kind of local which can be given a new value with
set.
Fennel also uses #(foo) notation as shorthand for
anonymous functions. There are two main differences; the first is that
it uses $1, $2, etc instead of
%1, %2 for arguments. Secondly while Clojure
requires parens in this shorthand, Fennel does not. #5 in
Fennel is the equivalent of Clojure's (constantly 5).
;; clojure
(def handler #(my-other-function %1 %3))
(def handler2 (constantly "abc"));; fennel
(local handler #(my-other-function $1 $3))
(local handler2 #"abc")Fennel does not have apply; instead you unpack arguments
into function call forms:
;; clojure
(apply add [1 2 3]);; fennel
(add (table.unpack [1 2 3])) ; unpack instead of table.unpack in older LuaIn Clojure, you have access to scoping information at compile time
using the undocumented &env map. In Fennel and Lua, environments are
first-class at runtime.
Clojure ships with a rich selection of data structures for all kinds
of situations. Lua (and thus Fennel) has exactly one data structure: the
table. Under the hood, tables with sequential integer keys are of course
implemented using arrays for performance reasons, but the table itself
does not "know" whether it's a sequence table or a map-like table. It's
up to you when you iterate thru the table to decide; you iterate on
sequence tables using ipairs and map-like tables using
pairs. Note that you can use pairs on
sequences just fine; you just won't get the results in order.
The other big difference is that tables are mutable. It's possible to use metatables to implement immutable data structures on the Lua runtime, but there's a significant performance overhead beyond just the inherent immutability penalty. Using the LuaFun library can get you immutable operations on mutable tables without as much overhead. However, note that generational garbage collection is still a very recent development on the Lua runtime, so purely-functional approaches that generate a lot of garbage may not be a good choice for libraries which need to run on a wide range of versions.
Like Clojure, any value can serve as a key. However, since tables are
mutable data, two tables with identical values will not be
= to each other as per
Baker and thus will act as distinct keys. Clojure's
:keyword notation is used in Fennel as a syntax for
strings; there is no distinct type for keywords.
Note that nil in Fennel is rather different from
Clojure; in Clojure it has many different meanings, ("nil punning") but
in Fennel it always represents the absence of a value. As such, tables
cannot contain nil. Attempting to put
nil in a table is equivalent to removing the value from the
table, and you never have to worry about the difference between "the
table does not contain this key" vs "the table contains a nil value at
this key". And setting key to a nil in a sequential table
will not shift all other elements, and will leave a "hole" in the table.
Use table.remove instead on sequences to avoid these
holes.
Tables cannot be called like functions, (unless you set up a special
metatable) nor can :keyword style strings. If a string key
is statically known, you can use tbl.key notation; if it's
not, you use the . form in cases where you can't
destructure: (. tbl key).
;; clojure
(dissoc my-map :abc)
(when-not (contains? my-other-map some-key)
(println "no abc"));; fennel
(set my-map.abc nil)
(when (= nil (. my-other-map some-key))
(print "no abc"))As was mentioned previously, Clojure has two types of scoping:
lexical and dynamic. Clojure vars can be declared in the dynamic scope
with the special metadata attribute, supported by def and
its derivatives, to be later altered with the binding
macro:
;; clojure
(def ^:dynamic *foo* 32)
(defn bar [x]
(println (+ x *foo*)))
(println (bar 10)) ;; => 42
(binding [*foo* 17]
(println (bar 10))) ;; => 27
(println (bar 10)) ;; => 42Fennel doesn't have dynamic scope. Instead we can use table mutability to alter values held, to be later dynamically looked up:
;; fennel
(local dynamic {:foo 32})
(fn bar [x]
(print (+ dynamic.foo x)))
(print (bar 10)) ;; => 42
(set dynamic.foo 17)
(print (bar 10)) ;; => 27In contrast to Clojure's binding, which only binds var
to a given value in the scope created by the binding macro,
the modification of the table here is permanent, and table values have
to be restored manually.
In Clojure, similarly to variables, dynamic functions can be defined:
;; clojure
(defn ^:dynamic *fred* []
"Hi, I'm Fred!")
(defn greet []
(println (*fred*)))
(greet) ;; prints: Hi, I'm Fred!
(binding [*fred* (fn [] "I'm no longer Fred!")]
(greet)) ;; prints: I'm no longer Fred!In Fennel we can simply define a function as part of the table,
either by assigning anonymous function to a table key, as done in the
variable example above, or by separating function name and table name
with a dot in the fn special:
;; fennel
(local dynamic {})
(fn dynamic.fred []
"Hi, I'm Fred!")
(fn greet []
(print (dynamic.fred)))
(greet) ;; prints: Hi, I'm Fred!
(set dynamic.fred (fn [] "I'm no longer Fred!"))
(greet) ;; prints: I'm no longer Fred!Another alternative is to use the var special. We can
define a variable holding nil, use it in some function, and
later set it to some other value:
;; fennel
(var foo nil)
(fn bar []
(foo))
(set foo #(print "foo!"))
(bar) ;; prints: foo!
(set foo #(print "baz!"))
(bar) ;; prints: baz!This can also be used for forward declarations like Clojure's
declare.
In Clojure, we have this idea that "everything is a seq". Lua and
Fennel, not being explicitly functional, have instead "everything is an
iterator". The book Programming in Lua has a
detailed explanation of iterators. The each special form
consumes iterators and steps thru them similarly to how
doseq does.
;; clojure
(doseq [[k v] {:key "value" :other-key "SHINY"}]
(println k "is" v));; fennel
(each [k v (pairs {:key "value" :other-key "SHINY"})]
(print k "is" v))When iterating thru maps, Clojure has you pull apart the key/value pair thru destructuring, but in Fennel the iterators provide you with them as separate values.
Since Fennel has no functions, it relies on macros to do things like
map and filter. Similarly to Clojure's
for, Fennel has a pair of macros that operate on iterators
and produce tables. icollect walks thru an iterator and
allows the body to return a value that's put in a sequential table to
return. The collect macro is similar in that it returns a
table, except the body should return two values, and the returned table
is key/value rather than sequential. The body of either macro allows you
to return nil to filter out that entry from the result
table.
;; clojure
(for [x [1 2 3 4 5 6]
:when (= 0 (% x 2))]
x) ; => (2 4 6)
(into {} (for [[k v] {:key "value" :other-key "SHINY"}]
[k (str "prefix:" v)]))
; => {:key "prefix:value" :other-key "prefix:SHINY"};; fennel
(icollect [i x (ipairs [1 2 3 4 5 6])]
(if (= 0 (% x 2)) x)) ; => [2 4 6]
(collect [k v (pairs {:key "value" :other-key "SHINY"})]
(values k (.. "prefix:" v)))
; => {:key "prefix:value" :other-key "prefix:SHINY"}Note that filtering values out using icollect does not
result in a table with gaps in it; each value gets added to the end of
the table.
All these forms accept iterators. Though the table-based
pairs and ipairs are the most common
iterators, other iterators like string.gmatch or
io.lines or even custom ones work just as well.
Tables cannot be lazy (again other than thru metatable cleverness) so to some degree iterators take on the role of laziness.
If you want the sequence abstraction from Clojure, the Cljlib library
provides Clojure's mapv, filter, and other
functions that work using a similar seq abstraction
implemented for ordinary tables with linear runtime cost of converting
tables to a sequential ones. In practice, using Cljlib allows porting
most Clojure data transformations almost directly to Fennel, though
their performance characteristics will vary a lot.
Tragically Clojure does not have pattern matching as part of the
language. Fennel fixes this problem by implementing the
case macro. Refer to the
reference for details. Since if-let just an anemic form
of pattern matching, Fennel omits it in favor of case.
;; clojure
(if-let [result (calculate-thingy)]
(println "Got" result)
(println "Couldn't get any results"));; fennel
(case (calculate-thingy)
result (print "Got" result)
_ (print "Couldn't get any results"))Modules in Fennel are first-class; that is, they are nothing more than tables with a specific mechanism for loading them. This is different from namespaces in Clojure which have some map-like properties but are not really data structures in the same way.
Clojure makes you replace the dashes in namespace names with underscores in filenames; Fennel lets you name the files consistently with the modules they contain.
In Clojure, vars are public by default. In Fennel, all definitions are local to the file, but including a local in a table that is placed at the end of the file will cause it to be exported so other code can use it. This makes it easy to look in one place to see a list of everything that a module exports rather than having to read thru the entire file.
;; clojure
(ns my.namespace)
(def ^:private x 13)
(defn add-x [y] (+ x y));; fennel
(local x 13)
(fn add-x [y] (+ x y))
{: add-x}Modules are loaded by require and are typically bound
using local, but they are also frequently destructured at
the point of binding.
;; clojure
(require '[clojure.pprint :as pp])
(require '[my.namespace :refer [add-x]])
(defn show-something []
(pp/pprint {:a 1 :b (add-x 13)}));; fennel
(local fennel (require :fennel))
(local {: add-x} (require :my.module))
(fn show-something []
(print (fennel.view {:a 1 :b (add-x 13)})))In any lisp, a macro is a function which takes an input form and
returns another form to be compiled in its place. Fennel makes this even
more explicit; macros are loaded as functions from special macro modules
which are loaded in compile scope. They are brought in using
import-macros:
;; macros.fnl
{:flip (fn [arg1 arg2] `(values ,arg2 ,arg1))};; otherfile.fnl
(import-macros {: flip} :macros)
(print (flip :abc :def))Instead of using ~ for unquote, Fennel uses the more
traditional ,. At the end of a quoted form you can use
table.unpack or unpack in place of
~@.
You can also define macros inline without creating a separate macro
module using macro, but these macros cannot be exported
from the module as they do not exist at runtime; also they cannot
interact with other macros.
Lists and symbols are strictly compile-time concepts in Fennel.
There are two kinds of ways to represent failure in Lua and Fennel.
The error function works a bit like throwing an
ex-info in Clojure, except instead of try and
catch we have pcall and xpcall to
call a function in "protected" state which will prevent errors from
bringing down the process. These can't be chained or seamlessly
re-thrown in the same way as Exceptions on the JVM are.
See the tutorial for details.
There is no cond in Fennel because if
behaves exactly the same as cond if given more than three
arguments.
Functions can return multiple
values. This can result in surprising behavior, but it's outside the
scope of this document to describe. You can use the values
form in a tail position to return multiple values.
Operators like + and or, etc are special
forms which must have the number of arguments fixed at compile time.
This means you cannot do things like (apply + [1 2 3]) or
call (* ((fn [] (values 4 5 6)))), though the latter would
work for functions rather than special forms.