Release 1.5.0

Makefile

@@ -180,6 +180,7 @@ upload: fennel fennel.lua fennel-bin fennel.exe
 		[email protected]:fennel-lang.org/downloads/
 
 release: guard-VERSION upload
+	git tag -v $(VERSION) # created by prerelease target
 	git push
 	git push --tags
 	@echo "* Update the submodule in the fennel-lang.org repository."
@@ -189,7 +190,6 @@ release: guard-VERSION upload
 
 prerelease: guard-VERSION ci test-builds
 	@echo "Did you look for changes that need to be mentioned in help/man text?"
-	exit 1 # TODO: update setup.md to stop linking to tarball
 	sed -i s/$(VERSION)-dev/$(VERSION)/ src/fennel/utils.fnl
 	$(MAKE) man
 	grep "$(VERSION)" setup.md > /dev/null

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.5.0 / ???
+## 1.5.0 / 2024-06-23
 
 ### New Features
 

man/man3/fennel-api.3

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.1.2
+.\" Automatically generated by Pandoc 2.17.1.1
 .\"
 .\" Define V font for inline verbatim, using C font in formats
 .\" that render this, and otherwise B font.
@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "fennel-api" "3" "2024-03-10" "fennel 1.5.0-dev" "Fennel\[aq]s Lua API"
+.TH "fennel-api" "3" "2024-06-23" "fennel 1.5.0" "Fennel\[aq]s Lua API"
 .hy
 .SH NAME
 .PP
@@ -76,6 +76,10 @@ Pass \f[V]_G\f[R] to disable sandboxing.
 .IP \[bu] 2
 \f[V]error-pinpoint\f[R]: a list of two strings indicating what to wrap
 compile errors in
+.IP \[bu] 2
+\f[V]keywords\f[R]: a table of the form
+\f[V]{:keyword1 true :keyword2 true}\f[R] containing symbols that should
+be treated as reserved Lua keywords.
 .PP
 You can pass the string \f[V]\[dq]_COMPILER\[dq]\f[R] as the value for
 \f[V]env\f[R]; it will cause the code to be run/compiled in a context
@@ -123,6 +127,13 @@ 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.
+.PP
+In Fennel 1.4.1 \f[V]fennel.repl\f[R] 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 \f[V]coroutine.create\f[R].
+You can pass \f[V]fennel.repl.repl\f[R] instead.
 .SS Customize REPL default options
 .PP
 Any fields set on \f[V]fennel.repl\f[R], which is actually a table with
@@ -238,7 +249,7 @@ end)
 Macro searchers store loaded macro modules in the
 \f[V]fennel.macro-loaded\f[R] table which works the same as
 \f[V]package.loaded\f[R] but for macro modules.
-.SH GET FENNEL-AWARE STACK TRACES.
+.SH GET FENNEL-AWARE STACK INFORMATION
 .PP
 The \f[V]fennel.traceback\f[R] function works like Lua\[aq]s
 \f[V]debug.traceback\f[R] function, except it tracks line numbers from
@@ -255,6 +266,19 @@ debug.traceback = fennel.traceback
 .PP
 Note that some systems print stack traces from C, which will not be
 affected.
+.PP
+The \f[V]fennel.getinfo\f[R] function works like Lua\[aq]s
+\f[V]debug.getinfo\f[R] function, except it tracks line numbers from
+Fennel code correctly.
+Functions defined from Fennel will have the \f[V]what\f[R] field set to
+\f[V]\[dq]Fennel\[dq]\f[R] instead of \f[V]\[dq]Lua\[dq]\f[R].
+.IP
+.nf
+\f[C]
+local mymodule = require(\[dq]module\[dq])
+print(fennel.getinfo(mymodule.func1).linedefined)
+\f[R]
+.fi
 .SH COMPILE FENNEL CODE TO LUA
 .SS Compile a file, AST, or byte iterator
 .IP
@@ -356,8 +380,9 @@ The list also contains these keys indicating where it was defined:
 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 \[dq]วัด\[dq] is three
-characters but only two visual columns.
+always correspond to visual columns; for instance
+\[dq]\[u0E27]\[u0E31]\[u0E14]\[dq] is three characters but only two
+visual columns.
 .SS sequence/key-value table
 .PP
 These are table literals in Fennel code produced by square brackets
@@ -650,8 +675,8 @@ this with Fennel later would result in an incorrect escape code in Lua
 .SH WORK WITH DOCSTRINGS AND METADATA
 .PP
 When running a REPL or using compile/eval with metadata enabled, each
-function declared with \f[V]fn\f[R] or \f[V]λ/lambda\f[R] will use the
-created function as a key on \f[V]fennel.metadata\f[R] to store the
+function declared with \f[V]fn\f[R] or \f[V]\[*l]/lambda\f[R] will use
+the created function as a key on \f[V]fennel.metadata\f[R] to store the
 function\[aq]s arglist and (if provided) docstring.
 The metadata table is weakly-referenced by key, so each function\[aq]s
 metadata will be garbage collected along with the function itself.
@@ -677,7 +702,7 @@ operate on that\[aq]s bound to the function.
 .IP
 .nf
 \f[C]
-local greet = fennel.eval(\[aq](λ greet [name] \[dq]Say hello\[dq] (print \[dq]Hello,\[dq] name))\[aq],
+local greet = fennel.eval(\[aq](\[*l] greet [name] \[dq]Say hello\[dq] (print \[dq]Hello,\[dq] name))\[aq],
                           {useMetadata = true})
 
 fennel.metadata[greet]
@@ -849,7 +874,7 @@ one which is used to print errors.
 .nf
 \f[C]
 (local fennel (require :fennel)
-(fn locals [env read on-values on-error scope]
+(fn locals [env read on-values on-error scope chars opts]
   \[dq]Print all locals in repl session scope.\[dq]
   (on-values [(fennel.view env.___replLocals___)]))
 
@@ -887,11 +912,12 @@ If you\[aq]re using the compiler programmatically, you can include a
 \f[V]:plugins\f[R] table in the \f[V]options\f[R] table to most compiler
 entry point functions.
 .PP
-Your plugin should contain a \f[V]:versions\f[R] table which contains a
-list of strings indicating every version of Fennel which you have tested
-it with.
+Your plugin should contain a \f[V]:versions\f[R] 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\[aq]s version with \f[V]string.find\f[R].
+If your plugin is used with a version of Fennel that doesn\[aq]t match
+\f[V]:versions\f[R] it will emit a warning.
 You should also have a \f[V]:name\f[R] field with the plugin\[aq]s name.
-If your plugin is used with a version of Fennel that isn\[aq]t in the
-list, it will emit a warning.
 .SH AUTHORS
 Fennel Maintainers.

man/man5/fennel-reference.5

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.1.2
+.\" Automatically generated by Pandoc 2.17.1.1
 .\"
 .\" Define V font for inline verbatim, using C font in formats
 .\" that render this, and otherwise B font.
@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "fennel-reference" "5" "2024-03-10" "fennel 1.5.0-dev" "Fennel Reference"
+.TH "fennel-reference" "5" "2024-06-23" "fennel 1.5.0" "Fennel Reference"
 .hy
 .SH NAME
 .PP
@@ -203,7 +203,7 @@ overflowing the stack, provided the call is in a tail position.
 .PP
 The final form in this and all other function forms is used as the
 return value.
-.SS \f[V]lambda\f[R]/\f[V]λ\f[R] nil-checked function
+.SS \f[V]lambda\f[R]/\f[V]\[*l]\f[R] nil-checked function
 .PP
 Creates a function like \f[V]fn\f[R] does, but throws an error at
 runtime if any of the listed arguments are nil, unless its identifier
@@ -233,11 +233,11 @@ the \f[V]?foo\f[R] 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.
 .PP
-The \f[V]λ\f[R] form is an alias for \f[V]lambda\f[R] and behaves
+The \f[V]\[*l]\f[R] form is an alias for \f[V]lambda\f[R] and behaves
 identically.
 .SS Docstrings and metadata
 .PP
-The \f[V]fn\f[R], \f[V]lambda\f[R], \f[V]λ\f[R] and \f[V]macro\f[R]
+The \f[V]fn\f[R], \f[V]lambda\f[R], \f[V]\[*l]\f[R] and \f[V]macro\f[R]
 forms accept an optional docstring.
 .IP
 .nf
@@ -246,7 +246,7 @@ forms accept an optional docstring.
   \[dq]Print the sum of x and y\[dq]
   (print (+ x y)))
 
-(λ pxyz [x ?y z]
+(\[*l] pxyz [x ?y z]
   \[dq]Print the sum of x, y, and z. If y is not provided, defaults to 0.\[dq]
   (print (+ x (or ?y 0) z)))
 \f[R]
@@ -1004,6 +1004,33 @@ Example:
 (do (local (_ _ z) (unpack [:a :b :c :d :e])) z)  => c
 \f[R]
 .fi
+.SS \f[V]tset\f[R] set table field
+.PP
+Sets the field of a given table to a new value.
+.PP
+Example:
+.IP
+.nf
+\f[C]
+(let [tbl {:d 32} field :d]
+  (tset tbl field 19) tbl) ; => {:d 19}
+\f[R]
+.fi
+.PP
+You can provide multiple successive field names to perform nested sets.
+For example:
+.IP
+.nf
+\f[C]
+(let [tbl {:a {:b {}}} field :c]
+  (tset tbl :a :b field \[dq]d\[dq]) tbl) ; => {:a {:b {:c \[dq]d\[dq]}}}
+\f[R]
+.fi
+.PP
+Since 1.5.0, \f[V]tset\f[R] is mostly redundant because \f[V]set\f[R]
+can be used for table fields.
+The main exception is that \f[V]tset\f[R] works with \f[V]doto\f[R] and
+\f[V]set\f[R] does not.
 .SS \f[V]with-open\f[R] bind and auto-close file handles
 .PP
 While Lua will automatically close an open file handle when it\[aq]s
@@ -2203,7 +2230,7 @@ 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]
+\f[I](Deprecated in 1.4.1, will be removed in future versions)\f[R]
 .PP
 If a table implements \f[V]__fennelrest\f[R] metamethod it is used to
 capture the remainder of the table.
@@ -2229,32 +2256,5 @@ Example:
   c) ;; => {:3 3 :4 4 :5 5 :6 6}
 \f[R]
 .fi
-.SS \f[V]tset\f[R] set table field
-.PP
-\f[I](Deprecated in 1.5.0)\f[R]
-.PP
-Sets the field of a given table to a new value.
-The field name does not need to be known at compile-time.
-Works on any table; the table does not have to be declared with
-\f[V]var\f[R] to change its fields.
-.PP
-Example:
-.IP
-.nf
-\f[C]
-(let [tbl {:d 32} field :d]
-  (tset tbl field 19) tbl) ; => {:d 19}
-\f[R]
-.fi
-.PP
-You can provide multiple successive field names to perform nested sets.
-For example:
-.IP
-.nf
-\f[C]
-(let [tbl {:a {:b {}}} field :c]
-  (tset tbl :a :b field \[dq]d\[dq]) tbl) ; => {:a {:b {:c \[dq]d\[dq]}}}
-\f[R]
-.fi
 .SH AUTHORS
 Fennel Maintainers.

man/man7/fennel-tutorial.7

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.1.2
+.\" Automatically generated by Pandoc 2.17.1.1
 .\"
 .\" Define V font for inline verbatim, using C font in formats
 .\" that render this, and otherwise B font.
@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "fennel-tutorial" "7" "2024-03-10" "fennel 1.5.0-dev" "Getting Started with Fennel"
+.TH "fennel-tutorial" "7" "2024-06-23" "fennel 1.5.0" "Getting Started with Fennel"
 .hy
 .SH NAME
 .PP

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.2)
- 2. Run `chmod +x fennel-1.4.2` to make it executable
- 3. Download the [signature](https://fennel-lang.org/downloads/fennel-1.4.2.asc)
-    and confirm it matches using `gpg --verify fennel-1.4.2*.asc`
+ 1. Download [the fennel script](https://fennel-lang.org/downloads/fennel-1.5.0)
+ 2. Run `chmod +x fennel-1.5.0` to make it executable
+ 3. Download the [signature](https://fennel-lang.org/downloads/fennel-1.5.0.asc)
+    and confirm it matches using `gpg --verify fennel-1.5.0*.asc`
     (optional but recommended).
- 4. Move `fennel-1.4.2` to a directory on your `$PATH`, such as `/usr/local/bin`
+ 4. Move `fennel-1.5.0` 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,12 +57,12 @@ 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.2-x86_64)
-        ([signature](https://fennel-lang.org/downloads/fennel-1.4.2-x86_64.asc))
-      - [Windows x86 32-bit](https://fennel-lang.org/downloads/fennel-1.4.2-windows32.exe)
-        ([signature](https://fennel-lang.org/downloads/fennel-1.4.2-windows32.exe.asc))
- 2. Run `chmod +x fennel-1.4.2*` to make it executable
- 3. Download the signature and confirm it matches using `gpg --verify fennel-1.4.2*.asc`
+      - [GNU/Linux x86_64](https://fennel-lang.org/downloads/fennel-1.5.0-x86_64)
+        ([signature](https://fennel-lang.org/downloads/fennel-1.5.0-x86_64.asc))
+      - [Windows x86 32-bit](https://fennel-lang.org/downloads/fennel-1.5.0-windows32.exe)
+        ([signature](https://fennel-lang.org/downloads/fennel-1.5.0-windows32.exe.asc))
+ 2. Run `chmod +x fennel-1.5.0*` to make it executable
+ 3. Download the signature and confirm it matches using `gpg --verify fennel-1.5.0*.asc`
     (optional but recommended).
  4. Move the downloaded binary to a directory on your `$PATH`, such as `/usr/local/bin`
 
@@ -94,9 +94,7 @@ them all here; please [see the wiki page on distribution for details](https://wi
 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.2.tar.gz)
-    or by running `make` in a source checkout.
+ 1. Build `fennel.lua` 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.5.0-dev)
+(local version :1.5.0)
 
 ;;; Lua VM detection helper functions