# 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]: ---- *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`]: ## 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 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*