motdmaker/README.md

# MOTD Maker - motd

`motd` is a command line utility which outputs a (semi) intelligible, randomly generated message to your standard output.

## Build and Install
##### Requirements
`git`, `rust`/`rustup`/`cargo`
##### Arch Linux
`sudo pacman -S git rust`
##### Ubuntu/Debian
`sudo apt install git rust`

#### Install
```bash
git clone https://code.lampnet.io/candle/motdmaker
cd motdmaker && cargo build --release
sudo mv target/release/motd /usr/local/bin/
```
You may remove the cloned directory.

## Usage

`motd` is best when customized with your own word pools and templates.

`motd` will look for a `$HOME/.motdrc`, `$XDG_CONFIG_HOME/.motdrc`, or `$XDG_CONFIG_HOME/motd/motdrc` file and use the settings there as defaults when running `motd` with no flags. If somehow `motd` is configured in a way that would result in an empty word list, it will fallback to the built in defaults.

```
# Example motdrc
# This file can be placed at:
#   ~/.motdrc
#   $XDG_CONFIG_HOME/.motdrc
#   $XDG_CONFIG_HOME/motd/motdrc
#   (or ~/.config/motd/motdrc if XDG_CONFIG_HOME is not set)

# Word lists - add custom words to the defaults
adjective = ["mystical", "ancient", "shimmering", "ethereal"]
noun = ["artifact", "prophecy", "wanderer", "sanctuary"]
verb = ["whispers", "echoes", "illuminates", "beckons"]
adverb = ["mysteriously", "gracefully", "eternally", "silently"]
location = ["in the forgotten realm", "beneath the starlit sky", "within the crystal caves"]

# Template customization
# template = "The {adjective} {noun} {verb} {adverb} {location}."

# Behavior settings
# Set to true to replace default word lists instead of extending them
replace = false
# Convert output to lowercase
lowercase = false
# Convert output to uppercase
uppercase = false

# Text processing
# Words to remove from output
strip = [".", ":"]
# Delimiter between words (default is space)
delimiter = "."
# Maximum length of generated message
cut_off = 100

# Write output to file instead of stdout, WARNING: will overwrite
# output = "$HOME/.MOTD"

# Note: CLI arguments will override these RC file settings 
```

### Word Files

You can also create custom word files inside of `$XDG_CONFIG_HOME/motd/`:
```
$XDG_CONFIG_HOME/motd/
|-nouns
|-adjectives
|-adverbs
|-locations
|-templates
```
You can dump the default word banks into their respectice word file and disable/add entries individually: 

```
mkdir -p $XDG_CONFIG_HOME/motd
motd -p templates > $XDG_CONFIG_HOME/motd/templates
motd -p nouns > $XDG_CONFIG_HOME/motd/nouns
motd -p adjectives > $XDG_CONFIG_HOME/motd/adjectives
motd -p adverbs > $XDG_CONFIG_HOME/motd/adverbs
motd -p locations > $XDG_CONFIG_HOME/motd/locations
```
Words are separated by line, meaning you can have multiple words treated as a single unit.\
Re-defining a word will not add an additional entry to the word pool.
Lines beginning with a `!` are actively removed from their respective word pool.\
Lines beginning with a `#` are ignored as comments.
Lines with the format `$()` can be `bash` expressions which are evaluated at runtime.\
Example: `nouns` file
```
# I'm really scared of these
!ocean
ocean
# The previous ocean will still not be added to the word pool
$(date +%H:%M)
```

Now running `motd` will remove 'ocean' from the noun word pool, while also adding the possibilty of running `date +%H:%M` when replacing a template's noun, which will give the current time of day.

```
motd -r # -r is to force the added nouns to be used, for this example
When the moon rises, the mighty 19:58 shines in the misty valley.
```

Word files don't have to live in your configuration directory, you can pass `motd` a custom `--configdir/-c`.

### Templates

Templates are separated by line. They can have as many or as few word types as you'd like.
* `{noun}` or `{n}`
* `{adjective}` or `{a}`
* `{verb}` or `{v}`
* `{adverb}` or `{d}`
* `{location}` or `{l}`

Bash expressions (`$()` form) in the `templates` file are evaluate at runtime.

## Examples

```
❯ motd -U -s . -s : -s , -D .
THE.ETERNAL.PHOENIX.BLOOMS.SILENTLY.WHERE.SHADOWS.DANCE
```
`-U`: Capitalizes output\
`-s`: Strips given character from generation\
`-D`: Change delimiter from `space`\
Note that the stripping of characters occurs first, then the delimiter is replaced with the argument.

```
❯ motd -v opens --noun book -n chair -d weirdly -t "A {n} {v} the {noun} {d}" -r
A chair opens the book weirdly
```
`--noun\-n\-v\-d`: Single word by type, to add to the word pool. Can be specified multiple times.\
`-t`: The template to base the message off. Using `-t` will force the template used to be argument given.\
`-r`: Only new words, passed as arguments, or from configuration files, will be used.

```
❯ motd -t "The {n} and the {noun} and the {n}."
The wizard and the knight and the ocean.
```
`-t`: Force template to be used.\
`--noun/-n`: Adding multiple noun positions and nothing else.

```
❯ motd -C 20 2>output.txt
❯ echo $?
1
❯ cat output.txt
Error: CutOffExceeded { attempts: 100, cut_off: 20 }
```
`-C`: Specify a max amount of characters the message can be.
`motd` exits with `1` when it is unable to generate a valid message. Either the template pool is too diluted, or you create a valid template within the confines you want.