feat(discard): add docs

changelog.md

@@ -8,6 +8,9 @@ deprecated forms.
 
 ## 1.5.1 / ???
 
+### New Features
+
+* Add support for discarding (Clojure's `#_`).
 ### Bug Fixes
 
 * `,doc`/`fennel.doc`: Don't mutate `:fnl/arglist` directly when showing callable form

from-clojure.md

@@ -464,6 +464,20 @@ other macros.
 
 Lists and symbols are strictly compile-time concepts in Fennel.
 
+## Discards
+
+Just like Clojure, Fennel supports the `#_` <https://clojure.org/guides/weird_characters#_discard>
+
+```fennel
+[1 #_ {:a :b} 3 #_ #_ (+ 4 5) 6 7 #_]
+```
+
+expands to
+
+```fennel
+[1 3 7]
+```
+
 ## Errors
 
 There are two kinds of ways to represent failure in Lua and

man/man3/fennel-api.3

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 2.17.1.1
+.\" Automatically generated by Pandoc 3.1.2
 .\"
 .\" 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-06-23" "fennel 1.5.0" "Fennel\[aq]s Lua API"
+.TH "fennel-api" "3" "2024-06-28" "fennel 1.5.1-dev" "Fennel\[aq]s Lua API"
 .hy
 .SH NAME
 .PP
@@ -380,9 +380,8 @@ 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]\[u0E27]\[u0E31]\[u0E14]\[dq] is three characters but only two
-visual columns.
+always correspond to visual columns; for instance \[dq]วัด\[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
@@ -675,8 +674,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]\[*l]/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]λ/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.
@@ -702,7 +701,7 @@ operate on that\[aq]s bound to the function.
 .IP
 .nf
 \f[C]
-local greet = fennel.eval(\[aq](\[*l] greet [name] \[dq]Say hello\[dq] (print \[dq]Hello,\[dq] name))\[aq],
+local greet = fennel.eval(\[aq](λ greet [name] \[dq]Say hello\[dq] (print \[dq]Hello,\[dq] name))\[aq],
                           {useMetadata = true})
 
 fennel.metadata[greet]

man/man5/fennel-reference.5

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 2.17.1.1
+.\" Automatically generated by Pandoc 3.1.2
 .\"
 .\" 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-06-23" "fennel 1.5.0" "Fennel Reference"
+.TH "fennel-reference" "5" "2024-06-28" "fennel 1.5.1-dev" "Fennel Reference"
 .hy
 .SH NAME
 .PP
@@ -148,6 +148,15 @@ Certain prefixes are expanded by the parser into longhand equivalents:
 .PP
 A semicolon and everything following it up to the end of the line is a
 comment.
+.PP
+Expressions (literals and tables) can be ignored by the parser if
+preceded by \f[V]#_\f[R] (like in Clojure):
+.IP \[bu] 2
+\f[V][1 #_ {:a :b} 3 #_ #_ (+ 4 5) 6 7 #_]\f[R] expands to
+\f[V][1 3 7]\f[R]
+.PP
+\f[V]#_\f[R]s stack and also don\[aq]t leak out after the end of the
+containing table
 .SH FUNCTIONS
 .SS \f[V]fn\f[R] function
 .PP
@@ -203,7 +212,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]\[*l]\f[R] nil-checked function
+.SS \f[V]lambda\f[R]/\f[V]λ\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 +242,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]\[*l]\f[R] form is an alias for \f[V]lambda\f[R] and behaves
+The \f[V]λ\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]\[*l]\f[R] and \f[V]macro\f[R]
+The \f[V]fn\f[R], \f[V]lambda\f[R], \f[V]λ\f[R] and \f[V]macro\f[R]
 forms accept an optional docstring.
 .IP
 .nf
@@ -246,7 +255,7 @@ forms accept an optional docstring.
   \[dq]Print the sum of x and y\[dq]
   (print (+ x y)))
 
-(\[*l] pxyz [x ?y z]
+(λ 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]

man/man7/fennel-tutorial.7

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 2.17.1.1
+.\" Automatically generated by Pandoc 3.1.2
 .\"
 .\" 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-06-23" "fennel 1.5.0" "Getting Started with Fennel"
+.TH "fennel-tutorial" "7" "2024-06-28" "fennel 1.5.1-dev" "Getting Started with Fennel"
 .hy
 .SH NAME
 .PP

reference.md

@@ -106,6 +106,12 @@ Certain prefixes are expanded by the parser into longhand equivalents:
 A semicolon and everything following it up to the end of the line is a
 comment.
 
+Expressions (literals and tables) can be ignored by the parser if preceded by `#_` (like in Clojure):
+
+* `[1 #_ {:a :b} 3 #_ #_ (+ 4 5) 6 7 #_]` expands to `[1 3 7]`
+
+`#_`s stack and also don't leak out after the end of the containing table
+
 ## Functions
 
 ### `fn` function