bash++

############################################################
# Bash resources you can 'source' from your Bash script.
#
# John Robertson <john@rrci.com>
# Initial release: Thu Sep 10 11:58:23 EDT 2020
#
# Fri Sep 11 22:13:16 EDT 2020
# Added malloc, new, delete, call, and fetch
#

# You can check this to see if bash++ has been sourced
BASH_PLUS_PLUS=true

# Global array to use as a return stack
declare -a __RTN_STK

function RTN_empty
############################################################
# Return logical TRUE if stack is empty, FALSE otherwise
# Arguments:
#    none
#
{
   local rtn=0
   [[ -n "${__RTN_STK:+foo}" ]] && rtn=1
   return $rtn
}

function RTN_push
############################################################
# Use this to push things onto the global return stack
# Arguments:
#    Whatever strings you wish placed on the stack
#
{
   local __opts=$(shopt -o -p nounset errexit)

   set -ue

   # For readability, store array index value here before using
   local -i ndx
   ndx=${__RTN_STK:+${#__RTN_STK[@]}}

   # Push arguments onto the stack
   while [[ -n "${1:+foo}" ]]; do

      # Place argument onto stack
      __RTN_STK[$ndx]="$1"

      ((++ndx))
      # Discard argument
      shift

   done

   # Restore options
   eval $__opts
}

function BackTrace
############################################################
# Generate a GDB(ish) style stack dump
{
   local i j

   1>&2 echo "----------- Stack Dump ------------"
   for ((i= 1; i < ${#BASH_SOURCE[@]}; ++i)); do

      ((j= i-1)) || true

      1>&2 echo -e "\ti=$i, j=$j ${BASH_SOURCE[$i]}:${BASH_LINENO[$j]} ${FUNCNAME[$i]} ()"
   done
}

function RTN_pop
############################################################
# Use this to pop things off of the return stack
# Arguments:
#    Names of global varibles to be loaded by popping
#    strings from the stack.
#
{
   # Necessary to avoid "unbound variable" exception
   local __opts=$(shopt -o -p nounset)
   set -u

   local -i arg ndx sz

   # Get current size of stack
   sz=${__RTN_STK:+${#__RTN_STK[@]}}

   # Generate correct array index
   (( ndx = sz - 1 )) || true

   # Walk through supplied references backwards
   for (( arg= $#; arg ; --arg )); do

      if ((ndx < 0)); then
         local line file
         # Print out a stack dump
         BackTrace
         read line file < <(caller)
         die "ERROR: ndx= '$ndx' cannot have a negative value; called from $file:$line"
      fi

      # Copy item on stack to *reference
      eval ${!arg}="\${__RTN_STK[\$ndx]}"

      # pop item from stack, free memory
      unset __RTN_STK[$ndx]
      ((--ndx)) || true
   done

   # Restore options
   eval $__opts
}

# Global heap counter integer 
declare -i __HC=0

function malloc
############################################################
# Allocate a global "address" from the "heap"
# Arguments:
#    0 or more flags which will be passed to the 'declare' builtin.
#      e.g. '-A' for associative array 
# Returns:
#   "address" of allocated memory
#
{
   # Increment global heap counter
   (( ++__HC ))

   # compose unique "address" for this allocation
   local addr="__heap_${__HC}"

   # "allocate" object gets marked for global visibility,
   # and possibly other 'declare' flags
   declare -g $@ $addr
   # push "address" onto result stack
   RTN_push $addr
}

function new ()
############################################################
# 'new' operator to allocate object & call class constructor
# Arguments:
#   classname
#   constructor_arg1         (optional)
#   ...
# Returns:
#   "address" of new object
#
{
   # Stash the class name with the object
   local __class=$1

   # Discard class name from argv
   shift

   # Allocate an associative array from our "heap"
   malloc -A

   # Retrieve "address" of new object
   RTN_pop __R1

   # Imprint class name on the object
   eval $__R1[__class]=$__class

   # Call class constructor
   eval $__class::$__class $__R1  \$@

   # Push address on return stack
   RTN_push $__R1

}

function delete ()
############################################################
# 'delete' operator to call class destructor, free object
# Arguments:
#   object_address
# Returns:
#   nothing
#
{
   # address of object
   local this=$1

   # class name of object
   eval local __class=\${$this[__class]}

   # Call class destructor
   eval $__class::~$__class $this

   # Free object memory
   unset $this
}


function show ()
############################################################
# Print object contents
# Arguments:
#   object1_address
#   object2_address (optional)
#   ...
# Returns:
#   Nothing
#
{
   declare -p $@
}

function fetch ()
############################################################
# Convenient way to access class member values
# Arguments:
#   address.member
# Returns:
#   value of member on the return stack
#
{
   # address of object
   local this=${1%.?*} __member=${1#?*.}

   eval RTN_push \"\${$this[$__member]}\"

}

function call ()
############################################################
# Call an object member function
# Arguments:
#   address.funcName
#   func_arg1 (optional)
#   ...
# Returns:
#   Whatever funcName() returns
#
{
   # address of object
   local this=${1%.?*} __func=${1#?*.}
   # class name of object
   eval local __class=\${$this[__class]}

   shift

   # Call class member function
   eval $__class::$__func $this \$@
}

function regex_read ()
############################################################
# Similar to bash 'read' builtin, but parses subsequent
# read buffer using the supplied regular expression.
# Arguments:
#   regex pattern
# Returns:
#   logical TRUE if read was successful
#   or logical FALSE on end-of-file condition.
# Return stack:
#   Full string match (if any)
#   token1_match (if any)
#   ...
#   Last argument is _always_ number of matches found. Pop it first.
#   
{
   # Stash the regular expression
   local ndx count regex="$1"

   # All other args are for 'read'
   shift

   # Call read with other supplied args. Fails on EOF
   IFS= read $@ || return 1

   # Apply regular expression parsing to read buffer
   if [[ $REPLY =~ $regex ]]; then
      # Place results on return stack
      count=${#BASH_REMATCH[@]}
      for (( ndx= 0; ndx < count; ++ndx )); do
         RTN_push "${BASH_REMATCH[$ndx]}"
      done
      # Last stack arg is number of match results
      RTN_push $count

   else
      # regex failed to match
      RTN_push 0
   fi
}

function die ()
############################################################
# Same as 'die' in perl - Print supplied args to stderr
# prefixed with source file name and line number,
# then exit indicating error.
#
{
   local line file
   read line file < <(caller)
   1>&2 echo "$file:$line $@"
   exit 1
}

function hkselect
################################################
# Approximate replacement for bash's builtin `select'.
# hkselect() does not require the user to press enter key
# to finalize choice.
# Usage: hkselect arg1 ...
#
# User choices are supplied as args to the function, and
# the hotkey may be indicated by placing an `&' in
# the preceding character, e.g.
#   press&kplease
# where `k' is the hotkey. If a hotkey is not indicated,
# then one will be assigned automatically.
#
# Command flags:
# -b 'keystr|funcname|arg1 arg2 ...'   Bind escape-based key (F1-F12, Arrows, ...) to a function
# -B global_arr_name                   Array of -b arguments
# -p left_pad                          Left margin padding count
# -r 'rebuke string'                   String to print when user pressed invalid key
# -s 'subtitle string'                 Subtitle to print below choices
# -w max_width                         Limit the width of choices layout
#
# Global variables:
#   HKSELKEY       - key the user pressed when making a successful choice
#   REPLY          - zero based index of the arg whose hotkey was pressed
#
# RETURN: upon return the value of HKSELKEY will contain the key which
# the user pressed, and REPLY will contain the 0-based index of the
# matching argument passed when hkselect() was called
#
# Sat Mar 27 16:52:53 EDT 2021
# John Robertson <john@rrci.com>
{
   # Stash current shell options
   local __opts=$(shopt -o -p nounset errexit)
   set -ue +xv

   # We cache composed labels and layout information
   declare -gA _HKSEL_CACHE

   local tmp arg argc dcarg i j len pos lr lcol uc dc warg wlbl wrow wcol argc
   local TROWS TWIDTH BLD NRM UND HK subtitle maxwidth pad=2
   local -A rv_hk_m hk_m bkfunc_m  bkargs_m
   local opt OPTIND bkey bfunc bfuncargs is_cached=0
   # namerefs for cached information
   local -n nr_nrows nr_ncols nr_hk_m nr_wcol_a nr_warg_a nr_lbl_a

   TWIDTH=$(tput cols)
   TROWS=$(tput lines)
   UND=$(tput smul)
   BLD=$(tput bold)
   NRM=$(tput sgr0)
   HK="$(tput setaf 4)$(tput setab 7)$BLD"

   local rebuke="${BLD}Please choose one of the highlighted keys$NRM"

   while getopts ':b:B:p:r:s:w:' opt; do
      case $opt in
         b) IFS='|' read bkey bkfunc bkargs <<<"$OPTARG"

            # Add binding to the bound-key map
            bkfunc_m[$bkey]=$bkfunc
            bkargs_m[$bkey]="$bkargs"
            ;;
         B)
            local -n _hkselect_bkargs_a=$OPTARG
            if [[ -n "${_hkselect_bkargs_a[@]:+foo}" ]]; then
               for arg in "${_hkselect_bkargs_a[@]}"; do
                  IFS='|' read bkey bkfunc bkargs <<<"$arg" || true
                  # Add binding to the bound-key map
                  bkfunc_m[$bkey]=$bkfunc
                  bkargs_m[$bkey]="$bkargs"
               done
            fi
            # unreference supplied array
            unset -n _hkselect_bkargs_a
            ;;
         p) pad=$OPTARG;;
         r) rebuke="$OPTARG";;
         s) subtitle="$OPTARG";;
         w) TWIDTH=$OPTARG;;
         \?) die "Invalid option: -$OPTARG";;
      esac
   done
   shift $((OPTIND-1))

   # Make sure these are bound, and empty
   HKSELKEY=
   REPLY=

   # possibly clip TWIDTH
   [[ -n "${maxwidth:+foo}" ]] && ((TWIDTH = TWIDTH > maxwidth ? maxwidth : TWIDTH))

   ### Determine all hotkey assignments
   local arg_ndx argcat sum
   local -a pri_char_a dcarg_a
   local -A ccount_map
   # Determine argc, identify supplied hotkey assignments
   argc=${#@}
   for ((i=0; i < argc; ++i)); do
      # function name is at $0, so we start at $1
      (( arg_ndx = i + 1 ))

      # copy arg into convenient variable
      eval arg=\${$arg_ndx}

      argcat+="$arg"

      # Stash a downcased version of arg for efficiency
      dcarg=$(tr '[:upper:]' '[:lower:]' <<<"$arg")
      dcarg_a[$i]="$dcarg"

      # Look for an ampersand
      tmp=${arg%%&*}
      len=${#tmp}
      # May not exist
      [[ $len = ${#arg} ]] && continue

      (( pos = len + 1 )) || true

      # Get lowercase hotkey character
      dc=${dcarg:pos:1}

      # Map to arg index forward & backward
      hk_m[$dc]=$i
      rv_hk_m[$i]=$dc
   done

   #### Checksum to uniquely identify this content ###
   sum=$(md5sum <<<"$TWIDTH${argcat:+$argcat}")
   # Strip junk at end of sum
   sum=${sum%  -}

   # Our cache key is caller information
   local ckey=$(caller)

   # check for a matching key in the cache
   if [[ -n "${_HKSEL_CACHE[$ckey]:+foo}" ]]; then
      # Key was found, so compare value against current checksum
      if [[ ! ${_HKSEL_CACHE[$ckey]} = $sum ]]; then
         # Cache is stale, discard it
         unset nrows_${sum} ncols_${sum} warg_a_${sum} wcol_a_${sum} lbl_a_${sum} hk_m_${sum}
      else
         # Use previously cached results
         is_cached=1
      fi
   else
      # Map the checksum on ckey
      _HKSEL_CACHE[$ckey]=$sum
   fi

   # Set our namerefs
   nr_nrows=nrows_${sum}
   nr_ncols=ncols_${sum}
   nr_warg_a=warg_a_${sum}
   nr_wcol_a=wcol_a_${sum}
   nr_lbl_a=lbl_a_${sum}
   nr_hk_m=hk_m_${sum}

   if (( ! is_cached )); then
      # Create new global variables with unique names
      declare -g nrows_${sum} ncols_${sum}
      declare -ga warg_a_${sum} wcol_a_${sum} lbl_a_${sum}
      declare -gA hk_m_${sum}

      # Copy in results obtained above
      for dc in "${!hk_m[@]}"; do
         nr_hk_m[$dc]=${hk_m[$dc]}
      done
   fi

   # Assign hotkeys and perform layout only if not cached
   if (( ! is_cached )); then
      # Make character count map as needed
      for ((i=0; i < argc; ++i)); do

         # Already be mapped?
         [[ -n ${rv_hk_m[$i]:+foo} ]] && continue

         # Unpack downcased arg
         dcarg="${dcarg_a[$i]}"

         # Check for usable hotkey characters
         for ((j=0; j < ${#dcarg}; ++j)); do
            dc=${dcarg:$j:1}
            # Skip disallowed charcters
            [[ -n ${nr_hk_m[$dc]:+foo} || ! $dc =~ [[:alnum:]] ]] && continue
            [[ -n ${ccount_map[$dc]:+foo} ]] || ccount_map[$dc]=0
            (( ++ccount_map[$dc] ))
         done
      done

      # Get ccount_map contents into pri_char_a, characters sorted on ascending count
      read -d $'\0' -a pri_char_a < <(
         cut -f1 < <(
            sort -n -k2 < <(
               for key in "${!ccount_map[@]}"; do
                  echo -e "$key\t${ccount_map[$key]}"
               done
            )
         )
      ) || true

      # Assign hotkeys to args
      for ((i=0; i < argc; ++i)); do
         # Skip existing assignments
         [[ -n ${rv_hk_m[$i]:+foo} ]] && continue

         # Look for prioritized hotkey
         for (( j= 0; j < ${#pri_char_a[@]}; ++j )); do
            dc=${pri_char_a[$j]}
            dcarg="${dcarg_a[$i]}"
            
            # Already mapped? character in string?
            [[ -z ${nr_hk_m[$dc]:+foo} && $dcarg =~ $dc  ]] || continue

            # map hotkey foward and backward
            nr_hk_m[$dc]=$i
            rv_hk_m[$i]=$dc
            break
         done
      done
      # No longer needed
      unset ccount_map pri_char_a
      # FIXME: here we *assume* a hotkey was assigned to every arg

      # Fix up labels, etc
      for ((i=0; i < argc; ++i)); do

         # Get a convenient copy of arg
         (( arg_ndx = i + 1 ))
         eval arg=\${$arg_ndx}

         # Handle case of args with no hotkey supplied
         if [[ ! $arg =~ \& ]]; then

            # Catch common mistake
            [[ -z "${rv_hk_m[$i]:+foo}" ]] &&\
               die 'ERROR: command flag args must precede choice args here: '$(caller)

            # Remember the length of the argument
            len=${#arg}
            nr_warg_a[$i]=$len
            dc=${rv_hk_m[$i]}
            dcarg="${dcarg_a[$i]}"

            # Identify the position where the character belongs
            tmp=${dcarg%%$dc*}
            len=${#tmp}
            (( pos = len + 1 ))

         else # arg was supplied with hotkey pre-assigned

            # Remember the length of the argument, adjusted for ampersand
            (( len = ${#arg} - 1 ))
            nr_warg_a[$i]=$len
            dc=${rv_hk_m[$i]}
            tmp=${arg%%&*}
            len=${#tmp}
            (( pos = len + 2 ))
         fi
         uc=$(tr '[:lower:]' '[:upper:]' <<<$dc)
         nr_lbl_a[$i]="$UND${arg:0:$len}$HK$uc$NRM$UND${arg:$pos}$NRM"
      done

      # Iterate to find optimum layout
      nr_nrows=1
      nr_ncols=$argc
      while true; do

         wcol=0

         # cycle through supplied arguments
         for (( i=0; i < argc; ++i )); do

            # On which logical column are we operating?
            (( lcol = i % nr_ncols )) || true

            # Reset row width at first column
            (( wrow = lcol ? wrow : 0 )) || true

            # compute width of current label
            warg=${nr_warg_a[$i]}
            (( wlbl = warg + pad ))

            # Go with max of previous column width, or current lbl width
            (( wcol = wlbl > wcol ? wlbl : wcol ))

            # Accumulate the column width
            (( wrow += wcol ))


            if (( wrow > TWIDTH )); then
               # Try adding a row
               (( ++nr_nrows ))
               break
            fi
            # Remember the column width
            nr_wcol_a[$lcol]=$wcol
         done

         (( nr_nrows > TROWS )) && die "$nr_nrows is too many rows, and I can't scroll!"
         
         [[ -z "${wrow:+foo}" ]] && die "No items from which to choose!"
         # Success criterion
         (( wrow <= TWIDTH )) && break

         # adjust ncols to reflect addition of a new row
         (( nr_ncols = argc / nr_nrows + (argc % nr_nrows ? 1 : 0) ))
      done
   fi # is_cached

   # Present choices to user
   for (( i=0; i < argc; ++i )); do
      # On which logical row are we operating?
      (( lr = i / nr_ncols )) || true
      
      # On which logical column are we operating?
      (( lcol = i % nr_ncols )) || true

      # Move down to first line on new row, but not first time
      (( i && !lcol )) && echo

      # Reset row width at first column
      if (( ! lcol )); then
         wrow=0
         pos=$pad
      fi

      # Put cursor at beginning of column on this line
      (( fwd = pos - wrow ))

      tput cuf $fwd
      (( wrow += fwd ))

      # print the label
      echo -n "${nr_lbl_a[$i]}"
      warg=${nr_warg_a[$i]}
      (( wrow += warg ))
      # Update horizontal position
      wcol=${nr_wcol_a[$lcol]}
      (( pos += wcol ))
   done

   # Save cursor position
   echo && tput sc

   [[ -n ${subtitle:+foo} ]] && echo -n "$subtitle"

   # Hide cursor
   tput civis

   # varibles for the loop below
   local escbuf= is_invalid=0

   # User now makes a choice
   while true; do

      # read will return when a key is pressed
      read -sN 1 HKSELKEY

      # We may have a function bound to enter key
      if [[ $'\n' = $HKSELKEY ]]; then
         bkey=$'\n'
         if [[ -n "${bkfunc_m[$bkey]:+foo}" ]]; then
            # Get the callback function
            bkfunc=${bkfunc_m[$bkey]}
            bkargs=${bkargs_m[$bkey]}
            # Fire the callback function
            eval $bkfunc \$bkargs
            # Check return code
            (( $? )) || break
         else
            is_invalid=1
         fi
      fi

      # Handling of bound keys
      if (( !is_invalid && ${#escbuf} )); then
         # Append key to escbuf
         escbuf+=$HKSELKEY
         # See if there is more to come
         if ! read -st 0; then
            if [[ -n "${bkfunc_m[$escbuf]:+foo}" ]]; then
               # Get the callback function
               bkfunc="${bkfunc_m[$escbuf]}"
               bkargs="${bkargs_m[$escbuf]}"
               # Clear HKSELKEY
               HKSELKEY=
               # Fire callback function
               eval $bkfunc \$bkargs
               # Check return code
               (( $? )) || break
            else
               escbuf=
               is_invalid=1
            fi
         else
            # Need more characters
            continue
         fi
      fi

      # ESC could mean exit, or that a bound key was pressed
      if [[ 0 = $is_invalid && $'\e' = $HKSELKEY ]]; then
         # Check for more queued keystrokes
         read -st 0 || break

         # more queued keystrokes means we buffer this
         escbuf=$HKSELKEY
         continue
      fi

      # Check for possible unescaped hotkeys
      if [[ 0 = $is_invalid && -n $HKSELKEY ]]; then
         # Look for a case insensitive match in our hotkey map
         dc=$(tr '[:upper:]' '[:lower:]' <<<$HKSELKEY)
         if [[ -n ${nr_hk_m[$dc]:+foo} ]]; then
            i=${nr_hk_m[$dc]}
            (( REPLY = i )) || true
            echo
            break
         else
            is_invalid=1
         fi
      fi

      # Possibly rebuke user
      if (( is_invalid )); then
         tput rc
         echo -n "$rebuke"
         sleep 0.5
         tput rc
         tput el
         [[ -n ${subtitle:+foo} ]] && echo -n "$subtitle"
      fi
      is_invalid=0
   done

   # Restore the cursor
   tput cvvis

   # Discard references
   unset -n nr_nrows nr_ncols nr_hk_m nr_wcol_a nr_warg_a nr_lbl_a

   # Restore options
   eval $__opts
}