tbls

for expanding random table entries

1. Requirements
2. Installing
3. Architecture
4. Tutorial
   • Random Selections
   • Expansion
   • Filters
5. Roadmap
6. 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

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

• random table entries (ADDED in vHydrogen)
• expanding macros (ADDED in vHydrogen)
• table files plugin: syntax highlighting + folding (ADDED vHelium)
• 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