283 lines
8.8 KiB
Markdown
283 lines
8.8 KiB
Markdown
# Bash Template Command
|
|
|
|
*I no longer use this using [Bonzai][] instead. But it does have some good bash tricks to keep around including self-completion.*
|
|
|
|
[Bonzai]: <https://github.com/rwxrob/bonzai>
|
|
|
|
----
|
|
|
|
*This `README.md` is autogenerated.*
|
|
|
|
This is a GitHub template repo that will be copied instead of forked to
|
|
create a new Bash command with a command something like this:
|
|
|
|
```
|
|
gh repo create rwxrob/mycmd -p rwxrob/template-bash-command
|
|
```
|
|
|
|
This `cmd` inside can then be renamed and finished.
|
|
|
|
## Naming Conventions
|
|
|
|
* Name repos containing single bash commands with `cmd-`
|
|
* Name template repos beginning with `template-`
|
|
* Start command functions with `x.` to be completed
|
|
* Name `CONF` accessors with `x.` and full path
|
|
* Use dot (`.`) pathing in `CONF` key names
|
|
|
|
Think of `x` as in "executable" command.
|
|
|
|
> ⚠️
|
|
> Note that all versions of Vim current have a bug that does not allow
|
|
> dot (`.`) to be included in the function name even though it is
|
|
> explicitly allowed by bash. So you may have to add `.` to your
|
|
> `/usr/share/vim/vim82/syntax/sh.vim` file anywhere a function name
|
|
> expression is defined. I have yet to isolate it out and override it in
|
|
> my own `.vimrc`. It is a minimal edit.
|
|
|
|
## Builtins and Utilities
|
|
|
|
A number of builtin and frequently used utility functions have been
|
|
included for convenience. These save developers from adding other
|
|
moronic things like `sed` and `awk` subprocesses. Obviously, not all of
|
|
this is needed for many Bash scripts. Just remove what you do not need
|
|
or want.
|
|
|
|
### `_initialize`
|
|
|
|
The `_initialize` function is meant to contain initialization code and
|
|
be placed at the beginning of the script to be found easily even though
|
|
it is called at the bottom of the script (as bash requires). It is
|
|
passed the arguments that are passed to the script itself. This function can be omitted.
|
|
|
|
### `_alternatives`
|
|
|
|
The `_alternatives` function (usually placed after `_initialize`
|
|
provides a hook for dealing with alternative arguments to those that
|
|
identify commands (`x.*`). If the first argument to the script does not
|
|
match a command function then this function will be called before the
|
|
default `x.usage` command allowing shortcuts and other argument
|
|
alternatives and intelligent sensing of what command function is wanted
|
|
by simply examining the argument list. This can be useful when you wish
|
|
to provide shortcuts for longer commands but do not want to clutter the
|
|
command usage and completion list. For example, `zet dex.titles` could
|
|
be trapped in `_alternatives` to call `zet titles`.
|
|
|
|
### `_have`
|
|
|
|
Returns true (0) if the first argument exists as an executable in the
|
|
current `PATH`. Otherwise, return false (1).
|
|
|
|
### `_checkdep`
|
|
|
|
Checks that the first argument exists as an executable in the current
|
|
`PATH`. If so, returns true (0). If not, prints a generic error message
|
|
in English and returns false (1). The "progressive enhancement" design
|
|
principle requires minimal functionality using what is available and
|
|
progressively upgrading based on what is detected.
|
|
|
|
### `_newest`
|
|
|
|
Uses `ls` to return the newest file or directory in the specified
|
|
directory.
|
|
|
|
### `_trim`
|
|
|
|
Removes all whitespace (`[:space:]`) from the beginning and ending
|
|
of a string without invoking a subprocess.
|
|
|
|
### `_filter`
|
|
|
|
Reads the first argument or each line of standard input passing
|
|
each individually as the first argument to the calling function one at
|
|
a time. The UNIX philosophy requires all commands be filters whenever possible.
|
|
|
|
### `_buffer`
|
|
|
|
Reads the first argument or all lines of standard input and then
|
|
passes them to the calling function as the first argument. The UNIX philosophy requires all command be filters whenever possible.
|
|
|
|
### `_reduce`
|
|
|
|
Takes the name of an array and a bash extended regular expression
|
|
and prints only the array entries that match, one to a line suitable for
|
|
converting back into an array with `IFS=$'\n'` or just as an in-memory
|
|
`grep` replacement.
|
|
|
|
### `_jsonstr`
|
|
|
|
Encodes first argument or all standard input into a single line of JSON text. This function depends on the `jq` command.
|
|
|
|
### `_urlencode`
|
|
|
|
Encodes the first argument or all standard input using standard URL
|
|
encoding suitable for passing to `curl` or whatever. This function has
|
|
no external dependencies.
|
|
|
|
## Dependencies
|
|
|
|
Required:
|
|
|
|
* Bash 4+
|
|
|
|
Optional:
|
|
|
|
* `pandoc` - for rich help docs
|
|
* `jq` - for `json` and anything that uses it
|
|
|
|
## Justification
|
|
|
|
Bash is the dominant shell scripting language and the official default
|
|
Linux interactive shell, which reduces cognitive overhead; every command
|
|
line *is* a line of code that could be put into script as is. Bash
|
|
scripts are at the core of cloud, containers, and Kubernetes. Bash 4+
|
|
with its associative array support, powerful regular expressions, and
|
|
multiple ways of feeding data to loops easily covers the needs
|
|
previously requiring Python and Perl scripts. Bash scripts are also much
|
|
more powerful, safer, flexible, and performant than POSIX shell or Zsh.
|
|
|
|
## Guidelines
|
|
|
|
* Write GitHub Flavored Markdown only
|
|
* Use present tense ("outputs" over "will output")
|
|
* Prefer term "output" and "display" over ~~print~~
|
|
* Follow the [naming conventions](#naming-conventions)
|
|
* Use the official bash path: `#!/bin/bash`
|
|
* Use of `#!/usr/bin/bash` is outdated
|
|
* Using `#!/usr/bin/env bash` introduces unnecessary risk
|
|
* Explicitly export `PATH` in script when possible
|
|
* Always check script with [`shellcheck`] before releasing
|
|
* Always use `bc` for *any* floating point math
|
|
|
|
[`shellcheck`]: <https://www.shellcheck.net>
|
|
|
|
## Security
|
|
|
|
This script is expected to be installed for a specific user and only
|
|
ever run by that user. No additional security vetting for running as an
|
|
untrusted user has been done.
|
|
|
|
## Legal
|
|
|
|
Copyright 2021 Rob Muhlestein <rob@rwx.gg>
|
|
Released under Apache-2.0 License
|
|
Please mention rwxrob.tv
|
|
|
|
## The `bar` Command
|
|
|
|
```
|
|
cmd bar
|
|
```
|
|
|
|
Bar the things.
|
|
|
|
## The `config` Command
|
|
|
|
```
|
|
cmd config
|
|
cmd config KEY
|
|
cmd config KEY VALUE
|
|
cmd config KEY ""
|
|
cmd config keys
|
|
cmd config val[ues]
|
|
cmd config dir[ectory]
|
|
cmd config path [file]
|
|
cmd config edit [file]
|
|
cmd config del[ete]
|
|
```
|
|
|
|
The `config` command is for reading, writing, and displaying standard
|
|
open desktop configuration properties. Pass an empty string to delete
|
|
a property.
|
|
|
|
### Arguments
|
|
|
|
With no arguments outputs all the currently cached configuration
|
|
settings.
|
|
|
|
With a single KEY argument fetches the value for that key and outputs
|
|
it unless it is one of the following special (reserved) key names:
|
|
|
|
* `dir*` full path to config directory
|
|
* `path` full path to specific config file (default: `values`)
|
|
* `edit` opens config file in editor (default: `editor` or `$EDITOR)
|
|
* `keys` output the configuration keys, one per line
|
|
* `val*` output the configuration values, one per line
|
|
* `del*` if key argument then delete a specific key, otherwise prompt
|
|
|
|
With more than one argument the remaining arguments after the KEY will
|
|
be combined into the VALUE and written to a `values` file in the
|
|
configuration directory.
|
|
|
|
### Configuration Directory
|
|
|
|
The configuration directory path relies on the following environment
|
|
variables:
|
|
|
|
* `EXE` - defaults to name of currently running command (cmd)
|
|
* `HOME` - checked for `$HOME/.config/$EXE/values`
|
|
* `XDG_CONFIG_HOME` - overrides `$HOME/.config`
|
|
* `CONFIG_DIR` - full path to directory containing `values` file
|
|
|
|
The `CONFIG_DIR` always takes priority over anything else if set, but is
|
|
never implied. If the directory does not exist it will be created the
|
|
first time a value is set.
|
|
|
|
### Configuration `values` File Format
|
|
|
|
The file (which is almost always located at
|
|
`~/.config/cmd/values`) uses the simplest possible format to
|
|
facilitate standard UNIX parsing and filtering with any number of
|
|
existing tools (and no `jq` dependency).
|
|
|
|
* One KEY=VALUE per line
|
|
* KEYs may be anything but the equal sign (`=`)
|
|
* VALUEs may be anything but line returns must be escaped
|
|
|
|
Note that this is *not* the same as Java properties and other similar
|
|
format. It is designed for ultimate simplicity, efficiency, and
|
|
portability.
|
|
|
|
## The `foo` Command
|
|
|
|
Foos things.
|
|
|
|
## The `help` Command
|
|
|
|
```
|
|
cmd help [COMMAND]
|
|
```
|
|
|
|
Displays specific help information. If no argument is passed displays
|
|
general help information (main). Otherwise, the documentation for the
|
|
specific argument keyword is displayed, which usually corresponds to
|
|
a COMMAND name (but not necessarily). All documentation is written in
|
|
GitHub Flavored Markdown and will displayed as a web page if `pandoc`
|
|
and `$HELP_BROWSER` are detected, otherwise, just the Markdown is sent
|
|
to `$PAGER` (default: more).
|
|
|
|
Also see `readme` and `usage` commands.
|
|
|
|
## Generate `README.md` File
|
|
|
|
```
|
|
cmd readme > README.md
|
|
```
|
|
|
|
The `readme` command will output the embedded help documentation in raw
|
|
GitHub Flavored Markdown suitable for use as a `README.md` file on
|
|
GitHub or similar hosting service.
|
|
|
|
## The `some.config.setting` Command
|
|
|
|
Get and set `some.config.setting`.
|
|
|
|
## The `usage` Command
|
|
|
|
Displays a summary of usage.
|
|
|
|
----
|
|
|
|
*Autogenerated Sat Dec 18 11:13:17 AM EST 2021*
|
|
|