Release 1.4.1

changelog.md

@@ -6,7 +6,7 @@ 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.
 
-## 1.4.1 / ???
+## 1.4.1 / 2024-02-19
 
 ### New Features
 

man/man3/fennel-api.3

@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "fennel-api" "3" "2023-12-01" "fennel 1.4.0" "Fennel\[aq]s Lua API"
+.TH "fennel-api" "3" "2024-02-19" "fennel 1.4.1" "Fennel\[aq]s Lua API"
 .hy
 .SH NAME
 .PP
@@ -120,7 +120,25 @@ source of the generated lua code.
 .PP
 By default, metadata will be enabled and you can view function
 signatures and docstrings with the \f[V],doc\f[R] command in the REPL.
-.SH EVAULATE A STRING OF FENNEL
+.SS Customize REPL default options
+.PP
+Any fields set on \f[V]fennel.repl\f[R], which is actually a table with
+a \f[V]__call\f[R] metamethod rather than a function, will used as a
+fallback for any options passed to \f[V](fennel.repl)\f[R] before
+defaults are applied, allowing one to customize the default behavior of
+\f[V](fennel.repl)\f[R]:
+.IP
+.nf
+\f[C]
+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
+end
+\f[R]
+.fi
+.SH EVALUATE A STRING OF FENNEL
 .IP
 .nf
 \f[C]
@@ -270,10 +288,12 @@ Accepts \f[V]filename\f[R] in \f[V]options\f[R] like
 .PP
 This is useful when streaming data into the compiler to allow you to
 avoid loading all the code into a single string in one go.
+The first argument should be a stateful iterator; in other words a
+function which returns one byte at a time.
 .IP
 .nf
 \f[C]
-local lua = fennel.compileStream(strm[, options])
+local lua = fennel.compileStream(stream[, options])
 \f[R]
 .fi
 .PP

man/man5/fennel-reference.5

@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "fennel-reference" "5" "2023-12-01" "fennel 1.4.0" "Fennel Reference"
+.TH "fennel-reference" "5" "2024-02-19" "fennel 1.4.1" "Fennel Reference"
 .hy
 .SH NAME
 .PP
@@ -534,31 +534,6 @@ Example:
 but it has a small performance cost, so it\[aq]s recommended to use
 \f[V]...\f[R] instead in cases that are sensitive to overhead.
 .PP
-If a table implements \f[V]__fennelrest\f[R] 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
-.PP
-Example:
-.IP
-.nf
-\f[C]
-(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}
-\f[R]
-.fi
-.PP
 When destructuring a non-sequential table, you can capture the original
 table along with the destructuring by using \f[V]&as\f[R]:
 .PP
@@ -1710,21 +1685,22 @@ The first form becomes the return value for the whole expression, and
 subsequent forms are evaluated solely for side-effects.
 .SS \f[V]tail!\f[R]
 .PP
-The \f[V]tail!\f[R] form asserts that its argument is called in a tail
-position.
-You can use this when using tail calls to recurse over large data sets
-in a way that might not be obvious; that way if the code is changed so
-that the recursive call is no longer a tail call, it will cause a
-compile error instead of overflowing the stack on large data sets.
+Tail calls will be optimized automatically.
+However, the \f[V]tail!\f[R] 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.
 .IP
 .nf
 \f[C]
 (fn process-all [data i]
   (case (process (. data i))
     :done (print \[dq]Process completed.\[dq])
     :next (process-all data (+ i 1))
-    :skip (do (process-all data (+ i 2))
-;;             \[ha]\[ha]\[ha]\[ha]\[ha]\[ha]\[ha]\[ha]\[ha]\[ha]\[ha] Compile error: Must be in tail position
+    :skip (do (tail! (process-all data (+ i 2)))
+;;             \[ha]\[ha]\[ha]\[ha]\[ha] Compile error: Must be in tail position
               (print \[dq]Skipped\[dq] (+ i 1)))))
 \f[R]
 .fi
@@ -1777,17 +1753,11 @@ You can use the \f[V]assert-repl\f[R] macro to do this:
 \f[R]
 .fi
 .PP
-This works like the built-in \f[V]assert\f[R] 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.
-(This would be \f[V]input\f[R], \f[V]value\f[R], and \f[V]helper\f[R] in
-the example above.)
-It takes an optional options table as its third argument which accepts
-all the same values as the \f[V]fennel.repl\f[R] function in the API.
-.PP
-You can \f[V],return EXPRESSION\f[R] from the repl to replace the
-original failing condition with a different arbitrary value.
-Returning false or nil will trigger a regular \f[V]assert\f[R] failure.
+This works as a drop-in replacement for the built-in \f[V]assert\f[R]
+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 (\f[V]input\f[R], \f[V]value\f[R], and \f[V]helper\f[R] in the
+example above).
 .PP
 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
@@ -1796,6 +1766,27 @@ library.
 If you use the \f[V]--assert-as-repl\f[R] flag when running Fennel,
 calls to \f[V]assert\f[R] will be replaced with \f[V]assert-repl\f[R]
 automatically.
+.PP
+\f[B]Note:\f[R] In Fennel 1.4.0, \f[V]assert-repl\f[R] accepted an
+options table for \f[V]fennel.repl\f[R] as an optional third argument.
+This was removed as a bug in 1.4.1, as it broke compatibility with
+\f[V]assert\f[R].
+.PP
+The REPL spawned by \f[V]assert-repl\f[R] applies the same default
+options as \f[V]fennel.repl\f[R], which as of Fennel 1.4.1 can be
+configured from the API.
+See the Fennel API reference for details.
+.SS Recovering from failed assertions
+.PP
+You can \f[V],return EXPRESSION\f[R] from the repl to replace the
+original failing condition with a different arbitrary value.
+Returning false or nil will trigger a regular \f[V]assert\f[R] failure.
+.PP
+\f[B]Note:\f[R] Currently, only a single value can be returned from the
+REPL this way.
+While \f[V],return\f[R] can be used to make a failed assertion recover,
+if the calling code expects multiple return values, it may cause
+unspecified behavior.
 .SH MACROS
 .PP
 All forms which introduce macros do so inside the current scope.
@@ -2194,6 +2185,10 @@ the second argument.
 Note that this should only be used in exceptional circumstances, and if
 you are able to avoid it, you should.
 .SH DEPRECATED FORMS
+.PP
+The \f[V]#\f[R] form is a deprecated alias for \f[V]length\f[R], and
+\f[V]\[ti]=\f[R] is a deprecated alias for \f[V]not=\f[R], kept for
+backwards compatibility.
 .SS \f[V]require-macros\f[R] load macros with less flexibility
 .PP
 \f[I](Deprecated in 0.4.0)\f[R]
@@ -2231,5 +2226,33 @@ allowed globals so that referring to it later on will not cause a
 compiler error.
 However, globals are also available in the \f[V]_G\f[R] table, and
 accessing them that way instead is recommended for clarity.
+.SS Rest destructuring metamethod
+.PP
+\f[I](Deprecated in 1.4.1)\f[R]
+.PP
+If a table implements \f[V]__fennelrest\f[R] 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
+.PP
+Example:
+.IP
+.nf
+\f[C]
+(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}
+\f[R]
+.fi
 .SH AUTHORS
 Fennel Maintainers.

man/man7/fennel-tutorial.7

@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "fennel-tutorial" "7" "2023-12-01" "fennel 1.4.0" "Getting Started with Fennel"
+.TH "fennel-tutorial" "7" "2024-02-19" "fennel 1.4.1" "Getting Started with Fennel"
 .hy
 .SH NAME
 .PP
@@ -37,7 +37,7 @@ Even if not, Lua is one of the simplest programming languages in
 existence, so if you\[aq]ve programmed before you should be able to pick
 it up without too much trouble, especially if you\[aq]ve used another
 dynamic imperative language with closures.
-The Lua reference manual (https://www.lua.org/manual/5.1/) is a fine
+The Lua reference manual (https://www.lua.org/manual/5.4/) is a fine
 place to look for details, but Fennel\[aq]s own Lua
 Primer (https://fennel-lang.org/lua-primer) is shorter and covers the
 highlights.
@@ -329,7 +329,7 @@ over numeric keys starting with 1 until it hits a \f[V]nil\f[R].
 You can use any Lua iterator (https://www.lua.org/pil/7.1.html) with
 \f[V]each\f[R], but these are the most common.
 Here\[aq]s an example that walks through matches in a
-string (https://www.lua.org/manual/5.1/manual.html#pdf-string.gmatch):
+string (https://www.lua.org/manual/5.4/manual.html#pdf-string.gmatch):
 .IP
 .nf
 \f[C]
@@ -715,13 +715,15 @@ Return values in the repl will get pretty-printed, but calling
 If you don\[aq]t already have one, it\[aq]s recommended for debugging to
 define a printer function which calls \f[V]fennel.view\f[R] on its
 argument before printing it:
-\f[V](local fennel (require :fennel)) (fn _G.pp [x] (print (fennel.view x)))\f[R]
+\f[V](local fennel (require :fennel)) (fn _G.pp [x] (print (fennel.view x)))\f[R].
+If you add this definition to your \f[V]\[ti]/.fennelrc\f[R] file it
+will be available in the standard repl.
 .IP \[bu] 2
 Lua programmers should note Fennel functions cannot do early returns.
 .SH OTHER STUFF JUST WORKS
 .PP
 Note that built-in functions in Lua\[aq]s standard
-library (https://www.lua.org/manual/5.1/manual.html#5) like
+library (https://www.lua.org/manual/5.4/manual.html#6) like
 \f[V]math.random\f[R] above can be called with no fuss and no overhead.
 .PP
 This includes features like coroutines, which are often implemented

rockspecs/fennel-1.4.1-1.rockspec

@@ -0,0 +1,8 @@
+package = "fennel"
+local fennel_version = "1.4.1"
+version = (fennel_version .. "-1")
+source = {url = ("https://fennel-lang.org/downloads/fennel-" .. fennel_version .. ".tar.gz")}
+description = {summary = "A lisp that compiles to Lua", detailed = ("Get your parens on--write macros and " .. "homoiconic code on the Lua runtime!"), license = "MIT", homepage = "https://fennel-lang.org/"}
+dependencies = {"lua >= 5.1"}
+build = {type = "builtin", install = {bin = {fennel = "fennel"}}, modules = {fennel = "fennel.lua"}}
+return nil

setup.md

@@ -35,12 +35,12 @@ installed on your system.
 This method requires you to manually update the `fennel` script when
 you want to use a newer version that has come out.
 
- 1. Download [the fennel script](https://fennel-lang.org/downloads/fennel-1.4.0)
- 2. Run `chmod +x fennel-1.4.0` to make it executable
- 3. Download the [signature](https://fennel-lang.org/downloads/fennel-1.4.0.asc)
-    and confirm it matches using `gpg --verify fennel-1.4.0*.asc`
+ 1. Download [the fennel script](https://fennel-lang.org/downloads/fennel-1.4.1)
+ 2. Run `chmod +x fennel-1.4.1` to make it executable
+ 3. Download the [signature](https://fennel-lang.org/downloads/fennel-1.4.1.asc)
+    and confirm it matches using `gpg --verify fennel-1.4.1*.asc`
     (optional but recommended).
- 4. Move `fennel-1.4.0` to a directory on your `$PATH`, such as `/usr/local/bin`
+ 4. Move `fennel-1.4.1` to a directory on your `$PATH`, such as `/usr/local/bin`
 
 **Note**: You can rename the script to `fennel` for convenience. Or
 you can leave the version in the name, which makes it easy to keep
@@ -57,14 +57,14 @@ This method requires you to manually update the `fennel` binary when
 you want to use a newer version that has come out.
 
  1. Choose one the options below, depending on your system:
-      - [GNU/Linux x86_64](https://fennel-lang.org/downloads/fennel-1.4.0-x86_64)
-        ([signature](https://fennel-lang.org/downloads/fennel-1.4.0-x86_64.asc))
-      - [GNU/Linux arm32](https://fennel-lang.org/downloads/fennel-1.4.0-arm32)
-        ([signature](https://fennel-lang.org/downloads/fennel-1.4.0-arm32.asc))
-      - [Windows x86 32-bit](https://fennel-lang.org/downloads/fennel-1.4.0-windows32.exe)
-        ([signature](https://fennel-lang.org/downloads/fennel-1.4.0-windows32.exe.asc))
- 2. Run `chmod +x fennel-1.4.0*` to make it executable
- 3. Download the signature and confirm it matches using `gpg --verify fennel-1.4.0*.asc`
+      - [GNU/Linux x86_64](https://fennel-lang.org/downloads/fennel-1.4.1-x86_64)
+        ([signature](https://fennel-lang.org/downloads/fennel-1.4.1-x86_64.asc))
+      - [GNU/Linux arm32](https://fennel-lang.org/downloads/fennel-1.4.1-arm32)
+        ([signature](https://fennel-lang.org/downloads/fennel-1.4.1-arm32.asc))
+      - [Windows x86 32-bit](https://fennel-lang.org/downloads/fennel-1.4.1-windows32.exe)
+        ([signature](https://fennel-lang.org/downloads/fennel-1.4.1-windows32.exe.asc))
+ 2. Run `chmod +x fennel-1.4.1*` to make it executable
+ 3. Download the signature and confirm it matches using `gpg --verify fennel-1.4.1*.asc`
     (optional but recommended).
  4. Move the downloaded binary to a directory on your `$PATH`, such as `/usr/local/bin`
 
@@ -97,7 +97,7 @@ The Fennel compiler can be added to your code repository, and then
 loaded from Lua.
 
  1. Get the `fennel.lua` library. You can get this from a
-    [release tarball](https://fennel-lang.org/downloads/fennel-1.4.0.tar.gz)
+    [release tarball](https://fennel-lang.org/downloads/fennel-1.4.1.tar.gz)
     or by running `make` in a source checkout.
  2. Add `fennel.lua` to your code repository.
  3. Add the following lines to your Lua code:

src/fennel/utils.fnl

@@ -5,7 +5,7 @@
 
 (local view (require :fennel.view))
 
-(local version :1.4.1-dev)
+(local version :1.4.1)
 
 ;;; Lua VM detection helper functions