tbls/doc/Tutorial.md

# 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 `src/flib.fnl`.

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

Consider the following tables:

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

:: fruit
banana
apple
pear
```

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

Example output:

```
Evelyn eats one pear
Evelyn eats one bananas
```