Fennel Reference

https://fennel-lang.org/reference
Admin
Fennel is a Lisp-like programming language that compiles to Lua, providing a powerful macro system...
Tokens:14,171
Snippets:184
Trust Score:8.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Fennel `while` loop example

Source: https://fennel-lang.org/reference

A basic example of a `while` loop that continues until a specific condition is met.

```fennel
(var done? false)
(while (not done?)
  (print :not-done)
  (when (< 0.95 (math.random))
    (set done? true)))
```

--------------------------------

### Partial Application Example

Source: https://fennel-lang.org/reference

Creates a new function by pre-filling some arguments of an existing function. The returned function calls the original function directly.

```fennel
(fn add-print [x y] (print (+ x y)))
(partial add-print 2)
```

--------------------------------

### Import and use 'when2' macro

Source: https://fennel-lang.org/reference

This example shows how to import the 'when2' macro from a local module and use it in Fennel code. The macro is expanded at compile time.

```fennel
(import-macros {: when2} :my-macros)

(when2 (= 3 (+ 2 a))
  (print "yes")
  (finish-calculation))
```

--------------------------------

### Define a single macro using 'macro'

Source: https://fennel-lang.org/reference

This example defines a single macro named 'my-max' using the 'macro' macro. The syntax is similar to defining a function.

```fennel
(macro my-max [x y]
  `(let [x# ,x y# ,y]
     (if (< x# y#) y# x#)))
```

--------------------------------

### Fennel `if` conditional example

Source: https://fennel-lang.org/reference

Demonstrates the usage of the `if` conditional with multiple condition/body pairs, including a catch-all else case.

```fennel
(let [x (math.random 64)]
  (if (= 0 (% x 10))
      "multiple of ten"
      (= 0 (% x 2))
      "even"
      "I dunno, something else"))
```

--------------------------------

### Fennel List Syntax Example

Source: https://fennel-lang.org/reference

Lists are used to denote calls to functions, macros, and specials. They are a compile-time construct.

```fennel
(print "hello world")
```

--------------------------------

### Compile-time macro import with dynamic module name

Source: https://fennel-lang.org/reference

This example shows a valid way to import macros using a dynamically constructed module name at compile time. It uses `...` to refer to the current module's path.

```fennel
(import-macros mymacros (.. ... ".macros"))
```

--------------------------------

### Fennel `when` conditional example

Source: https://fennel-lang.org/reference

Shows a typical use case for the `when` conditional, intended for side-effecting operations.

```fennel
(when launch-missiles?
  (power-on)
  (open-doors)
  (fire))
```

--------------------------------

### Fennel Identifier Syntax Example

Source: https://fennel-lang.org/reference

Illustrates valid identifier characters and the preference for dashes as word separators.

```fennel
my-variable-name
```

--------------------------------

### Define global variable with a function in Fennel

Source: https://fennel-lang.org/reference

Demonstrates the deprecated `global` form to set a global variable to a function. This example defines `prettyprint` which uses `fennel.view` to print its argument.

```fennel
(global prettyprint (fn [x] (print (fennel.view x))))
```

--------------------------------

### Generated Lua code from Fennel example

Source: https://fennel-lang.org/reference

This is the Lua code generated by the Fennel example that uses the `lua` special form. It shows the transformed identifiers and the resulting Lua print statement.

```lua
local foo_bar = 3
local foo_bar0 = "hello"
print(foo_bar0 .. " world")
return nil
```

--------------------------------

### Fennel Case with Valid OR Binding

Source: https://fennel-lang.org/reference

This example demonstrates a correct usage of `or` within a `where` clause when all patterns bind the necessary variables. Ensure all variables used in guards are present in all `or`-ed patterns to avoid compilation errors.

```fennel
;; ok
(case [1 2 3]
  (where (or [a b 2] [a b 3]) (< a 0) (<= b 1))
  :body)
```

--------------------------------

### Fennel Colon String Syntax

Source: https://fennel-lang.org/reference

Strings starting with a colon are supported if they contain only valid symbol characters.

```fennel
:fennel-lang.org
```

--------------------------------

### Fennel rest destructuring with __fennelrest metamethod

Source: https://fennel-lang.org/reference

Shows an example of a deprecated `__fennelrest` metamethod for custom rest destructuring in Fennel. The metamethod captures the remainder of a table into a new table, mapping numeric indices to string keys.

```fennel
(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)
```

--------------------------------

### Fennel Binding Pinning with User Input

Source: https://fennel-lang.org/reference

This example shows binding pinning used with user input. The `(= pass)` form checks if the user input matches the `pass` variable from the outer scope. This is useful for authentication or conditional logic based on external values.

```fennel
(let [pass :hunter2]
  (case (user-input)
    (where (= pass)) :login
    _ :try-again!))
```

--------------------------------

### Fennel Match with Successful Pinned Binding

Source: https://fennel-lang.org/reference

This `match` example succeeds because the symbol `x` is pinned to the outer scope value of 95, and the pattern also expects `x` to be 95. Symbols `a` and `b` are fresh bindings.

```fennel
(let [x 95]
 (match [52 85 95]
   [a b x] :yes))
```

--------------------------------

### Fennel Underscore Prefix Convention

Source: https://fennel-lang.org/reference

Identifiers starting with underscores indicate a local binding that is not intended for use.

```fennel
_unused_local
```

--------------------------------

### Fennel Binding Pinning with Match

Source: https://fennel-lang.org/reference

This example demonstrates successful binding pinning where the outer scope variable `x` (with value 1) matches the value in the `case` pattern (also 1). The `(= x)` form ensures the match only occurs if the values are equal.

```fennel
(let [x 1]
  (case [1]
    ;; 1 == 1
    (where [(= x)]) x
    _ :no-match))
```

--------------------------------

### Fennel function using lua special form

Source: https://fennel-lang.org/reference

This example demonstrates how to use the `lua` special form within a Fennel function to return a value from Lua. It iterates over a table and returns the key if the predicate is met.

```fennel
(fn find [tbl pred]
  (each [key val (pairs tbl)]
    (when (pred val)
      (lua "return key"))))
```

--------------------------------

### Get String or Table Length with `length`

Source: https://fennel-lang.org/reference

Returns the length of a string or table. For tables with nils, the result is undefined; use `ipairs` or `table.maxn` for specific cases.

```fennel
(+ (length [1 2 3 nil 8]) (length "abc")) ; => 6 or 8
```

--------------------------------

### Fennel Match with Nil Binding

Source: https://fennel-lang.org/reference

Unlike `case`, `match` does not require a `?` prefix for `nil` bindings. If a symbol already exists as `nil` in the outer scope, it will be treated as a new, unpinned binding if the matched value is not `nil`. This example shows a `nil` binding not matching, and falling through to the `?no-input` pattern.

```fennel
(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")))
```

--------------------------------

### Fennel Case with Combined Guards using OR

Source: https://fennel-lang.org/reference

Combine multiple patterns within a single `where` clause using `or` when they share the same body and guards. This allows for more concise matching when alternative structures should be treated identically. This example matches either `[a 3 9]` or `[a 1 2]` where `a` is 5.

```fennel
(case [5 1 2]
  (where (or [a 3 9] [a 1 2]) (= 5 a)) "Either [5 3 9] or [5 1 2]"
  _ "anything else")
```

--------------------------------

### Fennel Case Binding Re-use

Source: https://fennel-lang.org/reference

Symbols bound within a `case` pattern are independent of the outer scope, allowing names to be reused without affecting existing bindings. This example shows `x` being rebound within the pattern.

```fennel
(let [x 1]
  (case [:hello]
    ;; `x` is simply bound to the first value of [:hello]
    [x] x))
```

--------------------------------

### Fennel Match with Conflicting Bindings

Source: https://fennel-lang.org/reference

The `match` expression always pins symbols to outer scope values if they exist. This example demonstrates a failure to match because the symbol `a` is bound to different values (85 and 95) within the same pattern list.

```fennel
(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))
```

--------------------------------

### Fennel Case with Guard Clauses

Source: https://fennel-lang.org/reference

Use guard clauses in `case` patterns to match based on conditions beyond simple structure or value equality. The `where` symbol introduces conditions that must all evaluate to true for the pattern to match. This example matches a list where the first element is 91 and the sum of elements is even.

```fennel
(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)
```

--------------------------------

### Fennel Case with Invalid OR Binding

Source: https://fennel-lang.org/reference

Avoid combining patterns with `or` in `where` clauses if different variables are bound in different patterns or if some variables are missing. This can lead to compilation errors due to undefined variables in guards. This example shows an invalid usage where `b` is not present in the first pattern.

```fennel
;; bad
(case [1 2 3]
  ;; Will fail to compile because `b' is not present in the first
  ;; pattern but the guard still uses it.
  (where (or [a 1 2] [a b 3]) (< a 0) (< b 1))
  :body)
```

--------------------------------

### Fennel Binding Pinning with Mismatch

Source: https://fennel-lang.org/reference

Use the unary `(= binding-name)` form within a `where` guard to pin a binding to an existing outer scope value. This ensures the pattern only matches if the outer binding's value is equal to the value being matched. This example shows a mismatch where `x` (1) is not equal to `:hello`.

```fennel
(let [x 1]
  (case [:hello]
    ;; 1 != :hello
    (where [(= x)]) x
    _ :no-match))
```

--------------------------------

### Fennel code with lua special form and identifier mangling

Source: https://fennel-lang.org/reference

Illustrates how Fennel's `lua` special form handles local variables and identifier mangling. Fennel transforms `foo-bar` to `foo_bar` for valid Lua identifiers. The example shows printing a concatenated string using a mangled variable.

```fennel
(local foo-bar 3)
(let [foo-bar :hello]
  (lua "print(foo_bar0 .. \" world\")"))
```

--------------------------------

### Using `pick-values` with variadic functions

Source: https://fennel-lang.org/reference

Demonstrates how `pick-values` can be used to limit the number of arguments passed to variadic functions.

```fennel
(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 (= ... nil)
      sum
      (add sum ...))))

(add (pick-values 2 10 10 10 10)) ; => 20
(->> [1 2 3 4 5] (table.unpack) (pick-values 3) (add)) ; => 6
```

--------------------------------

### Basic Case Matching with Literal and Destructuring Patterns

Source: https://fennel-lang.org/reference

Demonstrates matching against literal values and destructuring tables with specific elements. Patterns are evaluated in order.

```fennel
(case mytable
  59      :will-never-match-hopefully
  [9 q 5] (print :q q)
  [1 a b] (+ a b))
```

--------------------------------

### Import macro module and access macros using dot notation

Source: https://fennel-lang.org/reference

This snippet demonstrates importing an entire macro module and accessing its macros using dot notation. This is an alternative to destructuring imports.

```fennel
(import-macros mine :my-macros)

(mine.when2 (= 3 (+ 2 a))
  (print "yes")
  (finish-calculation))
```

--------------------------------

### Debug macro expansion with 'macrodebug'

Source: https://fennel-lang.org/reference

This snippet demonstrates using 'macrodebug' to inspect the expansion of a macro. It repeatedly expands top-level macros in a given form and prints the result.

```fennel
(macrodebug (-> abc
                (+ 99)
                (< 0)
                (when (os.exit))))
; -> (if (< (+ abc 99) 0) (do (os.exit)))
```

--------------------------------

### Handling `pick-values` with fewer values than requested

Source: https://fennel-lang.org/reference

Illustrates the behavior of `pick-values` when the number of supplied values is less than the requested count, noting differences between `select` and table literal behavior.

```fennel
(select :# (pick-values 5 "one" "two")) ; => 5
[(pick-values 5 "one" "two")]           ; => ["one" "two"]
```

--------------------------------

### Matching Multiple Return Values

Source: https://fennel-lang.org/reference

Shows how to use parentheses within `case` to match against multiple return values from a function, useful for error handling.

```fennel
(case (io.open "/some/file")
  (nil msg) (report-error msg)
  f (read-file f))
```

--------------------------------

### Matching Identical and Different Values in a Table

Source: https://fennel-lang.org/reference

Illustrates how to match when the first two elements of a table are the same non-nil value, or when they are different non-nil values. Order of patterns is crucial.

```fennel
(case mytable
  ;; the first and second values of mytable are the same non-nil value
  [a a] (* a 2)
  ;; the first and second values are not nil and are not the same value
  [a b] (+ a b))
```

--------------------------------

### Fennel `each` loop with `&until` clause

Source: https://fennel-lang.org/reference

Demonstrates how to terminate an `each` loop early using the `&until` clause based on a condition.

```fennel
(local out [])
(each [_ value (pairs tbl) &until (< max-len (length out))]
  (table.insert out value))
```

--------------------------------

### Expand `pick-values` macro

Source: https://fennel-lang.org/reference

Shows the expansion of the `pick-values` macro into a `let` expression for managing multiple return values.

```fennel
(pick-values 2 (func))

expands to

(let [[_0_ _1_] [(func)]] (values _0_ _1_))
```

--------------------------------

### Fennel comparison and arithmetic operators

Source: https://fennel-lang.org/reference

Illustrates the usage of standard comparison and arithmetic operators in Fennel.

```fennel
(= 2 2 (table.unpack [2 5])) ; will evaluate to true
```

--------------------------------

### Matching Nested Tables and Capturing Remaining Elements

Source: https://fennel-lang.org/reference

Illustrates matching against nested table structures and using `&` to capture all remaining elements in a sequential table, similar to `let`.

```fennel
(case mytable
  {:subtable [a b ?c] :depth depth} (* b depth)
  _ :unknown)
```

--------------------------------

### Fennel Match with New Guard Syntax

Source: https://fennel-lang.org/reference

Demonstrates the preferred `where` syntax for guards in `match` expressions. This syntax is more readable and consistent with `case` expressions.

```fennel
(match [1 2 3]
  (where [a 2 3] (< 0 a)) "new guard syntax")
```

--------------------------------

### Fennel `do` form for multiple expressions

Source: https://fennel-lang.org/reference

Demonstrates the use of the `do` form to evaluate multiple expressions in sequence, returning the last value.

```fennel
(if launch-missiles?
    (do
      (power-on)
      (open-doors)
      (fire))
    false-alarm?
    (promote lt-petrov))
```

--------------------------------

### Handling Optional Nil Values in Patterns

Source: https://fennel-lang.org/reference

Shows how to use `?` to indicate that a symbol can optionally be `nil` during pattern matching. This allows for flexibility in matching values.

```fennel
(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)
```

--------------------------------

### Fennel `for` loop with step and `&until`

Source: https://fennel-lang.org/reference

Shows a numeric `for` loop with a step value and an `&until` clause for early termination.

```fennel
(for [i 1 10 2]
  (log-number i)
  (print i))
```

```fennel
(var x 0)
(for [i 1 128 &until (maxed-out? x)]
  (set x (+ x i)))
```

--------------------------------

### match-try for multi-step pattern matching

Source: https://fennel-lang.org/reference

Equivalent to case-try but uses 'match' internally, pinning values in the catch block with those in the original steps. Suitable for sequential operations with specific error handling.

```fennel
(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))))
```

--------------------------------

### Bind and auto-close file handles with with-open

Source: https://fennel-lang.org/reference

Ensures file handles are closed immediately after the body executes, even if errors occur. Destructuring is disallowed; bindings must have a ':close' method.

```fennel
;; 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
```

```fennel
;; 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>"]
```

--------------------------------

### Expanded code from 'when2' macro

Source: https://fennel-lang.org/reference

This is the compile-time expansion of the 'when2' macro usage shown previously. It demonstrates how the macro transforms the input code.

```fennel
(if (= 3 (+ 2 a))
  (do
    (print "yes")
    (finish-calculation)))
```

--------------------------------

### Fcollect Range Comprehension

Source: https://fennel-lang.org/reference

Builds a sequential table by traversing a range. Use when you need to iterate over a numerical range and collect results.

```fennel
(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)
```

--------------------------------

### Fn with docstring

Source: https://fennel-lang.org/reference

The `fn` form also accepts an optional docstring for documentation purposes.

```fennel
(fn pxy [x y]
  "Print the sum of x and y"
  (print (+ x y)))
```

--------------------------------

### Function with docstring and metadata

Source: https://fennel-lang.org/reference

Functions can accept a metadata table in place of a docstring, or in addition to it. This table can store arbitrary key-value pairs.

```fennel
(fn add [...]
  {:fnl/docstring "Add arbitrary amount of numbers."
   :fnl/arglist [a b & more]}
  (case (values (select :# ...) ...)
    (0) 0
    (1 a) a
    (2 a b) (+ a b)
    (_ a b) (add (+ a b) (select 3 ...))))
```

--------------------------------

### Table Lookup with `.`

Source: https://fennel-lang.org/reference

Looks up a key in a table. Supports nested lookups with multiple arguments. For compile-time known string keys, direct access like `mytbl.field` is preferred.

```fennel
(. mytbl myfield)
```

```fennel
(let [t {:a [2 3 4]}] (. t :a 2)) ; => 3
```

--------------------------------

### Fennel `each` loop with `pairs` iterator

Source: https://fennel-lang.org/reference

Illustrates a general iteration using `each` with the `pairs` iterator to process table elements.

```fennel
(each [key value (pairs mytbl)]
  (print "executing key")
  (print (f value)))
```

--------------------------------

### Evaluating Code During Compile-Time

Source: https://fennel-lang.org/reference

Demonstrates the use of `eval-compiler` to execute code during the compilation phase, providing access to the compiler's scope.

```fennel
(eval-compiler
  (each [name (pairs _G)]
    (print name)))
```

--------------------------------

### Hash Function Literal Shorthand

Source: https://fennel-lang.org/reference

A concise syntax for simple anonymous functions, useful as parameters to higher-order functions. Supports up to 9 arguments named $1-$9 or varargs with $... .

```fennel
#(+ $1 $2)
```

```fennel
#$3
```

```fennel
#[$1 $2 $3]
```

```fennel
#{:a $1 :b $2}
```

```fennel
#$
```

```fennel
#val
```

```fennel
#[:one :two $...]
```

```fennel
#$.foo
```

--------------------------------

### Fennel Case with Separate Guards (Equivalent to OR)

Source: https://fennel-lang.org/reference

This demonstrates the expanded form of the `or` in `where` clauses, showing that separate `where` clauses for each pattern are equivalent. Use this form for clarity or when patterns have slightly different binding requirements.

```fennel
(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")
```

--------------------------------

### Using Ignored Symbols for Placeholders and Fallbacks

Source: https://fennel-lang.org/reference

Demonstrates the use of `_` (and `_b`) as placeholders for any value, including `nil`. A trailing `_` can act as a default or 'else' case.

```fennel
(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)
```

--------------------------------

### Lambda with docstring

Source: https://fennel-lang.org/reference

Functions created with `lambda` or `λ` can include an optional docstring for documentation.

```fennel
(λ 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)))
```

--------------------------------

### Let Destructuring

Source: https://fennel-lang.org/reference

Allows destructuring of tables into local bindings. Supports sequential and non-sequential tables, with shorthand for matching keys and capturing remainders.

```fennel
(let [[a b c] [1 2 3]]
  (+ a b c))
```

```fennel
(let [{:msg message : val} {:msg "hello there" :val 19}]
  (print message)
  val)
```

```fennel
(let [[a b & c] [1 2 3 4 5 6]]
  (table.concat c ","))
```

```fennel
(let [{:a a :b b &as all} {:a 1 :b 2 :c 3 :d 4}]
  (+ a b all.c all.d))
```

```fennel
(let [(x y z) (table.unpack [10 9 8])]
  (+ x y z))
```

--------------------------------

### Sequential Table Comprehension with `icollect`

Source: https://fennel-lang.org/reference

Creates a sequential table from an iterator's values. Omits `nil` values. Similar to `map` and `filter` in other languages.

```fennel
(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)
```

```fennel
(icollect [_ x (ipairs [2 3]) &into [9]]
  (* x 11))
;; -> [9 22 33]
```

--------------------------------

### case-try for multi-step pattern matching

Source: https://fennel-lang.org/reference

Evaluates a series of pattern matching steps with an optional catch clause for fallback matching. Useful for sequential operations where any step might fail.

```fennel
(fn handle [conn token]
  (case-try (conn:receive :*l)
    input (parse input)
    (where (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))))
```

--------------------------------

### Fennel Match with Obsolete Guard Syntax

Source: https://fennel-lang.org/reference

Shows the older, now obsolete, infix `?` operator syntax for guards in `match` expressions. While still supported for backward compatibility, the `where` syntax should be preferred.

```fennel
([a 2 3] ? (< 0 a)) "obsolete guard syntax"
```

--------------------------------

### String Concatenation with `..`

Source: https://fennel-lang.org/reference

Concatenates multiple arguments into a single string. Numbers are coerced to strings. Subject to compile-time limits.

```fennel
(.. "Hello" " " "world" 7 "!!!") ; => "Hello world7!!!"
```

--------------------------------

### Fennel Unquote Macro Expansion

Source: https://fennel-lang.org/reference

The ',' prefix expands to a call to the 'unquote' macro.

```fennel
,foo
```

--------------------------------

### Nil-Safe Table Lookup with `?.`

Source: https://fennel-lang.org/reference

Performs a table lookup that short-circuits to `nil` if any key is not found. Useful for safely accessing nested data structures.

```fennel
(?. mytbl myfield)
```

```fennel
(let [t {:a [2 3 4]}] (?. t :a 4 :b)) ; => nil
```

```fennel
(let [t {:a [2 3 4 {:b 42}]}] (?. t :a 4 :b)) ; => 42
```

--------------------------------

### Define a macro module with 'when2'

Source: https://fennel-lang.org/reference

This snippet defines a macro module that exports a 'when2' macro. The macro takes a condition and a body, expanding into an 'if' statement with a 'do' block.

```fennel
(fn when2 [condition body1 & rest-body]
  (assert body1 "expected body")
  `(if ,condition
     (do ,body1 ,(unpack rest-body))))

{:when2 when2}
```

--------------------------------

### Fennel Infinity and NaN Syntax

Source: https://fennel-lang.org/reference

Represents infinity, negative infinity, NaN, and negative NaN.

```fennel
.inf
```

```fennel
-.inf
```

```fennel
.nan
```

```fennel
-.nan
```

--------------------------------

### Dynamic Method Call

Source: https://fennel-lang.org/reference

Performs a method call where the method name is dynamic. Use when the method to be called is determined at runtime.

```fennel
(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))
```

--------------------------------

### Declare local variable with var

Source: https://fennel-lang.org/reference

Introduces a new local variable within the current scope that can be modified later using 'set'.

```fennel
(var x 83)
```

--------------------------------

### Fennel Sequential Table Syntax

Source: https://fennel-lang.org/reference

Square brackets denote sequential tables, used for literal data structures and delimiting new identifiers in specials and macros.

```fennel
[1 2 3]
```

--------------------------------

### Method Call with Fixed Name

Source: https://fennel-lang.org/reference

Looks up and calls a function in a table using the ':' syntax. This is a common idiom for object-oriented programming in Fennel.

```fennel
(let [f (assert (io.open "hello" "w"))]
  (f:write "world")
  (f:close))
```

--------------------------------

### Interactive Debugging with assert-repl

Source: https://fennel-lang.org/reference

Replaces `assert` to drop into a REPL when a condition is false or nil, allowing inspection of local variables. Intended for development; requires Fennel as a library for AOT compilation.

```fennel
(let [input (get-input)
      value []]
  (fn helper [x]
    (table.insert value (calculate x)))
  (assert-repl (transform helper value) "could not transform"))
```

--------------------------------

### Fennel Table Shorthand Syntax

Source: https://fennel-lang.org/reference

Shorthand for table keys where a string is followed by a symbol of the same name.

```fennel
{: this} ; is shorthand for {:this this}
```

--------------------------------

### Let Binding with Locals

Source: https://fennel-lang.org/reference

Introduces a new scope for local bindings. Bindings are immutable within the scope and shadowed by inner scopes. The last form in the body is the return value.

```fennel
(let [x 89
      y 198]
  (print (+ x y 12)))
```

--------------------------------

### Range Accumulation with `faccumulate`

Source: https://fennel-lang.org/reference

Identical to `accumulate` but iterates over a numerical range defined by `for`-like bindings. Supports `&until` for early termination.

```fennel
(faccumulate [n 0 i 1 5] (+ n i)) ; => 15
```

--------------------------------

### Fennel Hash Macro Expansion

Source: https://fennel-lang.org/reference

The '#' prefix expands to a call to the 'hashfn' macro.

```fennel
#foo
```

--------------------------------

### Key-Value Table Comprehension with `collect`

Source: https://fennel-lang.org/reference

Creates a table from an iterator's key-value pairs. The body can return two values (key, value) or omit `values` for brevity. `nil` values are omitted.

```fennel
(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 [(.. "color-" v) k]
        [key value] (tset tbl key value))))
  tbl)
```

```fennel
(collect [k v (pairs {:a 85 :b 52 :c 621 :d 44})]
  k (* v 5))
```

--------------------------------

### Accidental Argument Evaluation in Macros

Source: https://fennel-lang.org/reference

Demonstrates how a macro can unintentionally evaluate its arguments multiple times if they have side effects. Use auto gensym or other techniques to prevent this.

```fennel
(var v 1)
(macros {:my-max (fn [x y]
                   `(if (< ,x ,y) ,y ,x))})

(fn f [] (set v (+ v 1)) v)

(print (my-max (f) 2)) ; -> 3 since (f) is called twice in the macro body above
```

--------------------------------

### Basic Function Literal

Source: https://fennel-lang.org/reference

A standard way to define an anonymous function with named arguments.

```fennel
(fn [a b] (+ a b))
```

--------------------------------

### Fennel Function Definition via Local Binding

Source: https://fennel-lang.org/reference

Defines a function and binds it to the local variable 'pxy'. This is equivalent to a named function but allows for different indentation.

```fennel
(local pxy (fn [x y]
             (print (+ x y))))
```

--------------------------------

### Multi-valued Return for Failure

Source: https://fennel-lang.org/reference

Signals failure by returning nil followed by an error message. Useful for functions that can fail validation.

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

--------------------------------

### Accessing metadata with fennel.metadata

Source: https://fennel-lang.org/reference

Use the `fennel.metadata` API to retrieve specific metadata values or the entire metadata table associated with a function.

```fennel
(local {: metadata} (require :fennel))
(metadata:get foo :deprecated)
```

```fennel
(local {: metadata} (require :fennel))
(metadata:get foo2 :added)
```

```fennel
(local {: metadata} (require :fennel))
(metadata:get some-function)
```

--------------------------------

### Define a table of macros using 'macros'

Source: https://fennel-lang.org/reference

This snippet uses the 'macros' macro to define multiple macros within a table. Note that code inside macro definitions runs in a separate compiler environment.

```fennel
(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))
```

--------------------------------

### Compile-time Module Inclusion

Source: https://fennel-lang.org/reference

Loads and embeds Fennel/Lua module code at compile time. The bundled code is wrapped in a function and set on `package.preload` for on-demand loading via `require`.

```fennel
(include :my.embedded.module)
```

--------------------------------

### Local Declaration

Source: https://fennel-lang.org/reference

Declares a new local binding within an existing scope, similar to `let` but without a body. Recommended for top-level file-wide locals. Supports destructuring.

```fennel
(local tau-approx 6.28318)
```

--------------------------------

### Lambda with nil-checked arguments

Source: https://fennel-lang.org/reference

Use `lambda` to create functions that throw runtime errors for nil arguments, unless prefixed with '?'. The `λ` form is an alias.

```fennel
(lambda [x ?y z]
  (print (- x (* (or ?y 1) z))))
```

--------------------------------

### Fennel Named Function Definition

Source: https://fennel-lang.org/reference

Defines a named function 'pxy' that takes two arguments and prints their sum. This is the preferred style for readability and recursion.

```fennel
(fn pxy [x y]
  (print (+ x y)))
```

--------------------------------

### Iterator Accumulation with `accumulate`

Source: https://fennel-lang.org/reference

Performs accumulation over an iterator, similar to `fold` or `reduce`. The first two bindings act as the accumulator and its initial value.

```fennel
(accumulate [sum 0
             i n (ipairs [10 20 30 40])]
    (+ sum n)) ; -> 100
```

--------------------------------

### Fennel Quote Macro Expansion

Source: https://fennel-lang.org/reference

The '`' prefix expands to a call to the 'quote' macro.

```fennel
`foo
```

--------------------------------

### Function with deprecated and added metadata

Source: https://fennel-lang.org/reference

Metadata can store version information like deprecation or addition dates, accessible via the `fennel.metadata` API.

```fennel
(fn foo []
  {:deprecated "v1.9.0"
   :fnl/docstring "*DEPRECATED* use foo2"}
  ;; old way to do stuff
  )
```

```fennel
(fn foo2 [x]
  {:added "v2.0.0"
   :fnl/docstring "Incompatible but better version of foo!"}
  ;; do stuff better, now with x!
  x)
```

--------------------------------

### Function with docstring and metadata table literal

Source: https://fennel-lang.org/reference

Metadata table literals can follow docstrings for convenience. The docstring is automatically inserted into the metadata table.

```fennel
(fn some-function [x ...]
  "Docstring for some-function."
  {:fnl/arglist [x & xs]
   :other :metadata}
  (let [xs (...)]
    ;; ...
    ))
```

--------------------------------

### Defining Methods in Fennel

Source: https://fennel-lang.org/reference

Defines a function that can be called as a method. The first argument, conventionally named 'self', refers to the table.

```fennel
(local t {})

(fn t.enable [self]
  (set self.enabled? true))

(t:enable)
```

--------------------------------

### Maybe Threading Macro `-?>`

Source: https://fennel-lang.org/reference

Similar to `->`, but stops threading if a form evaluates to nil or false. Use for safe, sequential access to nested data structures.

```fennel
(-?> {:a {:b {:c 42}}}
     (. :a)
     (. :missing)
     (. :c)) ; -> nil
```

--------------------------------

### Custom macro searcher function

Source: https://fennel-lang.org/reference

This code defines and registers a custom macro searcher function. This allows Fennel to find macro modules in non-standard locations, such as within archives.

```fennel
(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)
```

--------------------------------

### Preventing Symbol Capture with Auto Gensym

Source: https://fennel-lang.org/reference

Illustrates how to prevent accidental symbol capture in macros by appending '#' to identifier names, invoking auto gensym for unique local names.

```fennel
(macros {:my-max (fn [x y]
                   `(let [x2 ,x y2 ,y]
                      (if (< x2 y2) y2 x2)))})

(print (my-max 10 20))
; Compile error in 'x2' unknown:?: macro tried to bind x2 without gensym; try x2# instead
```

--------------------------------

### Doto Macro for Side Effects

Source: https://fennel-lang.org/reference

Splices a value into subsequent forms for side effects, returning the original value. Useful for resource management like opening and closing files.

```fennel
(doto (io.open "/tmp/err.log")
  (: :write contents)
  (: :close))

;; equivalent to:
(let [x (io.open "/tmp/err.log")]
  (: x :write contents)
  (: x :close)
  x)
```

--------------------------------

### Fennel Function Assignment to Table Field

Source: https://fennel-lang.org/reference

Explicitly assigns a function to a table field, demonstrating the equivalent of the 'fn functions.p' syntax.

```fennel
(set functions.p (fn [x y z]
                   (print (* x (+ y z)))))
```

--------------------------------

### Fennel Multi-Symbol Syntax

Source: https://fennel-lang.org/reference

Symbols with dots or colons are multi-symbols. The part before the first dot or colon is an identifier, and the part after is a field lookup.

```fennel
my-table.field
```

```fennel
my-object:method
```

--------------------------------

### Fennel Number Syntax with Underscores

Source: https://fennel-lang.org/reference

Underscores can be used to separate digits in numbers for readability.

```fennel
1_000_000
```

--------------------------------

### Fennel Table Literal Syntax

Source: https://fennel-lang.org/reference

Curly brackets denote key/value table literals (dictionaries).

```fennel
{:a 1 :b 2}
```

--------------------------------

### Macro Compile Error with Global Function Call

Source: https://fennel-lang.org/reference

Shows a compile error that occurs when a macro attempts to call a global function that is not properly imported or defined in the macro environment. Ensure functions are available in the compiler scope or use `import-macros`.

```fennel
(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)
```

--------------------------------

### Fennel Comment Syntax

Source: https://fennel-lang.org/reference

Semicolons indicate comments, extending to the end of the line.

```fennel
; This is a comment
```

--------------------------------

### Set table field with tset

Source: https://fennel-lang.org/reference

Sets a field of a given table to a new value, supporting nested fields. Mostly redundant since 1.5.0 due to 'set', but works with 'doto'.

```fennel
(let [tbl {:d 32} field :d]
  (tset tbl field 19) tbl) ; => {:d 19}
```

```fennel
(let [tbl {:a {:b {}}} field :c]
  (tset tbl :a :b field "d") tbl) ; => {:a {:b {:c "d"}}}
```

--------------------------------

### Fennel Function Definition in Table Field

Source: https://fennel-lang.org/reference

Defines a function and assigns it to a field 'p' within the 'functions' table. This is an alternative to binding as a local.

```fennel
(local functions {})

(fn functions.p [x y z]
  (print (* x (+ y z))))
```

--------------------------------

### Set local variable or table field

Source: https://fennel-lang.org/reference

Changes the value of a variable declared with 'var' or a field within a table. Supports static and dynamic field access.

```fennel
(set x (+ x 91)) ; var
```

```fennel
(let [t {:a 4 :b 8}]
  (set t.a 2) t) ; => {:a 2 :b 8}
```

```fennel
(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}}
```

--------------------------------

### Fennel Anonymous Function Definition

Source: https://fennel-lang.org/reference

Defines an anonymous function that takes two arguments and prints their sum. The function is not bound to a name.

```fennel
(fn [x y]
  (print (+ x y)))
```

--------------------------------

### Forward Threading Macro `->`

Source: https://fennel-lang.org/reference

Splices a value into the first argument of subsequent forms. Useful for chaining function calls where the result of one is the input to the next.

```fennel
(-> 52
    (+ 91 2) ; (+ 52 91 2)
    (- 8)    ; (- (+ 52 91 2) 8)
    (print "is the answer")) ; (print (- (+ 52 91 2) 8) "is the answer")
```

--------------------------------

### Tail Call Assertion `tail!`

Source: https://fennel-lang.org/reference

Asserts that a call is in tail position, enabling compiler optimization. Use to prevent stack overflows in recursive functions by ensuring tail call optimization.

```fennel
(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)))))

```

--------------------------------

### Fennel String Syntax with Escaped Quotes

Source: https://fennel-lang.org/reference

Strings use double-quotes and require escaping internal double quotes with backslashes. Supports newline characters.

```fennel
"This string contains \"escaped quotes\" and a\nnewline."
```

--------------------------------

### Backward Threading Macro `->>`

Source: https://fennel-lang.org/reference

Splices a value into the last argument of subsequent forms. Use when the output of a function needs to be the final argument of the next.

```fennel
(-?>> :a
      (. {:a :b})
      (. {:b :missing})
      (. {:c 42})) ; -> nil
```
Tokens:
Raw