tbls/README.md

# tbls

for expanding random table entries

1. [Requirements](#requirements)
2. [Installing](#installing)
3. [Architecture](#architecture)
4. [Tutorial](#tutorial)
   * [Random Selections](#random-selections)
   * [Expansion](#expansion)
   * [Filters](#filters)
5. [Roadmap](#roadmap)
6. [Resources](#resources)

## Requirements

- Fennel 1.3.1 on PUC Lua 5.4
- gnu recutils 1.9: for querying metadata
- just 1.34.0: just a task runner

## Installing

You can run the script: `fennel src/main.fnl`.

Or you can compile a binary and use that.
See `just compile`.

There is also a vim plugin for the `tbls` format.
See `vim-tbls/README.md`.

## Architecture

- `src/story.fnl`: core of the project. where all the file handling and text parsing happens
- `src/main.fnl`: wrapper for story.fnl. the ui.
- `src/filter.fnl` logic for applying filters to strings
- `lib/*.fnl` libraries and helper functions

![Autogenerated Dependency Graph][deps]

[deps]: doc/deps.png "Autogenerated Dependency Graph"

## Tutorial

### Random Selections

At its most basic, `tbls` selects a random element from a table.

Suppose you have a few tables:

```
:: suit
Hearts
Bells
Whistles
Cups
Knives
Shovels

:: card
Ace
One
Two
[...]
Queen
King
Beast
```

`tbls` might return "Whistles" from suit.
Or "Two" from card.

### Expansion

But wait there's more.
`tbls` will also expand certain text found in a table entry.

Let's add another table:

```
:: draw
[card] of [suit]
```

When you place the name of a table in `[squarebrackets]`,
then `tbls` views that as a placeholder
for a random item from that table.
It will expand that text.
So 'draw' might end up being "Thief of Shovels"
or "Twelve or Cups".

### Filters

`tbls` can run arbitary filters on text after expanding it.
Example filters can be found in `lib/filters.fnl`.

To apply filters,
dot-chain them at the end
of a table reference.

Consider the following tables:

```
:: origin
Evelyn eats one [fruit.c]
Evelyn eats many [fruit.c.s]

:: fruit
banana
apple
pear
```

`s`, `plural`, and `pluralize`
are all different ways
to call the 'plural' filter function.
`c` is 'capitalize.'

Example output:

```
Evelyn eats one Pear
Evelyn eats many Bananas
```


## Roadmap

- [x] random table entries (ADDED in vHydrogen)
- [x] expanding macros (ADDED in vHydrogen)
- [x] table files plugin: syntax highlighting + folding (ADDED vHelium)
- [x] expansion filters (ADDED vHelium)
- [ ] table context

## Resources

inspired heavily by tracery:
<https://github.com/galaxykate/tracery>

and this list-to-html geneator from slight adjustments:
<https://slightadjustments.blogspot.com/p/generator.html>

but also paper elemental's:
<https://paperelemental.blogspot.com/p/list-to-html-generator.html>

and perchance:
<https://perchance.org/welcome>