📝🗄️

Dozens B. McCuzzins 2024-08-04 22:03:38 -06:00
parent 7ec9978919
commit f6729fe7c1
13 changed files with 275 additions and 46 deletions

119
README.md
View File

@ -2,18 +2,126 @@
for expanding random table entries
1. [Requirements](#requirements)
2. [Installing](#installing)
3. [Tutorial](#tutorial)
* [Random Selections](#random-selections)
* [Expansion](#expansion)
* [Filters](#filters)
4. [Roadmap](#roadmap)
5. [Resources](#resources)
## Requirements
Built with
Fennel 1.3.1 on PUC Lua 5.4
- Fennel 1.3.1 on PUC Lua 5.4
- gnu recutils 1.9: for querying metadata
- just 1.34.0: just a task runner
## Usage
## 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)
@ -27,7 +135,10 @@ See `just compile`.
inspired heavily by tracery:
https://github.com/galaxykate/tracery
and paper elemental's list-to-html generator:
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:

View File

@ -1,6 +1,6 @@
# Tutorial
## Tutorial
## Random Selections
### Random Selections
At its most basic, `tbls` selects a random element from a table.
@ -28,7 +28,7 @@ Beast
`tbls` might return "Whistles" from suit.
Or "Two" from card.
## Expansion
### Expansion
But wait there's more.
`tbls` will also expand certain text found in a table entry.
@ -47,10 +47,10 @@ It will expand that text.
So 'draw' might end up being "Thief of Shovels"
or "Twelve or Cups".
## Filters
### Filters
`tbls` can run arbitary filters on text after expanding it.
Example filters can be found in `src/flib.fnl`.
Example filters can be found in `lib/filters.fnl`.
To apply filters,
dot-chain them at the end
@ -60,8 +60,8 @@ Consider the following tables:
```
:: origin
Evelyn eats one [fruit]
Evelyn eats many [fruit.s]
Evelyn eats one [fruit.c]
Evelyn eats many [fruit.c.s]
:: fruit
banana
@ -72,10 +72,11 @@ 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 one bananas
Evelyn eats one Pear
Evelyn eats many Bananas
```

BIN
doc/deps.png 100644

Binary file not shown.

After

Width:  |  Height:  |  Size: 35 KiB

65
doc/src/readme.m4 100644
View File

@ -0,0 +1,65 @@
changequote(<!,!>)dnl Or else `code blocks` confuse m4
# 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"
include(<!doc/Tutorial.md!>)
## 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>

View File

@ -1,42 +1,85 @@
set quiet
# show all recipes
default:
just --list --unsorted
# compile binary
[group('build')]
compile:
fennel --compile-binary src/main.fnl tbls /usr/local/lib/liblua.a /usr/local/include/lua5.4
alias build := compile
# run test file
_test-story:
fennel test/story.test.fnl
# test main
_test-main:
for i in $(seq 1 10); do fennel src/main.fnl -i test/morpheme-word-epithet.txt -k name; done
# run all tests
test: _test-main _test-story
# bump version
bump:
#!/usr/local/bin/bash
currname=$(recsel doc/meta.rec -P version)
currnum=$(recsel doc/versions.rec -e "Name = '$currname'" -P Number)
nextnum=$((currnum + 1))
nextname=$(recsel doc/versions.rec -e "Number = $nextnum" -P Name)
echo "Bumping version from $currname to $nextname:"
recset doc/meta.rec -f version -s $nextname
recset doc/meta.rec -f updated -S $(gdate +'%Y-%m-%d')
recsel doc/meta.rec
# show full metadata
meta:
awk 'FNR==1{print ""}{print}' doc/*.rec | recsel -t meta -j version
# install all
[group('install')]
install: install-plugin install-binary
# install vim plugin
[group('install')]
install-plugin:
cp -r vim-tbls/* ~/.config/nvim
# install binary
[group('install')]
install-binary: compile
cp tbls ~/bin
# run all tests
[group('test')]
test: test-main test-story
# run test file
[group('test')]
test-story:
fennel test/story.test.fnl
# test main
[group('test')]
test-main:
for i in $(seq 1 10); do fennel src/main.fnl -i test/morpheme-word-epithet.txt -k name; done
# build all docs
[group('docs')]
docs: deps readme
# build readme
[group('docs')]
readme:
m4 doc/src/readme.m4 > README.md
# create dependency graph
[group('docs')]
deps:
ag require src \
| sed 's/\(.*\.fnl\).*require :\([^\.]*\)\.\([^)]*\)).*/"\1" -> "\2\/\3.fnl"/' \
| awk 'BEGIN { print "digraph {" } { print } END { print "}" }' \
| dot -Tpng \
> doc/deps.png
# create dependency graph but sixel
[group('docs')]
depsxl:
ag require src \
| sed 's/\(.*\.fnl\).*require :\([^\.]*\)\.\([^)]*\)).*/"\1" -> "\2\/\3.fnl"/' \
| awk 'BEGIN { print "digraph {" } { print } END { print "}" }' \
| dot -Tpng \
| magick - -geometry 800 sixel:-
# bump version
[group('docs')]
bump:
#!/usr/local/bin/bash
currname=$(recsel doc/v/meta.rec -P version)
currnum=$(recsel doc/v/versions.rec -e "Name = '$currname'" -P Number)
nextnum=$((currnum + 1))
nextname=$(recsel doc/v/versions.rec -e "Number = $nextnum" -P Name)
echo "Bumping version from $currname to $nextname:"
recset doc/v/meta.rec -f version -s $nextname
recset doc/v/meta.rec -f updated -S $(gdate +'%Y-%m-%d')
recsel doc/v/meta.rec
# show full metadata
[group('docs')]
meta:
awk 'FNR==1{print ""}{print}' doc/v/*.rec | recsel -t meta -j version

View File

@ -1,9 +1,9 @@
(local {: contains?} (require :src.table))
(local {:split split-full} (require :src.string))
(local {: contains?} (require :lib.table))
(local {:split split-full} (require :lib.string))
(local split (partial split-full "[^%.]*"))
(fn filter [s]
(let [filters (require :src.flib)
(let [filters (require :lib.filters)
[str & funs] (split s)]
(var res str)
(each [_ f (ipairs funs)]

View File

@ -8,6 +8,7 @@
(print)
(print "Basic Options:")
(print " -h|--help print this message and exit")
(print " -v|--version print version and exit")
(print " -i|--input <file> name of input file")
(print " -k|--origin-table-key <key> name of a table in the input file")
(print " -s|--origin-table-string <string> a string template")
@ -28,6 +29,12 @@
(do
(show-help)
(os.exit 0))
(where [a] (or (= a "-v") (= a "--version")))
(let [handle (io.popen "recsel doc/meta.rec -P version")
result (handle:read "*a")]
(print result)
(handle:close)
(os.exit 0))
(where [a input] (or (= a "-i") (= a "--input")))
(set opts.input input)
(where [a key] (or (= a "-k") (= a "--origin-table-key")))

View File

@ -1,8 +1,8 @@
;; helper funs
(local tbl (require :src.table))
(local tbl (require :lib.table))
(local {: filter} (require :src.filter))
(local {:split _split} (require :src.string))
(local split (partial _split "[^%.]*"))
(local split
(partial (. (require :lib.string) :split) "[^%.]*"))
(fn lines [filename callback]
(case (pcall #(with-open [file (io.open filename)] (each [line (file:lines)] (callback line))))
@ -58,7 +58,9 @@
str
(do
(assert (tbl.has-key? corpus word)
(string.format "Error trying to expand \"%s\". Corpus does not contain a table called \"%s\"" str word))
(string.format
"Error trying to expand \"%s\". Corpus does not contain a table called \"%s\""
str word))
(let [next-str (string.format "%s%s%s"
(string.sub str 1 (- i 1))
(if (length fs)