#!/bin/bash

# Mode: rec
# File: linge.rc Version 1.0
# Brief: bash commands called from .bashrc file.
# Author: Strategist Christopher Dimech
# Copyright: 2021 Strategist Christopher Dimech
# License: Gnu Affero General Public License (Gnu AGPL)
# + Version 3 or any later version.
# # End of rec

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

## h1 * Copying Conditions

#                                    _      
#  __ ___ _ __ _  _   __ ___ _ _  __| |_ _  
# / _/ _ \ '_ \ || | / _/ _ \ ' \/ _` | ' \ 
# \__\___/ .__/\_, | \__\___/_||_\__,_|_||_|
#        |_|   |__/                         

# This file belongs to Behistun, a Gnu Package.

# Behistun is free software.  You can re-distribute Behistun as is, or
# modify it under the terms of the Gnu Affero General Public License
# as published by the Free Software Foundation, either version 3 of
# the License, or (at your option) any later version.

# A copy of the license is included in the file "gnu--agpl.texi".  If
# not, see <http://www.gnu.org/licenses/>.

# ############################################################

## h1 * Commentary:

# The .bashrc file runs every an interactive shell is launched.
# Bash allows hyphens in function names, but not in --posix mode.

# A number of checkboxes are displayed in this file.  They split the
# setup tasks for the user into simple steps.  When a job is
# completed, type the Capital Uppercase X inside the checkbox,
# i.e. changing the checkbox tag from [ ] to [X].  The '[0/5]' in the
# TODO Outline indicates how many jobs with checkboxes have been
# completed, and the total number of checkboxes present.  Once all
# checkboxes are completed, change the "TODO" Item with a "DONE" Item
# by removing the word "TODO" with "DONE".

# * TODO User defined setup jobs [0/5]
#   - [ ] dircolors - Set directory path and file name
#   - [ ] xmodmap - Set directory path and file name
#         Interchanges Ctrl with Alt key by modifying keymaps in Xorg.
#   - [ ] Set starting directory for the Command Line Terminal.

# Code:

# ######################################################

PF ()
{
 printf "%s\n" "$@"
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

PFB ()
{
 local -r blu=$(tput bold)$(tput setaf 39)
 local -r sgr=$(tput sgr0)
 printf "%s"   "$blu"
 printf "%s\n" "$@" 
 printf "%s"   "$sgr"
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

PF2 ()
{
 printf "%s\n\n" "$@"
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-heading-usage ()
{
 printf '%s\n' "linge-heading-usage .$*. $#"
 if (( $# == 0 )); then
   PF "Display a heading"
   echo
   PF "  linge-heading [OPTIONS] HEADING"
   echo
   PF "Generic Program Information"
   PF "---------------------------"
   PF "" "-u1   Brief list of options"
   PF    "-u2   Brief list of examples"
 fi

 case $1 in
  (1)
     PF " {-v VB, -v=VB, -vVB, --verbosity VB, --verbosity=VB}"
     PF " {-h, --help}, {-u, --usage}, {-V, --version}"
     ;;
  (2)
     PF "" 
     ;;
 esac
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-heading ()
{
 local -r etdate="V01 Jul 2021 Wk27" 
 local -r author="Strategist Christopher Dimech"

 if (( $# == 0 )); then
   printf '%s\n' "Display heading"
   printf "%s\n" "$etdate $author"
   printf '%s\n' "Invoke \`linge-heading -h' for details,"
   printf '%s\n' "or \`linge-heading -u' for a summary."
 fi

 local compact=0 emph=0
 while (( $# > 0 )); do
   case $1 in
    ("-V"|"--version")
      printf "%s\n" "$etdate $author"
      return 0
      ;;
    #------------------------------
    ("-v"|"--verbosity")  vb="$2" ; shift ; shift ;;
    ("-v="*|"--verbosity="*) vb="${1#*=}" ; shift 1 ;;
    ("-v"*) vb="${1#-v}" ; shift 1 ;;
    #------------------------------
    ("-h"|"--help")
      linge-heading-details
      return 0
      ;;
    #------------------------------
    ("-u"|"--usage")
      if [[ "$2" =~ ^[0123456789]+$ ]]; then
        usg="$2" ; shift ; shift
        printf '%s\n' "usg: .$usg."
        linge-heading-usage "$usg"
      else
        shift
        printf '%s\n' "usg: .$usg."
        linge-heading-usage "$usg"
      fi
      return 0
      ;;
    ("-u="*|"--usage="*)
      usg="${1#*=}" ; shift 1
      linge-heading-usage "$usg"
      return 0
      ;;
    ("-u"*)
      usg="${1#-u}" ; shift 1
      linge-heading-usage "$usg"
      return 0
      ;;
    #------------------------------
    ("-c") compact=1 ; shift 1 ;;
    ("-e") emph=1    ; shift 1 ;;
    (*) break ;;
   esac
 done

 local -r titl="$1"

 local mark="*"
 if (( $# > 1 )); then mark="$2"; fi

 # Scout: Using :::Gunga:Din as input, with : instead of blanks
 local -r prefix=${1%%[![:blank:]]*}  # :::

 # trim input to remove leading blanks
 local -r trimarg=${1#"$prefix"}      # 'Gunga:Din'
 
 ## Set emphasising mark using *
 #  The // instruction replaces all single character matches with *
 #  The ? instruction matches all single characters
 local -r emphmrk="${trimarg//?/$mark}"   # '*********'
 
 (( compact == 0 )) && echo
 if (( emph == 1 )); then
   printf '%s\n%s\n' "$1" "${prefix}${emphmrk}"
 else
   printf '%s\n' "$titl"
 fi
 (( compact == 0 )) && echo

}

alias HDG='linge-heading -e'

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-newline ()
{
 impl="echo"
 if [ "$impl" = "echo" ]; then  # [] is posix shell compliant
   echo
 else    
   printf '%s\n' ""
 fi
}

alias NWL='linge-heading -e'

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge_trk="${HOME}/Opstk/bin/gungadin-1.0/linge"
source "${linge_trk}/gunsteby/linge-nymph.rc"

# ######################################################

linge-details-numeric ()
{
 fmt="\n%s\n" fmt+="\n"
 printf "$fmt" "Validates numeric notation." 

 printf '%s\n' linge-numeric [OPTIONS] 
 
 HDG "Function Details"

 PF " -V, --version, -u, --usage, -h, --help"

 PFH " -f STY, --fmt=STY"
 PF  "    Format style."

 PFH "    STY | Desciption"
 PF  "    -------------------------------------------"
 PF  "    F   | Fixed-point number notation"
 PF  "    pF  | Positive fixed-point notation"
 PF  "    nF  | Negative fixed-point notation"
 PF  "    E   | Floating-point number notation"
 PF  "    pE  | Positive floating-point notation"
 PF  "    nE  | Negative floating-point notation" ""

 PF "\$1 NUM  First numeric number."
 PF "\$2 NUM  Second numeric number."

}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-usage-numeric ()
{
 case $1 in
  (1)
     PF " {-V, --version}, {-h, --help}, {-u, --usage}"
     PF " {-v VB, -v=VB, -vVB, --verbosity VB, --verbosity=VB}"
     PF " {-f FRMT, --frmt FRMT} | FRMT: [I|F|pF|nF|E|pE|nE]"
     PF " {--impl IMPL, --impl=IMPL} | IMPL: [regexp|shglob]"
     PF " -o"
     ;;
  (2)
     HDG "Usage"
     PF2 " Print result in text format with -o"
     PF  " linge-numeric -o 2.143      | Result: 1"
     PF  " linge-numeric -o 2.143E+07  | Result: 1"
     PF  " linge-numeric -o 2.143E-02  | Result: 1"
     PF  " linge-numeric -o -I 34      | Result: 1"

     echo
     PF " validnum=\$( linge-numeric -o -I 3 )"
     ;;
  (3)
     HDG "Conditional Expression"
     PF " num=\"3\"" 
     PF " if linge-numeric -I \"\$num\"" 
     PF " then"
     PF "   # code if num is numeric"
     PF " else"
     PF "   # code if num is not numeric"
     PF " fi"
     ;;
 esac

}

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

linge-numeric ()
{
 local -r etdate="V01 Jul 2021 Wk27" 
 local -r author="Strategist Christopher Dimech"
 
 local vb=1 fm="E" impl="regexp"
 local outval=0 ledescval=0 errnum=0 ledesc=()

 local indic=0   # indicator
 local errnum=1  # numeric error code

 (( $# == 0 )) && PF "Invoke \`linge-numeric -h' for details."
 
 local outval=0
 while (( $# > 0 )); do
   opt="$1"
   case $opt in
    ("-V"|"--version")
      printf "%s\n" "$etdate $author"
      return 0
      ;;
    # .............................
    ("-v"|"--verbosity")  vb="$2" ; shift ; shift ;;
    ("-v="*|"--verbosity="*) vb="${1#*=}"; shift 1 ;;
    ("-v"*) vb="${1#-v}"; shift 1 ;;
    # .............................
    ("-h"|"--help")
      linge-details-numeric
      return 0
      ;;
    ("-u"|"--usage")
      PF "linge-numeric OPTIONS NUM"
      linge-usage-numeric "$vb"
      return 0
      ;;
    # .............................
    ("-o") outval=1 ; shift 1 ;;
    ("--ledesc") ledescval=1 ; outval=1 ; shift 1 ;;
    # .............................
    ("-f"|"--frmt") fm="$2" ; shift ; shift ;;
    ("-f="*|"--frmt="*) fm="${1#*=}" ; shift 1 ;;
    ("--impl") impl="$2"; shift ; shift ;;
    ("--impl="*) impl="${1#*=}"; shift 1 ;;
    # .............................
    ("-I")  fm="I"  ; shift 1 ;;
    ("-Ip") fm="Ip" ; shift 1 ;;
    ("-In") fm="In" ; shift 1 ;;
    ("-F")  fm="F"  ; shift 1 ;;
    ("-Fp") fm="Fp" ; shift 1 ;;
    ("-Fn") fm="Fn" ; shift 1 ;;
    ("-E")  fm="E"  ; shift 1 ;;
    ("-Ep") fm="Ep" ; shift 1 ;;
    ("-En") fm="En" ; shift 1 ;;
    # .............................
    ("--")
	   shift 1 ; break ;;
    ("-"*)
           errstr=" 64  | $1 command line usage error"
           errnum=64 ; ledesc+=("$errstr")
           shift 1 ;;
    (*)
	   break ;;
    # .............................
   esac  # case ends here
 done  # while ends here

 # -----------------------------------------------------
 # Implementation uses Regular Expressions or Globbing Patterns
 
 impl="shell-extglob"
 if [[ "$impl" == "shell-regexp" ]]; then
   # Using Regular-Expressions

   # Expression | Description of Regular Expression
   # -----------+-------------------------------------------  
   # (regex)?   | Match zero or one occurrences of given regex
   # (regex)*   | Match zero or more occurrences of given regex
   # (regex)+   | Match one or more occurrences of given regex

   # \+ avoids Regular Expression Meta-Character Interpretation
     
   # Integer number notation
   local itg='^[-+]?[0-9]+$'
   local pitg='^\+?[0-9]+$'
   local nitg='^-[0-9]+$'
 
   # Fixed-Point number notation
   local fxp='^[-+]?[0-9]*[.,]?[0-9]+$'
   local pfxp='^\+?[0-9]*[.,]?[0-9]+$'
   local nfxp='^-[0-9]*[.,]?[0-9]+$'
 
   # Floating-Point number notation
   local flp='^[-+]?[0-9]*[.,]?[0-9]+([eE][-+]?[0-9]+)?$'
   local pflp='^\+?[0-9]*[.,]?[0-9]+([eE][-+]?[0-9]+)?$'
   local nflp='^-[0-9]*[.,]?[0-9]+([eE][-+]?[0-9]+)?$'

   # The =~ operator in double bracket conditionals [[ ]], regards the
   # right side an extended regular expression.

   case $fm in
    ("I")
           [[ "$1" =~ $itg  ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed integer validation"
	   (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("Ip")
           [[ "$1" =~ $pitg ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed positive integer validation"
	   (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("In") 
	   [[ "$1" =~ $nitg ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed negative integer validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("F") 
	   [[ "$1" =~ $fxp  ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed fixed point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("Fp") 
	   [[ "$1" =~ $pfxp ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed positive fixed point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;; 
    ("Fn") 
	   [[ "$1" =~ $nfxp ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed negative fixed point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("E") 
	   [[ "$1" =~ $flp  ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed floating point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("Ep") 
	   [[ "$1" =~ $pflp ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed positive floating point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("En")
	   [[ "$1" =~ $nflp ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed negative floating point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    (*) 
	   [[ "$1" =~ $flp  ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed floating point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
   esac

 # -----------------------------------------------------
 elif [[ "$impl" == "shell-extglob" ]]; then
   # Using Shell Extended Globbing Patterns

   # Pattern 	 | Description of Extended Globs
   # ------------+------------------------------------------------
   # ?(pattern) | Match zero or one occurrences of the patterns
   # *(pattern) | Match zero or more occurrences of the patterns
   # +(pattern) | Match one or more occurrences of the patterns
     
   local itg='?([-+])+([0-9])'
   local itga='?([-+])+([[:digit:]])'  # alternative to itg
   
   local pitg='?(+)+([0-9])'
   local nitg='-+([0-9])'

   local fxp='?([-+])*([0-9])?([.,])+([0-9])'
   local pfxp='?(+)*([0-9])?([.,])+([0-9])'
   local nfxp='-*([0-9])?([.,])+([0-9])'

   local flp='?([-+])*([0-9])?([.,])+([0-9])?([eE]?([-+])+([0-9]))'
   local pflp='?(+)*([0-9])?([.,])+([0-9])?([eE]?([-+])+([0-9]))'
   local nflp='-*([0-9])?([.,])+([0-9])?([eE]?([-+])+([0-9]))'

   # The == and != operators in double bracket conditionals [[ ]],
   # regard the right side as a Globbing Patterns.

   case $fm in
    ("I")
           [[ "$1" == $itg  ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed integer validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("Ip")
           [[ "$1" == $pitg ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed positive integer validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("In")
           [[ "$1" == $nitg ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed negative integer validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("F")
           [[ "$1" == $fxp  ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed fixed point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("Fp")
           [[ "$1" == $pfxp ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed positive fixed point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("Fn")
           [[ "$1" == $nfxp ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed negative fixed point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("E")
           [[ "$1" == $flpe ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed floating point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("Ep")
           [[ "$1" == $pflp ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed positive floating point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    ("En")
           [[ "$1" == $nflp ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed negative floating point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
    (*)
           [[ "$1" == $flp  ]] && { indic=1 ; errnum=0 ; }
           errstr=" 1   | $1 failed floating point real validation"
           (( indic != 1 )) && ledesc+=("$errstr") ;;
   esac

 fi

 # -----------------------------------------------------
 # Function outputs a status or a string

 # Avoid errnum 127 as it commonly indicates "Program Not Found".
 (( ${#ledesc[@]} == 0 )) && ledesc="0 | successful termination"
 
 if [ "$vb" -ge 3 ]; then
   printf '%s\n' "args: $@ | \$@"
   printf '%s\n' "indic: $indic"
 fi

 # Mode: rec
 #  Topic: Line Continuation with backslash \
 #    Desc: Commands can be split anywhere by adding the line
 #    + continuation backslash \ character as the last character of the
 #    + line followed by a line-break.
 #    Exception: The continuation character is not required when a
 #    + line-break is inserted at a point where a command cannot end
 #    + such as after the && or || operators.
 #  Topic: Failures of the conditional expression { p && q || r }
 #    Desc: { p && q || r } assumes that q does not fail.  If q fails
 #    + or returns a false logical value, r will execute even if p
 #    + succeeds.
 # # End of rec 
 
 # fnstatus | 0 designates success | otherwise failure
 local fnstatus
 if (( outval == 0 )); then
   fnstatus=$(( indic == 1 ? 0 : 1 ))  # conditional operator
   (( errnum > 0 )) && fnstatus=$errnum
   return "$fnstatus"
 else
   # indic=1 designates confirmation, otherwise refutation
   (( ledescval != 1 )) && echo "$indic" \
      || { echo "errno" ; printf '%s\n' "${ledesc[@]}" ; }
 fi

}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-parade-numeric ()
{
 num="3"
 if linge-numeric -I "$num"
 then
   printf '%s\n' "$num is numeric integer"
 else
   printf '%s\n' "$num fails numeric integer validation"
 fi

 num="3.142"
 # condition equivalent to `if linge-numeric -I "$num"`
 if { linge-numeric -I "$num" ; }
 then
   printf '%s\n' "$num is numeric integer"
 else
   printf '%s\n' "$num fails numeric integer validation"
 fi
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-details-ngnum ()
{
 HDG "Option Summary"

 printf '%s\n' "-f STY, --fmt=STY"
 printf '%s\n' "   Format style for numerals."

 PF "   STY    | Description"
 PF "   ---------------------------------------------"
 PF "   bc     | Utilises basic calculator program bc"
 PF "   fxdpnt | Fixed-point numeric notation"
 PF "   fltpnt | Floating-point numeric notation"
 PF "   ngre   | Negative Regular Expression"
    
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-usage-ngnum ()
{
 case $1 in
  (1)
     PF " {-V, --version}"
     PF " {-v LV, -v=LV, -vLV, --verbosity LV, --verbosity=LV}"
     PF " {-h, --help}, {-u LV, -u=LV, -uLV, --usage=LV}"
     PF " {-f STY, --fmt=STY} | STY: [nF|nE]"
     ;;
  (2)
     HDG "Usage"
     printf '%s\n' " linge-ngnum -1.358 | Result: "
     printf '%s\n' " linge-ngnum  8.531 | Result: "
     ;;
  (*)
     printf '%s\n' " "
     ;;
 esac
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-ngnum ()
{

 if (( $# == 0 )); then
   printf '%s\n' "Invoke \`linge-ngnum -h' for details."
   return 0  
 fi
 
 local impl="bc" outval=0

 while (( $# > 0 )); do
   opt="$1"
   case $opt in
    ("-V"|"--version")
      local -r etdate="V01 Jul 2021 Wk27"
      printf "%s\n" " $etdate Matematiker Christopher Dimech "
      return 0
      ;;
    #------------------------------
    ("-v"|"--verbosity")      vb="$2"      ; shift ; shift ;;
    ("-v="*|"--verbosity="*)  vb="${1#*=}" ; shift 1 ;;
    ("-v"*) vb="${1#-v}" ; shift 1 ;;
    #------------------------------
    ("-h"|"--help")
      printf '%s\n' "Validates numeric formats."
      linge-details-ngnum
      return 0
      ;;
    ("-u"|"--usage")
      printf '%s\n' ""
      linge-usage-ngnum "$vb"
      return 0
      ;;
    # ..............................
    ("-o") outval=1 ; shift 1 ;;
    ("-f"|"--frmt")      frmt="$2"      ; shift ; shift ;;
    ("-f="*|"--frmt="*)  frmt="${1#*=}" ; shift 1 ;;
    # ..............................
    ("--") shift 1 ; break ;;
    (*) break ;;
   esac  #  case ends here
 done  # while ends here

 # ---------------------------------------------------------------
    
 if (( outval == 1 )); then
   k=$( linge-numeric -o -En "$1" )
 else
   k=$( echo "$1 < 0" | bc -l )
   [[ "$k" =~ "error" ]] && k=0
 fi
 
 if (( outval == 0 )); then
   local fnstatus=1            # failure
   (( k == 1 )) && fnstatus=0  # success
   return "$fnstatus"
 else
   echo "$k"
 fi
 
}

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

linge-numeric-pintgr ()
{

 ## The $? instruction
 #  $? gets the Exit Status of last executed command.
 #  Running the same function in separate bash sessions yields
 #  independent values for $? because sessions running in separate
 #  command line console terminals use independent environments.

 local vb=0
 local impl="last-command-status"
 (( $# > 1 )) && impl="$2"

 case $impl in
  ("last-command-status")
    linge-numeric -Ip "$1"
    rstatus=$?
    (( vb > 0 )) && echo "last-command-status \$? | $rstatus"
    return "$rstatus"
    ;;
  (*)
    r=$( linge-numeric -o -Ip "$1" )
    (( r == 1 )) && return 0 || return 1
    ;;
 esac

}
    
# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

linge-usage-nearint ()
{
 case $1 in 
  (1)
     PF " {-V, --version}"
     PF " {-v LV, -v=LV, -vLV, --verbosity LV, --verbosity=LV}"
     PF " {-h, --help}, {-u LV, -u=LV, -uLV, --usage=LV}"
     ;;
  (2)
     HDG "Usage"
     ;;
  (*)
     printf '%s\n' " "
     ;;
 esac
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-nearint ()
{

 while (( $# > 0 )); do
   opt="$1"
   case $opt in
    ("-V"|"--version")
      local -r etdate="V01 Jul 2021 Wk27"
      printf '' "$etdate Strategist Christopher Dimech" ""
      return 0
      ;;
    # ..............................
    ("-v"|"--verbosity")  vb="$2" ; shift ; shift ;;
    ("-v="*|"--verbosity="*) vb="${1#*=}"; shift 1 ;;
    ("-v"*) vb="${1#-v}"; shift 1 ;;
    # ..............................
    ("-h"|"--help")
      printf '%s\n'   "linge-nearint OPER NUMA NUMB"
      printf '%s\n'   "Rounds a floating point number."
      printf '%s\n'   "OPER  Operator."
      printf '%s\n'   "NUMA  First number."
      printf '%s\n\n' "NUMB  Second number."
      return 0
      ;;
    ("-u"|"--usage")
      HDG "Usage"
      printf '%s\n' "  linge-nearint 18.21"
      printf '%s\n' "  linge-nearint 34.55"
      printf '%s\n' "  linge-nearint / 21.3 34.55"
      return 0
      ;;
    # ..............................
    (*) break ;;
    # ..............................
   esac  #  case ends here
 done  # while ends here

 # -----------------------------------------------------
 
 if (( $# > 3 )); then
   printf '%s\n' "More than two agrguments passed to linge-nearint"
 fi

 # using fixed-point number notation

 local psv=0 ngv=0
 if (( $# == 1 )); then
   fxpnt="$1"
 elif (( $# == 3 )); then
   oper="$1" ; anum="$2" ; bnum="$3"
   comp="$anum $oper $bnum"
   fxpnt=$( echo "$comp" | bc -l )
 else
   fxpnt=0
 fi

 psv=$( linge-numeric -o -Fp "$fxpnt" )
 ngv=$( linge-numeric -o -Fn "$fxpnt" )
 if (( psv == 1 )); then
   inear=$( echo "($fxpnt + 0.5) / 1" | bc )
 elif (( ngv == 1 )); then
   inear=$( echo "($fxpnt - 0.5) / 1" | bc )
 fi
 
 printf '%s\n' "$inear"

}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

## h1 * Printing multiple lines including warnings

linge-details-printf-multiple ()
{
 printf '%s\n' "Prints multiple lines of text, with alias set to \`pfm'"
 printf '%s\n' ""
 printf '%s\n' "Example: pfm -- \"-d DIR\""
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-usage-printf-multiple ()
{
 case $1 in
  (2)
     linge-usage-printf-multiple-en
     ;;
  (*)
     PF " linge-printf-multiple [OPTIONS] "
     PF "   Prints a heading"
     PF "   "
     PF " -V, --version"
     PF " -v LV, -v=LV, -vLV, --verbosity LV, --verbosity=LV"
     PF " {-u LV, -u=LV, -uLV, --usage=LV}, {-h, --help}"
     PF " -f STY, --fmt=STY} | STY: [nF|nE]"
     PF " -H, -H CNT, -H=CNT, -HCNT, --heading CNT, --heading=CNT"
     PF " -W, -W CNT, -W=CNT, -WCNT, --warning CNT, --warning=CNT"
     PF " -E, -E CNT, -E=CNT, -ECNT, --error CNT, --error=CNT"
     PF " -b CN, -b=CN, -bCN, --blu CN, --blu=CN"
     PF " -g CN, -g=CN, -gCN, --grn CN, --grn=CN"
     PF " -c CN, -c=CN, -cCN, --cyn CN, --cyn=CN"
     PF " -r CN, -r=CN, -rCN, --red CN, --red=CN"
     PF " -m CN, -m=CN, -mCN, --mgn CN, --mgn=CN"
     PF " -o CN, -o=CN, -oCN, --org CN, --org=CN"
     PF " {--colf CN, --colf=CN}, {-l CN, -l=CN, -lCN}"
     ;;
 esac
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-details-printf-multiple ()
{
 if (( $# >= 1 )); then
   if [[ "$1" == "fr" || "$1" == "it" ]]; then
     comlang="$1"
   else
     comlang="${LANG:0:2}"
     (( vb >=2 )) && printf '%s\n' "Using locale $LANG"
   fi
 else
   comlang="${LANG:0:2}"
   (( vb >=2 )) && printf '%s\n' "Using locale $LANG"
 fi

 case $comlang in
  ("fr")
    printf '\n%s\n' "Affiche du texte en couleur."
    printf '%s\n' "  linge-printf-multiple [OPTIONS] TEXT.."
    linge-details-printf-multiple-fr
    ;;
  ("it")
    printf '\n%s\n' "Visualizza il testo utilizzando il colore."
    printf '%s\n' "  linge-printf-multiple [OPTIONS] TEXT.."
    linge-details-printf-multiple-it
    ;;
  (*)
    printf '\n%s\n' "Displays coloured text."
    printf '%s\n' "  linge-printf-multiple [OPTIONS] TEXT.."
    linge-details-printf-multiple-en
    ;;
 esac
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

linge-printf-multiple ()
{
 local -r etdate="V01 2021 Jul 21 Wk27"  
 local -r author="Matematiker Christopher Dimech"  

 ## Set Graphic Rendition for coloured terminal display.
 #  Using tput command to access terminfo database capabilities. In
 #  1981, Mary Ann Horton made the first terminfo library, using human
 #  understandable names and improving access speed over termcap.

 # 8-bit (256, 2^8) colours
 local -r blu=$(tput bold)$(tput setaf 39)
 local -r grn=$(tput bold)$(tput setaf 46)
 local -r cyn=$(tput bold)$(tput setaf 51)
 local -r red=$(tput bold)$(tput setaf 196)
 local -r mgn=$(tput bold)$(tput setaf 201)
 local -r org=$(tput bold)$(tput setaf 208)

 # Select Graphic Rendition Zero (sgr0) resets to non-colour display
 local sgr=$(tput sgr0)
 local rst="$sgr" ctp=""
 
 # Local arguments plus other
 local vb=1  nwline=1  cn=0  nl=0  captr=0
 local comlang=""

 declare -a edverr  # declare array for error messages

 (( $# == 0)) && printf "%s\n" "$etdate $author"
 
 while (( $# > 0 )); do
   case $1 in
    ("-V"|"--version")            # { -V }
      printf "%s\n" "$etdate Strategist Christopher Dimech"
      return 0
      ;;
    # --------------------------------------------------
    ("-v"|"--verbosity")          # { -v NUM }
      linge-numeric-pintgr "$2"
      if (( $? == 0 )); then
        vb="$2" ; shift ; shift
      else
        edverr+=(" {-v NUM} NUM fails numeric validation")
	shift  
      fi
      ;;
    ("-v="*|"--verbosity="*)      # { -v=NUM }
      linge-numeric-pintgr "${1#*=}"
      if (( $? == 0 )); then
        vb="${1#*=}" ; shift 1
      else
	shift 1
        edverr+=(" {-v NUM} NUM fails numeric validation")
      fi
      ;;
    ("-v"*)                       # { -v NUM }
      linge-numeric-pintgr "${1#-v}"
      if (( $? == 0 )); then      # numeric match success
        vb="${1#-v}" ; shift 1
      else
	shift 1
        edverr+=(" {-vNUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    ("-h"|"--help")               # { -h LANG }
      linge-numeric-pintgr "$2"
      (( $? == 0 )) && { comlang="$2" ; shift ; shift ; }
      linge-details-printf-multiple "$comlang"
      return 0
      ;;
    ("-h="*|"--help="*)           # { -h=[LANG] }
      linge-numeric-pintgr "${1#*=}"
      (( $? == 0 )) && { comlang="${1#*=}" ; shift 1 ; }
      linge-details-printf-multiple "$comlang"
      return 0
      ;;
    ("-h"*)                       # { -h[LANG] }
      linge-numeric-pintgr "${1#-h}"
      (( $? == 0 )) && { comlang="${1#-h}" ; shift 1 ; }
      linge-details-printf-multiple "$comlang"
      return 0
      ;;
    # --------------------------------------------------
    ("-u"|"--usage")
      # { -u NUM, -u } allows optional argument value
      if { linge-numeric -Ip "$2" ; }; then
        usg="$2" ; shift ; shift
      else
	usg=1 ; shift 1
      fi
      linge-usage-printf-multiple "$usg"
      return 0
      ;;
    ("-u="*|"--usage="*)
      # { -u=2, -u= } allows optional argument value
      if linge-numeric -Ip "${1#*=}" ; then
        usg="${1#*=}" ; shift 1
      else
	usg=1 ; shift 1
      fi
      linge-usage-printf-multiple "$usg"
      return 0
      ;;
    ("-u"*)          # { -uNUM }
      if linge-numeric -Ip "${1#*-u}" ; then
        usg="${1#*-u}" ; shift 1
      else
	shift 1
        edverr+=(" {-uNUM} NUM fails numeric validation")
      fi
      linge-usage-printf-multiple "$usg"
      return 0
      ;;
    # --------------------------------------------------
    ("-n")                        # { -n }
      nwline=0 ; shift ;;
    # --------------------------------------------------
    ("-H"|"--heading")            # { -H NUM }
      ctp="$mgn"
      if linge-numeric -Ip "$2" ; then
        nl="$2" ; shift ; shift
      else
        nl=1 ; shift 1
	edverr+=(" {-H NUM} Num fails numeric verification")
      fi
      ;;
    ("-H="*|"--heading="*)        # { -H=NUM } 
      ctp="$mgn"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
        nl=1 ; shift 1
	edverr+=(" {-H=NUM} Num fails numeric verification")
      fi
      ;;
    ("-H"*)  # { -HNUM }
      ctp="$mgn"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
        nl=1 ; shift 1
	edverr+=(" {-HNUM} Num fails numeric verification")
      fi
      ;;
    # --------------------------------------------------
    ("-W"|"--warning")
      # { -W NUM, -W } allows optional argument value
      ctp="$blu"
      if linge-numeric -Ip "$2" ; then
        nl="$2" ; shift ; shift
      else
        nl=1 ; shift 1
      fi
      ;;
    ("-W="*|"--warning="*)
      # { -W=NUM, -W= } allows optional argument value
      ctp="$blu"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
        nl=1 ; shift 1
      fi
      ;;
    ("-W"*|"--warning"*)  # { -WNUM }
      ctp="$blu"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
        nl=1 ; shift 1
	edverr+=(" {-WNUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    ("-E"|"--error")
      # { -E NUM, -E } allows optional argument value
      ctp="$red"
      if linge-numeric -Ip "$2" ; then
        nl="$2" ; shift ; shift
      else
        nl=1 ; shift 1
      fi
      ;;
    ("-E="*|"--error="*)
      # { -E=NUM, -E= } allows optional argument value
      ctp="$red"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
        nl=1 ; shift 1
      fi
      ;;
    ("-E"*)          # { -ENUM }
      ctp="$red"
      if linge-numeric -Ip "${1#-E}" ; then
        nl="${1#-E}" ; shift 1
      else
        nl=1 ; shift 1
	edverr+=(" {-ENUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    ("-b"|"--blu")
      # { -b NUM, -b } allows optional argument value
      ctp="$blu"
      if linge-numeric -Ip "$2" ; then
	echo "blue $2 $?"
        nl="$2" ; shift ; shift
      else
	nl=1 ; shift 1
      fi
      ;;
    ("-b="*|"--blu="*)
      # { -b=NUM, -b= } allows optional argument value
      ctp="$blu"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
        nl=1 ; shift 1
      fi
      ;;
    ("-b"*)  # { -bNUM }
      ctp="$blu"
      if linge-numeric -Ip "${1#-b}" ; then
        nl="${1#-b}" ; shift 1
      else
	nl=1 ; shift 1
	edverr+=(" {-bNUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    ("-g"|"--grn")
      # { -g NUM, -g } allows optional argument value
      ctp="$grn"
      if linge-numeric -Ip "$2" ; then
        nl="$2" ; shift ; shift
      else
	nl=1 ; shift 1
      fi
      ;;
    ("-g="*|"--grn="*)
      # { -g=NUM, -g= } allows optional argument value
      ctp="$grn"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
	nl=1 ; shift 1
      fi
      ;;
    ("-g"*)  # { -gNUM }
      ctp="$grn"
      if linge-numeric -Ip "${1#-g}" ; then
        nl="${1#-g}" ; shift 1
      else
	nl=1 ; shift 1
	edverr+=(" {-gNUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    ("-c"|"--cyn")
      # { -c NUM, -c } allows optional argument value
      ctp="$cyn"
      if linge-numeric -Ip "$2" ; then
        nl="$2" ; shift ; shift
      else
	nl=1 ; shift 1
      fi
      ;;
    ("-c="*|"--cyn="*)
      # { -c=NUM, -c= } allows optional argument value
      ctp="$cyn"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
	nl=1 ; shift 1
      fi
      ;;
    ("-c")  # { -cNUM }
      ctp="$cyn"
      if linge-numeric -Ip "${1#-c}" ; then
        nl="${1#-c}" ; shift 1
      else
	nl=1 ; shift 1
	edverr+=(" {-cNUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    ("-r"|"--red")
      # { -r NUM, -r } allows optional argument value
      ctp="$red"
      if linge-numeric -Ip "$2" ; then
        nl="$2" ; shift ; shift
      else
	nl=1 ; shift 1 
	edverr+=(" {-r NUM} NUM fails numeric validation")
      fi
      ;;
    ("-r="*|"--red="*)
      # { -r=NUM, -r= } allows optional argument value
      ctp="$red"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
	nl=1 ; shift 1
      fi
      ;;
    ("-r"*)  # { -rNUM }
      ctp="$red"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
	nl=1 ; shift 1 
	edverr+=(" {-rNUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    ("-m"|"--mgn")
      # { -m NUM, -m } allows optional argument value
      ctp="$mgn"
      if linge-numeric -Ip "$2" ; then
        nl="$2" ; shift ; shift
      else
	nl=1 ; shift 1
      fi
      ;;
    ("-m="*|"--mgn="*)
      # { -m NUM, -m } allows optional argument value 
      ctp="$mgn"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
	nl=1 ; shift 1
      fi
      ;;
    ("-m"*)   # { -mNUM }
      ctp="$mgn"
      if linge-numeric -Ip "${1#-m}" ; then
        nl="${1#-m}" ; shift 1
      else
	nl=1 ; shift 1 
	edverr+=(" {-mNUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    ("-o"|"--org")
      # { -o NUM, -o } allows optional argument value
      ctp="$org"
      if linge-numeric -Ip "$2" ; then
        nl="$2" ; shift ; shift
      else
	nl=1 ; shift 1
      fi
      ;;
    ("-o="*|"--org="*)
      # { -o=NUM, -o= } allows optional argument value
      ctp="$org"
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
	nl=1 ; shift 1 
      fi
      ;;
    ("-o"*)  # { -oNUM }
      ctp="$org"
      if linge-numeric -Ip "${1#-o}" ; then
        nl="${1#-o}" ; shift 1
      else
	nl=1 ; shift 1 
	edverr+=(" {-oNUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    ("--colf")       # { --colf 233 }
      if linge-numeric -Ip "$2" ; then
        cn="$2" ; shift ; shift
      else
        cn=208 ; shift 1
	edverr+=(" {--colf NUM} NUM fails numeric validation")
      fi
      nl=1
      ctp=$(tput bold)$(tput setaf $cn) ; rst="$sgr"
      ;;
    ("--colf="*)     # { --colf=233 }
      if linge-numeric -Ip "${1#*=}" ; then
        cn="${1#*=}" ; shift ; shift
      else
        cn=208 ; shift 1
	edverr+=(" {--colf=NUM} NUM fails numeric validation")
      fi
      nl=1
      ctp=$(tput bold)$(tput setaf $cn) ; rst="$sgr"
      ;;
    # --------------------------------------------------
    ("-l")
      # {-l NUM, -l} allows optional argument value
      if linge-numeric -Ip "$2" ; then
        nl="$2" ; shift ; shift
      else
        nl=1 ; shift 1
      fi
      ;;
    ("-l="*)
      # { -l=NUM, -l= } allows optional argument value
      if linge-numeric -Ip "${1#*=}" ; then
        nl="${1#*=}" ; shift 1
      else
        nl=1 ; shift 1
      fi
      ;;
    ("-l"*)  # { -lNUM }
      if linge-numeric -Ip "${1#-l}" ; then
        nl="${1#-l}" ; shift 1
      else
        nl=1 ; shift 1
	edverr+=(" {-lNUM} NUM fails numeric validation")
      fi
      ;;
    # --------------------------------------------------
    (":") printf '%s\n' "Requires an argument value" ;;
    ("?") printf '%s\n' "Invalid option:" ;;
    ("--") shift 1 ; break ;;
    (*) opt_error=1 ; break ;;
    # --------------------------------------------------
   esac
 done
 
 # -----------------------------------------------------

 ## h2 PRINT Print text with regular or warning colour

 # alternative validation for integers using parameter expansion
 # var=12345
 # echo "${var//[0-9]/}"
 # case ${var//[0-9]/} in
 #   ?*) echo "var: string or non-integer" ;;
 #   *)  echo "var: integer" ;;
 # esac

 # echo "aggr: |${aggr[*]}|"
 # echo "nwline: $nwline | nl: $nl"

 # ---------------------------------------------------------------
 ## printf format descriptor
 #  When there are more arguments than declared in the printf format
 #  descriptor, the descriptor is repeated as necessary to consume all
 #  arguments.

 aggr=("$@")
 (( nwline == 1 )) && fs='\n' || fs=' '

 if (( ${#edverr[@]} > 0 )); then
   printf '\n%s%s%s\n' $red "List of detected errors" $sgr
   printf '%s\n' "${edverr[@]}"
   echo
 fi

 local rge='^[0-9]+$'
 if [[ "$nl" =~ $rge ]]; then

   impl="rnge"
   case $impl in
    # .............................
    # Implementation using array loop
    ("loop")
      local argc=$#
      (( nl > argc )) && nl=$argc
      for (( j=0; j<argc; j++ )); do
	(( j+1 <= nl )) && printf '%s%s%s${fs}' $ctp "${aggr[j]}" $rst
	(( j+1 > nl )) && printf '%s${fs}' "${aggr[j]}"
      done
      ;;
    # .............................
    # Implementation using array range
    ("rnge")
      (( nl > 0 ))  && printf "%s${fs}" "${ctp}${aggr[@]:0:nl}${rst}"
      (( nl < $# )) && printf "%s${fs}" "${aggr[@]:nl}"
      ;;
   esac

 fi

 (( nwline == 0 )) && echo
 
 return 0

}

# ------------------------------------------------------

# Define a bash shell function rather than an alias

pfm ()
{
  linge-printf-multiple "$@"
}

# ######################################################

## h1 * Set Aliases

## h2   * Use of Colour 

linge-register ()
{
 local blu=$(tput bold)$(tput setaf 39)
 local sga=$blu sgr=$(tput sgr0)
     
 local fm='%s\n'
 _PF="printf $fm"
 
 echo
 printf '%s\n' "edvart" "******"

 echo
 $_PF "For usage information invoke the -u command"
 $_PF "  edvart-molniya-comint -u"
 
 echo 
 $_PF "$sga edvart-molniya-comint $sgr"
 $_PF "   Displays matching patterns in plain-text data sets."

 echo 
 $_PF "$sga edvart-molniya-comint $sgr"
 $_PF "   Displays matching patterns in plain-text data sets."

 $_PF "$sga edvart-cygnium-engine $sgr"
 $_PF "   Tool for efficiently transferring and synchronizing files"
 $_PF "   between networked computers and storage devices by comparing"
 $_PF "   file modification times and sizes."

 $_PF "$sga edvart-curiplaya-tautona $sgr"
 $_PF "   Tool for efficiently transferring and synchronizing files"
}

# ############################################################

<<- "_comment"
* set alternatives for listing files in a unix-like terminal
_comment

linge-cmd-list ()
{
 local exec_rc=0
 case "$1" in
  ("-V"|"--version")
    local -r etdate="V01 Jul 2021 Wk27"
    printf '%s\n' "$etdate Strategist Christopher Dimech"
    return 0
    ;;
  ("-h"|"--help")
    printf "Searches input files for lines containing matches.\n"
    printf "rs   File transfer of achive.\n"
    printf "rsu  Update by skipping newer files on receiver.\n"
    printf "rrs  Rapid file transfer.\n"
    return 0
    ;;
  # -----------------
  ("-e"|"--exec") exec_rc=1 ; shift 1 ;;
  # -----------------
  (*)
    printf "Invoke \`linge-cmd-list -h' for details.\n"
 esac

 # -----------------------------------------------------

 if (( exec_rc == 1 )); then

   # use colour scheme when listing files in unix-like terminal
   alias ls='ls --color'
   alias dir='dir --color'
   alias vdir='vdir --color'
   alias grep='grep --color'
   alias fgrep='fgrep --color'
   alias egrep='egrep --color'

   # ..............................
   # list information about files

   alias ld='ls -d */'  # list directories

   alias ll='ls -alF'
   alias la='ls -A'
   alias l='ls -CF'
   alias lt='ls -lt'     # sort by date
   alias lx='ls -lXB'    # sort by extension

   alias la='ls -A'
   alias la='ls -aF'     # List all and file types
   alias ll='ls -alF'
   alias ll='ls -lF'     # List <dir> style
    
   alias lr='ls -lR'     # recursive ls
   alias ltr='ls -ltr'   # sort by date recursively
   alias lcr='ls -lcr'   # sort by change time
   alias lur='ls -lur'   # sort by access time

   alias lsr='ls -lSr'   # sort by size
    
 fi

}

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

## h2   * Utilities
## h3     * linge-cmd-util

linge-cmd-util ()
{
 local exec_rc=0
 case $1 in
   ("-V"|"--version")
     local -r etdate="V01 Jul 2021 Wk27"
     printf '%s\n' "$etdate Strategist Christopher Dimech"
     return 0
     ;;
   ("-h"|"--help")
     printf "Set aliases for utilities.\n"
     return 0
     ;;
   ("-e"|"--exec") exec_rc=1 ; shift ;;
   # .................
   (*)
     printf "Invoke \`linge-cmd-util -h' for details.\n"
 esac

 if (( exec_rc == 1 )); then

   # recursive listing of directories and files
   # list directories only with display depth `-L LEVEL`
   alias tdl='tree -d -L'
     
   # remove each given file
   alias rmi='rm -i'    # prompt before every removal
   alias rmf='rm -f'    # ignore non-existent files, never prompt

   # view text files, `less' does not read entire file before display
   alias l='less'       # faster than `more' with backward movement
   alias m='more'       # reads entire file before display

   # view pdf files
   alias pdfa='atril'   # view pdf files
   alias pdfe='evince'  # view pdf files
    
   # side-by-side file difference using command terminal width
   alias difside='diff -y -W $(( $(tput cols) - 2 ))'

   alias festivox='xsel | festival --tts'  # text to speech
   alias figlet_showfonts='showfigfonts'  # show figlet fonts

 fi

}

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

## h2   * Path locations

## h3     * linge-environ-admir

linge-environ-admir ()
{
 local exec_rc=0
 case $1 in
  ("-V"|"--version")
    local -r etdate="V01 Jul 2021 Wk27"
    printf '%s\n\n' "$etdate Strategist Christopher Dimech"
    return 0
    ;;
  ("-h"|"--help")
    printf "Set aliases for path locations.\n"
    printf "agenda: HOME/Agenda\n"
    printf "gnupa:  HOME/ActiveJobs/Books/Infocs/Gnupa\n"
    printf "tdr:    HOME/ActiveJobs/Reports/Tdr"
    return 0
    ;;
  # .................
  ("-e"|"--exec") exec_rc=1 ; shift ;;
  # .................
  (*)
    printf '%s\n' "Invoke \`linge-environ-admir -h' for details."
 esac # case ends here

 # --------------------------------

 # Set shortcuts to specific directories
 if (( exec_rc == 1 )); then
   alias agenda=${HOME}/Agenda
   alias gnupa=${HOME}/ActiveJobs/Books/Infocs/Gnupa
   alias tdr=${HOME}/ActiveJobs/Reports/Tdr
   alias tdrdev=${HOME}/05-Development
   alias hagbard='echo agenda gnupa tdrdev'
 fi

}

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

## h3 linge-aggr-util

linge-aggr-util ()
{
 local exec_rc=0
 case $1 in
  ("-V"|"--version")
    local -r etdate="V01 Jul 2021 Wk27"
    printf '%s\n\n' "$etdate Strategist Christopher Dimech"
    return 0
    ;;
  ("-h"|"--help")
    printf 'Set aliases for path locations.\n'
    printf 'agenda: HOME/Agenda\n'
    printf 'gnupa:  HOME/ActiveJobs/Books/Infocs/Gnupa\n'
    printf 'tdr:    HOME/ActiveJobs/Reports/Tdr'
    return 0
    ;;
  # .................
  ("-e"|"--exec") exec_rc=1 ; shift 1 ;;
  # .................
  (*)
    printf 'Invoke \`linge-aggr-util -h\` for details.\n'
    ;;
 esac

 if (( exec_rc == 1 )); then
   linge-cmd-list --exec
   linge-cmd-util --exec
   linge-environ-admir --exec
 fi
}

# ..............................................................

## h3 linge-environ-opcom

linge-environ-opcom ()
{
 # Prints useful directories.  
 sgr=$(tput sgr0) ; sga=$(tput setaf 200)
 
 printf "${sga}Useful Directories:"
 printf " cd ~/01chaos/tdr  cd admir/gungadin${sgr}"
}

# ======================================================

## h3 linge-usage-cal

linge-usage-calc ()
{
 case $1 in
  (1)
     printf '%s\n' "linge-calc OPTIONS EXPR"
     printf '%s\n' "-v LV, -v=LV, -vLV, --verbosity LV, --verbosity=LV"
     printf '%s\n' "-u LV, -u=LV, -uLV, --usage LV, --usage=LV"
     printf '%s\n' "{-V, --version}, {-h, --help}"
     ;;
  (2)
     HDG "Usage"
     printf '%s\n' "  linge-calc \"18.21 + 34.55\""
     printf '%s\n' "  linge-calc \"10^2\""
     printf '%s\n' "  linge-calc \"var=10 ; ++var\""
     printf '%s\n' "  linge-calc \"var=10 ; var++\""
     printf '%s\n' "  linge-calc \"10 > 5\""
     ;;
 esac	
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

## h3 linge-calc

linge-calc ()
{
 while (( $# > 0 )); do
   opt="$1"
   case $opt in
    ("-V"|"--version")
      local -r etdate="V01 Jul 2021 Wk27"
      pfm "$etdate Matematiker Christopher Dimech" ""
      return 0
      ;;
    # --------------------------------------------------
    ("-v"|"--verbosity")  vb="$2" ; shift ; shift ;;
    ("-v="*|"--verbosity="*) vb="${1#*=}"; shift 1 ;;
    ("-v"*) vb="${1#-v}"; shift 1 ;;
    # --------------------------------------------------
    ("-u"|"--usage")
      return 0
      ;;
    ("-h"|"--help")
      printf "%s\n" "Performs mathematical computations with bc."
      printf "%s\n" "EXPR  Mathematical expression."
      HDG "Supported Mathematical Functions"
      PF " s(x)    Sine of x, x is in radians"
      PF " c(x)    Cosine of x, x is in radians"
      PF " a(x)    Arctangent of x, arctanent returns radians"
      PF " l(x)    Natural logarithm of x"
      PF " e(x)    Exponential function of raising e to the value x"
      PF " j(n,x)  Bessel function of integer order n of x"
      PF " sqrt(x) Square root of number x"
      return 0
      ;;
    # ..............................
    (*) break ;;
    # ..............................
   esac  #  case ends here
 done  # while ends here

 rslt=$( echo "$1" | bc -l )

 echo "$rslt"
}

# ======================================================

## h3 linge-table

linge-table ()
{
 local vb=1 predicate_error=0 width=0 align="right"

 local _PF="printf %s\n"
 local _PF1="printf \n%s\n" _PF2="printf %s\n\n"

 # * Negative Prefixes (non- and un-)
 #   un-   Indicates not, lack of, or absence of something.
 #   non-  Used with any word, thus the most useful and versatile.
 
 while (( $# > 0 )); do  # $# is decremented by shift
  opt="$1"
  case $opt in
   ("-V"|"version")
     local -r etdate="V01 Jul 2021 Wk27"   
     $_PF2 " $etdate Strategist Christopher Dimech"
     return 0
     ;;
   ("-h"|"--help")
     $_PF "Prints parameters in table format"
     $_PF "Includes Dynamic Width Adjustment"
     return 0
     ;;
   ("-u"|"--usage")
     printf '\n%s' "Usage" "*****"
     printf '\n\n%s\n' "linge-calc OPTIONS EXPR"
     printf '%s\n\n' "-V, --version, -u, --usage, -h, --help"
     printf '%s\n' "Examples" "********"
     sa="\"The finest\" \"man I knew\""
     sb="\"Was our\" \"regimental bhisti,\" \"Gunga Din,\""
     $_PF1 "linge-table -w 18 --align \"l\" $sa"
     $_PF "linge-table -w 18 --align \"r\" $sb"
     return 0
     ;;
   # ..............................
   # separate values by a space {-v 2} or equal sign {-v=2}
   ("-v"|"--verbosity") vb="$2" ; shift 2 ;;
   ("-v="*|"--verbosity="*)
     vb="${1#*=}"
     linge-numeric -f "pI" "$vb"
     shift 1
     ;;
   # ..............................
   ("-w"|"--width") width="$2" ; shift 2 ;;
   ("-w="*|"--width="*) width="${1#*=}" ; shift 1 ;;
   #
   ("--align") align="$2" ; shift 2 ;;
   ("--align="*) align="${1#*=}" ; shift 1 ;;
   # ..............................
   #
   ("--")
          # leave loop at start of non-option arguments
          shift 1 ; break ;;
   ("-"*)
          # detect un-planned options
          predicate_error=1
          if (( vb >= 1 )); then
            printf '\n%s\n' "? unrecognised predicate $1"
          fi  
          shift 1
          ;;
   (*)
          # predicate error or start of non-option arguments
          if [ "$predicate_error" -eq 1 ]; then
	    predicate_error=2
            if (( vb >= 1 )); then
              printf '%s\n\n' ": unrecognised or missing value $1"
            fi
            shift 1
          else
	    if (( vb >= 3 )); then
              $_PF1 "Start of non-option arguments, leave option loop"
              printf '%s\n\n' "arg: $1"
            fi
            break
          fi
          ;;
  esac # case ends here
 done # while ends here

 # ................................
 # Dynamic adjustment of cell width

 local dynadj=0
 for arg in "$@"
 do
   # Alternative conditional | [ "${#arg}" -gt "$width" ]
   (( ${#arg} > width )) && { width=${#arg} ; dynadj=1 ; }
 done

 if (( dynadj > 0 && vb > 1 )); then
   printf "%s\n" "Dynamic Cell Width Adjustment"
   printf "%s\n\n" "width: Adjusted to $width"
 fi

 # -----------------------------------------------------
 
 local frmt="%${width}s  |  "
 if [ "$align" = "left" ] || [ "$align" = "l" ]; then
   frmt="%-${width}s  |  "
 fi
 (( vb > 1 )) && printf '%s\n' "frmt: $frmt"

 printf "$frmt" "$@" ; echo
}

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

## h1 * Terminal Prompt String

<< _comment
* Command terminal prompt and dircolors
Set directory path and file name for dircolors setup
See Marginalia Section [A]
_comment

# ..............................................................

## h2   * linge-console-tcodes

## h3   * linge-console-tcodes

linge-console-tcodes ()
{
 local vb=0 exec_rc=0
 local _PF="printf %s\n" _PF2="printf %s\n\n"

 # $# is decremented by shift
 while (( $# > 0 )); do
  opt="$1"
  case $opt in
   ("-V"|"version")
     local -r etdate="V01 Jul 2021 Wk27"   
     $_PF2 " $etdate Strategist Christopher Dimech"
     return 0
     ;;
   ("-h"|"--help")
     $_PF "Set console prompt with 8-bit (2^8 = 256) colours using"
     $_PF "the terminfo database."
     $_PF "Console Command Line Terminal is a text interface"
     $_PF "for executing unix-like programs."
     return 0
     ;;
   # ..............................
   # separate values by a space {-v 2} or equal sign {-v=2}
   ("-v"|"--verbosity") vb="$2" ; shift 2 ;;
   ("-v="*|"--verbosity="*) vb="${1#*=}" ; shift 1 ;;
   # ..............................
   ("-e"|"--exec") exec_rc=1 ; shift 1 ;;
   # ..............................
   # leave while loop at start of non-option arguments
   ("--") shift 1 ; break ;;
   ("-"*) $_PF "? unrecognised predicate $1" ; shift 1 ;;
   (*) $_PF ": unrecognised or missing value $1"; shift 1 ;;
  esac
 done # while ends here

 # .....................................................

 # printf format string repeats for all arguments present
 if (( vb >= 2 )); then
   printf '%s\n' "" "Option arguments" "****************"
   $_PF "" "vb: $vb" "exec_rc: $exec_rc" 
 fi
 
 opts="$@"
 if (( vb >= 1 ))
 then
   if (( $# > 0 )); then
     printf '%s\n' "" "Non-option arguments" "********************"
     printf '%s\n' "" "opts: $opts" ""
   else
     printf '%s\n' "" "# No non-option arguments encountered" ""
   fi
 fi

 # --------------------------------------------------------------

 # * 8-Bit tput processing for 256-colour capability
 #   The tput utility uses the terminfo database to generate
 #   terminal-dependent output to the shell.
 
 local sgr dblue gren3 morcd oranr
 sgr=$(tput sgr0)
 white=$(tput setaf 7)   ; dblue=$(tput setaf 33) 
 morcd=$(tput setaf 171) ; oranr=$(tput setaf 202)

 # Expansion of working directory as if it were a prompt string
 local workdr="\w" ; workdr=${workdr@P}  # parameter expansion

 # Determine length of PS1 prompt string
 local usernm="$USER" hostnm=`cat /proc/sys/kernel/hostname`
 local pstr="${usernm}@${hostnm}: $workdr"
 local plen="${#pstr}" ; wlen=$(( plen - hlen + 1 ))
 
 local sa sb wa wb
 if (( vb >= 3 )); then
   printf '%s\n' "Function variables" "******************" ""
   printf '%s\n' "workdr: $workdr"
   printf '%s\n' "usernm: $usernm"
   printf '%s\n' "hostnm: $hostnm"
   printf '%s\n' "pstr:   $pstr"
  
   sa="plen: $plen" ; wa=${#sa} ; wa=$(( wa + 2 ))
   sb="wlen: $wlen" ; wb=${#sb} ; wb=$(( wb + 2 ))

   # print plen and wlen in a table
   tabl_align="left-align"
   if [ "$tabl_align" = "left-align" ]; then
     frmt="%-${wa}s  |  %-${wa}s\n"
     printf '%s\n' "frmt: $frmt"
     printf "$frmt" "$sa" "$sb"
   elif [ "$tabl_align" = "righn-align" ]; then
     frmt="%${wa}s  |  %${wa}s\n"
     printf '%s\n' "frmt: $frmt"
     printf "$frmt" "$sa" "$sb"
   else
     printf "%s\n" "plen: $plen;|  wlen: $wlen" | column -t -s ';'
   fi
   
 fi

 # * Bash Shell has four console terminal command prompt variables.
 #   PS1  Expanded and used as the primary prompt string showing the
 #        System User Name, Machine Host Name, and Working Directory.
 #        For PS1, non-printing sequences are enclosed by \[ and \].
 #   PS0  Expanded and used by interactive shells after reading a
 #        command and before the command is executed.
 
 if (( wlen > 72 )); then
   # Working directory is printed on the next line.
   PS1="\n\[${dblue}\]\u\[${white}\]@\[${dblue}\]\h\[${white}\]:\n"
   PS1="$PS1+ \[${morcd}\]\w\n\[${oranr}\]"
 else
   PS1="\n\[${dblue}\]\u\[${white}\]@\[${dblue}\]\h\[${white}\]:"
   PS1="$PS1 \[${morcd}\]\w\n\[${oranr}\]"
 fi
   
 PS0="${sgr}" 

}

# ..............................................................

## h3 linge-prompt

linge-prompt ()
{
 linge-console-tcodes "$@"
}

# ..............................................................

## h2   * linge-console-ocbit-ecodes

linge-cnsl-ocbit-ecodes ()
{
 local exec_rc=0
 while (( $# > 0 )); do
   opt="$1"
   case $opt in
    ("-V"|"--version")
      local -r etdate="V01 Jul 2021 Wk27"
      printf '%s\n' "$etdate Strategist Christopher Dimech"
      return 0
      ;;
    ("-h"|"--help")
      printf "Uses an 8-bit colour command terminal prompt.\n"
      printf "Octa-Bit colour uses 256 (2^8) colours.\n"
      printf "Escape codes are used.\n"
      return 0
      ;;
    # ...............
    ("-e"|"--exec") exec_rc=1 ; shift 1 ;;
    # ...............
    (*) shift 1 ;;
   esac # case ends here
 done # while ends here

 # --------------------------------------------------------------

  if (( exec_rc == 1 )); then
   sgr="\033[39m"       ; cyan1="\e[38;5;51m"
   gold1="\e[38;5;214m" ; red1="\e[38;5;196m"

   # PS1 uses \[ and \] to begin and end a sequence of non-printing
   # characters.  Next line is used to print working directory.
   PS1="\n\[${cyan1}\]\u@\h:\n"
   PS1=$PS1"+ \[${gold1}\]\w\n\[${red1}\]"

   # PS0 is used after reading a command and before executing it.
   PS0="$sgr"  # set value of PS0
 fi
}

# ..............................................................

## h2   * linge-console-qdbit-ecodes

linge-cnsl-qdbit-ecodes ()
{
 local exec_rc=0
 while (( $# > 0 )); do
   opt="$1"
   case $opt in
    ("-V"|"version")
      local -r etdate="V01 Jul 2021 Wk27"
      printf '%s\n' "$etdate Strategist Christopher Dimech"
      return 0
      ;;
    ("h"|"--help")
      printf "Use 4-bit colour terminal command prompt.\n"
      printf "Quad-Bit colour uses 16 (2^4) colours.\n"
      printf "Escape codes are used.\n"
      return 0
      ;;
    # .............................
    ("-v"|"--verbosity")     vb="$2"      ; shift ; shift ;;
    ("-v="*|"--verbosity="*) vb="${1#*=}" ; shift 1 ;;
    # .............................
    ("--exec") exec_rc=1 ; shift ;;
    # .............................
    (*) exec_rc=0 ;;
   esac # case ends here
 done # while ends here

 # --------------------------------
 
 if (( exec_rc == 1 )); then
   cyn="\e[01;36m" ; ylw="\e[01;33m"  # bold cyan and bold yellow
   red="\e[01;31m" ; sgr="\033[39m"   # bold red and regular foreground

   # PS1 encloses non-printing characters with \[ and \]
   # Print working directary \w on next line
   PS1="\n\[${cyn}\]\u@\h:\n"
   PS1=$PS1"+ \[${ylw}\]\w\n\[${red}\]" # print working directory

   # PS0 is used after reading a command and before executing it.
   PS0="${sgr}"
 fi

}

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

## h1 * Set key-maps and term-colours

## h2 linge-console-keymap

linge-console-keymap ()
{
 local exec_rc=0
 local narg="$#"
 while (( $# > 0 )); do
   opt="$1"
   case $opt in
    ("-V"|"version")
      local -r etdate="V01 Jul 2021 Wk27"
      printf "$etdate Strategist Christopher Dimech"
      return 0
      ;;
    ("h"|"--help")
      printf "Prints first set of lines from named files.\n"
      printf "\$1 NUM  Number of lines to print.\n"
      printf "\$2 DIR  Directory.\n"
      return 0
      ;;
    # ................
    ("-e"|"--exec") exec_rc=1 ; shift ;;
    # ................
    (*)
      printf '%s\n' "Invoke \`linge-console-keymap -h' for details."
      break
      ;;
   esac # case ends here
 done # while ends here

 # --------------------------------------------------------------
 
 # Tasks
 # 1. re-map modifier keys for dvorak keyboard
 # 2. set ls colour scheme when in a unix-like terminal
 #    -b option specifies the bourne again shell

 # LINGE_TRK  Variable tracking path to linge utilities  

 # LSCOLR_DFLT="$LS_COLORS"
 # LS_COLORS=${LS_COLORS}:"di=1;31:ex=1;31"
 # export LS_COLORS

 # set environment variable for ls command
 LS_COLORS="di=4;34:ex=1;31"

 # Using ${HOME} because ~/Opstk is not expanded but treated literally
 linge_trk="${HOME}/Opstk/bin/gungadin-1.0/linge"
 echo "linge_trk: ${linge_trk}"

 # Reset LS_COLORS used by { ls --color=auto }"
 if (( exec_rc == 1 )); then
   linge-console-tcodes
   eval "$( dircolors -b ${linge_trk}/linge-dircolors )"
   xmodmap ${linge_trk}/linge-xmodmap  # re-maps Ctrl, Meta, Super
 fi

}

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

## h2 linge-fountainhead-usage

linge-fountainhead-usage ()
{
 case $1 in
  (1)
     HDG " Gungadin-Linge"
     pfm " linge-fountainhead [OPTIONS]"
     pfm "  {-v VB, -v=VB, -vVB, --verbosity VB, --verbosity=VB}"
     pfm "  {-u LV, -u=LV, -uLV, --usage LV, --usage=LV}"
     pfm "  {-h, --help}, {-V, --version}"
     ;;
 esac    
}

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

## h2 linge-fountainhead-details

linge-fountainhead-details ()
{
  local -r locale="$LANG"

  case $1 in
   (1)
     HDG " TODO"
     pfm " linge-fountainhead [OPTIONS]"
     ;;
 esac    
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

## h1 ** Executes the configuration provided by the linge resources  

# Uses a here-document for multi-line commenting.
# The hyphen in <<- is used to ignores leading tab characters.
# Quoting the limit string _comment displays variable names verbatim,
# without command substitution.

<<- "_comment"
* Command terminal prompt and dircolors
Set directory path and file name for dircolors setup
See Marginalia Section [A]
_comment

## h2 linge-fountainhead

linge-fountainhead ()
{
 local -r etdate="V01 2021 Jul 21 Wk27"
 local -r author="Strategist Christopher Dimech"

 if (( $# <= 0 )); then
   printf '%s\n' "linge-fountainhead"
   printf '%s\n' "$etdate $author"
 fi    

 # -----------------------------------------------------
 impl="while"
 if [[ "$impl" == "while" ]]; then
 
   while true; do
     read -p "Update Gungadin-Linge Console" execin
     case $execin in
      [Yy]* ) exec_rc=1 ; break ;;
      [Nn]* ) exec_rc=0 ; break ;;
      [Qq]* ) exec_rc=0 ; break ;;
          * ) echo "Answer with \`Yes', \`y', \`No', \`n'."
              echo "Use \`Q' or \`q' to quit"
	      ;;
     esac
   done

 # -----------------------------------------------------
 elif [[ "$impl" == "select" ]]; then

   echo "Update Gungadin-Linge Console"
   select execin in "Yes" "yes" "Y" "y" "No" "no" "N" "n"; do
     case $execin in
      Yes ) exec_rc=1 ; break ;;
      No  ) break ;;
      *   ) echo "Answer with \`Yes', \`y', \`No', \`n'."
            echo "Use \`Q' or \`q' to quit"
	    ;;
     esac
   done

 fi

 # -----------------------------------------------------
      
 local exec_rc=""
 while (( $# > 0 )); do
   opt="$1"
   case $opt in
    ("-V"|"version")
      printf '%s\n' "$etdate $author"
      printf '%s\n' "Incorporates the Gungadin-Linge Bash Shell"
      printf '%s\n' "functionality to the Command Line Terminal Console"
      return 0
      ;;
    #------------------------------
    ("-v"|"--verbosity")     vb="$2"      ; shift ; shift ;;
    ("-v="*|"--verbosity="*) vb="${1#*=}" ; shift 1 ;;
    ("-v"*) vb="${1#-v}" ; shift 1 ;;
    #------------------------------
    ("-h"|"--help")
      shift 1
      printf '%s\n' "Reads and executes the user .bashrc resource"
      printf '%s\n' "configuration file using the source command."
      printf '%s\n' "Bash functions return integer error codes from 0"
      printf '%s\n' "to 255.  A zero exit status indicates success."
      linge-fountainhead-details
      return 0
      ;;
    #------------------------------
    ("-u"|"--usage")
      linge-fountainhead-usage "$usg"
      usg="$2" ; shift 2
      return 0
      ;;
    ("-u="*|"--usage="*)
      linge-fountainhead-usage "$usg"
      usg="${1#*=}" ; shift 1
      return 0
      ;;
    ("-u"*)
      linge-fountainhead-usage "$usg"
      usg="${1#-v}" ; shift 1
      return 0
      ;;
    #------------------------------
    (*)
      printf '%s\n' "Invoke \`linge-source-rc -h' for details."
      break
      ;;
   esac # case ends here
 done # while ends here

 # -----------------------------------------------------
 
 # alternatively use `source ~/.bashrc` or `. ${HOME}/.bashrc'
 (( exec_rc == 1 )) && source "${HOME}/.bashrc"

 # Bash functions return an integer error code with a zero exit status
 # indicating success.  A non-zero exit status indicates failure.  Exit
 # statuses fall between 0 and 255. 
 return 0

}

alias LFD='linge-fountainhead' 

# ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

## h1 * Call Gungadin Functionality

## h2   linge-launch

linge-launch ()
{
 local edvart_rc=0
 local deploy="go-on-error"

 while (( $# > 0 )); do
   opt="$1"
   case $opt in
    ("-V"|"version")
      local -r etdate="V01 2021 Jul 21 Wk27"
      printf '%s\n\n' "$etdate Strategist Christopher Dimech"
      return 0
      ;;
    ("-h"|"--help")
      printf '%s\n' "Reads and executes the user .bashrc resource"
      printf '%s\n' "configuration file using the source command."
      printf '%s\n' "Bash functions return integer error codes from 0"
      printf '%s\n' "to 255.  A zero exit status indicates success."
      return 0
      ;;
    # ................
    ("-v"|"--verbosity")     vb="$2"      ; shift ; shift ;;
    ("-v="*|"--verbosity="*) vb="${1#*=}" ; shift 1 ;;
    # ................
    ("--edvart-rc") edvart_rc=1 ; shift ;;
    # ................
    ("--go-on-error")     # Control Status, continue and allow failure
      deploy="go-on-error"
      shift ;;
    ("--nogo-on-error")   # Control Status, refuse to proceed on error
      deploy="nogo-on-error"
      shift ;;
    # ................
    ("--") shift ; break ;;
    ("-"*)
      # this pattern follows -- because it always over-rides --
      printf '%s\n' "Wrong parameter."
      [ "$deploy" = "go-on-error" ] && shift 1
      [ "$deploy" = "nogo-on-error" ] && return 1
      ;;
    (*)
      printf '%s\n' "Invoke \`linge-launch -h' for details."
      [ "$deploy" = "go-on-error" ] && break
      [ "$deploy" = "nogo-on-error" ] && return 1
      ;;
   esac  # case ends here
 done  # while ends here

 # -----------------------------------------------------

 echo 
 linge-console-keymap --exec  # colour and keymap utils
 linge-aggr-util --exec       # aggretate of other utils

 linge_trkrc="${HOME}/Opstk/bin/gungadin-1.0/linge"
 source "${linge_trkrc}/linge-gungadin-usage.rc"

 # set resource path and enable functionality in edvart.rc
 if (( edvart_rc == 1 )); then
   edvart_trkrc="${HOME}/Opstk/bin/gungadin-1.0/linge/edvart"
   source "${edvart_trkrc}/edvart.rc"
 fi
 
}

# ++++++++++++++++++++++++++++++++++++++++++++++++++++++

# launch configuration provided by linge.sh
linge-launch --edvart-rc

# ######################################################

## m1 * Marginalia
#                      _           _ _      
#  _ __  __ _ _ _ __ _(_)_ _  __ _| (_)__ _ 
# | '  \/ _` | '_/ _` | | ' \/ _` | | / _` |
# |_|_|_\__,_|_| \__, |_|_||_\__,_|_|_\__,_|
#                |___/                      

# ......................................................

## m2 MA Bash Conditional Expressions

# Conditional expressions are used by the compound command `[[  ]]`

# -v varname
#    True if variable varname is set (has been assigned a value).
# -z string
#    True if the length of string is zero.
# -n string
#    True if the length of string is non-zero.

# ......................................................

# Example: Redirection construct without indentation

# cat <<- "_label"
# grep -ir --exclude=\*.el --include=\*.{org,texi}"
#   -C 8 "hilbert" /marshall "
# _label

# ......................................................

# Example: Indentation with tabs and variable names 

# <tab> cat <<- "_label"
# <tab> Searches input files for lines containing matches.
# <tab> $@ ARGS  Array of all arguments.
# <tab> _label

# ......................................................

## m2   @mc  setxkbmap and xmodmap

# Set keyboard layout map with setxkbmap.
# `setxkbmap -help`   Prints setxkbmap usage.
# `setxkbmap -query`  Prints current keyboard layout.
# `setxkbmap -layout us -variant dvorak`  Sets dvorak layout.

# Modify key and pointer button mappings with xmodmap.
# `xmodmap -help`  Print usage informanion. 
# `xmodmap -pm`    Print modifier map.

# Re-map Ctrl, Alt, Hyper, and Super keys.
# To display key-map table, use `-pke` option
#   `xmodmap -pke | grep "Control\|Alt\|Meta\|Super"`

# ......................................................

## m2   @mf  4-Bit Colour Codes

#   |---------------------------------------|
#   | Special Attribute Codes               |
#   |---------------------------------------|
#   | None  00 | Bold    01 | Underscore 04 |
#   | Blink 05 | Reverse 07 | Concealed  08 |
#   |---------------------------------------|

#   |------------------------------------------------|
#   | Foreground Color Codes: For Text               |
#   |------------------------------------------------|
#   | Black 30   | Red     31 | Green 32 | Yellow 33 |
#   | Blue  34   | Magenta 35 | Cyan  36 | White  37 |
#   | Regular 39 |                                   |
#   |------------------------------------------------|

# ......................................................
#  [BRF] Automate values using Bash Shell Parameter Expansion
  
#  The Colon Command `:` at the beginning expands arguments and
#  performs redirections only, without executing the line.

# linge-molniya-region using parameter expansion

# ######################################################

# file ends here [linge.rc]
