--use-bit-lib
flag to allow bitwise operations to
work in LuaJITmacro-searchers
table for finding macros similarly
to package.searchers
&as
inside pattern matchessym
function in compile scope now takes a source
table second argument:until
clauses for early termination in all
loops:escape-newlines?
and
:prefer-colon?
options in fennel.view?.
where
/or
clauses in match
fennel.view
doc
...
inside
eval-compiler
&
character in identifiers;
will be disallowed later&as
collect
/icollect
)...
arguments consistently with Lua when
requiring modulesimport-macros
would not respect certain
compiler options__fennelview
metamethod
on userdata metatables,reload
; see
,help
for a full list--no-compiler-sandbox
did not apply in
import-macros
macrodebug
fail to print correctly--no-sandbox-compiler
to
--no-compiler-sandbox
in help/docs:
when used with methods that are not
valid Lua namesThis release introduces the plugin system as well as starting to sandbox the compiler environment for safer code loading. Nothing is blocked yet, but it emits warnings when macros use functionality that is not considered safe; future versions will prevent this.
@
list?
and sym?
in compiler
API.--lua
CLI flag for specifying a custom Lua
command/executable. (#324)This release features a version of the Fennel compiler that is self-hosted and written entirely in Fennel!
include
would
get skipped.This release mostly includes small bug fixes but also adds the
with-open
macro for automating closing file handles,
etc.
include
calls would splice
locals incorrectly$...
(#298)with-open
macro for auto-closing file handles
(#295)--native-module
and --native-library
to --compile-binary
command#
) couldn't be used
as multisyms (#294)fennel.searchModule
function to module APIinclude
to ignore compiler
options$HOME
env var
was not setThis release mostly includes small bug fixes, but also introduces a very experimental command for compiling standalone executables.
--compile-binary
command (#281)This release adds support for Lua 5.3's bitwise operators as well as
a new way of importing macro modules. It also adds
pick-values
and pick-args
for a little more
flexibility around function args and return values. The compiler now
tries to emit friendlier errors that suggest fixes for problems.
import-macros
for more flexible macro module
loading (#269)rshift
, lshift
,
bor
, band
, bnot
, and
bxor
FENNEL_DEBUG=trace
__fennelview
metamethod for custom
serializationdofile
would report the wrong
filenameinclude
of Lua modules that
lack a trailing newline (#234)pick-values
and pick-args
macros
(as limit-*
: #246, as pick-*
: #256)macroexpand
helper to expand macro forms during
compilation (#258)macrodebug
utility macro for printing expanded
macro forms in REPL (#258)This release mostly contains small bug fixes.
include
could not be nested without
repetition (#214)else
to emit twice in some contexts
(#212)This release mostly contains small bug fixes.
--load FILE
argument to command-line
launcher (#193)each
to work with raw iterator values (#201)--check-unused-locals
This release introduces docstrings as well as several new features to the macro system and some breaking changes; the most significant being the new unquote syntax and the requirement of auto-gensym for identifiers in backtick.
doc
for displaying them
in repl:detect-cycles? false
in fennelview to turn off
"#<table 1>" outputx#
syntax for auto-gensym inside backticklambda
arity checks when using
destructuring:one-line
output in fennelviewinclude
special form to selectively inline modules
in compiled output--require-as-include
to inline required modules in
compiled output--eval
argument to command-line launcherFENNEL_PATH
to
path
match
?
in pattern
matchingreadline.lua
is
available--globals
and --globals-only
options
to launcher scriptluaexpr
and
luastatement
for a single lua
specialif
expressions in many
situations#
special with length
@
(unquote) with ,
; comma is
no longer whitespace~
in symbols other than
~=
hashfn
and #
reader macro for
shorthand functions like #(+ $1 $2)
macro
to make defining a single macro easier(comment)
special which emits a Lua comment in the
generated source(foo:bar baz)
;
disallow :
in symbolsThis release mostly contains small bug fixes.
not=
as an alias for ~=
in-scope?
which caused
match
outer unification to fail~=
comparisonsThe second minor release introduces backtick, making macro authoring much more streamlined. Macros may now be defined in the same file, and pattern matching is added.
macros
--add-package-path
and
--add-fennel-path
to launcher script-?>
and -?>>
macros@
(later changed to ,
)match
macro for pattern matchingThis release contains a few small bug fixes.
The first real release sees the addition of several "creature comfort" improvements such as comments, iterator support, line number tracking, accidental global protection, pretty printing, and repl locals. It also introduces the name "Fennel".
defn
macrodoto
macro->
and ->>
macrospack
,
$
, block
, *break
,
special
.
formvar
; disallow regular locals from being setglobal
; refuse to set globals without it&
require-macros
//
for integer division on Lua 5.3+fennel.dofile
and fennel.searcher
for
require
supportpartial
local
:
for method callseach
lambda
/λ
for arity-checked
functionswhen
The initial version (named "fnl") was created in 8 days and then set aside for several years.
These are all the special forms recognized by the Fennel compiler. It does not include built-in Lua functions; see the Lua reference manual or the Lua primer for that.
Remember that Fennel relies completely on Lua for its runtime. Everything Fennel does happens at compile-time, so you will need to familiarize yourself with Lua's standard library functions. Thankfully it's much smaller than almost any other language.
Fennel source code should be UTF-8-encoded text, although currently only ASCII forms of whitespace and numerals are supported.
fn
functionCreates a function which binds the arguments given inside the square
brackets. Will accept any number of arguments; ones in excess of the
declared ones are ignored, and if not enough arguments are supplied to
cover the declared ones, the remaining ones are nil
.
Example:
fn pxy [x y]
(print (+ x y))) (
Giving it a name is optional; if one is provided it will be bound to it as a local. Even if you don't use it as an anonymous function, providing a name will cause your stack traces to be more readable, so it's recommended. Providing a name that's a table field will cause it to be inserted in a table instead of bound as a local.
lambda
/λ
arity-checked functionCreates a function like fn
does, but throws an error at
runtime if any of the listed arguments are nil, unless its identifier
begins with ?
.
Example:
lambda [x ?y z]
(print (- x (* (or ?y 1) z)))) (
Note that the Lua runtime will fill in missing arguments with nil when they are not provided by the caller, so an explicit nil argument is no different than omitting an argument.
The λ
form is an alias for lambda
and
behaves identically.
(Since 0.3.0)
Both the fn
and lambda
/λ
forms
of function definition accept an optional docstring.
fn pxy [x y]
("Print the sum of x and y"
print (+ x y)))
(
λ pxyz [x ?y z]
("Print the sum of x, y, and z. If y is not provided, defaults to 0."
print (+ x (or ?y 0) z))) (
These are ignored by default outside of the REPL, unless metadata is
enabled from the CLI (---metadata
) or compiler options
{useMetadata=true}
, in which case they are stored in a
metadata table along with the arglist, enabling viewing function docs
via the doc
macro.
>> (doc pxy)
(pxy x y)
Print the sum of x and y
All function metadata will be garbage collected along with the
function itself. Docstrings and other metadata can also be accessed via
functions on the fennel API with fennel.metadata
.
(Since 0.3.0)
It's pretty easy to create function literals, but Fennel provides an even shorter form of functions. Hash functions are anonymous functions of one form, with implicitly named arguments. All of the below functions are functionally equivalent.
fn [a b] (+ a b)) (
hashfn (+ $1 $2)) (
#(+ $1 $2)
This style of anonymous function is useful as a parameter to higher order functions, such as those provided by Lua libraries like lume and luafun.
The current implementation only allows for hash functions to use up
to 9 arguments, each named $1
through $9
, or
those with varargs, delineated by $...
instead of the usual
...
. A lone $
in a hash function is treated as
an alias for $1
.
Hash functions are defined with the hashfn
macro or
special character #
, which wraps its single argument in a
function literal. For example,
3 ; same as (fn [x y z] z)
#$1 $2 $3] ; same as (fn [a b c] [a b c])
#[$; same as (fn [x] x) (aka the identity function)
#$ ; same as (fn [] val)
#val :one :two $...] ; same as (fn [...] ["one" "two" ...]) #[
Hash arguments can also be used as parts of multisyms. For instance,
#$.foo
is a function which will return the value of the
"foo" key in its first argument.
partial
partial
applicationReturns a new function which works like its first argument, but fills the first few arguments in place with the given ones. This is related to currying but different because calling it will call the underlying function instead of waiting till it has the "correct" number of args.
Example:
partial (fn [x y] (print (+ x y))) 2) (
This example returns a function which will print a number that is 2 greater than the argument it is passed.
pick-values
emit
exactly n values(Since 0.4.0)
Discard all values after the first n when dealing with multi-values
(...
) and multiple returns. Useful for composing functions
that return multiple values with variadic functions. Expands to a
let
expression that binds and re-emits exactly n values,
e.g.
pick-values 2 (func)) (
expands to
let [(_0_ _1_) (func)] (values _0_ _1_)) (
Example:
pick-values 0 :a :b :c :d :e) ; => nil
(pick-values 2 (table.unpack [:a :b :c]))] ;-> ["a" "b"]
[(
fn add [x y ...] (let [sum (+ (or x 0) (or y 0))]
(if (= (select :# ...) 0) sum (add sum ...))))
(
pick-values 2 10 10 10 10)) ; => 20
(add (->> [1 2 3 4 5] (table.unpack) (pick-values 3) (add)) ; => 6 (
Note: If n is greater than the number of values
supplied, n values will still be emitted. This is reflected when using
(select "#" ...)
to count varargs, but tables
[...]
ignore trailing nils:
select :# (pick-values 5 "one" "two")) ; => 5
(pick-values 5 "one" "two")] ; => ["one" "two"] [(
pick-args
create a function of fixed arity(Since 0.4.0)
Like pick-values
, but takes an integer n
and a function/operator f
, and creates a new function that
applies exactly n
arguments to f
.
Example, using the add
function created above:
(pick-args 2 add) ; expands to `(fn [_0_ _1_] (add _0_ _1_))`
(-> [1 2 3 4 5] (table.unpack) ((pick-args 3 add))) ; => 6
(local count-args (partial select "#"))
((pick-args 3 count-args) "still three args, but 2nd and 3rd are nil") ; => 3
let
scoped localsIntroduces a new scope in which a given set of local bindings are used.
Example:
let [x 89]
(print (+ x 12)) ; => 101 (
These locals cannot be changed with set
but they can be
shadowed by an inner let
or local
. Outside the
body of the let
, the bindings it introduces are no longer
visible.
Any time you bind a local, you can destructure it if the value is a table or a function call which returns multiple values:
Example:
let [(x y z) (unpack [10 9 8])]
(+ x y z)) ; => 27 (
Example:
let [[a b c] [1 2 3]]
(+ a b c)) ; => 6 (
If a table key is a string with the same name as the local you want
to bind to, you can use shorthand of just :
for the key
name followed by the local name.
Example:
let [{:msg message : val} {:msg "hello there" :val 19}]
(print message)
(; prints "hello there" and returns 19 val)
When destructuring a sequential table, you can capture all the
remainder of the table in a local by using &
:
Example:
let [[a b & c] [1 2 3 4 5 6]]
(table.concat c ",")) ; => "3,4,5,6" (
When destructuring a non-sequential table, you can capture the
original table along with the destructuring by using
&as
:
Example:
let [{:a a :b b &as all} {:a 1 :b 2 :c 3 :d 4}]
(+ a b all.c all.d)) ; => 10 (
with-open
bind and auto-close file handles(Since 0.4.2)
While Lua will automatically close an open file handle when it's
garbage collected, GC may not run right away; with-open
ensures handles are closed immediately, error or no, without
boilerplate.
The usage is similar to let
, except:
:close
method.After executing the body, or upon encountering an error,
with-open
will invoke (value:close)
on every
bound variable before returning the results.
The body is implicitly wrapped in a function and run with
xpcall
so that all bound handles are closed before it
re-raises the error.
Example:
;; Basic usage
with-open [fout (io.open :output.txt :w) fin (io.open :input.txt)]
("Here is some text!\n")
(fout:write ; => first line of input.txt
((fin:lines)))
;; This demonstrates that the file will also be closed upon error.
var fh nil)
(local (ok err)
(pcall #(with-open [file (io.open :test.txt :w)]
(set fh file) ; you would normally never do this
(error :whoops!))))
(io.type fh) ; => "closed file"
(; => [false "<error message and stacktrace>"] [ok err]
local
declare localIntroduces a new local inside an existing scope. Similar to
let
but without a body argument. Recommended for use at the
top-level of a file for locals which will be used throughout the
file.
Example:
local tau-approx 6.28318) (
Supports destructuring and multiple-value binding.
match
pattern matching(Since 0.2.0)
Evaluates its first argument, then searches thru the subsequent pattern/body clauses to find one where the pattern matches the value, and evaluates the corresponding body. Pattern matching can be thought of as a combination of destructuring and conditionals.
Note: Lua also has "patterns" which are matched against strings similar to how regular expressions work in other languages; these are two distinct concepts with similar names.
Example:
match mytable
(59 :will-never-match-hopefully
9 q 5] (print :q q)
[1 a b] (+ a b)) [
In the example above, we have a mytable
value followed
by three pattern/body clauses. The first clause will only match if
mytable
is 59. The second clause will match if
mytable
is a table with 9 as its first element and 5 as its
third element; if it matches, then it evaluates
(print :q q)
with q
bound to the second
element of mytable
. The final clause will only match if
mytable
has 1 as its first element; if so then it will add
up the second and third elements.
Patterns can be tables, literal values, or symbols. If a symbol is
already in scope, then the value is checked against the existing value,
but if it's a new local then the symbol is bound to the value. The
_
pattern is treated as a wildcard that always matches.
Tables can be nested, and they may be either sequential
([]
style) or key/value ({}
style) tables.
Sequential tables will match if they have at least as many elements as
the pattern. (To allow an element to be nil, use a symbol like
?this
.) Tables will never fail to match due to having too
many elements. You can use &
to capture all the
remaining elements of a sequential table, just like
let
.
match mytable
(* b depth)
{:subtable [a b ?c] :depth depth} ( _ :unknown)
You can also match against multiple return values using parentheses. (These cannot be nested, but they can contain tables.) This can be useful for error checking.
match (io.open "/some/file")
(
(nil msg) (report-error msg) f (read-file f))
Pattern matching performs unification, meaning that if x
has an existing binding, clauses which attempt to bind it to a different
value will not match:
let [x 95]
(match [52 85 95]
(; because a=85 and a=95
[b a a] :no ; because x=95 and x=52
[x y z] :no ; a and b are fresh values while x=95 and x=95 [a b x] :yes))
There is a special case for _
; it is never bound and
always acts as a wildcard. If no clause matches, it returns nil.
Sometimes you need to match on something more general than a structure or specific value. In these cases you can use guard clauses:
match [91 12 53]
(= 5 a)) :will-not-match
(where [a b c] (= 0 (math.fmod (+ a b c) 2)) (= 91 a)) c) ; -> 53 (where [a b c] (
In this case the pattern should be wrapped in parentheses (like when
matching against multiple values) but the first thing in the parentheses
is the where
symbol. Each form after the pattern is a
condition; all the conditions must evaluate to true for that pattern to
match.
If several patterns share the same body and guards, such patterns can
be combined with or
special in the where
clause:
match [5 1 2]
(or [a 3 9] [a 1 2]) (= 5 a)) "Will match either [5 3 9] or [5 1 2]"
(where ("will match anything else") _
This is essentially equivalent to:
match [5 1 2]
(3 9] (= 5 a)) "Will match either [5 3 9] or [5 1 2]"
(where [a 1 2] (= 5 a)) "Will match either [5 3 9] or [5 1 2]"
(where [a "will match anything else") _
However, patterns which bind variables, should not be combined with
or
if different variables are bound in different patterns
or some variables are missing:
;; bad
match [1 2 3]
(;; Will throw an error because `b' is nil for the first
;; pattern but the guard still uses it.
or [a 1 2] [a b 3]) (> a 0) (> b 1))
(where (
:body)
;; ok
match [1 2 3]
(or [a b 2] [a b 3]) (> a 0) (>= b 1))
(where ( :body)
Note:: The match
macro can be used in
place of the if-let
macro from Clojure. The reason Fennel
doesn't have if-let
is that match
makes it
redundant.
Note 2:: Prior to Fennel 0.8.2 the
match
macro used infix ?
operator to test
patterns against the guards. While this syntax is still supported,
where
should be preferred instead:
match [1 2 3]
(2 3] (> a 0)) "new guard syntax"
(where [a 2 3] ? (> a 0)) "obsolete guard syntax") ([a
global
set global
variableSets a global variable to a new value. Note that there is no distinction between introducing a new global and changing the value of an existing one. This supports destructuring and multiple-value binding.
Example:
global prettyprint (fn [x] (print (fennel.view x)))) (
Note that every global is also exposed on the _G
table,
which can often be a better choice than using global
.
var
declare local
variableIntroduces a new local inside an existing scope which may have its
value changed. Identical to local
apart from allowing
set
to work on it.
Example:
var x 83) (
Supports destructuring and multiple-value binding.
set
set
local variable or table fieldChanges the value of a variable introduced with var
.
Will not work on globals or let
/local
-bound
locals. Can also be used to change a field of a table, even if the table
is bound with let
or local
, provided the field
is given at compile-time.
Example:
set x (+ x 91)) (
Example:
let [t {:a 4 :b 8}]
(set t.a 2) t) ; => {:a 2 :b 8} (
Supports destructuring and multiple-value binding.
tset
set table fieldSet the field of a given table to a new value. The field name does
not need to be known at compile-time. Works on any table, even those
bound with local
and let
.
Example:
let [tbl {:d 32} field :d]
(tset tbl field 19) tbl) ; => {:d 19} (
You can provide multiple successive field names to perform nested sets.
In any of the above contexts where you can make a new binding, you can use multiple value binding. Otherwise you will only capture the first value.
Example:
let [x (values 1 2 3)]
(; => 1 x)
Example:
let [(file-handle message code) (io.open "foo.blah")]
(; => "foo.blah: No such file or directory" message)
Example:
global (x-m x-e) (math.frexp 21)), {:m x-m :e m-e} ; => {:e 5 :m 0.65625} (
Example:
do (local (_ _ z) (unpack [:a :b :c :d :e])) z) => c (
if
conditionalChecks a condition and evaluates a corresponding body. Accepts any
number of condition/body pairs; if an odd number of arguments is given,
the last value is treated as a catch-all "else". Similar to
cond
in other lisps.
Example:
let [x (math.random 64)]
(if (= 0 (% x 10))
("multiple of ten"
= 0 (% x 2))
("even"
"I dunno, something else"))
All values other than nil or false are treated as true.
when
single
side-effecting conditionalTakes a single condition and evaluates the rest as a body if it's not nil or false. This is intended for side-effects.
Example:
when launch-missiles?
(
(power-on)
(open-doors) (fire))
each
general iterationRun the body once for each value provided by the iterator. Commonly
used with ipairs
(for sequential tables) or
pairs
(for any table in undefined order) but can be used
with any iterator.
Example:
each [key value (pairs mytbl)]
(print key (f value))) (
Any loop can be terminated early by placing an :until
clause at the end of the bindings:
local out [])
(each [_ value (pairs tbl) :until (< max-len (length out))]
(table.insert out value)) (
Most iterators return two values, but each
will bind any
number. See Programming in
Lua for details about how iterators work.
for
numeric loopCounts a number from a start to stop point (inclusive), evaluating the body once for each value. Accepts an optional step.
Example:
for [i 1 10 2]
(print i)) (
This example will print all odd numbers under ten.
Like each
, loops using for
can also be
terminated early with an :until
clause. The clause is
checked before each iteration of the body; if it is true at the
beginning then the body will not run at all.
var x 0)
(for [i 1 128 :until (maxed-out? x)]
(set x (+ x i))) (
do
evaluate multiple forms returning last valueAccepts any number of forms and evaluates all of them in order,
returning the last value. This is used for inserting side-effects into a
form which accepts only a single value, such as in a body of an
if
when multiple clauses make it so you can't use
when
. Some lisps call this begin
or
progn
.
if launch-missiles?
(do
(
(power-on)
(open-doors)
(fire))
false-alarm? (promote lt-petrov))
and
, or
, not
: boolean+
, -
, *
, /
,
//
, %
, ^
: arithmetic>
, <
, >=
,
<=
, =
, not=
: comparisonlshift
, rshift
, band
,
bor
, bxor
, bnot
: bitwise
operationsThese all work as you would expect, with a few caveats. The bitwise
operators are only availible in Lua 5.3+, unless you use the
--use-bit-lib
flag or the useBitLib
flag in
the options table, which lets them be used in LuaJIT. The integer
division operator (//
) is only availible in Lua 5.3+.
They all take any number of arguments, as long as that number is
fixed at compile-time. For instance, (= 2 2 (unpack [2 5]))
will evaluate to true
because the compile-time number of
values being compared is 3.
Note that these are all special forms which cannot be used as higher-order functions.
..
string concatenationConcatenates its arguments into one string. Will coerce numbers into strings, but not other types.
Example:
"Hello" " " "world" 7 "!!!") ; => "Hello world7!!!" (..
length
string or
table length(Changed in 0.3.0: the function was called #
before.)
Returns the length of a string or table. Note that the length of a
table with gaps (nils) in it is undefined; it can return a number
corresponding to any of the table's "boundary" positions between nil and
non-nil values. If a table has nils and you want to know the last
consecutive numeric index starting at 1, you must calculate it yourself
with ipairs
; if you want to know the maximum numeric key in
a table with nils, you can use table.maxn
.
Example:
+ (length [1 2 3 nil 8]) (length "abc")) ; => 6 or 8 (
.
table lookupLooks up a given key in a table. Multiple arguments will perform nested lookup.
Example:
(. mytbl myfield)
Example:
let [t {:a [2 3 4]}] (. t :a 2)) ; => 3 (
Note that if the field name is a string known at compile time, you
don't need this and can just use mytbl.field
.
?.
table
lookupLooks up a given key in a table. Multiple arguments will perform
nested lookup. If any of subsequent keys is not present, will
short-circuit to nil
.
Example:
(?. mytbl myfield)
Example:
let [t {:a [2 3 4]}] (?. t :a 4 :b)) ; => nil
(let [t {:a [2 3 4 {:b 42}]}] (?. t :a 4 :b)) ; => 42 (
:
method callLooks up a function in a table and calls it with the table as its first argument. This is a common idiom in many Lua APIs, including some built-in ones.
(Since 0.3.0) Just like Lua, you can perform a method call
by calling a function name where :
separates the table
variable and method name.
Example:
let [f (assert (io.open "hello" "w"))]
("world")
(f:write (f:close))
If the name of the method isn't known at compile time, you can use
:
followed by the table and then the method's name as a
string.
Example:
let [f (assert (io.open "hello" "w"))
(
method1 :write
method2 :close]: f method1 "world")
(: f method2)) (
Both of these examples are equivalent to the following:
let [f (assert (io.open "hello" "w"))]
("world")
(f.write f (f.close f))
values
multi-valued
returnReturns multiple values from a function. Usually used to signal failure by returning nil followed by a message.
Example:
fn [filename]
(if (valid-file-name? filename)
(
(open-file filename)values nil (.. "Invalid filename: " filename)))) (
while
good old while
loopLoops over a body until a condition is met. Uses a native Lua
while
loop, so this can be faster than recursion.
Example:
var done? false)
(while (not done?)
(print :not-done)
(when (> (math.random) 0.95)
(set done? true))) (
collect
,
icollect
table comprehension macrosThe collect
macro takes a "iterator binding table" in
the format that each
takes, and an expression that produces
key-value pairs, and runs through the iterator, filling a new table with
the key-value pairs produced by the expression. The expression must
produce 2 values, or nil.
collect [k v (pairs {:apple "red" :orange "orange"})]
(values (.. "color-" v) k))
(;; -> {:color-orange "orange" :color-red "apple"}
;; equivalent to:
let [tbl {}]
(each [k v (pairs {:apple "red" :orange "orange"})]
(match (values (.. "color-" v) k)
(tset tbl key value)))
(key value) ( tbl)
The icollect
macro is almost identical, except that the
expression returns one value and the new table is filled sequentially to
produce a sequential table. Adding a when
condition around
the expression can act effectively as a filter, since inserting a nil
value into a table is a no-op.
icollect [_ v (ipairs [1 2 3 4 5 6])]
(when (> v 2) (* v v)))
(;; -> [9 16 25 36]
;; equivalent to:
let [tbl []]
(each [_ v (ipairs [1 2 3 4 5 6])]
(tset tbl (+ (length tbl) 1) (when (> v 2) (* v v))))
( tbl)
Like each
and for
, the table comprehensions
support an :until
clause for early termination.
->
,
->>
, -?>
and -?>>
threading macrosThe ->
macro takes its first value and splices it
into the second form as the first argument. The result of evaluating the
second form gets spliced into the first argument of the third form, and
so on.
Example:
-> 52
(+ 91 2) ; (+ 52 91 2)
(- 8) ; (- (+ 52 91 2) 8)
(print "is the answer")) ; (print (- (+ 52 91 2) 8) "is the answer") (
The ->>
macro works the same, except it splices it
into the last position of each form instead of the first.
-?>
and -?>>
, the thread maybe
macros, are similar to ->
& ->>
but they also do checking after the evaluation of each threaded form. If
the result is false or nil then the threading stops and the result is
returned. -?>
splices the threaded value as the first
argument, like ->
, and -?>>
splices
it into the last position, like ->>
.
This example shows how to use them to avoid accidentally indexing a nil value:
-?> {:a {:b {:c 42}}}
(
(. :a)
(. :missing); -> nil
(. :c)) -?>> :a
(
(. {:a :b})
(. {:b :missing})42})) ; -> nil (. {:c
While ->
and ->>
pass multiple
values thru without any trouble, the checks in -?>
and
-?>>
prevent the same from happening there without
performance overhead, so these pipelines are limited to a single
value.
Note that these have nothing to do with "threads" used for concurrency; they are named after the thread which is used in sewing. This is similar to the way that
|>
works in OCaml and Elixir.
doto
Similarly, the doto
macro splices the first value into
subsequent forms. However, it keeps the same value and continually
splices the same thing in rather than using the value from the previous
form for the next form.
doto (io.open "/tmp/err.log")
(: :write contents)
(: :close))
(
;; equivalent to:
let [x (io.open "/tmp/err.log")]
(: x :write contents)
(: x :close)
( x)
The first form becomes the return value for the whole expression, and subsequent forms are evaluated solely for side-effects.
include
(since 0.3.0)
include :my.embedded.module) (
Load Fennel/Lua module code at compile time and embed in the compiled
output. The module name must be a string literal that can resolve to a
module during compilation. The bundled code will be wrapped in a
function invocation in the emitted Lua and set on
package.preload[modulename]
; a normal require
is then emitted where include
was used to load it on demand
as a normal module.
In most cases it's better to use require
in your code
and use the requireAsInclude
option in the API
documentation and the --require-as-include
CLI flag
(fennel --help
) to accomplish this.
The require
function is not part of Fennel; it comes
from Lua. However, it works to load Fennel code. See the end of the tutorial and Programming in Lua for
details about require
.
All forms which introduce macros do so inside the current scope. This is usually the top level for a given file, but you can introduce macros into smaller scopes as well. Note that macros are a compile-time construct; they do not exist at runtime. As such macros cannot be exported at the bottom of a module.
import-macros
load macros from a separate module(Since 0.4.0)
Loads a module at compile-time and binds its functions as local macros.
A macro module exports any number of functions which take code forms
as arguments at compile time and emit lists which are fed back into the
compiler as code. The module calling import-macros
gets
whatever functions have been exported to use as macros. For instance,
here is a macro module which implements when2
in terms of
if
and do
:
fn when2 [condition body1 ...]
(assert body1 "expected body")
(if ,condition
`(do ,body1 ,...)))
(
{:when2 when2}
A full explanation of how macros work is out of scope for this
document, but you can think of it as a compile-time template function.
The backtick on the third line creates a template for the code emitted
by the macro. The ,
serves as "unquote" which splices
values into the template. (Changed in 0.3.0: @
was used
instead of ,
before.)
Assuming the code above is in the file "my-macros.fnl" then it turns this input:
import-macros {: when2} :my-macros)
(
= 3 (+ 2 a))
(when2 (print "yes")
( (finish-calculation))
and transforms it into this code at compile time by splicing the arguments into the backtick template:
if (= 3 (+ 2 a))
(do
(print "yes")
( (finish-calculation)))
The import-macros
macro can take any number of
binding/module-name pairs. It can also bind the entire macro module to a
single name rather than destructuring it. In this case you can use a dot
to call the individual macros inside the module:
import-macros mine :my-macros)
(
= 3 (+ 2 a))
(mine.when2 (print "yes")
( (finish-calculation))
Note that all macro code runs at compile time, which happens before runtime. Locals which are in scope at runtime are not visible during compile-time. So this code will not work:
local (module-name file-name) ...)
(import-macros mymacros (.. module-name ".macros")) (
However, this code will work, provided the module in question exists:
import-macros mymacros (.. ... ".macros")) (
See "Compiler API" below for details about additional functions visible inside compiler scope which macros run in.
require-macros
load macros with less flexibilityThe require-macros
form is like
import-macros
, except it does not give you any control over
the naming of the macros being imported. It is strongly recommended to
use import-macros
instead.
By default, Fennel will search for macro modules using the same logic
it uses to search for normal runtime modules: by walking thru entries on
fennel.path
and checking the filesystem for matches.
However, in some cases this might not be suitable, for instance if your
Fennel program is packaged in some kind of archive file and the modules
do not exist as distinct files on disk.
To support this case you can add your own searcher function to the
fennel.macro-searchers
table. For example, assuming
find-in-archive
is a function which can look up strings
from the archive given a path:
local fennel (require :fennel))
(
fn my-searcher [module-name]
(let [filename (.. "src/" module-name ".fnl")]
(match (find-in-archive filename)
(values (partial fennel.eval code {:env :_COMPILER})
code (
filename))))
table.insert fennel.macro-searchers my-searcher) (
The searcher function should take a module name as a string and return two values if it can find the macro module: a loader function which will return the macro table when called, and an optional filename. The loader function will receive the module name and the filename as arguments.
macros
define several
macros(Since 0.3.0)
Defines a table of macros. Note that inside the macro definitions, you cannot access variables and bindings from the surrounding code. The macros are essentially compiled in their own compiler environment. Again, see the "Compiler API" section for more details about the functions available here.
macros {:my-max (fn [x y]
(let [x# ,x y# ,y]
`(if (< x# y#) y# x#)))})
(
print (my-max 10 20))
(print (my-max 20 10))
(print (my-max 20 20)) (
macro
define a single
macromacro my-max [x y]
(let [x# ,x y# ,y]
`(if (< x# y#) y# x#))) (
If you are only defining a single macro, this is equivalent to the
previous example. The syntax mimics fn
.
macrodebug
print the expansion of a macromacrodebug (-> abc
(+ 99)
(> 0)
(when (os.exit))))
(; -> (if (> (+ abc 99) 0) (do (os.exit)))
Call the macrodebug
macro with a form and it will
repeatedly expand top-level macros in that form and print out the
resulting form. Note that the resulting form will usually not be
sensibly indented, so you might need to copy it and reformat it into
something more readable.
Note that this prints at compile-time since macrodebug
is a macro.
It's easy to make macros which accidentally evaluate their arguments more than once. This is fine if they are passed literal values, but if they are passed a form which has side-effects, the result will be unexpected:
var v 1)
(macros {:my-max (fn [x y]
(if (< ,x ,y) ,y ,x))})
`(
fn f [] (set v (+ v 1)) v)
(
print (my-max (f) 2)) ; -> 3 since (f) is called twice in the macro body above (
(Since 0.3.0) In order to prevent accidental symbol
capture2,
you may not bind a bare symbol inside a backtick as an identifier.
Appending a #
on the end of the identifier name as above
invokes "auto gensym" which guarantees the local name is unique.
macros {:my-max (fn [x y]
(let [x2 ,x y2 ,y]
`(if (< x2 y2) y2 x2)))})
(
print (my-max 10 20))
(; Compile error in 'x2' unknown:?: macro tried to bind x2 without gensym; try x2# instead
macros
is useful for one-off, quick macros, or even some
more complicated macros, but be careful. It may be tempting to try and
use some function you have previously defined, but if you need such
functionality, you should probably use import-macros
.
For example, this will not compile in strict mode! Even when it does
allow the macro to be called, it will fail trying to call a global
my-fn
when the code is run:
fn my-fn [] (print "hi!"))
(
macros {:my-max (fn [x y]
(
(my-fn)let [x# ,x y# ,y]
`(if (< x# y#) y# x#)))})
(; Compile error in 'my-max': attempt to call global '__fnl_global__my_2dfn' (a nil value)
eval-compiler
Evaluate a block of code during compile-time with access to compiler scope. This gives you a superset of the features you can get with macros, but you should use macros if you can.
Example:
eval-compiler
(each [name (pairs _G)]
(print name))) (
This prints all the functions available in compiler scope.
Inside eval-compiler
, macros
, or
macro
blocks, as well as import-macros
modules, these functions are visible to your code.
As of 0.6.0 the compiler will warn you if you try to use globals
outside a certain predetermined safe list in a macro; this will turn
into an error in a future version of Fennel. You can disable this
warning by providing the command-line argument
--no-compiler-sandbox
or by passing
{:compiler-env _G}
in the options table when invoking the
compiler programmatically.
Please note that the sandbox is not suitable to be used as a robust security mechanism. It has not been audited and should not be relied upon to protect you from running untrusted code.
Note that lists are compile-time concepts that don't exist at
runtime; they are implemented as tables which have a special metatable
to distinguish them from regular tables defined with square or curly
brackets. Similarly symbols are tables with a string entry for their
name and a marker metatable. You can use tostring
to get
the name of a symbol.
list
- return a list, which is a special kind of
table used for code
sym
- turn a string into a symbol
list?
- is the argument a list?
sym?
- is the argument a symbol?
table?
- is the argument a non-list table?
sequence?
- is the argument a non-list
sequential table (created with []
, as opposed to
{}
)?
gensym
- generates a unique symbol for use in
macros.
varg?
- is this a ...
symbol which
indicates var args?
multi-sym?
- a multi-sym is a dotted symbol which
refers to a table's field
gensym
- generate a guaranteed-unique
symbol
view
- fennel.view
table
serializer
assert-compile
- works like assert
but
takes a list/symbol as its third argument in order to provide pinpointed
error messages.
These functions can be used from within macros only, not from any
eval-compiler
call:
in-scope?
- does this symbol refer to an in-scope
local?macroexpand
- performs macroexpansion on its argument
form; returns an ASTNote that other internals of the compiler exposed in compiler scope are subject to change.
lua
Escape HatchThere are some cases when you need to emit Lua output from Fennel in
ways that don't match Fennel's semantics. For instance, if you are
porting an algorithm from Lua that uses early returns, you may want to
do the port as literally as possible first, and then come back to it
later to make it idiomatic. You can use the lua
special
form to accomplish this:
fn find [tbl pred]
(each [key val (pairs tbl)]
(when (pred val)
(lua "return key")))) (
Lua code inside the string can refer to locals which are in scope;
however note that it must refer to the names after mangling has been
done, because the identifiers must be valid Lua. The Fennel compiler
will emit foo-bar
as foo_bar
in the Lua output
in order for it to be valid. When in doubt, inspect the compiler output
to see what it looks like.
Normally in these cases you would want to emit a statement, in which case you would pass a string of Lua code as the first argument. But you can also use it to emit an expression if you pass in a string as the second argument.
Note that this should only be used in exceptional circumstances, and if you are able to avoid it, you should.
The fennel
module provides the following functions for
use when embedding Fennel in a Lua program. If you're writing a pure
Fennel program or working on a system that already has Fennel support,
you probably don't need this.
Any time a function takes an options
table argument,
that table will usually accept these fields:
allowedGlobals
: a sequential table of strings of the
names of globals which the compiler will allow references to. Set to
false to disable checks.correlate
: when this is truthy, Fennel attempts to emit
Lua where the line numbers match up with the Fennel input code; useful
for situation where code that isn't under your control will print the
stack traces.useMetadata
(since 0.3.0): enables or disables
metadata, allowing use
of the doc macro. Intended for development purposes (see performance note); defaults to
true for REPL only.requireAsInclude
(since 0.3.0): Alias any
static require
calls to the include
special,
embedding the module code inline in the compiled output. If the module
name isn't a string literal or resolvable at compile time, falls back to
require
at runtime. Can be used to embed both fennel and
Lua modules.env
: an environment table in which to run the code; see
the Lua manual.compilerEnv
: an environment table in which to run
compiler-scoped code for macro definitions and
eval-compiler
calls. Internal Fennel functions such as
list
, sym
, etc. will be exposed in addition to
this table. Defaults to a table containing limited known-safe globals.
Pass _G
to disable sandboxing.unfriendly
: disable friendly compiler/parser error
messages.You can pass the string "_COMPILER"
as the value for
env
; it will cause the code to be run/compiled in a context
which has all compiler-scoped values available. This can be useful for
macro modules or compiler plugins.
Note that only the fennel
module is part of the public
API. The other modules (fennel.utils
,
fennel.compiler
, etc) should be considered compiler
internals subject to change.
.repl([options]) fennel
Takes these additional options:
readChunk()
: a function that when called, returns a
string of source code. The empty is string is used as the end of source
marker.pp
: a pretty-printer function to apply on values.onValues(values)
: a function that will be called on all
returned top level values.onError(errType, err, luaSource)
: a function that will
be called on each error. errType
is a string with the type
of error, can be either, 'parse', 'compile', 'runtime', or 'lua'.
err
is the error message, and luaSource
is the
source of the generated lua code.src/fennel/view.fnl
will produce output that can be fed
back into Fennel (other than functions, coroutines, etc) but you can use
a 3rd-party pretty-printer that produces output in Lua format if you
prefer.
If you don't provide allowedGlobals
then it defaults to
being all the globals in the environment under which the code will run.
Passing in false
here will disable global checking
entirely.
By default, metadata will be enabled and you can view function
signatures and docstrings with the doc
macro from the
REPL.
local result = fennel.eval(str[, options[, ...]])
The options
table may also contain:
filename
: override the filename that Lua thinks the
code came from.Additional arguments beyond options
are passed to the
code and available as ...
.
local result = fennel.dofile(filename[, options[, ...]])
table.insert(package.loaders or package.searchers, fennel.searcher)
local mylib = require("mylib") -- will compile and load code in mylib.fnl
Normally Lua's require
function only loads modules
written in Lua, but you can install fennel.searcher
into
package.searchers
(or in Lua 5.1
package.loaders
) to teach it how to load Fennel code.
If you would rather change some of the options you can use
fennel.makeSearcher(options)
to get a searcher function
that's equivalent to fennel.searcher
but overrides the
default options
table.
The require
function is different from
fennel.dofile
in that it searches the directories in
fennel.path
for .fnl
files matching the module
name, and also in that it caches the loaded value to return on
subsequent calls, while fennel.dofile
will reload each
time. The behavior of fennel.path
mirrors that of Lua's
package.path
.
If you install Fennel into package.searchers
then you
can use the 3rd-party lume.hotswap function to
reload modules that have been loaded with require
.
The fennel.traceback
function works like Lua's
debug.traceback
function, except it tracks line numbers
from Fennel code correctly.
If you are working on an application written in Fennel, you can override the default traceback function to replace it with Fennel's:
debug.traceback = fennel.traceback
print(fennel.searchModule("my.mod", package.path))
If you just want to find the file path that a module would resolve to
without actually loading it, you can use
fennel.searchModule
. The first argument is the module name,
and the second argument is the path string to search. If none is
provided, it defaults to Fennel's own path.
Returns nil
if the module is not found on the path.
local lua = fennel.compileString(str[, options])
Accepts indent
as a string in options
causing output to be indented using that string, which should contain
only whitespace if provided. Unlike the other functions, the
compile
functions default to performing no global checks,
though you can pass in an allowedGlobals
table in
options
to enable it.
local lua = fennel.compileStream(strm[, options])
Accepts indent
in options
as per above.
The code can be loaded via dostring or other methods. Will error on bad input.
local lua = fennel.compile(ast[, options])
Accepts indent
in options
as per above.
local stream = fennel.stringStream(str)
Useful for the REPL or reading files in chunks. This will NOT insert newlines or other whitespace between chunks, so be careful when using with io.read(). Returns a second function, clearstream, which will clear the current buffered chunk when called. Useful for implementing a repl.
local bytestream, clearstream = fennel.granulate(chunks)
The fennel.parser
function returns a stateful iterator
function. It returns true in the first return value if an AST was read,
and returns nil if an end of file was reached without error. Will error
on bad input or unexpected end of source.
local parse = fennel.parser(strm)
local ok, ast = parse()
-- Or use in a for loop
for ok, ast in parse do
print(ok, ast)
end
The fennel.parser
function takes two optional arguments;
a filename and a table of options. Supported options are both booleans
that default to false:
unfriendly
: disable enhanced parse error reportingcomments
: include comment nodes in ASTThe AST returned by the parser consists of data structures
representing the code. Passing AST nodes to the fennel.view
function will give you a string which should round-trip thru the parser
to give you the same data back. The same is true with
tostring
, except it does not work with kv tables.
AST nodes can be any of these types:
A list represents a call to function/macro, or destructuring multiple
return values in a binding context. It's represented as a table which
can be identified using the fennel.list?
predicate function
or constructed using fennel.list
which takes any number of
arguments for the contents of the list.
The list also contains these keys indicating where it was defined:
filename
, line
, bytestart
, and
byteend
. This data is used for stack traces and for
pinpointing compiler error messages.
These are table literals in Fennel code produced by square brackets
(sequences) or curly brackets (kv tables). Sequences can be identified
using the fennel.sequence?
function and constructed using
fennel.sequence
. There is no predicate or constructor for
kv tables; any table which is not one of the other types is assumed to
be one of these.
At runtime there is no difference between sequences and kv tables which use monotonically increasing integer keys, but the parser is able to distinguish between them.
Sequences have their source data in filename
,
line
, etc keys just like lists. But kv tables cannot have
this, because adding arbitrary keys to the table would change its
contents, so these fields are instead stored on the metatable. The
metatable for kv tables also includes a keys
sequence which
tells you which order the keys appeared originally, since kv tables are
unordered and there would otherwise be no way to reconstruct this
information.
Symbols typically represent identifiers in Fennel code. Symbols can
be identified with fennel.sym?
and constructed with
fennel.sym
which takes a string name as its first argument
and a source data table as the second. Symbols are represented as tables
which store their source data in fields on themselves. Unlike the other
tables in the AST, they do not represent collections; they are used as
scalar types.
Note: nil
is not a valid AST; code that
references nil will have the symbol named "nil"
which
unfortunately prints in a way that is visually indistinguishable from
actual nil
.
This is a special type of symbol-like construct (...
)
indicating functions using a variable number of arguments. Its meaning
is the same as in Lua. It's identified with fennel.varg?
and constructed with fennel.varg
.
These are literal types defined by Lua. They cannot carry source data.
By default, ASTs will omit comments. However, when the
:comment
field is set in the parser options, comments will
be included in the parsed values. They are identified using
fennel.comment?
and constructed using the
fennel.comment
function. They are represented as tables
that have source data as fields inside them.
In most data context, comments just get included inline in a list or
sequence. However, in a kv table, this cannot be done, because kv tables
must have balanced key/value pairs, and including comments inline would
imbalance these or cause keys to be considered as values and vice versa.
So the comments are stored on the comments
field of
metatable instead, keyed by the key or value they were attached to.
(Since 0.3.0)
When running a REPL or using compile/eval with metadata enabled, each
function declared with fn
or λ/lambda
will use
the created function as a key on fennel.metadata
to store
the function's arglist and (if provided) docstring. The metadata table
is weakly-referenced by key, so each function's metadata will be garbage
collected along with the function itself.
You can work with the API to view or modify this metadata yourself,
or use the doc
macro from fennel to view function
documentation.
In addition to direct access to the metadata tables, you can use the following methods:
fennel.metadata:get(func, key)
: get a value from a
function's metadatafennel.metadata:set(func, key, val)
: set a metadata
valuefennel.metadata:setall(func, key1, val1, key2, val2, ...)
:
set pairsfennel.doc(func, fnName)
: print formatted documentation
for function using name. Utilized by the doc
macro, name is
whatever symbol you operate on that's bound to the function.= fennel.eval([[
greet (λ greet [name] "Say hello" (print (string.format "Hello, %s!" name)))
]], {useMetadata = true})
-- fennel.metadata[greet]
-- > {"fnl/docstring" = "Say hello", "fnl/arglist" = ["name"]}
-- works because greet was set globally above for example purposes only
.eval("(doc greet)", { useMetadata = true })
fennel-- > (greet name)
-- > Say hello
.metadata:set(greet, "fnl/docstring", "Say hello!!!")
fennel.doc(greet, "greet!")
fennel--> (greet! name)
--> Say hello!!!
Enabling metadata in the compiler/eval/REPL will cause every function to store a new table containing the function's arglist and docstring in the metadata table, weakly referenced by the function itself as a key.
This may have a performance impact in some applications due to the extra allocations and garbage collection associated with dynamic function creation. The impact hasn't been benchmarked, and may be minimal particularly in luajit, but enabling metadata is currently recommended for development purposes only to minimize overhead.
This isn't Fennel-specific, but the loadCode
function
takes a string of Lua code along with an optional environment table and
filename string, and returns a function for the loaded code which will
run inside that environment, in a way that's portable across any Lua
5.1+ version.
local f = fennel.loadCode(luaCode, { x = y }, "myfile.lua")
Fennel's plugin system is extremely experimental and exposes internals of the compiler in ways that no other part of the compiler does. It should be considered unstable; changes to the compiler in future versions are likely to break plugins, and each plugin should only be assumed to work with specific versions of the compiler that they're tested against. The backwards-compatibility guarantees of the rest of Fennel do not apply to plugins.
Compiler plugins allow the functionality of the compiler to be extended in various ways. A plugin is a module containing various functions in fields named after different compiler extension points. When the compiler hits an extension point, it will call each plugin's function for that extension point, if provided, with various arguments; usually the AST in question and the scope table.
symbol-to-expression
call
do
fn
destructure
The destructure
extension point is different because
instead of just taking ast
and scope
it takes
a from
which is the AST for the value being destructured
and a to
AST which is the AST for the form being
destructured to. This is most commonly a symbol but can be a list or a
table.
The scope
argument is a table containing all the
compiler's information about the current scope. Most of the tables here
look up values in their parent scopes if they do not contain a key.
Plugins can also contain repl commands. If your plugin module has a field with a name beginning with "repl-command-" then that function will be available as a comma command from within a repl session. It will be called with a table for the repl session's environment, a function which will read the next form from stdin, a function which is used to print normal values, and one which is used to print errors.
local fennel (require :fennel)
(fn locals [env _read on-values on-error]
("Print all locals in repl session scope."
(on-values [(fennel.view env.___replLocals___)]))
{:repl-command-locals locals}
$ fennel --plugin locals-plugin.fnl
Welcome to Fennel 0.8.0 on Lua 5.4!
Use ,help to see available commands.
>> (local x 4)
nil
>> (local abc :xyz)
nil
>> ,locals
{
:abc "xyz"
:x 4
}
The docstring of the function will be used as its summary in the ",help" command listing. Unlike other plugin hook fields, only the first plugin to provide a repl command will be used.
Plugins are activated by passing the --plugin
argument
on the command line, which should be a path to a Fennel file containing
a module that has some of the functions listed above. If you're using
the compiler programmatically, you can include a :plugins
table in the options
table to most compiler entry point
functions.