tbls/README.md

147 lines
2.7 KiB
Markdown

# 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>