# spout A terminal application for generating nonsense. ## Installation 1. Clone this repo 2. `cargo build` ## Usage ### Command line options ``` Usage: spout [OPTIONS] Arguments: Path to data directory Options: -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 Random: %%?%% - choose a word from any 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 Literal: %%"foo%% - choose the literal string following the double quote ``` 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". Literal values are simply copied into the final sentence verbatim. Note that these values only begin with a double quote (single quotes are not permitted) and do not terminate with an additional double quote. The primary use case of literal values is to avoid having to create a new category file for only a handful of options you might not use very often. ### 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. %%?%%: kid tested, mother approved. My favorite text editor is %%"vi|"emacs%%. ``` ## Planned features / TODO * ~~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