157 lines
5.1 KiB
Markdown
157 lines
5.1 KiB
Markdown
# 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.
|