template-bash-command/README.md

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, but anything with more than two subcommands will benefit from the builtin tab completion, embedded Markdown help documentation support, and included functions (usage, _filter, _buffer, _have, etc.)

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
• 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

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 ""

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. The special dir KEY is reserved and always outputs the full path to the current configuration directory containing the values file. The special path KEY is reserved and always outputs the full path to the values file itself.

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 Wed Aug 25 12:52:34 AM EDT 2021