.functions

#----- header -----
[ "${0##*/}" != "${BASH_SOURCE##*/}" ] || { >&2 echo -e "ERROR\tfile must be sourced ($0)"; return 2; }
[[ "$BASH_VERSION" =~ 5|4.[2-4] ]] || { >&2 echo -e 'ERROR\tbash ~> 4.2 required'; exit 126; }
#------------------

set -o pipefail
shopt -s extglob
#pedant, ref: http://mywiki.wooledge.org/glob#nullglob
shopt -u nullglob


#NOTE 'command' is unsuitable since returns aliases and functions
function __WHICH() { \which "$@"; }
function __READLINK() { \readlink ${VERBOSE:+ -v} "$@"; }

#function __YQ() { \yq ??? "$@"; }
function __JQ() { \jq --exit-status "$@"; }
function __JQR() { \jq "$@" | \jq --exit-status --raw-output '. // empty'; }

#TODO call it merge1 since it ONLY handles 1st level
function __JQ_merge() { \jq --slurp 'reduce .[] as $item ({}; . * $item)'; }
#TODO merge_deep(er)
#jq -s '[.[] | to_entries] | flatten | reduce .[] as $dot ({}; .[$dot.key] += $dot.value)'
#TODO when key1: valu1, key1: valu2 -> key1: [ valu1, valu2 ]
# also maybe something like group_by(.key) | map({key:.[0].key,value:(map(.value) | join(" "))})
#def merge_at_key(separator):
#  reduce .[] as $o
#    ([];
#     $o["key"] as $k
#     | (map(.key) | index($k)) as $i
#     | if $i then (.[$i] | .value) += (separator + $o["value"])
#       else . + [$o] end);
# I think we can rewrite ^^ better
#
# Recursively meld a and b,
# concatenating arrays and
# favoring b when there is a conflict
#def meld(a; b):
#  a as $a | b as $b
#  | if ($a|type) == "object" and ($b|type) == "object"
#    then reduce ([$a,$b]|add|keys_unsorted[]) as $k ({};
#      .[$k] = meld( $a[$k]; $b[$k]) )
#    elif ($a|type) == "array" and ($b|type) == "array"
#    then $a+$b
#    elif $b == null then $a
#    else $b
#    end;
# then invoked as: jq -f meld.jq 1.json 2.json 'reduce inputs as $i (.; meld(.; $i))
#
# one-shot function definition and invocation
#$ jq -s 'def deepmerge(a;b):
#  reduce b[] as $item (a;
#    reduce ($item | keys_unsorted[]) as $key (.;
#      $item[$key] as $val | ($val | type) as $type | .[$key] = if ($type == "object") then
#        deepmerge({}; [if .[$key] == null then {} else .[$key] end, $val])
#      elif ($type == "array") then
#        (.[$key] + $val | unique)
#      else
#        $val
#      end)
#    );
#  deepmerge({}; .)' file1.json file2.json

function __CURL() { \curl --connect-timeout 3 --fail --silent --location ${VERBOSE:+ '--verbose' '--progress-bar'} "$@"; }

# override 'exit on error' program flow
function __continue() { [ -n "$CONTINUE" ]; }

function pause() {
  local _default='Press [ENTER] to continue ... '
  read -p "${*:-$_default}"
}


function confirm() {
  read -n 1 -t 15 -p 'Are you sure (y/N)? '
  echo
  [ "${REPLY^^}" = "Y" ]
}


# mimic 'set -x' and send STDERR to file
function runv() {
  local indent=`printf '%.0s+' {1..$SHLVL}`
  #TODO wrap arguments in " for easy copy+paste
  >&2 printf '%s %s\n' "$indent" "$*"

  # set to <blank> is insufficient
  ${NOOP:+return 0}

  if [ `to_int $DEBUG` -gt 1 -o `to_int $TRACE` -eq 1 ]; then
    local command=${FUNCNAME[1]:-$1}
    local outf=`mktemp -t "${command##*/}-XXXXXXXX"`
    exec > >( tee "$outf" ) 2> >( tee "${outf}.err" >&2 )
    >&2 caller 1
  fi

  "$@"
}
# likely to be invoked in subshell
export -f runv

#TODO is_what() returns 'type -t' or 'declare -p' mapped back to English
#function is_what

function __is_type() {  #WARN! selective short-circuit on first error
  local -Ar __types=(
      ['a']='array'       ['array']='a'
      ['A']='hash'        ['hash']='A'
      ['f']='function'    ['function']='f'
      ['i']='integer'     ['integer']='i'
      ['l']='lower'       ['lower']='l'
      ['n']='nref'        ['nref']='n'
      ['-']='string'      ['string']='-'
      ['r']='readonly'    ['readonly']='r'
      ['u']='upper'       ['upper']='u'
    )

  local keyword=${FUNCNAME[1]#is_}
  local DEBUG QUIET=1 VERBOSE
  local -i use_stdin=0

  local -i OPTIND; local opt OPTARG long_opts=()
  while getopts ':hdqvS' opt; do
    case "$opt" in
      d)    DEBUG=1 ;;
      q)    QUIET=1 ;;
      v)    VERBOSE=1;;
      S)    use_stdin=1 ;;

      :)    log.error "missing argument (${!OPTIND})" ;;&
     \-)    [[ "$OPTARG" =~ \= ]] || log.notice "assuming flag (--${OPTARG})"
            long_opts+=( "--${OPTARG}" )
            (( OPTIND++ ))
            ;;
     \?)    #long_opts+=( "-${OPTARG}" ) ;;
            log.error "unsupported option (-${OPTARG})" ;&
      h|*)  >&2 cat << EOF
Usage: $FUNCNAME ...
EOF
    esac
  done
  shift $((OPTIND - 1))
  #FIXME naked '-' implies problem with getopts
  [ "$1" != '-' ] || { log.error "naked dash (-) argument"; return; }

  # evaluate verbosity flags
  [ -n "${DEBUG}${VERBOSE}" ] && unset QUIET

  # read STDIN (pipe) if no args
  (( ${use_stdin:-0} )) && set -- $( < /dev/stdin )
  (( $# )) || return

  case "${keyword:?}" in
    dir*|file)
            while (( $# )); do
              if [[ "$keyword" =~ dir ]]; then [ -d "$1" ]; else [ -f "$1" ]; fi || {
                  [ -n "$QUIET" ] || log.error "$keyword not found (${1:?})"; return 1; }
              shift
            done
            return
            ;;
    exec*)  local bin
            while (( $# )); do
              #WARN 'command' returns matches on alias and functions
              bin=$( __WHICH "${1:?}" 2>/dev/null ) || {
                  [ -n "$QUIET" ] || log.error "$keyword not found (${1:?})"; return 1; }

              ${VERBOSE:+echo "$bin"}
              shift
            done
            return
            ;;
    func*)  while (( $# )); do
              declare -F "$1" &>/dev/null || {
                  [ -n "$QUIET" ] || log.error "$keyword not found ($1)"; return 1; }

              ${VERBOSE:+whereis_function "$1"}
              shift
            done
            return
            ;;
    read*)  local -i _readonly=1 ;;

    *)      [ -n "${__types[$keyword]}" ] || {
                log.error "unsupported type ($keyword)"; return 2; }
  esac

  local whatami flag=
  while (( $# )); do
    # naked '-' not absorbed by getopts()
    [ "$1" != '-' ] || return

    # suss out functions during 'readonly'
    [ "$( type -t "$1" )" = 'function' ] && flag='-F'

    whatami=$( declare -p $flag "$1" 2>/dev/null | awk '{ print $2; }' ) || {
        log.error "type detection failed ($1)"; return 1
      }
    (( $_readonly )) && whatami=${whatami//[^r]/} || whatami=${whatami//[r-]/}

    [[ "${whatami#-}" =~ ${__types[$keyword]} ]] || {
        [ -n "$QUIET" ] || log.error "type mismatch ($1: ${__types[${whatami#-}]} != $keyword)"
        return 1
      }
    shift
  done
}
# data-type wrappers
for f in array dir{,ectory} exec{,utable} file hash integer string function readonly nref; do
  eval function is_$f '{ __is_type "$@"; }'
done


#alt: grep -qE '^0x[0-9a-f]+$|[0-9]+$' - -- <<< "$@"
function is_number() { to_int $1 &>/dev/null; }

function is_interactive() { [[ $- =~ i ]] || tty -s || [ -n "`tset -q`" ]; }


#DO NOT MOVE!!
# Properly belongs in '.functions_os[.cygwin]' but required for various
# scripts and helper functions. Leaving it here simplifies includes.
function is_windows() {
  if [ $# -eq 0 ]; then
    [[ "${OSTYPE:-`uname -o`}" =~ [cC]ygwin|[mM]sys ]]
    return
  fi

  local bin
  #WARN multi-arg supported, but not recommended
  while (( $# )); do
    for op in 'echo' 'readlink -e' 'is_exec -v'; do
      bin=`$op "$1"` || continue
      if [ "${bin:0:1}" = '/' ]; then break; fi
    done
    [[ "${bin:?}" =~ ^/cygdrive ]] || { file "$bin" | grep -q 'for MS Windows'; } || return
    shift
  done
}
readonly -f is_windows


function __is_markup() {
  : ${cmd:?detection command}       # magic injection
  local -i rc

{ # logging wrapper
  if [ $# -eq 0 ]; then
    "${cmd[@]}"
  else
    while (( $# )); do
      if [ -f "$1" ] || [[ "${1:0:1}" =~ \.|/ ]]; then
        "${cmd[@]}" < "$1"
      elif [ -n "$1" ]; then
        "${cmd[@]}" <<< "$1"
      else
        false
      fi || { rc=$?; break; }

      shift
    done
  fi
  : ${rc=$?}
} 2>&1 >/dev/null | log.debug

  # fancy-pants I/O redirection above will SIGPIPE (128+13) on no error
  #ref: https://unix.stackexchange.com/a/254747, signal(7)
  [ $rc -eq 0 -o $? -eq 141 ] || {
      [ -n "${VERBOSE}" ] && log.error "invalid input" "$1"
      return 1
    }
}

#NOTE 'yaml' module accepts both JSON and self
function is_yaml() {
  cmd=( python '-c' 'import yaml, sys; yaml.safe_load(sys.stdin)' ) \
      __is_markup "$@"
}

function is_json() {
  #alt: jq --exit-status . <file|string>
  cmd=( python '-c' 'import json, sys; json.load(sys.stdin)' ) \
      __is_markup "$@"
}


function define() {
  # Assign a HEREDOC to a variable.
  # To collapse space/tab indentation use dash in indirection like so '<<-_EOF'
  # Contents will be expanded unless marker ('_EOF') is quoted.
  #
  # Usage: define VAR <<_EOF ...
#TODO? </dev/stdin

  IFS=$'\n' read -r -d '' "$1" || true
}


#TODO? extend to other types
function whereis_function() (
  shopt -s extdebug

  while (( $# )); do
    declare -F "${1:?}"
    shift
  done | awk '{ printf("%-25s\t%-50s #%d\n", $1, $3, $2); }'
)


function list_functions() (
  local format='%-25s\t%-50s #%d\n'

  if [ $# -eq 0 ]; then
    shopt -s extdebug; declare -F `compgen -A function`
  else
    while (( $# )); do
      [ -s "$1" ] || { shift; continue; }

      env -i $SHELL --noprofile --norc -s 2>/dev/null <<- _EOF
        source "$1"
        shopt -s extdebug
        # sub-shell loses sourced contents
        compgen -A function | while read; do declare -F "\${REPLY}"; done
_EOF
      shift
    done
  fi | awk -v fmt="$format" '{ printf fmt, $1, $3, $2; }'
)


function copy_function() {
  # arg1: source name or fully declared format
  # argN: destination
  #
  # Does NOT support recursion since fails easily or in unintended ways.
  # Using SED with BOL, EOL or whitespace detection isn't reliable either.

  local fname=${1:?source} body
  local -i overwrite=0

  shift

#FIXME flip IF test over but check length of $1, also remove assignment at top
#also the formatting assumptions is wildly dangerous!
  if grep --quiet -e '() {' - -- <<< "$fname" ; then
    body=$fname
    fname=`awk '{print $1; exit}' <<< "$body"`
  else
    # allow side-channel injection   ???
    : ${body:=`declare -f "$fname"`}
  fi

  [ -n "$fname" -a -n "$body" ] || return

  for target in "$@"; do
    # ignore badly-formed arguments
    [ -n "$target" ] || continue

    #log.* may not be defined as yet
    if declare -F "$target" &>/dev/null; then
      if [ ${overwrite:-0} -eq 1 ]; then
#        is_readonly "$target" && {
#            [ -n "$VERBOSE" ] && log "ERROR\toverwrite read-only function ($target)"
#            return 1
#          }
        [ -n "$VERBOSE" ] && log "NOTICE\toverwriting function ($target)"
      else
        [ -n "$VERBOSE" ] && log "WARN\tfunction exits ($target)"
        continue
      fi
    fi

    #alt: "function $target ${body#*\(\)}"
    eval "${body/$fname/$target}"
  done
}


function rename_function() {
  copy_function "${1:?source}" "${2:?dest}" && unset -f "$1"
}


function convert_path() {
  # Usage: caller use 'while read()' one entry per line for whitespace
  # management if providing multiple arguments, assign to array, or set --
  #
  #WARN validity/existence of the path is NOT checked!
  # also makes NO attempt to detect/expand wildcard patterns
  #
  # Cygwin handles whitespace in "$PATH" and they must remain un-escaped.
  # This *magical* behavior does NOT extend to other PATH-like variables!
  #     eg. GOPATH, RUBYPATH, RUBYLIB, PUPPET_MODULE_PATH, JAVA_HOME
  #
  # However, interactive use of paths must be inside quotes or escaped
  # since the $SHELL parser is not so gifted.
  #
  # cygpath only modifies the first occurance of '/cygdrive' or '[A-Z]:'
  # unless '-p' but delimiter in input MUST consistently match opposite
  # of desired output format (';' for Windows, ':' for Unix). Any intermix
  # or requesting Windows output from Windows input yields garbage. But
  # Unix output from Unix input is usually benign.

  local QUOTE quote flags=()
  # do NOT default quote character
  [ -n "${QUOTE+X}" ] && : ${quote=$QUOTE}

  local -i escape=1 abs=0
  local -i OPTIND; local opt OPTARG long_opts=()
  while getopts ':haeEq:t:-:' opt; do
    case "$opt" in
      a)    abs=1 ;;
      e)    escape=1 ;;     # default
      E)    escape=0 ;;
      q)    quote=$OPTARG; readonly escape=0 ;;
      t)    long_opts+=( '--type' "$OPTARG" ) ;;

     \-)    long_opts+=( "--${OPTARG}" )
            [[ "$OPTARG" =~ \= ]] || log.notice "assuming flag (--${OPTARG})"
            ;;
      :)    log.error "missing argument (${!OPTIND})" ;;&
    # pass-thru unhandled args to cygpath
     \?)    long_opts+=( "-${OPTARG}" ) ;;
      h|*)  >&2 cat << EOF
Usage: $FUNCNAME ...
EOF
    esac
  done
  shift $((OPTIND - 1))

  local _format="${quote}%s${quote}\n"
  [ ${escape:-0} -eq 1 ] && _format='%q\n'
  local IFS=$'\n'

  [ ${abs:-0} -eq 1 ] && set -- `readlink -m "$@"`
  if is_windows; then
	set -- `cygpath "${long_opts[@]}" -- "$@" 2>/dev/null`
  fi

  printf "$_format" "$@"
}
#TODO
#function convert_path=os.filepath.print

#TODO has_value(s), has_key(s)

#FIXME keys/values use same nref detection
function array.contains() {
#Usage: <array|hash> value(s) ...
  (( $# > 1 )) || return 2

  local -n object
  is_nref "${1:?array}" && eval object="\${!$1}" || object=$1
  is_array -v "${!object}" || return

  shift

  #compute once
  local elements=${object[*]}
  #if keys() then ${!object[*]}

  while (( $# )); do
    #NOTE grep matches on blank which is not helpful
    [ -n "$1" ] || { shift; continue; }

    grep --quiet --word-regexp "$1" -- <<< "$elements" || return
    shift
  done
}


function string.contains() {
#Usage: <object> substring(s) ...
  local DELIM delim op flags=()
  [ -n "${DELIM+X}" ] && : ${delim=$DELIM}

  local -i skip_blank=0 use_stdin=0 reverse_arg=0 exact=0
#FIXME rename flags to grep_opts, and use assoc array of flags([use_stdin]=0 etc

  local -i OPTIND; local OPTARG opt #long_opts=()
  while getopts ':hD:o:RSxz' opt; do
    case "$opt" in
      D)    delim=$OPTARG ;;
      o)    op=$OPTARG ;;
      S)    use_stdin=1 ;;
      R)    reverse_arg=1 ;;
      x)    exact=1 ;;
      z)    skip_blank=1 ;;

      :)    log.error "missing argument (-$OPTARG)" ;;&

      #WARN getopts blindly consumes 1 char at a time, ignores word splitting
      #  so will walk an argument string with embedded '-' instead of stopping
      #
      # assume unhandled flags are 'grep' options
     \?)    : ${op=grep}
            #FIXME test OPTIND for longopt
            #[[ "${!OPTIND}" =~ ^--[a-z] ]] with '='?
            flags+=( "-$OPTARG" )
            ;;

      h|*)  >&2 cat << _EOF
Usage: $FUNCNAME [ options ] <object> [ substring ... ]
  -D        delimiter char(s)
  -o        method of comparison: grep, pe (parameter expansion), regex (bash)
  -S        use STDIN for input string(s)
  -z        ignore empty strings, else will ERROR
  -R        reverse argument order; <substring> [ object ... ]
...
_EOF
    esac
  done
  shift $((OPTIND - 1))

#TODO handle nref like array.contains()
  local object=${1:?object}; shift
  (( $# )) || { [ ${use_stdin:-0} -eq 1 ] && set -- $( < /dev/stdin ); }
  (( $# )) || return 2

  function __compare() {
    case "$op" in
      pe)   [ "${2#*$1}" != "$2" ] ;;
      regex) [[ "$2" =~ $1 ]] ;;
      exact) [[ "$2" == "$1" ]] ;;
      *)    [[ "$2" == *"$1"* ]]
    esac
  }

  (( $reverse_arg )) && local _save=$object

  while read sub; do
    # empty string is 'false' but can be ignored
    if [ -z "$sub" ]; then
      (( $skip_blank )) && continue || return
    fi

    (( $reverse_arg )) && { object=$sub; sub=$_save; }

    if [ "$op" == 'grep' ]; then
      [ -n "$delim" ] && sub="${delim}\?${sub}${delim}\?"
      grep --quiet "${flags[@]}" ${delim:+'--extended-regexp'} "$sub" - -- <<< "$object"

    elif [ -n "$delim" ]; then
      local _IFS=$delim
      (( ${#delim} > 1 )) && _IFS=$'§'   #(shell: Alt+0167, vi: C-v+167)
      IFS=$_IFS read -r -a tokens <<< "${object//$delim/$_IFS}"

      local -i found=0
      for tok in "${tokens[@]}"; do
        __compare "$sub" "$tok" && { found=1; break; }
      done
      (( $found ))

    else __compare "$sub" "$object"; fi || return
  done < <( IFS=$'\n'; echo "$*" )
}

#TODO define is_substring() to call above


function addPath() {
  # pre-/post-pend [multiple] elements to an environment variable
  # but does NOT sub-divide arguments!

#TODO use string.join() to handle arbitrary delimiters and whitespace
#TODO? rewrite callers as PATH=`DELIM=$delim string.join -v <VARNAME> $1 $2`
  local PREPEND k
  local -i prepend=0 use_stdin=0
  [ -n "${PREPEND+X}" ] && prepend=1

  local -i OPTIND; local OPTARG opt
  while getopts ':hk:PS' opt; do
    case "$opt" in
      k)    k=$OPTARG ;;
      P)    prepend=1 ;;
      S)    use_stdin=1 ;;
#      [dvq]) dqv+=( "-$OPTARG" )

      :)    log.error "missing argument (-$OPTARG)" ;;&
     \?)    log.error "unsupported option (-$OPTARG)" ;&
      h|*)  >&2 cat <<_EOF
Usage: $FUNCNAME -k VAR path...
_EOF
            return 2
    esac
  done
  shift $((OPTIND - 1))

  (( $# )) || { [ ${use_stdin:-0} -eq 1 ] && set -- $( < /dev/stdin ); }
  (( $# )) || return 2

  local delim flags=()
  case "${k:-$1}" in
    ''|?(-|.)*/*) k=PATH ;&

    # '-a' unroll symlinks for accurate comparison
    PATH)   delim=':'; flags+=( '-Epa' ) ;;

#TODO GOPATH, RUBYPATH etc. use PATHSEP
  esac

  : ${delim:=${PATHSEP:-':'}}
  local -n kval=${k:?VAR_name}

#FIXME detect if new path already has ^/cygpath and don't invoke cygpath()

  local -ir __prepend=${prepend:-0}     #save
  while read item; do
    [ -n "$item" ] || { shift; continue; }
    prepend=$__prepend                  #restore

    is_dir "$item" || continue

#TODO set IFS=$delim instead or use explicit arg
    if ! string.contains -D "$delim" "$kval" "$item"; then
      [ $prepend -eq 1 ] && kval="${item}${delim}${kval}" || kval+="${delim}${item}"
      log.debug "add element to $k ($item)"
    fi
    shift
  done < <( convert_path "${flags[@]}" "$@" )

  # remove leading, trailing and any leftover repeated delimiter
  kval=${kval##$delim}; kval=${kval%%$delim}
  kval=${kval//${delim}${delim}/$delim}
}

#TODO simply treat as DELETE=1 addPath
function rmPath() {
  : ${1:?VAR_name or path}
  local k delim

  case "${k:=$1}" in
    # VAR unspecified
    ?(.)/*) k=PATH ;&
    PATH)   delim=':' ;;

    #GOPATH, RUBYPATH etc. use PATHSEP
  esac

  : ${delim:=${PATHSEP:-':'}}
  local -n kval=${k:?VAR_name}
  # split into tokens. unset array element to erase
  #alt: eval $k=`loop`
  kval=$( IFS=$delim
      read -ra items <<< "${!k}"
      while read line; do
        for i in "${!items[@]}"; do
          if [ "${items[i]}" = "$line" ]; then unset 'items[i]'; log.debug "remove element ($i, $line)"; fi
        done
      done < <( readlink -m "$@" )
      echo "${items[*]}"
    )

  # remove leading, trailing and any leftover repeated delimiter
  kval=${kval##$delim}; kval=${kval%%$delim}
  kval=${kval//${delim}${delim}/$delim}
}


#TODO? if QUOTE=1 use printf '%q'
function string.join() {
  local DELIM delim QUOTE quote ESCAPE escape
  [ -n "${DELIM+X}" ] && delim=$DELIM
  [ -n "${QUOTE+X}" ] && quote=$QUOTE
  [ -n "${ESCAPE+X}" ] && escape=$ESCAPE

  local flags=
  local -i OPTIND; local opt OPTARG
  while getopts ':d:e:lq:uz' opt; do
    case "$opt" in
      d)    delim=$OPTARG ;;
      e)    escape=$OPTARG ;;
      l)    flags+=l ;;     # to_lower
      q)    quote=$OPTARG ;;
      u)    flags+=u ;;     # to_upper
      z)    flags+=z ;;     # remove blanks

      :)    log.error "missing argument (-$OPTARG)" ;;&
     \?)    log.error "unsupported option (-$OPTARG)" ;&
      h|*)  >&2 cat <<_EOF
Usage: $FUNCNAME [ options ] <str> [<str> ...]
  -l        to lower case
  -u        to upper case
  -z        remove blank args
_EOF
            return 2
    esac
  done
  shift $((OPTIND - 1))

  # legacy invocation
  [ -n "${delim+X}" ] || { delim=$1; shift; }

  # escape whitespace, or even delimiter (rare)
  if [ -n "$quote" ]; then
    [ "$quote" = "$delim" ] && escape=$delim
  else
    : ${escape=${IFS:0:1}}
  fi

  # unset empty args and remove holes
  if [[ $flags =~ z ]]; then
    local -a args=( "$@" )

    for i in "${!args[@]}"; do
      [ -n "${args[$i]}" ] || unset 'args[i]'
    done
    set -- "${args[@]}"
  fi

  [ -n "$escape" ] && set -- "${@//$escape/\\$escape}"
  #WARN unintended side-effects
  [[ "${escape}${delim}${quote}" =~ [a-zA-Z] && "$flags" =~ l|u ]] &&
      log.warn "case change poses severe risk (escape=${escape}, delim=${delim}, quote=${quote})"
  [[ "$flags" =~ l ]] && set -- "${@,,}"
  [[ "$flags" =~ u ]] && set -- "${@^^}"

  # shortcut
  [ -z "$quote" -a ${#delim} -le 1 ] && { local IFS=$delim; echo "$*"; return; }

  # prepend each word during expansion
  local IFS=
  local str=${*/#/${quote}${delim}${quote}}
  # strip leading 'delim' and tack on trailing 'quote'
  echo "${str#${quote}${delim}}$quote"
}
# backwards compat
function join_string() { log.warn "DEPRECATED! use 'string.join()'"; string.join "$@"; }

function join_quote() { log.warn "DEPRECATED! use 'string.join()'"; QUOTE=\' string.join "$@"; }

# using 'echo' requires IFS='\n'. TODO
function to_upper() { if (( $# )); then local IFS=$'\n'; echo "${*^^}"; else tr '[:lower:]' '[:upper:]'; fi }

function to_lower() { if (( $# )); then local IFS=$'\n'; echo "${*,,}"; else tr '[:upper:]' '[:lower:]'; fi }


function bool_to_int() {
# Usage: [-u] <value|VAR_NAME> ...
  local -i to_bool unset

  local -i OPTIND; local opt OPTARG
  while getopts ':r' opt; do
    case "$opt" in
#      u)    unset=1 ;;
      r)    to_bool=1 ;;

#      :)
     \?)    log.error "unsupported option (-$OPTARG)" ;&
      h|*)  >&2 cat <<_EOF
Usage: $FUNCNAME ...
_EOF
            return 2
    esac
  done
  shift $((OPTIND - 1))

  case "${1,,}" in
    0|false) if [ ${to_bool:-0} -eq 1 ]; then echo 'false'; else echo 0; false; fi ;;
    1|true)  if [ ${to_bool:-0} -eq 1 ]; then echo 'true'; else echo 1; true; fi ;;

#      # assign truthiness to named variable, if false optionally unset it
#      [a-z]*)   if [[ "$BASH_VERSION" =~ 5|4.[3-9] ]]; then
#                  local -n vref; vref=$1 || return
#                  vref=`$FUNCNAME "$vref"`
#                else
#                  local v=${1^^}
#                  $FUNCNAME ${!v}
#                fi
#               [ ${unset:-0} -eq 1 ] && unset $1
    *)  return 2
  esac
}
function to_bool() { bool_to_int -r "$1"; }

function to_int() { printf '%d\n' "${@:-X}" 2>/dev/null; }

#function __GETOPT() {
#https://stackoverflow.com/questions/192249/how-do-i-parse-command-line-arguments-in-bash
#https://gist.github.com/kaushalmodi/74e9875d5ab0a2bc1010447f1bee5d0a
#getopt --longoptions 'file:,verbose' --options '+vf:' -- --verbose -f foobar another thing
#yields: --verbose -f 'foobar' -- 'another' 'thing'
#
#Usage: __GETOPT [--options ${getopts_string without leading ':'}] [--longoptions <longopt] --name ${0:-$FUNCNAME} -- "$@"
# for any items that LOOK like options (leading '-') either put them behind an *obvious* not an option, OR put '--' between arg sequence you want parsed and "ignore everything after"
#consume via:
# set -- `__GETOPT ...` || return 2 from parse error or getopt is the old version
#otherwise parsed_args=( `__GETOPT ...` )
#
# while (($#)); do
#   case "$1" in
#     --) shift; break; # reached end of short+long options. tack $@ onto downstream command
#     -s|--long) stuff; items+=( $2 ); shift
#   esac
#   shift
# done
#
# http://mywiki.wooledge.org/BashFAQ/035
#   IFS='
# '
  # if [[ $option =~ (\[((no|dont)-?)\]). ]]; then
    # option2=${option/"${BASH_REMATCH[1]}"/}
    # option2=${option2%%[<{().[]*}
    # printf '%s\n' "${option2/=*/=}"
    # option=${option/"${BASH_REMATCH[1]}"/"${BASH_REMATCH[2]}"}
  # fi
  # option="${option%%[<{().[]*}"
  # printf '%s\n' "${option/=*/=}"
# }



function version_to_int() (
  shopt -s nocaseglob
  : ${1:?}

  # superficial input sanitation
  set -- "${@//-/.}"; set -- "${@//[^0-9]/}"

  while (( $# )); do
    printf '%.3d' ${1//./ }		#deliberate un-quoted
    echo; shift
  done
)


# dpkg --compare-versions $A <OP> $B
#
# use parameter expansion to replace dot by space, how about '-rcX'?
#
#xarr=(${CurrV//./ })
#yarr=(${ExpecV//./ })
#
#
# suppose that ExpecV is newer (bigger) or equal to CurrV version:
#
#isnewer=true
#
#
# loop over array keys:
#
#for i in "${!xarr[@]}"; do
#  if [ ${yarr[i]} -gt ${xarr[i]} ]; then
#    break
#  elif [ ${yarr[i]} -lt ${xarr[i]} ]; then
#    isnewer=false
#    break
#  fi
#done
#
#function compare_versions {
#    local a=${1%%.*} b=${2%%.*}
#    [[ "10#${a:-0}" -gt "10#${b:-0}" ]] && return 1
#    [[ "10#${a:-0}" -lt "10#${b:-0}" ]] && return 2
#    a=${1:${#a} + 1} b=${2:${#b} + 1}
#    [[ -z $a && -z $b ]] || compare_versions "$a" "$b"
#}
#
#simple greater-than
# [ bigger = `printf '%s\n' $ver1 $ver2 | sort --check=quiet --version-sort --stable | head -n 1` ]
#
# ref: https://stackoverflow.com/questions/4023830/how-to-compare-two-strings-in-dot-separated-version-format-in-bash
# handle x.y.z with optional '-XX##' or 1.4.0b2
# see also https://dazuma.github.io/versionomy/
#version_compare() {
#    if [[ $1 =~ ^([0-9]+\.?)+$ && $2 =~ ^([0-9]+\.?)+$ ]]; then
#        local l=(${1//./ }) r=(${2//./ }) s=${#l[@]}; [[ ${#r[@]} -gt ${#l[@]} ]] && s=${#r[@]}
#
#        for i in $(seq 0 $((s - 1))); do
#            [[ ${l[$i]} -gt ${r[$i]} ]] && return 1
#            [[ ${l[$i]} -lt ${r[$i]} ]] && return 2
#        done
#
#        return 0
#    else
#        echo "Invalid version number given"
#        exit 1
#    fi
#}
#
#function compare_versions() {
#    # Trivial v1 == v2 test based on string comparison
#    [[ "$1" == "$2" ]] && return 0
#
#    # Local variables
#    local regex="^([0-9]+.*)-r([0-9]*)$" va1=() vr1=0 va2=() vr2=0 len i IFS="."
#
#    # Split version strings into arrays, extract trailing revisions
#    if [[ "$1" =~ ${regex} ]]; then
#        va1=(${BASH_REMATCH[1]})
#        [[ -n "${BASH_REMATCH[2]}" ]] && vr1=${BASH_REMATCH[2]}
#    else
#        va1=($1)
#    fi
#    if [[ "$2" =~ ${regex} ]]; then
#        va2=(${BASH_REMATCH[1]})
#        [[ -n "${BASH_REMATCH[2]}" ]] && vr2=${BASH_REMATCH[2]}
#    else
#        va2=($2)
#    fi
#
#    # Bring va1 and va2 to same length by filling empty fields with zeros
#    (( ${#va1[@]} > ${#va2[@]} )) && len=${#va1[@]} || len=${#va2[@]}
#    for ((i=0; i < len; ++i)); do
#        [[ -z "${va1[i]}" ]] && va1[i]="0"
#        [[ -z "${va2[i]}" ]] && va2[i]="0"
#    done
#
#    # Append revisions, increment length
#    va1+=($vr1)
#    va2+=($vr2)
#    len=$((len+1))
#
#    # *** DEBUG ***
#    #echo "TEST: '${va1[@]} (?) ${va2[@]}'"
#
#    # Compare version elements, check if v1 > v2 or v1 < v2
#    for ((i=0; i < len; ++i)); do
#        if (( 10#${va1[i]} > 10#${va2[i]} )); then
#            return 1
#        elif (( 10#${va1[i]} < 10#${va2[i]} )); then
#            return 2
#        fi
#    done
#
#    # All elements are equal, thus v1 == v2
#    return 0
#}


function min() {
  local flag=()

  while (( $# )); do
    [ -n "$1" ] || { shift; continue; }
#FIXME use getopts
    [[ $1 = -[a-zA-Z] ]] && flag+=( "$1" ) || break
    shift
  done
  local IFS=$'\n'
  sort --numeric-sort "${flag[@]}" "$*" | head -n 1
}

function max() { min -r "$@"; }

# Array or Hash
#TODO bash 4.2.46 doesn't support 'nref', use 'eval ${$1}'
#  bash 4.4 has "${!nref[@]@Q}" but that puts single-quotes around each element
#
if [[ "$BASH_VERSION" =~ 5|4.4 ]]; then
#----
function keys() { values "$@"; }

function values() {
  local format keys

  local -i OPTIND; local opt OPTARG
  while getopts ':hf:lqu' opt; do
    case "$opt" in
      f)    format=${OPTARG} ;;
      l)    format='@L' ;;
      q)    format='@Q' ;;
      u)    format='@U' ;;

      :)    log.error "missing argument (${!OPTIND})" ;;&
     \?)    log.error "unsupported option (-$OPTARG)" ;&
      h|*)  >&2 cat << EOF
Usage: $FUNCNAME ...
EOF
            return 2
    esac
  done
  shift $((OPTIND - 1))

#FIXME
#  local -n object
#  is_nref "${1:?array}" && eval object="\${!$1}" || object=$1
#  is_array -v "${!object}" || return

  local -n nref=${1:?varname}
  if [ "${FUNCNAME[1]}" = keys ]; then
    keys='!nref'; LOG_LEVEL=WARN is_hash "${!nref}"
    set --      # remove args to force '*'
  fi

  case "$format" in
    '')     : ;;
    \@L|,,) [ -n "${keys+X}" ] && format=to_lower ;;&
    \@U|^^) [ -n "${keys+X}" ] && format=to_upper ;;&
    # fake 'keys' to use pipe
    ?(to_)@(upper|lower)) : ${keys=''} ;;&

    #NOTE adds quotes when empty which breaks [ -n "`value ...`" ]
    \@[kQ]) local IFS= ;;&
    # keys & format can not be combined
    *)      [ -z "$keys" ] || {
                log.error "unsupported format ($format) ${keys+with keys}"
                return 2; }
  esac

#FIXME just ugly as sin
  local printf='%s\n'   #NOTE '%q' emits '' when empty, which breaks [ -n "`values ..." ]
  # use printf() since IFS ignored when $2
  if [ "${keys+X}${format+Y}" = "XY" ]; then
    eval printf '%s\\n' "\${${keys:-nref}[${2:-*}]}" | $format
  else
    eval printf '%s\\n' "\${${keys:-nref}[${2:-*}]${format}}"
  fi
}
#----
#else
# non-nref method
fi

#WARN complex formatting (eg. @[kQ]) have unintended side-effects
function value() { values "$@" | head -n 1; }


function array.print() {
  local printf
  local -i to_json= with_keys=

  local -i OPTIND; local opt OPTARG
  while getopts ':hjkPV' opt; do
    case "$opt" in
      *)    with_keys=1; local -A printf=() ;;&
      k)    printf=( ['key']='%s\n' ['value']='%q ' ) ;;
      P)    printf=( ['key']='%s\t' ['value']='%q ' ) ;;  #alt: key='%s\n' value='\t%s\n'
      j)    printf=( ['key']='%s\n' ['value']='%s,' ); to_json=1 ;;

      # consume with eval
      V)    printf=( ['key']='%s=' ['value']='%q' ['keyf']='^^' )
            local one=''
            ;;

      :)    log.error "missing argument (${!OPTIND})" ;;&
     \?)    log.error "unsupported option (-$OPTARG)" ;&
      h|*)  >&2 cat << EOF
Usage: $FUNCNAME ...
EOF
            return 2
    esac
  done
  shift $((OPTIND - 1))

  local vref=${1:?varname} kval=$2
  shift 2

#TODO? leverage formatting as defined in values()
#https://www.gnu.org/savannah-checkouts/gnu/bash/manual/html_node/Shell-Parameter-Expansion.html

  if [ ${with_keys:-0} -eq 1 ] && LOG_LEVEL=WARN is_hash "$vref"; then
    while read key; do
      # simple filter on 'key'
      [ -n "$kval" ] && { [ "$key" = "$kval" ] || continue; }

      eval printf "${printf['key']@Q}" "\${key${printf['keyf']}}"
      printf "${printf['value']}" $( value${one-s} ${printf['valuef']:+'-f' "${printf['valuef']}"} "$vref" "$key" )
      echo
    done < <( keys "$@" ) |
        if [ ${to_json:-0} -eq 1 ]; then
          __JQ -Rn 'reduce inputs as $i ({}; . + {($i): (input | fromjson? // split(",") - [""] | [ .[] | tonumber? // . ])})'
        else cat; fi
  else
    [ ${to_json:-0} -eq 1 ] || {        # single path bandaid
        [ ${with_keys:-0} -eq 1 ] && unset 'printf[value]'; }
    printf "${printf['value']:-%s\n}" $( values ${printf['valuef']:+'-f' "${printf['valuef']}"} "$vref" ) |
        if [ ${to_json:-0} -eq 1 ]; then
          __JQ -R 'split(",") - [""] | [ .[] | tonumber? // . ]'
        else cat; fi
  fi
}

function hash.print() { array.print -k "$@"; }

#TODO define 'to_hash' 'to_array'
#TODO array functions; push, pop, delete, replace, truncate
#TODO array.append|.add|.insert, prune|delete, length, equal, is_empty, clear, dedup, index_of|key,


function expand_dvq() {
  # standardize behavior keyed off of 'special' variables
  local v level

  for v in DEBUG VERBOSE QUIET NOOP; do
    local -n vref="__${v,,}"
    c=${v:0:1}; c=${c,,}

    # String compare is more robust than Integer
    [ -z "${!v}" -o "${!v}" = "0" ] && continue

    level=$(printf "%d" ${!v} 2>/dev/null) || level=1
    # {1..$level} doesn't work without eval
    eval printf -v vref "%0.s$c" {1..$level}
    # prepend '-' (dash)
    vref="-${vref}"
  done
}


# simple implementation
function log() {
  local -u level
  local fname=
  local -i offset=1

  if [ "${FUNCNAME[1]:0:4}" = 'log.' ]; then
    : ${level:=${FUNCNAME[1]:4}}
    : $((offset++))
  fi
  [ -n "${FUNCNAME[$offset]}" ] &&
      fname="[${BASH_SOURCE[offset]##*/}:${FUNCNAME[offset]}] "

  if [ $# -eq 0 ]; then
    local line=$( < /dev/stdin )
    >&2 echo -e "${level:-LOG}\t${fname}${line}"
  else
    while (( $# )); do
      >&2 echo -e "${level:-LOG}\t${fname}$1"
      shift
    done
  fi
}

function log.none() { return; }

function log.debug() {
  local -i rc=$?

  [ -n "$DEBUG" ] && log "$@"
  return ${RC:-$rc}
}

function log.info() {
  local -i rc=$?

  [ -n "${VERBOSE}${DEBUG}" ] && log "$@"
  return ${RC:-$rc}
}

function log.notice() {
  local -i rc=$?

  log "$@"
  return ${RC:-$rc}
}

function log.error() {
  local -i rc=$?

  log "$@"
  if [ ${SHLVL:-1} -eq 1 -o -z "$BASH_SOURCE" ] ||
      [[ $(\ps -p $PPID | awk 'END { print $NF; }') =~ screen ]]; then
    return ${RC:-$rc}
  fi
  __continue || exit ${RC:-$rc}
}

copy_function log.debug log.trace
copy_function log.notice log.warn


# more efficient
if is_exec -q pv; then
  function cat() { pv -q "$@"; }
fi


# vim: expandtab:ts=8:sw=4