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.
,doc/fennel.doc: Don't mutate
:fnl/arglist directly when showing callable form(set (. tgt k1 ...) v) now works on known globals and
$, $1 ... $9 in hashfnssym,
list or sequence is shadowedfennel.traceback behavior closer to Lua's
traceback by not modifying non-string and
non-nil values.pick-values is now a special, allowing it to emit
better Lua output.fennel.getinfo as source-map-aware equivalent of
debug.getinfo.& and &as in the same
destructure clause.--require-as-include.and/or forms
with potential side-effects.--keywords option to add to the list of built-in
Lua keywords.,complete ,d -> ,doc.(set ___repl___.view-opts.depth 100).(set (. tbl field) val).fennel.compile function now accepts an AST,
iterator, or file.(pick-values 0 (side-effects)) now correctly preserves
side effects_foo arguments in
lambda.,compile repl
command.and/or inside
(fn [...]) now propagate varargs.macrodebug on cyclic macro expansions now serialize to
valid code (no @1, ..)(tail! (f x)) could sometimes compile
to return return f(x)tail! ensure its target is not a special form call
like (tail! (or x (f)))make installThis was the last release that provided Linux arm32 binaries.
fennel.repl is now a callable table, allowing the
default (fennel.repl) options to be customized by setting
option fields on the table itself. This accidentally caused
incompatibility with
coroutine.create.lambda being
ignored.band operator.icollect with &into and
multiple values.assert-repl, as a drop-in replacement for
assert, no longer takes an opts param(. (a-macro) k) bypassed protections
against invalid Lua output__fennelrest destructuring
metamethod.tail! which asserts that the argument is called in
tail position.assert-repl to make an assertion which opens a repl
when it fails.--assert-as-repl flag to replace
assert calls with assert-repl.,return FORM command.*1, *2, and
*3 locals.fennel.runtime-version will return version information
as a table if given optional argument___repl___ table, allowing
method redefinition at runtime.metadata.get is called
without a key.:byte-escape option to fennel.view for
overriding default char escapesfennel-api(3),
fennel-reference(5), and fennel-tutorial(7)
from their respective documentation.Note for packagers: The man page
fennel.1 has been moved to man/man1/fennel.1
along with the new generated man pages. For build scripts that copy
files manually in lieu of make install, this may require an
update.
{:true 1 true 2} emit with
unstable key order{:__metatable true} (as in
pandoc-lua) breaks fennel.viewmacros only accepts table
literals, not table-returning exprs__pairs metamethod in fennel.viewcase which does pattern matching without pinning
existing localscase-try which works like match-try
without pinning localsfaccumulate macro as range analog to
accumulateNO_COLOR env
var is set& for rest args in function arglists for
consistency with leterror-pinpoint option to support custom error
highlightingfn special now allows arbitrary compiler metadata
keys via the metadata table syntax{:once val} or
{:once val :after other-val}. See fennel.view
docstring for more infoset did not catch unknown locals when
setting table fieldsctrl-d in
readlinefennel.install function to the API for adding the
searchertable? predicate to fennel API to go with
list?, sym?, etc(values) consistently evaluates to zero
valuespairs table traversal for
reproducible buildsfcollect 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-binarynilnil 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/ornil 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
matchimport-macrosfennel.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
matchIt'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.viewpick-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.viewfennel.view for better indentation
handlingdoc&as... arguments consistently with Lua when
requiring modules__fennelview metamethod
on userdata metatables... inside
eval-compilerimport-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-macrosmacrodebug
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 backports all the features from the 1.3.0 release to the pre-self-hosted version of the compiler for bootstrapping purposes. There should be no reason to use this, other than to build a newer version.
match rewrite as well as
case, case-try, and
match-tryaccumulate, faccumulate, and
fcollect macros?. macrocollect and icollect macros:until support in each and other
loops.&as destructuringThis 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
bxormacroexpand 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 lengthhashfn 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
destructuringmatchluaexpr 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 supportpartiallocaldoto macro: for method callseachlambda/λ for nil-argument-checked
functionswhen&. formpack,
$, block, *break,
specialdefn 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. If you already have a piece of Lua code you just want to see translated to Fennel, use antifennel.
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, also known as dictionaries. For example:
{:a 1 :b 2} In a table if you have a string key followed by
a symbol of the same name as the string, you can use : as
the key and it will be expanded to a string containing the name of the
following symbol.
{: this} ; is shorthand for {:this this}[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. Infinity and negative infinity
are represented as .inf and -.inf. NaN and
negative Nan are .nan and -.nan.
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 can only be
used for 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 another way of
writing the string "fennel-lang.org".
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:
(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. The following mean exactly the same thing; the first is preferred mostly for indentation reasons, but also because it allows recursion:
(fn pxy [x y]
(print (+ x y)))
(local pxy (fn [x y]
(print (+ x y))))Providing a name that's a table field will cause it to be inserted in a table instead of bound as a local:
(local functions {})
(fn functions.p [x y z]
(print (* x (+ y z))))
;; equivalent to:
(set functions.p (fn [x y z]
(print (* x (+ y z)))))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:
(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.
Programmers coming from other languages in which it is an error to
call a function with a different number of arguments than it is defined
with often get tripped up by the behavior of fn. This is
where lambda is most useful.
The lambda, case, case-try,
match and match-try forms are the only place
where the ?foo notation is used by the compiler to indicate
that a nil value is allowed, but it is a useful notation to communicate
intent anywhere a new local is introduced.
The λ form is an alias for lambda and
behaves identically.
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 yAll 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 of
the next form:
>> ,doc add
(add a b & more)
Add arbitrary amount of numbers.(Since 1.3.0)
Arbitrary metadata keys are allowed in the metadata table syntax:
(fn foo []
{:deprecated "v1.9.0"
:fnl/docstring "*DEPRECATED* use foo2"}
;; old way to do stuff
)
(fn foo2 [x]
{:added "v2.0.0"
:fnl/docstring "Incompatible but better version of foo!"}
;; do stuff better, now with x!
x)In this example, the deprecated and added
keys are used to store a version of a hypothetical library on which the
functions were deprecated or added. External tooling then can leverage
this information by using Fennel's metadata API:
>> (local {: metadata} (require :fennel))
>> (metadata:get foo :deprecated)
"v1.9.0"
>> (metadata:get foo2 :added)
"v2.0.0"Such metadata can be any data literal, including tables, with the only restriction that there are no side effects. Fennel's lists are disallowed as metadata values.
(Since 1.3.1)
For editing convenience, the metadata table literals are allowed after docstrings:
(fn some-function [x ...]
"Docstring for some-function."
{:fnl/arglist [x & xs]
:other :metadata}
(let [xs [...]]
;; ...
))In this case, the documentation string is automatically inserted to the metadata table by the compiler.
The whole metadata table can be obtained by calling
metadata:get without the key argument:
>> (local {: metadata} (require :fennel))
>> (metadata:get some-function)
{:fnl/arglist ["x" "&" "xs"]
:fnl/docstring "Docstring for some-function."
:other "metadata"}Fennel itself only uses the fnl/docstring and
fnl/arglist metadata keys but third-party code can make use
of arbitrary keys.
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)) ; implementation detail; don't use directly#(+ $1 $2)This style of anonymous function is useful as a parameter to higher order functions. It's recommended only for simple one-line functions that get passed as arguments to other 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:
(fn add-print [x y] (print (+ x y)))
(partial add-print 2)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:
(let [x 89
y 198]
(print (+ x y 12))) ; => 299These 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:
(let [(x y z) (unpack [10 9 8])]
(+ x y z)) ; => 27Example:
(let [[a b c] [1 2 3]]
(+ a b c)) ; => 6If 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. This works for both creating tables and
destructuring them.
Example:
(let [{:msg message : val} {:msg "hello there" :val 19}]
(print message)
val) ; prints "hello there" and returns 19When 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"(Since 1.3.0): This also works with function argument lists,
but it has a small performance cost, so it's recommended to use
... instead in cases that are sensitive to overhead.
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)) ; => 10local 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.
case pattern matching(Since 1.3.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:
(case 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, any non-nil value as its second value 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 and two non-nil values after it; if so then it will add up
the second and third elements.
If no clause matches, the form evaluates to nil.
Patterns can be tables, literal values, or symbols. Any symbol is
implicitly checked to be not nil. Symbols can be repeated
in an expression to check for the same value.
Example:
(case mytable
;; the first and second values of mytable are not nil and are the same value
[a a] (* a 2)
;; the first and second values are not nil and are not the same value
[a b] (+ a b))It's important to note that expressions are checked in
order! In the above example, since [a a] is checked
first, we can be confident that when [a b] is checked, the
two values must be different. Had the order been reversed,
[a b] would always match as long as they're not
nil - even if they have the same value!
You may allow a symbol to optionally be nil by prefixing
it with ?.
Example:
(case mytable
;; not-nil, maybe-nil
[a ?b] :maybe-one-maybe-two-values
;; maybe-nil == maybe-nil, both are nil or both are the same value
[?a ?a] :maybe-none-maybe-two-same-values
;; maybe-nil, maybe-nil
[?a ?b] :maybe-none-maybe-one-maybe-two-values)Symbols prefixed by an _ are ignored and may stand in as
positional placeholders or markers for "any" value - including a
nil value. A single _ is also often used at
the end of a case expression to define an "else" style
fall-through value.
Example:
(case mytable
;; not-nil, anything
[a _b] :maybe-one-maybe-two-values
;; anything, anything (different to the previous ?a example!)
;; note this is effectively the same as []
[_a _a] :maybe-none-maybe-one-maybe-two-values
;; anything, anything
;; this is identical to [_a _a] and in this example would never actually match.
[_a _b] :maybe-none-maybe-one-maybe-two-values
;; when no other clause matched, in this case any non-table value
_ :no-match)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, see ? and
_ as above.) Tables will never fail to match due
to having too many elements - this means [] matches
any table, not an empty table. You can use
& to capture all the remaining elements of a sequential
table, just like let.
(case mytable
{:subtable [a b ?c] :depth depth} (* b 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.
(case (io.open "/some/file")
(nil msg) (report-error msg)
f (read-file f))Sometimes you need to match on something more general than a structure or specific value. In these cases you can use guard clauses:
(case [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) ; -> 53In 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:
(case [5 1 2]
(where (or [a 3 9] [a 1 2]) (= 5 a)) "Either [5 3 9] or [5 1 2]"
_ "anything else")This is essentially equivalent to:
(case [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
(case [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
(case [1 2 3]
(where (or [a b 2] [a b 3]) (< a 0) (<= b 1))
:body)Symbols bound inside a case pattern are independent from
any existing symbols in the current scope, that is - names may be
re-used without consequence.
Example:
(let [x 1]
(case [:hello]
;; `x` is simply bound to the first value of [:hello]
[x] x)) ; -> :helloSometimes it may be desirable to match against an existing value in
the outer scope. To do this we can "pin" a binding inside the pattern
with an existing outer binding with the unary
(= binding-name) form. The unary
(= binding-name) form is only valid in a
case pattern and must be inside a
(where) guard.
Example:
(let [x 1]
(case [:hello]
;; 1 != :hello
(where [(= x)]) x
_ :no-match)) ; -> no-match
(let [x 1]
(case [1]
;; 1 == 1
(where [(= x)]) x
_ :no-match)) ; -> 1
(let [pass :hunter2]
(case (user-input)
(where (= pass)) :login
_ :try-again!))Pinning is only required inside the pattern. Outer bindings are automatically available inside guards and bodies as long as the name has not been rebound in the pattern.
Note: The case macro can be used in
place of the if-let macro from Clojure. The reason Fennel
doesn't have if-let is that case makes it
redundant.
match pattern matchingmatch is conceptually equivalent to case,
except symbols in the patterns are always pinned with outer-scope
symbols if they exist.
It supports all the same syntax as described in case
except the pin ((= binding-name)) expression, as it is
always performed.
Be careful when using
matchthat your symbols are not accidentally the same as any existing symbols! If you know you don't intend to pin any existing symbols you should use thecaseexpression.
(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=95Unlike in case, if an existing binding has the value
nil, the ? prefix is not necessary - it would
instead create a new un-pinned binding!
Example:
(let [name nil
get-input (fn [] "Dave")]
(match (get-input)
;; name already exists as nil, "Dave" != nil so this *wont* match
name (.. "Hello " name)
?no-input (.. "Hello anonymous"))) ; -> "Hello anonymous"Note: 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")case-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 case.
If no catch pattern matches, nil is returned.
If there is no catch, the mismatched value will be returned as the value of the entire expression.
(fn handle [conn token]
(case-try (conn:receive :*l)
input (parse input)
(command-name params (= token)) (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.
match-try
for matching multiple stepsEquivalent to case-try but uses match
internally. See case and match for details on
the differences between these two forms.
Unlike case-try, match-try will pin values
in a given catch block with those in the original
steps.
(fn handle [conn token]
(match-try (conn:receive :*l)
input (parse input)
(command-name params token) (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))))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. If the table field
name is static, use tbl.field; if the field name is
dynamic, use (. tbl field).
Examples:
(set x (+ x 91)) ; var
(let [t {:a 4 :b 8}] ; static table field
(set t.a 2) t) ; => {:a 2 :b 8}
(let [t {:supported-chars {:x true}}
field1 :supported-chars
field2 :y] ; dynamic table field
(set (. t field1 field2) true) t) ; => {:supported-chars {:x true :y true}}Supports destructuring and multiple-value binding.
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)]
x) ; => 1Example:
(let [(file-handle message code) (io.open "foo.blah")]
message) ; => "foo.blah: No such file or directory"Example:
(do (local (_ _ z) (unpack [:a :b :c :d :e])) z) => ctset set table fieldSets the field of a given table to a new value.
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. For example:
(let [tbl {:a {:b {}}} field :c]
(tset tbl :a :b field "d") tbl) ; => {:a {:b {:c "d"}}}Since 1.5.0, tset is mostly redundant because
set can be used for table fields. The main exception is
that tset works with doto and set
does not.
with-open
bind and auto-close file handlesWhile 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 valuesDiscards 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 ...))))
(add (pick-values 2 10 10 10 10)) ; => 20
(->> [1 2 3 4 5] (table.unpack) (pick-values 3) (add)) ; => 6Note: 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"]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:
(when launch-missiles?
(power-on)
(open-doors)
(fire))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:
(each [key value (pairs mytbl)]
(print "executing key")
(print (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))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:
(for [i 1 10 2]
(log-number i)
(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)))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.
(if launch-missiles?
(do
(power-on)
(open-doors)
(fire))
false-alarm?
(promote lt-petrov))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. Multiple values at runtime will not be taken
into account.
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!!!"String concatenation is subject to the same compile-time limit as the operators above; it is not aware of multiple values at runtime.
length string or
table length(Changed in 0.3.0: it 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 on some versions
of Lua.
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)) ; => 3Note 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)) ; => 42icollect,
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. This is similar to how map works in several other
languages, but it is a macro, not a function.
If the value is nil, it is omitted from the return table. This is
analogous to filter in other languages.
(icollect [_ v (ipairs [1 2 3 4 5 6])]
(if (< 2 v) (* 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 (< 2 v) (* 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= v "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= v "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:
(collect [k v (pairs {:a 85 :b 52 :c 621 :d 44})]
k (* v 5))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:
(icollect [_ x (ipairs [2 3]) &into [9]]
(* x 11))
;; -> [9 22 33]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:
(accumulate [sum 0
i n (ipairs [10 20 30 40])]
(+ sum n)) ; -> 100The &until clause is also supported here for early
termination.
faccumulate range
accumulation(Since 1.3.0)
Identical to accumulate, but instead of taking an iterator and the
same bindings as each, it accepts the same bindings as
for and will iterate the numerical range. Accepts
&until just like for and
accumulate.
Example:
(faccumulate [n 0 i 1 5] (+ n i)) ; => 15fcollect 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.
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"))]
(f:write "world")
(f:close))In the example above, f:write is a single multisym. If
the name of the method or the table containing it isn't fixed, you can
use : followed by the table and then the method's name to
allow it to be a dynamic string instead:
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"))]
(f.write f "world")
(f.close f))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.
(local t {})
(fn t.enable [self]
(set self.enabled? true))
(t:enable)->,
->>, -?> 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})) ; -> nilWhile -> 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.
dotoSimilarly, 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.
tail!Tail calls will be optimized automatically. However, the
tail! form asserts that its argument is called in a tail
position. You can use this when the code depends on tail call
optimization; that way if the code is changed so that the recursive call
is no longer in the tail position, it will cause a compile error instead
of overflowing the stack later on large data sets.
(fn process-all [data i]
(case (process (. data i))
:done (print "Process completed.")
:next (process-all data (+ i 1))
:skip (do (tail! (process-all data (+ i 2)))
;; ^^^^^ Compile error: Must be in tail position
(print "Skipped" (+ i 1)))))include(include :my.embedded.module)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.
assert-repl(Since 1.4.0)
Sometimes it's helpful for debugging purposes to drop a repl right
into the middle of your code to see what's really going on. You can use
the assert-repl macro to do this:
(let [input (get-input)
value []]
(fn helper [x]
(table.insert value (calculate x)))
(assert-repl (transform helper value) "could not transform"))This works as a drop-in replacement for the built-in
assert function, but when the condition is false or nil,
instead of an error, it drops into a repl which has access to all the
locals that are in scope (input, value, and
helper in the example above).
Note that this is meant for use in development and will not work with ahead-of-time compilation unless your build also includes Fennel as a library.
If you use the --assert-as-repl flag when running
Fennel, calls to assert will be replaced with
assert-repl automatically.
Note: In Fennel 1.4.0, assert-repl
accepted an options table for fennel.repl as an optional
third argument. This was removed as a bug in 1.4.1, as it broke
compatibility with assert.
The REPL spawned by assert-repl applies the same default
options as fennel.repl, which as of Fennel 1.4.1 can be
configured from the API. See the Fennel API reference
for details.
You can ,return EXPRESSION from the repl to replace the
original failing condition with a different arbitrary value. Returning
false or nil will trigger a regular assert failure.
Note: Currently, only a single value can be returned
from the REPL this way. While ,return can be used to make a
failed assertion recover, if the calling code expects multiple return
values, it may cause unspecified behavior.
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 nested 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 moduleLoads 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 & rest-body]
(assert body1 "expected body")
`(if ,condition
(do ,body1 ,(unpack rest-body))))
{: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.
Assuming the code above is in the file "my-macros.fnl" then it turns this input:
(import-macros {: when2} :my-macros)
(when2 (= 3 (+ 2 a))
(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)
(mine.when2 (= 3 (+ 2 a))
(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.
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
macrosDefines 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
macro(macro 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 macro(macrodebug (-> 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 aboveIn 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# insteadmacros 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-compilerEvaluate 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, 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:
(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 change foo-bar to foo_bar in the Lua
output in order for it to be valid, as well as other transformations.
When in doubt, inspect the compiler output to see what it looks like.
For example the following Fennel code:
(local foo-bar 3)
(let [foo-bar :hello]
(lua "print(foo_bar0 .. \" world\")"))will produce this Lua code:
local foo_bar = 3
local foo_bar0 = "hello"
print(foo_bar0 .. " world")
return nilNormally 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 # form is a deprecated alias for
length, and ~= is a deprecated alias for
not=, kept for backwards compatibility.
require-macros
load macros with less flexibility(Deprecated in 0.4.0)
The require-macros form is like
import-macros, except it imports all macros without making
it clear what new identifiers are brought into scope. It is strongly
recommended to use import-macros instead.
pick-args
create a function of fixed arity(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.
global set global
variable(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:
(global prettyprint (fn [x] (print (fennel.view x))))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.
(Deprecated in 1.4.1, will be removed in future versions)
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}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. This is meant as a debugging aid and cannot give exact
numbers in all cases.useMetadata: 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: 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.assertAsRepl: Replace calls to assert with
assert-repl to allow for interactive debugging.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.error-pinpoint: a list of two strings indicating what
to wrap compile errors inkeywords: a table of the form
{:keyword1 true :keyword2 true} containing symbols that
should be treated as reserved Lua keywords.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.
If you are embedding Fennel in a context where ANSI escape codes are
not interpreted, you can set error-pinpoint to
false to disable the highlighting of compiler and parse
errors.
fennel.repl([options])Takes these additional options:
readChunk(): a function that when called, returns a
string of source code. Should return nil when there is no more source,
which will exit the repl.pp: a pretty-printer function to apply on values
(default: fennel.view).view-opts: an options table passed to pp
(default: {:depth 4}).onValues(values): a function that will be called on all
returned top level values. Takes a table of 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.
In Fennel 1.4.1 fennel.repl was changed from a normal
function to a callable table. This mostly behaves the same, but it can
cause problems with certain functions that are very picky about
functions. Unfortunately this includes coroutine.create.
You can pass fennel.repl.repl instead.
Any fields set on fennel.repl, which is actually a table
with a __call metamethod rather than a function, will used
as a fallback for any options passed to (fennel.repl)
before defaults are applied, allowing one to customize the default
behavior of (fennel.repl):
fennel.repl.onError = custom_error_handler
-- In rare cases this needs to be temporary, overrides
-- can be cleared by simply clearing the entire table
for k in pairs(fennel.repl) do
fennel.repl[k] = nil
endlocal 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[, ...]])Additional arguments beyond options are passed to the
code and available as ....
require("fennel").install().dofile("main.fnl")This is the equivalent of this code:
local fennel = require("fennel")
table.insert(package.loaders or package.searchers, fennel.searcher)
fennel.dofile("main.fnl") -- require calls in main.fnl can load fennel modulesNormally 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:
debug.traceback = fennel.tracebackNote that some systems print stack traces from C, which will not be affected.
The fennel.getinfo function works like Lua's
debug.getinfo function, except it tracks line numbers from
Fennel code correctly. Functions defined from Fennel will have the
what field set to "Fennel" instead of
"Lua".
local mymodule = require("module")
print(fennel.getinfo(mymodule.func1).linedefined)local lua = fennel.compile(fennelSource[, options])The first argument here can be a file name, an AST (usually produced
by fennel.parser), or a stateful iterator function of
bytes.
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 like
fennel.eval for error reporting purposes.
local lua = fennel.compileString(fennelcode[, options])Also aliased to fennel.compile-string for convenience
calling from Fennel.
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
endThe 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 (k/v tables). Sequences can be identified
using the fennel.sequence? function and constructed using
fennel.sequence. There is no predicate or constructor for
k/v 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 k/v tables which use monotonically increasing integer keys, but the parser is able to distinguish between them to improve error reporting.
Sequences and k/v tables have their source data in
filename, line, etc keys of their metatable.
The metatable for k/v tables also includes a keys sequence
which tells you which order the keys appeared originally, since k/v
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 contexts, comments just get included inline in a list or
sequence. However, in a k/v table, this cannot be done, because k/v
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.
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.
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,
which cannot be understood by the parser.
print(fennel.view({abc=123}[, options])
{:abc 123}The list of common options at the top of this document do not apply here; instead these options are accepted:
one-line? (default: false) keep the output string as a
one-linerdepth (number, default: 128) limit how many levels to
go (default: 128)detect-cycles? (default: true) don't try to traverse a
looping tablemetamethod? (default: true) use the __fennelview
metamethod if foundempty-as-sequence? (default: false) render empty tables
as []line-length (number, default: 80) length of the line at
which multi-line output for tables is forcedbyte-escape (function) If present, overrides default
behavior of escaping special characters in decimal format (e.g.
<ESC> -> \027). Called with the
signature (byte-escape byte view-opts), where byte is the
char code for a special characterescape-newlines? (default: false) emit strings with \n
instead of newlineprefer-colon? (default: false) emit strings in colon
notation when possibleutf8? (default: true) whether to use utf8 module to
compute string lengthsmax-sparse-gap (number, default: 10) maximum gap to
fill in with nils in sparse sequential tables before switching to curly
brackets.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.viewAll options can be set to {:once some-value} to force
their value to be some-value but only for the current
level. After that, such option is reset to its default value.
Alternatively, {:once value :after other-value} can be
used, with the difference that after first use, the options will be set
to other-value instead of the default value.
You can set a __fennelview metamethod on a table to
override its serialization behavior. It should take the table being
serialized as its first argument, a function as its second argument,
options table as third argument, and current amount of indentation as
its last argument:
(fn [t view options indent] ...)view function contains a pretty printer that can be used
to serialize elements stored within the table being serialized. If your
metamethod produces indented representation, you should pass
indent parameter to view increased by the
amount of additional indentation you've introduced. This function has
the same interface as __fennelview metamethod, but in
addition accepts colon-string? as last argument. If
colon? is true, strings will be printed as
colon-strings when possible, and if its value is false,
strings will be always printed in double quotes. If omitted or
nil will default to value of :prefer-colon?
option.
options table contains options described above, and also
visible-cycle? function, that takes a table being
serialized, detects and saves information about possible reachable
cycle. Should be used in __fennelview to implement cycle
detection.
__fennelview metamethod should always return a table of
correctly indented lines when producing multi-line output, or a string
when always returning single-line item. fennel.view will
transform your data structure to correct multi-line representation when
needed. There's no need to concatenate table manually ever -
fennel.view will apply general rules for your data
structure, depending on current options. By default multiline output is
produced only when inner data structures contains newlines, or when
returning table of lines as single line results in width greater than
line-size option.
Multi-line representation can be forced by returning two values from
__fennelview - a table of indented lines as first value,
and true as second value, indicating that multi-line
representation should be forced.
There's no need to incorporate indentation beyond needed to correctly align elements within the printed representation of your data structure. For example, if you want to print a multi-line table, like this:
@my-table[1
2
3]__fennelview should return a sequence of lines:
["@my-table[1"
" 2"
" 3]"]Note, since we've introduced inner indent string of length 10, when
calling view function from within __fennelview
metamethod, in order to keep inner tables indented correctly,
indent must be increased by this amount of extra
indentation.
Here's an implementation of such pretty-printer for an arbitrary sequential table:
(fn pp-doc-example [t view options indent]
(let [lines (icollect [i v (ipairs t)]
(let [v (view v options (+ 10 indent))]
(if (= i 1) v
(.. " " v))))]
(doto lines
(tset 1 (.. "@my-table[" (or (. lines 1) "")))
(tset (length lines) (.. (. lines (length lines)) "]")))))Setting table's __fennelview metamethod to this function
will provide correct results regardless of nesting:
>> {:my-table (setmetatable [[1 2 3 4 5]
{:smalls [6 7 8 9 10 11 12]
:bigs [500 1000 2000 3000 4000]}]
{:__fennelview pp-doc-example})
:normal-table [{:c [1 2 3] :d :some-data} 4]}
{:my-table @my-table[[1 2 3 4 5]
{:bigs [500 1000 2000 3000 4000]
:smalls [6 7 8 9 10 11 12]}]
:normal-table [{:c [1 2 3] :d "some-data"} 4]}Note that even though we've only indented inner elements of our table with 10 spaces, the result is correctly indented in terms of outer table, and inner tables also remain indented correctly.
When using the :preprocess option or
__fennelview method, avoid modifying any tables in-place in
the passed function. Since Lua tables are mutable and passed in without
copying, any modification done in these functions will be visible
outside of fennel.view.
Using :byte-escape to override the special character
escape format is intended for use-cases where it's known that the output
will be consumed by something other than Lua/Fennel, and may result in
output that Fennel can no longer parse. For example, to force the use of
hex escapes:
(print (fennel.view {:clear-screen "\027[H\027[2J"}
{:byte-escape #(: "\\x%2x" :format $)}))
;; > {:clear-screen "\x1b[H\x1b[2J"}While Lua 5.2+ supports hex escapes, PUC Lua 5.1 does not, so compiling this with Fennel later would result in an incorrect escape code in Lua 5.1.
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.
local f = fennel.loadCode(luaCode, { x = y }, "myfile.lua")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.
(fennel.runtime-version)print(fennel.runtimeVersion())
-- > Fennel 1.0.0 on PUC Lua 5.4The fennel.version field will give you the version of
just Fennel itself.
(since 1.3.1)
If an optional argument is given, returns version information as a table:
(fennel.runtime-version :as-table)
;; > {:fennel "1.3.1" :lua "PUC Lua 5.4"}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-expressioncalldofndestructureparse-errorassert-compileThe 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 (ignoring newlines and other whitespace), 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 chars opts]
"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 field which
either contains a list of strings indicating every version of Fennel
which you have tested it with, or a string containing a pattern which is
checked against Fennel's version with string.find. If your
plugin is used with a version of Fennel that doesn't match
:versions it will emit a warning. You should also have a
:name field with the plugin's name.