deprecate

They are just too risky to promote because people might create
dependencies on them. Something is either exported and public or it's
not.

README.md

@@ -1,5 +1,11 @@
 # 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
@@ -15,15 +21,19 @@ This `cmd` inside can then be renamed and finished.
 
 * Name repos containing single bash commands with `cmd-`
 * Name template repos beginning with `template-`
-* Start command functions with `x_` to be completed
+* Start command functions with `x.` to be completed
-* Start command functions with `x__` to not be completed
+* Name `CONF` accessors with `x.` and full path
+* Use dot (`.`) pathing in `CONF` key names
 
-Think of the `x` as in "executable" command.
+Think of `x` as in "executable" command.
 
-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
+> Note that all versions of Vim current have a bug that does not allow
-will not be included in help documentation and tab completion, but will
+> dot (`.`) to be included in the function name even though it is
-still be there. 
+> 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
 
@@ -37,7 +47,21 @@ or want.
 
 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 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`
 
@@ -127,6 +151,12 @@ more powerful, safer, flexible, and performant than POSIX shell or Zsh.
 
 [`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>  
@@ -248,5 +278,5 @@ Displays a summary of usage.
 
 ----
 
-*Autogenerated Tue Aug 31 09:39:48 PM EDT 2021*
+*Autogenerated Sat Dec 18 11:13:17 AM EST 2021*
 

cmd

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # shellcheck disable=SC2016
 set -e
 # export PATH="/bin:/usr/bin:/usr/local/bin" # safer, if you can
@@ -11,12 +11,29 @@ set -e
 : "${EXE:="${0##*/}"}"
 
 declare -A HELP
-declare -A CONFIG
+declare -A CONF
+
+# declare black=$'\e[30m'
+# declare red=$'\e[31m'
+# declare green=$'\e[32m'
+# declare yellow=$'\e[33m'
+# declare blue=$'\e[34m'
+# declare magenta=$'\e[35m'
+# declare cyan=$'\e[36m'
+# declare white=$'\e[37m'
+# declare reset=$'\e[0m'
 
 _initialize() {
   : # put initialization code here
 }
 
+_alternatives() {
+  # put alternative argument possibilities here
+  if [[ $CMD = f ]];then
+    x.foo "$@"
+  fi
+}
+
 HELP[main]='
 # Bash Template Command
 
@@ -35,15 +52,19 @@ This `cmd` inside can then be renamed and finished.
 
 * Name repos containing single bash commands with `cmd-`
 * Name template repos beginning with `template-`
-* Start command functions with `x_` to be completed
+* Start command functions with `x.` to be completed
-* Start command functions with `x__` to not be completed
+* Name `CONF` accessors with `x.` and full path
+* Use dot (`.`) pathing in `CONF` key names
 
-Think of the `x` as in "executable" command.
+Think of `x` as in "executable" command.
 
-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
+> Note that all versions of Vim current have a bug that does not allow
-will not be included in help documentation and tab completion, but will
+> dot (`.`) to be included in the function name even though it is
-still be there. 
+> 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
 
@@ -57,7 +78,21 @@ or want.
 
 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 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`
 
@@ -147,6 +182,12 @@ more powerful, safer, flexible, and performant than POSIX shell or Zsh.
 
 [`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>  
@@ -155,7 +196,7 @@ Please mention rwxrob.tv'
 
 HELP[foo]='Foos things.'
 
-x_foo() {
+x.foo () {
   _filter "$@" && return $?
   echo "would foo: $*"
 }
@@ -168,31 +209,33 @@ HELP[bar]='
 
 Bar the things.'
 
-x_foo() {
+x.bar() {
   _buffer "$@" && return $?
   echo "would bar: $*"
 }
 
 HELP[some.config.setting]='Get and set `some.config.setting`.'
 
-x_some.config.setting() {
+x.some.config.setting() {
-  x_config some.config.setting "$@"
+  x.config some.config.setting "$@"
-}
-
-x__hidden() {
-  _filter "$@" && return $?
-  echo "would run _hidden: $*"
 }
 
 ############################## BOILERPLATE ###########################
 ## Everything from here to the end of file can be snipped and updated
 ## with latest from https://github.com/rwxrob/template-bash-command.
 
-# -------------------------- utility command -------------------------
+# ------------------------------- usage ------------------------------
 
-HELP[usage]='Displays a summary of usage.'
+HELP[usage]='
 
-x_usage() {
+```
+'"$EXE"' usage
+```
+
+Display all possible commands. Note that this is usually easier by
+simply using tab completion instead.'
+
+x.usage() {
   local -a cmds
   for c in "${COMMANDS[@]}"; do
     [[ ${c:0:1} =~ _ ]] && continue
@@ -202,7 +245,7 @@ x_usage() {
   printf "usage: %s (%s)\n" "$EXE" "${cmds[*]}"
 }
 
-# --------------------------- help command ---------------------------
+# ------------------------------- help -------------------------------
 
 HELP[help]='
 
@@ -221,18 +264,20 @@ to `$PAGER` (default: more).
 Also see `readme` and `usage` commands.
 '
 
-x_help() { 
+x.help() { 
-  local name="${1:-main}" title body
+  local name="${1:-main}" title body file
   title=$(_help_title "$name") || true
   if [[ -z "$title" ]]; then
-    body="${HELP[$name]}"
     title="$EXE $name"
-    [[ $name = main ]] && title="$EXE"
+    [[ $name == main ]] && title="$EXE"
+  fi
+  if [[ $name == main ]]; then
+    body=$(x.readme)
+    body=${body#*$title}
   else
     body="${HELP[$name]}"
-    body=${body#*$title}
   fi
-  local file="/tmp/help-$EXE-$name.html"
+  file="/tmp/help-$EXE-$name.html"
   if _have pandoc ; then
     if _have "$HELP_BROWSER" && [[ -t 1 ]] ;then
       pandoc -f gfm -s --metadata title="$title" \
@@ -257,7 +302,7 @@ _help_title() {
   done <<< "${HELP[$name]}"
 }
 
-# -------------------------- readme command --------------------------
+# ------------------------------ readme ------------------------------
 
 HELP[readme]='
 ## Generate `README.md` File
@@ -270,7 +315,7 @@ 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.'
 
-x_readme() {
+x.readme() {
   _trim "${HELP[main]}"
   echo
   while IFS= read -r name; do
@@ -282,44 +327,46 @@ x_readme() {
   echo -e "----\n\n*Autogenerated $(date)*\n"
 }
 
-# x_json() { _jsonstr "$@"; }
+# ------------------------------ config ------------------------------
-# x_urlencode() { _urlencode "$@"; }
-
-# -------------------------- config command --------------------------
 
 HELP[config]='
 
 ```
 '"$EXE"' config
 '"$EXE"' config KEY
-'"$EXE"' config KEY VALUE
+'"$EXE"' config.set KEY VALUE
-'"$EXE"' config KEY ""
+'"$EXE"' config.set KEY ""
-'"$EXE"' config keys
+'"$EXE"' config.keys
-'"$EXE"' config val[ues]
+'"$EXE"' config.values
-'"$EXE"' config dir[ectory]
+'"$EXE"' config.directory
-'"$EXE"' config path [file]
+'"$EXE"' config.path [file]
-'"$EXE"' config edit [file]
+'"$EXE"' config.edit [file]
-'"$EXE"' config del[ete]
+'"$EXE"' config.delete
+'"$EXE"' config.read
+'"$EXE"' config.write
+'"$EXE"' config.dump
 ```
 
 The `config` command is for reading, writing, and displaying standard
-open desktop configuration properties. Pass an empty string to delete
+open desktop configuration properties. 
-a property.
 
 ### Arguments
 
-With no arguments outputs all the currently cached configuration
+With no arguments calls `dump` and outputs all the currently cached
-settings.
+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
+* `directory` full path to config directory
-* `path` full path to specific config file (default: `values`) 
+* `path`   full path to specific config file (default: `values`) 
-* `edit` opens config file in editor (default: `editor` or `$EDITOR)
+* `edit`   opens config file in editor (default: `editor` or `$EDITOR)
-* `keys` output the configuration keys, one per line
+* `keys`   output the configuration keys, one per line
-* `val*` output the configuration values, one per line
+* `values` output the configuration values, one per line
-* `del*` if key argument then delete a specific key, otherwise prompt
+* `delete` if key argument then delete a specific key, otherwise prompt
+* `read` reads the configuration file into CONF associative array
+* `write` write the CONF associative array to the configuration file
+* `dump` write the flattened CONF associative array to standard output
 
 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
@@ -350,98 +397,94 @@ existing tools (and no `jq` dependency).
 * 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
+Note that, although similar, this is *not* the same as Java properties
-format. It is designed for ultimate simplicity, efficiency, and
+and other similar format. It is designed for ultimate simplicity,
-portability.'
+efficiency, and portability.'
 
-x_config() {
+x.config() {
-  case $1 in 
-    dir*) shift; _config_dir  "$@"; return $? ;;
-    path) shift; _config_path "$@"; return $? ;;
-    edit) shift; _config_edit "$@"; return $? ;;
-    del*) shift; _config_del  "$@"; return $? ;;
-    keys) shift; _config_keys "$@"; return $? ;;
-    val*) shift; _config_vals "$@"; return $? ;;
-  esac
   case $# in
-    0) _config_dump ;; 
+    0) x.config.dump ;;
-    1) _config_get "$@" ;;
+    1) x.config.get "$@" ;;
-    *) _config_set "$@" ;;
+    *) x.config.set "$@" ;;
   esac
 }
 
-_config_edit() {
+x.config.edit() {
-  : "${CONFIG[editor]:="${EDITOR:=vi}"}"
+  : "${CONF[editor]:="${EDITOR:=vi}"}"
-  exec "${CONFIG[editor]}" "$(_config_path "${1:-values}")"
+  exec "${CONF[editor]}" "$(x.config.path "${1:-values}")"
 }
 
-_config_del() {
+x.config.delete() {
   if [[ -z "$1" ]];then
-    select key in "${!CONFIG[@]}"; do
+    select key in "${!CONF[@]}"; do
-      _config_del "$key"
+      x.config.delete "$key"
       return $? 
     done
   fi
-  _config_set "$1" ''
+  x.config.set "$1" ''
 }
 
-_config_keys() { printf "%s\n" "${!CONFIG[@]}"; }
+x.config.keys() { printf "%s\n" "${!CONF[@]}"; }
 
-_config_vals() { printf "%s\n" "${CONFIG[@]}"; }
+x.config.values() { printf "%s\n" "${CONF[@]}"; }
 
-_config_dir() {
+x.config.dir() {
   local dir="$HOME/.config/$EXE"
   [[ -n "$XDG_CONFIG_HOME" ]] && dir="$XDG_CONFIG_HOME/$EXE" 
   [[ -n "$CONFIG_DIR" ]] && dir="$CONFIG_DIR"
   [[ -n "$1" ]] && echo "$dir/$1" && return 0
   printf "%s" "$dir"
   [[ -t 1 ]] && echo
+  return 0
 }
 
-_config_path() { 
+x.config.path() { 
   local file=${1:-values}
-  printf "%s/%s" "$(_config_dir)" "$file"
+  printf "%s/%s" "$(x.config.dir)" "$file"
   [[ -t 1 ]] && echo
+  return 0
 }
 
-_config_set() {
+x.config.set() {
   local key="$1"; shift; local val="$*"
   val="${val//$'\n'/\\n}"
-  CONFIG["$key"]="$val"
+  CONF["$key"]="$val"
-  _config_write
+  x.config.write
 }
 
-_config_get() { 
+x.config.get() { 
-  printf "${CONFIG[$1]}"
+  printf "%s" "${CONF[$1]}"
   [[ -t 1 ]] && echo
+  return 0
 }
 
-_config_read() {
+x.config.read() {
-  local values="$(_config_path)"
+  local values="$(x.config.path)"
   [[ -r "$values" ]] || return 0
   while IFS= read -r line; do
     [[ $line =~ ^([^=]+)=(.+)$ ]] || continue
-    CONFIG["${BASH_REMATCH[1]}"]="${BASH_REMATCH[2]}"
+    CONF["${BASH_REMATCH[1]}"]="${BASH_REMATCH[2]}"
   done < "$values"
 }
 
-_config_write() {
+x.config.write() {
-  local dir="$(_config_dir)"
+  local dir="$(x.config.dir)"
   mkdir -p "$dir"
-  _config_dump > "$dir/values"
+  x.config.dump > "$dir/values"
 }
 
-_config_dump() {
+x.config.dump() {
-  (( ${#CONFIG[@]} == 0 )) && return 0
+  (( ${#CONF[@]} == 0 )) && return 0
   paste -d=\
-    <(printf "%s\n" "${!CONFIG[@]}") \
+    <(printf "%s\n" "${!CONF[@]}") \
-    <(printf "%s\n" "${CONFIG[@]}")
+    <(printf "%s\n" "${CONF[@]}") \
+  | sort
 }
 
 # ----------------------------- utilities ----------------------------
 
 _jsonstr() {
-  _checkdep jq
+  _checkdep jq || return $?
   _buffer "$@" && return $?
   jq -MRsc <<< "$1"
 }
@@ -472,7 +515,7 @@ _reduce() {
 
 _newest() {
   IFS=$'\n'
-  local -a f=($(ls -1 --color=never -trd ${1:-.}/* 2>/dev/null))
+  mapfile -t f < <(ls -1 --color=never -trd "${1:-.}"/* 2>/dev/null)
   [[ ${#f} > 0 ]] && echo "${f[-1]}"
 }
 
@@ -481,6 +524,8 @@ _trim() {
   echo -e "${it%"${it##*[![:space:]]}"}"
 }
 
+_join() { local IFS="$1"; shift; echo "$*"; }
+
 _have(){ type "$1" &>/dev/null; }
 
 _checkdep() {
@@ -501,12 +546,32 @@ _buffer() {
   "${FUNCNAME[1]}" "$(</dev/stdin)"
 }
 
+_prompt() {
+  local key="$1" def="$2" regx="$3" value first=yes
+  shift 3
+  local text="${*:-Enter value for %s [%s]: }"
+  [[ -z "$key" ]] && echo "Missing prompt key" >&2 && return 1
+  [[ -z "$regx" ]] && echo "Missing valid regx" >&2 && return 1
+  while [[ ! $value =~ $regx ]];do
+    printf "$text" "$key" "$def" >&2
+    IFS= read -r value
+    [[ -z "$value" ]] && value="$def"
+    [[ $value =~ ^\ +$ ]] && value=""
+    [[ -n "$first" ]] && unset first && continue
+    echo "Must match /$regx/" >&2
+  done
+  _trim "$value"
+}
+
 # --------------------- completion and delegation --------------------
 #      `complete -C foo foo` > `source <(foo bloated_completion)`
 
+x.config.read
+_have _initialize && _initialize "$@"
+
 while IFS= read -r line; do
-  [[ $line =~ ^declare\ -f\ x_ ]] || continue
+  [[ $line =~ ^declare\ -f\ x\. ]] || continue
-  COMMANDS+=( "${line##declare -f x_}" )
+  COMMANDS+=( "${line##declare -f x.}" )
 done < <(declare -F)
 mapfile -t COMMANDS < \
   <(LC_COLLATE=C sort < <(printf "%s\n" "${COMMANDS[@]}"))
@@ -514,29 +579,32 @@ mapfile -t COMMANDS < \
 if [[ -n $COMP_LINE ]]; then
   line=${COMP_LINE#* }
   for c in "${COMMANDS[@]}"; do
-    [[ ${c:0:${#line}} == "${line,,}" && ${c:0:1} != _ ]] && echo "$c"
+    [[ ${c:0:${#line}} == "${line,,}" ]] && echo "$c"
   done
   exit
 fi
 
-_config_read
-_initialize
-
 for c in "${COMMANDS[@]}"; do
   if [[ $c == "$EXE" ]]; then
-    "x_$EXE" "$@"
+    "x.$EXE" "$@"
     exit $?
   fi
 done
 
 if [[ -n "$1" ]]; then
-  declare cmd="$1"; shift
+  declare CMD="$1"; shift
   for c in "${COMMANDS[@]}"; do
-    if [[ $c == "$cmd" ]]; then
+    declare cmd=$(command -v "x.$c")
-      "x_$cmd" "$@"
+    if [[ $c == "$CMD" && -n "$cmd" ]]; then
+      "x.$CMD" "$@"
       exit $?
     fi
   done
 fi
 
-x_usage "$@"
+if _have _alternatives; then
+  _alternatives "$@" 
+  exit $?
+fi
+
+x.usage "$@"