# Bash Template Command *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. Obviously, not all of this is needed for many Bash scripts. Just remove what you do not need or want. If you want to keep a command but hide it from users just add another underscore to the prefix which turns it into a hidden command, which will not be included in help documentation and tab completion, but will still be there. The `readme` command (which generates this `README.md` file is a good candidate for this.) Be sure to check out the builtin and utility functions. Some of these can be removed as well if you really want. ## Naming Conventions * Name repos containing single bash commands with `cmd-` * Name template repos beginning with `template-` * Start command functions with `command_` to be completed * Start command functions with `command__` to not be completed ## Dependencies Required: * Bash 4+ Optional: * `pandoc` - for rich help docs * `jq` - for `json` and anything that uses it ## Justification Bash is the dominate 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`]: ## 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 dir cmd config path [file] cmd config edit [file] ``` 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) 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. ## Convert to JSON String ``` cmd json STRING cmd json <<< STRING cmd json < FILE cmd json < <(COMMAND) ``` Converts input into JSON string using `jq` (if found) containing only escaped (`\n`) line returns. ## 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 `usage` Command Displays a summary of usage. ---- *Autogenerated Fri Aug 27 09:16:17 AM EDT 2021*