147 lines
2.7 KiB
Markdown
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>
|