# spout

A terminal application for generating nonsense.

## Installation

1. Clone this repo
2. `cargo build`

## Usage

### Command line options

```
Usage: spout [OPTIONS] <DIRECTORY>

Arguments:
  <DIRECTORY>  Path to data directory

Options:
  -n, --sentences <N_SENTENCES>  Number of sentences to generate [default: 1]
      --unique                   Don't re-use entries in data files (program will fail upon running out)
  -h, --help                     Print help
```

### Template syntax

In order to generate a sentence, the program will fill in gaps in a sentence template.
Every randomized part of a sentence is surrounded on both sides by `%%`.
Between these markers is some kind of definition of how the gap should be filled:

```
Direct:   %%foo%%     - choose a word from the 'foo' category
Variable: %%?foo%%    - choose a word from the category assigned to the 'foo' variable
Multiple: %%foo|bar%% - choose a word from either the 'foo' or 'bar' category
```

Categories are sets of words/phrases that are randomly chosen from during sentence generation.

Variables are randomly assigned a category from all available categories, and will be interpreted as that category throughout a sentence.
This is useful for when you want to include multiple words from the same category, but don't care which one.

Separating category names and variables with a `|` will choose between the given options. This can be used when you want to pick a word from "foo" or "bar", but not "baz".

### Data files

This program requires a directory of text files in a particular format in order to work.
The directory can be anywhere on your system that you have read access.
This directory must contain a text file named `sentences.txt`.
It must also contain a text file for every template category that is used in the sentences file.
The program does not enforce the latter restriction until it attempts to generate sentences, crashing if a category file is missing.

The sentences file must contain exactly one sentence template per line.
Each category file also separates words by line.
Indeed, "words" can actually be phrases with spaces and punctuation (but not line breaks).
In both types of file, empty lines are ignored.

### Examples

These examples suppose the following files and sentence templates.

Example directory:
```
bar.txt
baz.txt
foo.txt
sentences.txt
```

Example templates:
```
I think %%foo%% is pretty neat.
I think %%bar%% is kind of lame.
%%foo%% is certainly better than %%bar%%.
I would take %%foo|baz%% over %%bar%% any day.
%%?x%% and %%?x%% are certainly things that exist.
```

## Planned features / TODO

* [ ] Re-implement argument parsing without `clap`
* [ ] Special variable syntax for picking from a category but not saving it: `%%?%%`
* [ ] Special syntax to choose between literal values rather than a category
* [ ] Back-reference system to capture and repeat generated phrases
* [ ] Learn how Markov chains work