a230e2d72052f55d78484656b5bbcc99c8b5158b — Phil Hagelberg 2 months ago cd1af64
Improve reference and api to mention fennel.view etc.
5 files changed, 34 insertions(+), 16 deletions(-)

M api.md
M changelog.md
M lua-primer.md
M reference.md
M src/fennel.fnl
M api.md => api.md +14 -5
@@ 48,17 48,13 @@ Takes these additional options:

* `readChunk()`: a function that when called, returns a string of source code.
  The empty is string is used as the end of source marker.
* `pp`: a pretty-printer function to apply on values.
* `pp`: a pretty-printer function to apply on values (default: `fennel.view`).
* `onValues(values)`: a function that will be called on all returned top level 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.

`src/fennel/view.fnl` will produce output that can be fed back into Fennel
(other than functions, coroutines, etc) but you can use a 3rd-party
pretty-printer that produces output in Lua format if you prefer.

If you don't provide `allowedGlobals` then it defaults to being all
the globals in the environment under which the code will run. Passing
in `false` here will disable global checking entirely.

@@ 290,6 286,19 @@ 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.

## Serialization

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, functions, and userdata though.

print(fennel.view({abc=123}[, options])
{:abc 123}

## Work with docstrings and metadata

*(Since 0.3.0)*

M changelog.md => changelog.md +2 -3
@@ 1,12 1,11 @@
# Summary of user-visible changes

Backwards-incompatible changes are **marked in bold**.
Changes are **marked in bold** which could result in backwards-incompatibility.

## 0.9.3 / ???
## 0.10.0 / ???

* Deprecate `pick-args` macro
* Support repl completion on methods inside tables
* Change how auto-gensym prefixes are calculated in compilation output
* Add separate `FENNEL_MACRO_PATH` environment variable for `fennel.macro-path`
* **Add separate `fennel.macro-path` for searching for macro modules**
* Fix a bug with strict global checking in macro modules

M lua-primer.md => lua-primer.md +1 -1
@@ 134,7 134,7 @@ multiple values. Note that `table.unpack` is just `unpack` in Lua 5.1.
You can explore a module by evaluating it in the REPL to display all
the functions and values it contains.

* `math`: all your standard math functions including trig and `random`
* `math`: all your standard math functions, trig, pseudorandom generator, etc
* `string`: all common string operations (except `split` which is absent)
* `os`: operating system functions like `exit`, `time`, `getenv`, etc

M reference.md => reference.md +16 -6
@@ 9,6 9,10 @@ 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.

Fennel source code should be UTF-8-encoded text, although currently
only ASCII forms of whitespace and numerals are supported.

@@ 150,7 154,7 @@ greater than the argument it is passed.

*(Since 0.4.0)*

Discard all values after the first n when dealing with multi-values (`...`)
Discards 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.

@@ 512,7 516,7 @@ Supports destructuring and multiple-value binding.

### `tset` set table field

Set the field of a given table to a new value. The field name does not
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, even those bound
with `local` and `let`.

@@ 596,7 600,7 @@ Example:

### `each` general iteration

Run the body once for each value provided by the iterator. Commonly
Runs 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.

@@ 772,6 776,8 @@ Example:

### `collect`, `icollect` table comprehension macros

*(Since 0.8.0)*

The `collect` macro takes a "iterator binding table" in the format
that `each` takes, and an expression that produces key-value pairs,
and runs through the iterator, filling a new table with the key-value

@@ 814,7 820,9 @@ clause for early termination.

### `accumulate` iterator accumulation

Run through an iterator and performs accumulation, similar to `fold`
*(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

@@ 834,6 842,8 @@ Example:
;; -> 2.5

The `:until` clause is also supported here for early termination.

### `values` multi-valued return

Returns multiple values from a function. Usually used to signal

@@ 965,7 975,7 @@ subsequent forms are evaluated solely for side-effects.
(include :my.embedded.module)

Load Fennel/Lua module code at compile time and embed in the compiled
Loads Fennel/Lua module code at compile time and embeds it in the compiled
output. The module name must be a string literal that can resolve to
a module during compilation.  The bundled code will be wrapped in a
function invocation in the emitted Lua and set on

@@ 987,7 997,7 @@ 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 smaller 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.
cannot be exported at the bottom of a module like functions and other values.

### `import-macros` load macros from a separate module

M src/fennel.fnl => src/fennel.fnl +1 -1
@@ 130,7 130,7 @@
            : view
            : eval
            :dofile dofile*
            :version :0.9.3-dev
            :version :0.10.0-dev
            : repl
            : syntax
            ;; backwards-compatibility aliases