Changes are marked in bold which could result in backwards-incompatibility.
Note that since 0.3.0, no deprecations have actually resulted in removals. They are advisory only and we have no plans to break the deprecated forms.
fcollect
macro for range "comprehension"include
splice modules in where they're used instead of at the topast-source
function to API to get file/line info from AST nodes&into
/&until
to certain looping constructs--compile-binary
nil
nil
were emitted by unquote
in a macro, and the macro was not compiled correctly because the resulting list length was calculated incorrectly,doc m.foo
did not resolve multisym to macro for macro modules loaded as macro table via (import-macros m :my.macro.module)
match-try
macro for chained pattern matching for steps which might failfennel.parser
function now accepts a string in addition to an iteratoraccumulate
macro can now accumulate over multiple valuesfn
special now accepts a metadata table in place of a docstring,reload mod
repl command can now reload macro modules--skip-include
would mistakenly emit a warningand
/or
nil
did not show up in REPL completiongranulate
and string-stream
functions in the APIglobal
form in favor of using the _G
tablecollect
to take two direct body arguments instead of requiring values
--rename-native-module
when compiling binaries:into
clause to collect
and icollect
--globals "*"
--require-as-include
fails to find a module to include--add-macro-path
for configuring macro path similarly to fennel module paths__fennelrest
metamethod for changing &
destructuring behavior&
destructuring inside match
import-macros
fennel.view
function no longer outputs invalid UTF-8 when given invalid input-?>
and -?>>
checked for false values, not just nillet
locals escaped their scope at the top level of the replfennelview.lua
from the repo as it is part of the main API nowdoc
special form; replace with ,doc
repl commandicollect
by avoiding unnecessary length checksif
are treated as nil, not zero values_
for else clause in match
It's Fennel's 5th birthday! We've got the new accumulate
macro for reducing over tables, plus a couple new repl commands and more flexibility when using include
.
accumulate
macro for reduce operations--skip-include
option to prevent modules from being included in output,apropos pattern
and ,apropos-doc pattern
repl commands,complete foo
repl commandfennel.syntax
function describing built-ins-c
alias for --compile
in command line argumentsinclude
and make --require-as-include
resolve module names dynamically. See the require section in the referencemax-sparse-gap
option in fennel.view
pick-args
macrofennel.macro-path
for searching for macro modules and FENNEL_MACRO_PATH
environment variableThis release mostly contains small bug fixes.
_ENV
as an unknown global?.
when used directly on nilwhere
--use-bit-lib
was not propagating to the REPLThis release contains one small bug fix.
The biggest change in this release is the addition of the :until
clause in all iteration forms to end iteration early.
?.
where
/or
clauses in match
--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.viewThis release mostly contains small bug fixes.
The highlight of this release is the table comprehension macros which take the place of map
in other lisps. The &as
clause in destructuring now allows you to access the original table even as you destructure it into its fields. The fennel.view
serializer has been completely rewritten to improve indentation.
collect
/icollect
)fennel.view
fennel.view
for better indentation handlingdoc
&as
...
arguments consistently with Lua when requiring modules__fennelview
metamethod on userdata metatables...
inside eval-compiler
import-macros
would not respect certain compiler options&
character in identifiers; will be disallowed laterThis release adds support for reloading modules in the repl, making interactive development more streamlined.
,reload
; see ,help
for a full list--no-compiler-sandbox
did not apply in import-macros
macrodebug
fail to print correctly:
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.
--lua
CLI flag for specifying a custom Lua command/executablelist?
and sym?
in compiler API@
This release features a version of the Fennel compiler that is self-hosted and written entirely in Fennel!
fennel.friend
module is now incorporated into the compiler, not separateinclude
would get skippedThis release mostly includes small bug fixes but also adds the with-open
macro for automating closing file handles, etc.
$...
with-open
macro for auto-closing file handles--native-module
and --native-library
to --compile-binary
commandfennel.searchModule
function to module APIinclude
calls would splice locals incorrectly#
) couldn't be used as multisymsinclude
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
commandThis 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 loadingrshift
, lshift
, bor
, band
, bnot
, and bxor
macroexpand
helper to expand macro forms during compilationmacrodebug
utility macro for printing expanded macro forms in REPLpick-values
and pick-args
macrosFENNEL_DEBUG=trace
__fennelview
metamethod for custom serializationdofile
would report the wrong filenameinclude
of Lua modules that lack a trailing newlineThis release mostly contains small bug fixes.
include
could not be nested without repetitionelse
to emit twice in some contextsThis release mostly contains small bug fixes.
--load FILE
argument to command-line launchereach
to work with raw iterator valuesThis 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.
include
special form to selectively inline modules in compiled outputdoc
for displaying them in repl#
special with length
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:detect-cycles? false
in fennelview to turn off "#<table 1>" outputx#
syntax for auto-gensym inside backtick:one-line
output in fennelview--require-as-include
to inline required modules in compiled output--eval
argument to command-line launcherFENNEL_PATH
to path
?
in pattern matchingreadline.lua
is available--globals
and --globals-only
options to launcher script(foo:bar baz)
; disallow :
in symbolslambda
argument checks when using destructuringmatch
luaexpr
and luastatement
for a single lua
special@
(unquote) with ,
; comma is no longer whitespace~
in symbols other than ~=
This 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.
-?>
and -?>>
macrosmatch
macro for pattern matchingmacros
@
(later changed to ,
)--add-package-path
and --add-fennel-path
to launcher scriptThis 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".
->
and ->>
macrosvar
; disallow regular locals from being setglobal
; refuse to set globals without itrequire-macros
//
for integer division on Lua 5.3+fennel.dofile
and fennel.searcher
for require
supportpartial
local
doto
macro:
for method callseach
lambda
/λ
for nil-argument-checked functionswhen
&
.
formpack
, $
, block
, *break
, special
defn
macroThe initial version (named "fnl") was created in 8 days and then set aside for several years.
This document covers the syntax, built-in macros, and 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. This is not an introductory text; see the tutorial for that.
A macro is a function which runs at compile time and transforms some Fennel code into different Fennel. A special form (or special) is a primitive construct which emits Lua code directly. When you are coding, you don't need to care about the difference between built-in macros and special forms; it is an implementation detail.
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.
The one exception to this compile-time rule is the fennel.view
function which returns a string representation of any Fennel data suitable for printing. But this is not part of the language itself; it is a library function which can be used from Lua just as easily.
Fennel source code should be UTF-8-encoded text.
(parentheses)
: used to delimit lists, which are primarily used to denote calls to functions, macros, and specials, but also can be used in binding contexts to bind to multiple values. Lists are a compile-time construct; they are not used at runtime. For example: (print "hello world")
{curly brackets}
: used to denote key/value table literals, for example: {:a 1 :b 2}
[square brackets]
: used to denote sequential tables, which can be used for literal data structures and also in specials and macros to delimit where new identifiers are introduced, such as argument lists or let bindings. For example: [1 2 3]
The syntax for numbers is the same as Lua's, except that underscores may be used to separate digits for readability. Non-ASCII digits are not yet supported.
The syntax for strings uses double-quotes "
around the string's contents. Double quotes inside a string must be escaped with backslashes. The syntax for these is the same as Lua's, except that strings may contain newline characters. Single-quoted or long bracket strings are not supported.
Fennel has a lot fewer restrictions on identifiers than Lua. Identifiers are represented by symbols, but identifiers are not exactly the same as symbols; some symbols are used by macros for things other than identifiers. Symbols may not begin with digits or a colon, but may have digits anywhere else. Beyond that, any unicode characters are accepted as long as they are not unprintable or whitespace, one of the delimiter characters mentioned above, one of the a prefix characters listed below, or one of these reserved characters:
'
~
;
@
Underscores are allowed in identifier names, but dashes are preferred as word separators. By convention, identifiers starting with underscores are used to indicate that a local is bound but not meant to be used.
The ampersand character &
is allowed in symbols but not in identifiers. This allows it to be reserved for macros, like the behavior of &as
in destructuring.
Symbols that contain a dot .
or colon :
are considered "multi symbols". The part of the symbol before the first dot or colon is used as an identifier, and the part after the dot or colon is a field looked up on the local identified. A colon is only allowed before the final segment of a multi symbol, so x.y:z
is valid but a:b.c
is not. Colon multi symbols cannot be used for anything but method calls.
Fennel also supports certain kinds of strings that begin with a colon as long as they don't contain any characters which wouldn't be allowed in a symbol, for example :fennel-lang.org
is a string.
Spaces, tabs, newlines, vertical tabs, form feeds, and carriage returns are counted as whitespace. Non-ASCII whitespace characters are not yet supported.
Certain prefixes are expanded by the parser into longhand equivalents:
#foo
expands to (hashfn foo)
`foo
expands to (quote foo)
,foo
expands to (unquote foo)
A semicolon and everything following it up to the end of the line is a comment.
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 given values of nil
.
Example:
Giving it a name is optional; if one is provided it will be bound to it as a local. Providing a name that's a table field will cause it to be inserted in a table instead of bound as a local:
Like Lua, functions in Fennel support tail-call optimization, allowing (among other things) functions to recurse indefinitely without overflowing the stack, provided the call is in a tail position.
The final form in this and all other function forms is used as the return value.
lambda
/λ
nil-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:
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)
The fn
, lambda
, λ
and macro
forms 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.
;; this only works in the repl
>> ,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.doc
and fennel.metadata
.
(Since 1.1.0)
All forms that accept a docstring will also accept a metadata table in the same place:
(fn add [...]
{:fnl/docstring "Add arbitrary amount of numbers."
:fnl/arglist [a b & more]}
(match (values (select :# ...) ...)
(0) 0
(1 a) a
(2 a b) (+ a b)
(_ a b) (add (+ a b) (select 3 ...))))
Here the arglist is overridden by that in the metadata table (note that the contents of the table are implicitly quoted). Calling ,doc
command in the REPL prints specified argument list:
>> ,doc add
(add a b & more)
Add arbitrary amount of numbers.
Fennel itself uses the metadata keys fnl/docstring
and fnl/arglist
but third-party code can make use of arbitrary keys.
(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:
This style of anonymous function is useful as a parameter to higher order functions. It's recommended only for simple one-line functions.
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])
#{:a $1 :b $2} ; same as (fn [a b] {:a a :b b})
#$ ; same as (fn [x] x) (aka the identity function)
#val ; same as (fn [] 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.
Unlike regular functions, there is no implicit do
in a hash function, and thus it cannot contain multiple forms without an explicit do
. The body itself is directly used as the return value rather than the last element in the body.
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:
This example returns a function which will print a number that is 2 greater than the argument it is passed.
let
scoped localsIntroduces a new scope in which a given set of local bindings are used.
Example:
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. The last form in the body is used as the return value.
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:
Example:
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)
val) ; prints "hello there" and returns 19
When destructuring a sequential table, you can capture all the remainder of the table in a local by using &
:
Example:
If a table implements __fennelrest
metamethod it is used to capture the remainder of the table. It can be used with custom data structures implemented in terms of tables, which wish to provide custom rest destructuring. The metamethod receives the table as the first argument, and the amount of values it needs to drop from the beginning of the table, much like table.unpack
Example:
(local t [1 2 3 4 5 6])
(setmetatable
t
{:__fennelrest (fn [t k]
(let [res {}]
(for [i k (length t)]
(tset res (tostring (. t i)) (. t i)))
res))})
(let [[a b & c] t]
c) ;; => {:3 3 :4 4 :5 5 :6 6}
When destructuring a non-sequential table, you can capture the original table along with the destructuring by using &as
:
Example:
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:
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:
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.
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
.
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.
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]
[b a a] :no ; because a=85 and a=95
[x y z] :no ; because x=95 and x=52
[a b x] :yes)) ; a and b are fresh values while x=95 and x=95
There is a special case for symbols beginning with _
; they are never bound and always act as a wildcards.
If no clause matches, the form evaluates to 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]
(where [a b c] (= 5 a)) :will-not-match
(where [a b c] (= 0 (math.fmod (+ a b c) 2)) (= 91 a)) c) ; -> 53
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:
This is essentially equivalent to:
(match [5 1 2]
(where [a 3 9] (= 5 a)) "Either [5 3 9] or [5 1 2]"
(where [a 1 2] (= 5 a)) "Either [5 3 9] or [5 1 2]"
_ "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.
(where (or [a 1 2] [a b 3]) (< a 0) (< b 1))
:body)
;; ok
(match [1 2 3]
(where (or [a b 2] [a b 3]) (< a 0) (<= b 1))
: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.9.0 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]
(where [a 2 3] (< 0 a)) "new guard syntax"
([a 2 3] ? (< 0 a)) "obsolete guard syntax")
match-try
for matching multiple stepsEvaluates a series of pattern matching steps. The value from the first expression is matched against the first pattern. If it matches, the first body is evaluated and its value is matched against the second pattern, etc.
If there is a (catch pat1 body1 pat2 body2 ...)
form at the end, any mismatch from the steps will be tried against these patterns in sequence as a fallback just like a normal match. If there is no catch, the mismatched value will be returned as the value of the entire expression.
(fn handle [conn]
(match-try (conn:receive :*l)
input (parse input)
(command-name params) (commands.get command-name)
command (pcall command (table.unpack params))
(catch
(_ :timeout) nil
(_ :closed) (pcall disconnect conn "connection closed")
(_ msg) (print "Error handling input" msg))))
This is useful when you want to perform a series of steps, any of which could fail. The catch
clause lets you keep all your error handling in one place. Note that there are two ways to indicate failure in Fennel and Lua; using the assert
/error
functions or returning nil followed by some data representing the failure. This form only works on the latter, but you can use pcall
to transform error
calls into values.
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:
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:
Example:
Supports destructuring and multiple-value binding.
tset
set table fieldSets 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:
You can provide multiple successive field names to perform nested sets. For example:
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:
Example:
(let [(file-handle message code) (io.open "foo.blah")]
message) ; => "foo.blah: No such file or directory"
Example:
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)]
(fout:write "Here is some text!\n")
((fin:lines))) ; => first line of input.txt
;; 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"
[ok err] ; => [false "<error message and stacktrace>"]
pick-values
emit exactly n values(Since 0.4.0)
Discards 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.
expands to
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 ...))))
(add (pick-values 2 10 10 10 10)) ; => 20
(->> [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:
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. The last form in the body is used as the return value.
Example:
each
general iterationRuns 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. Returns nil.
Example:
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))
Note: prior to fennel version 1.2.0, :until
was used instead of &until
; the old syntax is still supported for backwards compatibility.
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. Returns nil.
Example:
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.
while
good old while loopLoops over a body until a condition is met. Uses a native Lua while
loop. Returns nil.
Example:
(var done? false)
(while (not done?)
(print :not-done)
(when (< 0.95 (math.random))
(set done? true)))
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
.
Some other forms like fn
and let
have an implicit do
.
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 available 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 available 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:
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:
.
table lookupLooks up a given key in a table. Multiple arguments will perform nested lookup.
Example:
Example:
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:
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
icollect
, collect
table comprehension macros(Since 0.8.0)
The icollect
macro takes a "iterator binding table" in the format that each
takes, and returns a sequential table containing all the values produced by each iteration of the macro's body. If the value is nil, it is omitted from the return table. This is similar to how map
works in several other languages, but it is a macro, not a function.
(icollect [_ v (ipairs [1 2 3 4 5 6])]
(if (> 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) (if (> v 2) (* v v))))
tbl)
The collect
macro is almost identical, except that the body should return two things: a key and a value.
(collect [k v (pairs {:apple "red" :orange "orange" :lemon "yellow"})]
(if (not= k "yellow")
(values (.. "color-" v) k)))
;; -> {:color-orange "orange" :color-red "apple"}
;; equivalent to:
(let [tbl {}]
(each [k v (pairs {:apple "red" :orange "orange"})]
(if (not= k "yellow")
(match (values (.. "color-" v) k)
(key value) (tset tbl key value))))
tbl)
If the key and value are given directly in the body of collect
and not nested in an outer form, then the values
can be omitted for brevity:
Like each
and for
, the table comprehensions support an &until
clause for early termination.
Both icollect
and collect
take an &into
clause which allows you put your results into an existing table instead of starting with an empty one:
Note: Prior to fennel version 1.2.0, :into
was used instead of &into
; the old syntax is still supported for backwards compatibility.
accumulate
iterator accumulation(Since 0.10.0)
Runs through an iterator and performs accumulation, similar to fold
and reduce
commonly used in functional programming languages. Like collect
and icollect
, it takes an iterator binding table and an expression as its arguments. The difference is that in accumulate
, the first two items in the binding table are used as an "accumulator" variable and its initial value. For each iteration step, it evaluates the given expression and its value becomes the next accumulator variable. accumulate
returns the final value of the accumulator variable.
Example:
The &until
clause is also supported here for early termination.
fcollect
range comprehension macro(Since 1.1.1)
Similarly to icollect
, fcollect
provides a way of building a sequential table. Unlike icollect
, instead of an iterator it traverses a range, as accepted by the for
special. The &into
and &until
clauses work the same as in icollect
.
Example:
(fcollect [i 0 10 2]
(if (> i 2) (* i i)))
;; -> [16 36 64 100]
;; equivalent to:
(let [tbl {}]
(for [i 0 10 2]
(if (> i 2)
(table.insert tbl (* i i))))
tbl)
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))))
:
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:
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:
Unlike Lua, there's nothing special about defining functions that get called this way; typically it is given an extra argument called self
but this is just a convention; you can name it anything.
->
, ->>
, -?>
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)
(. :c)) ; -> nil
(-?>> :a
(. {:a :b})
(. {:b :missing})
(. {:c 42})) ; -> nil
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)
Loads Fennel/Lua module code at compile time and embeds it in the compiled output. The module name must resolve to a string literal 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 Modules and multiple files section in the tutorial and Programming in Lua for details about require
.
Starting from version 0.10.0 include
and hence --require-as-include
support semi-dynamic compile-time resolution of module paths similarly to import-macros
. See the relative require section in the tutorial for more information.
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 like functions and other values.
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}
For a full explanation of how this works see the macro guide. All forms in Fennel are normal tables you can use table.insert
, ipairs
, destructuring, etc on. The backtick on the third line creates a template list for the code emitted by the macro, and the comma 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:
and transforms it into this code at compile time by splicing the arguments into the backtick template:
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:
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:
However, this code will work, provided the module in question exists:
See "Compiler API" below for details about additional functions visible inside compiler scope which macros run in.
By default, Fennel will search for macro modules similarly to how it searches for normal runtime modules: by walking thru entries on fennel.macro-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)
code (values (partial fennel.eval code {:env :_COMPILER})
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 macroIf you are only defining a single macro, this is equivalent to the previous example. The syntax mimics fn
.
macrodebug
print the expansion of a macroCall 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 capture, 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:
This prints all the functions available in compiler scope.
Inside eval-compiler
, macros
, or macro
blocks, as well as import-macros
modules, the functions listed below are visible to your code.
list
- return a list, which is a special kind of table used for code.
sym
- turn a string into a symbol.
gensym
- generates a unique symbol for use in macros, accepts an optional prefix string.
list?
- is the argument a list? Returns the argument or false
.
sym?
- is the argument a symbol? Returns the argument or false
.
table?
- is the argument a non-list table? Returns the argument or false
.
sequence?
- is the argument a non-list sequential table (created with []
, as opposed to {}
)? Returns the argument or false
.
varg?
- is this a ...
symbol which indicates var args? Returns a special table describing the type or false
.
multi-sym?
- a multi-sym is a dotted symbol which refers to a table's field. Returns a table containing each separate symbol, or false
.
comment?
- is the argument a comment? Comments are only included when opts.comments
is truthy.
view
- fennel.view
table serializer.
get-scope
- return the scope table for the current macro call site.
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 the symbol refer to an in-scope local? Returns the symbol or nil
.macroexpand
- performs macroexpansion on its argument form; returns an AST.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.
As of 1.0.0 the compiler will not allow access to the outside world (os
, io
, etc) from macros. The one exception is print
which is included for debugging purposes. You can disable this by providing the command-line argument --no-compiler-sandbox
or by passing {:compiler-env _G}
in the options table when using the compiler API to get full access.
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 other internals of the compiler exposed in compiler scope but not listed above 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:
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. For example the following Fennel code:
will produce this Lua code:
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.
require-macros
load macros with less flexibility(Since 0.1.0, deprecated in 0.4.0)
The 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.
pick-args
create a function of fixed arity(Since 0.4.0, deprecated 0.10.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
global
set global variable(Since 0.1.0, deprecated in 1.1.0)
Sets 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:
Using global
adds the identifier in question to the list of allowed globals so that referring to it later on will not cause a compiler error. However, globals are also available in the _G
table, and accessing them that way instead is recommended for clarity.
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.
Only the fennel
module is part of the public API. The other modules are implementation details subject to change. Most functions will error
upon failure.
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. Defaults to the contents of the env
table, if provided, or the current environment.correlate
: when this is set, 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
repl command. 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 that is resolvable at compile time it 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.plugins
: list of compiler plugins.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.
Takes these additional options:
readChunk()
: a function that when called, returns a string of source code. The empty is string or nil is used as the end of source marker.pp
: a pretty-printer function to apply on values (default: fennel.view
).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.By default, metadata will be enabled and you can view function signatures and docstrings with the ,doc
command in the REPL.
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 ...
.
Additional arguments beyond options
are passed to the code and available as ...
.
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
. There is also a fennel.macro-path
which is used to look up macro modules.
If you install Fennel into package.searchers
then you can use the repl's ,reload mod
command to reload modules that have been loaded with require
.
The compiler sandbox makes it so that the module system is also isolated from the rest of the system, so the above require
calls will not work from inside macros. However, there is a separate fennel.macro-searchers
table which can be used to allow different modules to be loaded inside macros. By default it includes a searcher to load sandboxed Fennel modules and a searcher to load sandboxed Lua modules, but if you disable the compiler sandbox you may want to replace these with searchers which can load arbitrary modules.
The default fennel.macro-searchers
functions also cannot load C modules. Here's an example of some code which would allow that to work:
table.insert(fennel["macro-searchers"], function(module_name)
local filename = fennel["search-module"](module_name, package.cpath)
if filename then
local func = "luaopen_" .. module_name
return function() return package.loadlib(filename, func) end, filename
end
end)
Macro searchers store loaded macro modules in the fennel.macro-loaded
table which works the same as package.loaded
but for macro modules.
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:
Note that some systems print stack traces from C, which will not be affected.
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.
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.
Accepts filename
in options
as in fennel.eval
.
This is useful when streaming data into the compiler to allow you to avoid loading all the code into a single string in one go.
Accepts indent
and filename
in options
as per above.
The ast
here can be gotten from fennel.parser
.
Accepts indent
and filename
in options
as per above.
The fennel.parser
function returns a stateful iterator function. If a form was successfully read, it returns true followed by the AST node. Returns nil when it reaches the end. Raises an error if it can't parse the input.
local parse = fennel.parser(text)
local ok, ast = assert(parse()) -- just get the first form
-- Or use in a for loop
for ok, ast in parse do
if ok then
print(fennel.view(ast))
end
end
The first argument can either be a string or a function that returns one byte at a time. It 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 ASTplugins
: (since 1.2.0) An optional list of compiler plugins.The list of common options at the top of this document do not apply here.
The 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 non-sequence tables.
The fennel.ast-source
function takes an AST node and returns a table with source data around filename, line number, et in it, if possible. Some AST nodes cannot provide this data, for instance numbers, strings, and booleans, or symbols constructed within macros using the sym
function instead of backtick.
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.
Note that lists are compile-time constructs in Fennel. They do not exist at runtime, except in such cases as the compiler is in use at runtime.
The list also contains these keys indicating where it was defined: filename
, line
, col
, endcol
, bytestart
, and byteend
. This data is used for stack traces and for pinpointing compiler error messages. Note that column numbers are based on character count, which does not always correspond to visual columns; for instance "วัด" is three characters but only two visual columns.
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 to improve error reporting.
Sequences and kv tables have their source data in filename
, line
, etc keys of their 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 (filename
, line
, col
, etc) in fields on themselves. Unlike the other tables in the AST, they do not represent collections; they are used as scalar types.
Symbols can refer not just directly to locals, but also to table references like tbl.x
for field lookup or access.channel:deny
for method invocation. The fennel.multi-sym?
function will return a table containing the segments if the symbol if it is one of these, or nil otherwise.
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
.
The fennel.sym-char?
function will tell you if a given character is allowed to be used in the name of a symbol.
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.
The fennel.view
function takes any Fennel data and turns it into a representation suitable for feeding back to Fennel's parser. In addition to tables, strings, numbers, and booleans, it can produce reasonable output from ASTs that come from the parser. It will emit an unreadable placeholder for coroutines, compiled functions, and userdata though.
The list of common options at the top of this document do not apply here; instead these options are accepted:
one-line?
(boolean: default: false) keep the output string as a one-linerdepth
(number, default: 128) limit how many levels to go (default: 128)detect-cycles?
(boolean, default: true) don't try to traverse a looping tablemetamethod?
(boolean: default: true) use the __fennelview metamethod if foundempty-as-sequence?
(boolean, default: false) render empty tables as []line-length
(number, default: 80) length of the line at which multi-line output for tables is forcedescape-newlines?
(default: false) emit strings with \n instead of newlineprefer-colon?
(default: false) emit strings in colon notation when possibleutf8?
(boolean, default true) whether to use utf8 module to compute string lengthsmax-sparse-gap
(integer, default 10) maximum gap to fill in with nils in sparse sequential tables.preprocess
(function) if present, called on x (and recursively on each value in x), and the result is used for pretty printing; takes the same arguments as fennel.view
(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
repl command 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
command, name is whatever symbol you operate on that's bound to the function.local greet = fennel.eval('(λ greet [name] "Say hello" (print "Hello," name))',
{useMetadata = true})
fennel.metadata[greet]
-- > {"fnl/docstring" = "Say hello", "fnl/arglist" = ["name"]}
fennel.doc(greet, "greet")
-- > (greet name)
-- > Say hello
fennel.metadata:set(greet, "fnl/docstring", "Say hello!!!")
fennel.doc(greet, "greet!")
--> (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, but enabling metadata is currently recommended for development purposes only.
If you're writing a tool which performs syntax highlighting or some other operations on Fennel code, the fennel.syntax
function can provide you with data about what forms and keywords to treat specially.
local syntax = fennel.syntax()
print(fennel.view(syntax["icollect"]))
--> {:binding-form? true :body-form? true :macro? true}
The table has string keys and table values. Each entry will have one of "macro?"
, "global?"
, or "special?"
set to true
indicating what type it is. Globals can also have "function?"
set to true. Macros and specials can have "binding-form?"
set to true indicating it accepts a []
argument which introduces new locals, and/or a "body-form?"
indicating whether it should be indented with two spaces instead of being indented like a function call. They can also have a "define?"
key indicating whether it introduces a new top-level identifier like local
or fn
.
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.
This function does a best effort detection of the Lua VM environment hosting Fennel. Useful for displaying an "About" dialog in your Fennel app that matches the REPL and --version
CLI flag.
The fennel.version
field will give you the version of just Fennel itself.
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. Each plugin function should normally do side effects and return nil or error out. If a function returns non-nil, it will cause the rest of the plugins for a given event to be skipped.
symbol-to-expression
call
do
fn
destructure
parse-error
assert-compile
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 parse-error
and assert-compile
hooks can be used to override how fennel behaves down to the parser and compiler levels. Possible use-cases include building atop fennel.view
to serialize data with EDN-style tagging, or manipulating external s-expression-based syntax, such as tree-sitter queries.
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 scope]
"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.
Your plugin should contain a :versions
table which contains a list of strings indicating every version of Fennel which you have tested it with. You should also have a :name
field with the plugin's name.