args

#!/usr/bin/env bash
#
# ############################################################################
# Project: xSHELL (none)
# File...: args
# Created: Friday, 2022/02/11 - 20:09:07
# Author.: @fbnmtz, fgm (fabiano.matoz@gmail.com)
# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~~·~·~·~·~·~·~·~
# Last Modified: Saturday, 2025/08/02 - 07:56:50
# Modified By..: @fbnmtz, (fabiano.matoz@gmail.com)
# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~~·~·~·~·~·~·~·~
# Version: 0.2.28.1899
# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~~·~·~·~·~·~·~·~
# Description: 
#  >
# ############################################################################
# HISTORY:
#

_xLIB_ARGS_=true;

use hashs system utils

# update text used in function 'xusage'
    # @param $1 -> string to customize each text of help sections. Use this pattern:
        # -<option>="<text>"
    # <options> identify a section and it can be:
        # -h or --header
        # -p or --param
        # -b or --body
        # -f or --footer
# "<text>" is the string associated to this section and is required to be inside ""
xhelp(){
    # loop all params
    for param in "$@"; do
        # split key and value
        key=$(echo "$param" | cut -d '=' -f1)
        val=$(echo "$param" | cut -d '=' -f2)
        
        # check key arg
        case $key in
            -p|--param ) 
                    param_id="$(echo "$val" | cut -d '+' -f1)"; 
                    param_text="$(echo "$val" | cut -d '+' -f2-3)";
                    Hash.put "$args_hash" "$param_id" "$param_text";;
                    
            -b|--body   ) __HELP_BODY__+="$val" ;;
            -h|--header ) __HELP_HEADER__+="\n$val\n" ;;
            -f|--footer ) __HELP_FOOTER__+="$val" ;;
            --long-usage) __HELP_SHOW_ARGS__=true ;;
        esac
    done

    # set vars VERSION, _CREATED_AT_, _AUTHOR_NAME_
    .xs --init

    __HELP_USAGE__="usage: \n  ${GREEN}$APP${RESET} "
    if [ $(Hash.count "$args_hash") -le 10 ] || [ -n "$__HELP_SHOW_ARGS__" ]; then
        __HELP_USAGE__+="$(
            Hash.keys "$args_hash" | \
            sed 's/,--.[a-z,-]*//g' | \
            sed 's/,.[a-z,-]*//g' | \
            sed 's/^/[/g' | \
            sed 's/$/]/g' | \
            tr -s '\n' ' '
        )" 

        if [ -n "$RED" ]; then 
            # apply colors
            __HELP_USAGE__=${__HELP_USAGE__//-/${MAGENTA}-}
            __HELP_USAGE__=${__HELP_USAGE__//</${YELLOW}<}
            __HELP_USAGE__=${__HELP_USAGE__//\]/${RESET}\]}
            
            # TODO: optional arguments highlighting
            __HELP_USAGE__=${__HELP_USAGE__//'{'/${YELLOW}'{'}
        fi
    else
        __HELP_USAGE__+="[OPTIONS] "
    fi
}

# show usage information/help
# usage: xusage <options>
# `-> <options> can be:
#  -f|--field-error <field_name>  : raise error when a field is empty
#  -m|--missing-param <param_name> : raise error when a required param is missing
#  -r|--reject-unknow <option>     : raise error when a unknow option is used
#  -c|--custom <text>              : custom text to show on usage
#  -h|--help                     : show help message
#  -v|--version                  : show version of this script
xusage(){
    # Function to format help options with standard spacing on Darwin systems
    helpOptionsDarwin() {
        local max_length=0
        local options=()

        # Find the maximum length of the options
        while IFS= read -r line; do
            # Extract the option key (first word) from the line
            local option=$(echo "$line" | cut -d ':' -f 1)
            # Determine the length of the option key
            local length=${#option}
            # Update the maximum length if the current option key is longer
            if [ $length -gt $max_length ]; then
                max_length=$length
            fi
            # Add the entire line to the options array
            options+=("$line")
        done <<< "$(Hash.all "$args_hash")"

        # Format the options with standard spacing
        for option in "${options[@]}"; do
            # Extract the option key (first word) from the option
            local key=$(echo "$option" | cut -d ':' -f 1)
            key=${key/\:/ }
            # Extract the description (remaining words) from the option
            local desc=$(echo "$option" | cut -d ':' -f 2-)
            desc=$(echo "$desc" | cut -d '+' -f1)
            # Print the option key and description with standard spacing
            printf "     %-${max_length}s   %s\n" "$key" "$desc"
        done
    }

    # Function to format help options with standard spacing on Linux systems
    helpOptionsLinux(){
        for h in $(
            Hash.all "$args_hash" |      # get all hashes \
            sed "s/:/:/g" |             # add blue color to options description':'\
            sed "s/^-/:-/g" |           # add color to options/flags \
            sed 's/ /./g'               # replace ' ' with '.'  
        ); do
            b=$(echo -e $h | cut -d '+' -f2)
            # echo "'$b' - '$block'"
            if [ -n "${b// }" ]; then 
                [ "${b}" != "${block// /.}" ] && block="${b}" \
                    && __HELP_OPTIONS_DESCRIPTION__+="\n${BLUE}->:$block;${RESET}\n"
                # echo
            else 
                if [ -z "$outblock" ];then
                    block="Available.Options" && __HELP_OPTIONS_DESCRIPTION__+="\n${BLUE}->:$block;${RESET}\n"
                    outblock=true
                fi
                # [ -z "$block" ] && block="Available options" && __HELP_OPTIONS_DESCRIPTION__+="\n->:$block;\n"
            fi
            __HELP_OPTIONS_DESCRIPTION__+="$(echo -e ${h//./ } | cut -d '+' -f1)\n" 

            # apply colors
            if [ -n "$RED" ]; then 
                # arguments description highlighting
                __HELP_OPTIONS_DESCRIPTION__=${__HELP_OPTIONS_DESCRIPTION__//\:/${BLUE}\:}
                # flags highlighting
                __HELP_OPTIONS_DESCRIPTION__=${__HELP_OPTIONS_DESCRIPTION__//-/${MAGENTA}-}
                # block highlighting
                __HELP_OPTIONS_DESCRIPTION__=${__HELP_OPTIONS_DESCRIPTION__//->/${BLUE}->}
                # required arguments highlighting
                __HELP_OPTIONS_DESCRIPTION__=${__HELP_OPTIONS_DESCRIPTION__//</${YELLOW}<}
                # required arguments closing 
                __HELP_OPTIONS_DESCRIPTION__=${__HELP_OPTIONS_DESCRIPTION__//>/>${BLUE}}

                # TODO: optional arguments highlighting
                __HELP_OPTIONS_DESCRIPTION__=${__HELP_OPTIONS_DESCRIPTION__//"{"/"${YELLOW}{"}
            fi
        done

        __HELP_OPTIONS_DESCRIPTION__=$(echo "${__HELP_OPTIONS_DESCRIPTION__//./ }" | \
            awkColumn "-s=:" | \
            sed "s/;/:/g" | \
            sed 's/,/,  /g' )
    }
    
    # generate default help text if user not difined one
    [ -z "$__HELP_USAGE__" ] && xhelp --long-usage
    [ -n "$_ARGS_DEBUG" ] && xrunDebug "${xRUN_ARGS[@]}"
    
    case "$1" in
        -f|--field-error)
            xhelp --long-usage
            # remove header info on this error msg
            __HELP_HEADER__=''
            __exit_code=3 
            __usage_msg="${RED}Error!${RESET} empty value for ${YELLOW}'$2'${RESET} param.${RESET}\n\n" 
        ;;

        -m|--missing-param)
            xhelp --long-usage
            # remove header info on this error msg
            __HELP_HEADER__=''
            __exit_code=1 
            __usage_msg="${RED}Error!${RESET} Missing required param.${RESET}\n\n" 
        ;;
        -r|--reject-unknow)
            xhelp --long-usage
            # remove header info on this error msg
            __HELP_HEADER__=''
            __usage_msg="${RED}Error!${RESET} invalid option ${YELLOW}($2)${RESET}.${RESET}\n\n" 
        ;;
        -c|--custom)
            xhelp --long-usage
            __exit_code=4        
            __usage_msg="$2\n\n" 
        ;;
        -h|--help)
            xhelp
            __usage_full=true
        ;;
        -v|--version)
            echo "$_CURRENT_VERSION_"; exit
        ;;
        *) 
            __exit_code=0      
            __usage_msg="" 
        ;;
    esac

    # print debug info
    # [ -n "$_ARGS_DEBUG" ] && xrunDebug  "${xRUN_ARGS[@]}" ;
    
    # prints initial help text
    echo -e "${__HELP_HEADER__}\n${__usage_msg}${__HELP_USAGE__}"

    if [ -n "$__usage_full" ]; then
        # help body text (before params/args)
        [ -n "$__HELP_BODY__" ] && echo -e "\n${__HELP_BODY__}" 
        # [ -z "$block" ] && echo -e "Available options:" || echo -e "$block"
        
        # get all key/values from main hash
        #     pairs stored as 'key:value'. We parse to ':key:value' 
        #       --> sed to add ':' in begin of each line 
        #       --> column to equaly expand texts
        # Hash.all "$args_hash" | sed 's/^-/:-/g' | sed 's/,/,:/' | column -t -s ':'

        # case sys.os in
        case $(xsys.os) in
            # Darwin) __HELP_OPTIONS_DESCRIPTION__="\n$(helpOptionsDarwin)\n" ;;
            # Linux ) helpOptionsLinux ;;
            *) __HELP_OPTIONS_DESCRIPTION__="\n$(helpOptionsDarwin)\n" ;;
        esac

        echo -e "${__HELP_OPTIONS_DESCRIPTION__}${RESET}"
        
        # not null? prints footer 
        [ -n "$__HELP_FOOTER__" ] && echo -e "${__HELP_FOOTER__}\n" 
        echo -e "${GREEN}v${_CURRENT_VERSION_}${RESET} on ${YELLOW}${_UPDATED_AT_}${RESET} - writen by ${BOLD}${CYAN}${_AUTHOR_NAME_}${RESET}"
    
    else
        echo -e ""
    fi
    # quit with error code
    exit $__exit_code
}

# xarg: id="-h,--help" var=variable:value
    #   --> dynamic create ARGs/actions
    # @param $1: ARGs keys. Use comma (,) to separete multiple keys to same action
    #   --> id="-h,--help"
    # @param $2: action to execute with keys
    #   this can be: [code] or [var]
    #   --> code="cmd1; cmd2;"
    #       run custom commands (cmd1 ; cmd2)
    #   --> var=myVar1:value
    #       create a var named 'myVar1' and assign 'value'
    #       * var=myVar1+r
    #       create a var 'myVar1' and require another param as value. If next arg was empyt raise a error.
    # @param $3: description to generate help for this arg/action
#   --> desc="text" 
xarg(){
    #TODO: refactor code below
    while [ "$1" != "" ]; do
        case $1 in
            # planning a new feature
            # --value)
            #     # echo ''
            #     method=value
            #     value=$2

            # ;;
            -i| --id) 
                key=$1; shift
                option_key=$(echo "$1" | tr -s ',' '|')
                option_default=$1
                description=''

                # autocreate xarg variable with short flag letter
                # Ex: xarg function with -s param will generate variable xarg=s
                method=var
                action_vars=''
                var_name=xarg
                var_value=$(echo $option_key | cut -d '|' -f1 | cut -d '-' -f2)
                assign_vars=" $var_name+=\"$var_value\" "
                # [ -n "$action_vars" ] && action_vars+=" ; "
                action_vars+=" $assign_vars  "
                option_rule=''
                desc_var=""
            ;;
            -v|--var) 
                key=$1; shift
                method=var
                # action_vars=''
                var_name=''
                var_value=''
                option_rule=""
                
                # $1 content -> can be a list of values comma separated
                    # value,value
                
                for v in ${1//,/ }; do
                    
                    # method used in this arg
                    option_content=$v

                    var_name="$(echo "$option_content" | cut -d ':' -f1 | cut -d '+' -f1  )"

                    case "$option_content" in
                       *:* ) 
                            # ":" will directly set value to variable
                                #  variable:value
                            
                            var_value="$(echo "$option_content" | cut -d ':' -f2 | cut -d '+' -f1)"
                            assign_vars=" $var_name=\"$var_value\" "
                            # clear rules
                            option_rule=""
                            var_value=''
                        ;;
                       *+* ) 
                            # "+" will require a new arg in command line. this value will be set to variable
                                # variable+r 
                            
                            current_rule="$(echo "$option_content" | cut -d '+' -f2)"

                            case "$current_rule" in
                                # 'r' means 'required'
                                r)  
                                    option_rule+=" shift; .xs --require-value \"\$1\" \"$var_name\" ;" 
                                    desc_var+=" <$var_name>" 
                                    if [ -z "$var_value" ]; then
                                        assign_vars=" $var_name=\"\$1\" "
                                    fi

                                ;;
                                # 'o' for 'optional'
                                o)  
                                    option_rule+=" " 
                                    desc_var+=" {$var_name}" 
                                    if [ -z "$var_value" ]; then
                                        assign_vars=" [ -n \"\$2\" ] && { shift ; $var_name=\"\$1\" ;  } "
                                    fi
                                ;;
                            esac
                       ;;
                    esac
                    [ -n "$action_vars" ] && action_vars+=" ; "
                    action_vars+=" $option_rule $assign_vars  "
                    # fix priblem when require two vars
                    # ex --var v1+r,v2+r
                    option_rule=''
                done
                
            ;;
            -c|--code) 
                key=$1; shift
                method=code
                option_content=$1 
                desc_var=''

            ;;
            -d|--desc) 
                key=$1; shift
                description="$1" 
            ;;
            # FIXME: --block not working on Darwin system
            -b|--block|-g|--group|-s|--section)
                method=block
                block="$2"
            ;;
            -n|--longflag-nodash)
                method=longflags
                _xARGS_NO_DAHS=true
            ;;
            -h|--header)
                method=header
                .xs --require-value "$1" "$2"
                xhelp --header="$2"
            ;;
            -f|--footer)
                method=footer
                .xs --require-value "$1" "$2"
                xhelp --footer="$2"
            ;;
        esac
        shift
    done

    # bypass when no arguments has been defined
    if [ "$method" != "block" ] && [ "$method" != "longflags" ] && [ "$method" != "footer" ] && [ "$method" != "header" ]; then
        xhelp --param="${option_default}${desc_var}+${description}+${block}"
    fi

    # generate output
    case $method in
        var ) __runARGS_case_options+=" $option_key) $action_vars    ;; \n" ;;
        code) __runARGS_case_options+=" $option_key) $option_content ;; \n" ;;
        # --reject-unknow) __runARGS_case_options+="*) xusage -r \$1 ;; \n" ;;
    esac
}

# xrun "$@"
# generates a loop with case struct to evaluate all ARGs defined using `xarg`
xrun(){
    xRUN_ARGS="$@"

    xrunHelp(){
        echo -e "${GREEN}${UNDERLINE}'lib/args'${RESET} "$args_hash" functions (${YELLOW}xarg${RESET}, ${YELLOW}xrun${RESET})
        \n${YELLOW}1) xarg${RESET} -> set args to be validate in 'xrun' function
        \nusage: ${YELLOW}xarg ${CYAN}[OPTION] ${MAGENTA}<VALUE>${RESET}\
        \n\nAvailable options:\
        "
        echo "\
        \n${CYAN} -i, --id   ${MAGENTA} <VALUE>${RESET}; short and long key. ex: '-h,--help'\
        \n${CYAN} -c, --code ${MAGENTA} <VALUE>${RESET}; shell code to run by 'eval'\
        \n${CYAN} -v, --var  ${MAGENTA} <VALUE>${RESET}; define vars\
        \n${CYAN} -d, --desc ${MAGENTA} <TEXT> ${RESET}; description to this 'arg'\
        \n\n # Grouping options #\n
        \n${CYAN}  -b, --block   ${MAGENTA}<VALUE>${RESET} or\
        \n${CYAN}  -g, --group   ${MAGENTA}<VALUE>${RESET} or\
        \n${CYAN}  -s, --section ${MAGENTA}<VALUE>${RESET} or\
        \
        " | awkColumn "-s=;"
        # " | column -t -s ';'
        
        echo -e "\
        \nExamples:\
        \n  ${YELLOW}xarg ${CYAN}--id -h,--help ${MAGENTA}--code 'xusage --help'  ${CYAN}--desc ${MAGENTA}'run function \"xusage\"'${RESET}\
        \n  ${YELLOW}xarg ${CYAN}--id -v,--var  ${MAGENTA}--var  var:value,url+r  ${CYAN}--desc ${MAGENTA}'equivalent to \"var=value; read url\"'${RESET}\
        \n  ${YELLOW}xarg ${CYAN}--block ${MAGENTA}'new block'${RESET}\
        
        \n${YELLOW}2) xrun${RESET} -> create 'case struct/validate args' defined via 'function xarg' for your application\
        \n\nusage: ${YELLOW}xrun ${CYAN}[OPTIONS] ${MAGENTA}\"\$@\"${RESET}\
        \n\nAvailable options:\
        "
        
        echo "\
        \n  ${CYAN}--xapp-data${RESET};create default directory for \$APP data ($HOME/.xshell/$APP)\
        \n  ${CYAN}--xrequire-one${RESET};script will require at least one argument\
        \n  ${CYAN}--xreject-unknown${RESET};raise an error if your script receives args not defined\
        \n  ${CYAN}--xversionrc${RESET};use full version with rc (release candidate)
        \n  ${CYAN}--xcolors${RESET};enable color support\
        \n  ${CYAN}--xlib-dirs${RESET};show dirs where xshell lib search for LIBs\
        \n  ${CYAN}--xdebug${RESET};prints generated case with args for inspection\
        \n  ${CYAN}--xhelp${RESET};prints this message
        " |  awkColumn "-s=;" 
        # " |  awkColumn "-t=;"
        # " | awk '{ printf "%-8s", $1 } NR % 2 == 0 { printf "\n" }'  
        # " | awk '{ getline line; printf "%s\t%s\n", $0, line }'
        # " | awk -vOFS='\t' 'NF > 0 { $1 = $1 } 1'
        # " > awkColumn -t=;
        # " | column -t -s ';' 

        # echo -e "\n[!] ATENTION:\
        #     \n    1-You can't use 'xrun' arguments in your application.\
        #     \n    2-You must pass all of your app/script args to 'xrun' validate then.\
        #     \n\tex: xrun --xrequire-one \"\$@\"\
        #     \n    3-xrun args will be removed via shift; so they need to be before incoming args (\"\$@\")\
        #     "
        exit 0
    }
    
    xrunDebug(){
        echo -e "${RED}$(.xs --hl '-')\n# xSHELL DEBUG - begin\
            \n$(.xs --hl '-')${RESET}\n${YELLOW}# 1. variables:${RESET}\n\
            \n\$xSHELL_PATH: '$xSHELL_PATH'\
            \n\$xSHELL_LIBS: '(count $(echo -n "${xSHELL_LIBS[@]}" | tr -s ' ' '\n' | wc -l | tr -d ' '))$(echo "${xSHELL_LIBS[@]/$xSHELL_PATH\/}")'\

            \n\$APP: '$APP'\
            \n\$APP_PATH: '$0'\
            \n\$APP_DATA: '$APP_DATA'\

            \n\$@: '${_ARGS_[*]}'\
            \n\$_PARAMS_: '${_PARAMS_[*]}'\
            \n\$xarg: '$xarg'\

            \n\$_AUTHOR_NAME_: '$_AUTHOR_NAME_'\
            \n\$_AUTHOR_MAIL_: '$_AUTHOR_MAIL_'\
            \n\$_VERSION_: '$_VERSION_' ($xs_release_candidate)\
            \n$(.xs --hl '-')\n${YELLOW}# 2. xarg function:${RESET}\n\
            \n$(Hash.all "$args_hash" | cut -d '+' -f1)\
            \n$(.xs --hl '-')\n${YELLOW}# 3. xrun function:${RESET}\n\
            \n\$@: '${xRUN_ARGS}'\
            \n$__runARGS_case_\
            \n${RED}$(.xs --hl -)\n# xSHELL DEBUG - end\
            \n$(.xs --hl -)${RESET}";
    }
    
    generateCase(){
         # fill case with options (xarg)
        __runARGS_case_='case $1 in \n'
        __runARGS_case_+=$__runARGS_case_options
        __runARGS_case_+='esac'
        # apply escape codes (\n \t) when print
        __runARGS_case_=$(echo -e $__runARGS_case_)
        
        [ -n "$_ARGS_REQUIRED" ] && .xs --require-one "$@" && unset _ARGS_REQUIRED;

        # loop all params 
        while [ "$1" != "" ]; do
            # run generated 'case' code
            eval "$__runARGS_case_"
            shift
        done
    }

    # Function to handle joint short flags
    handleJointShortFlags() {
        local joint_flags="$1"  # The joint short flags passed as an argument
        local length=${#joint_flags}  # The length of the joint short flags string

        # Iterate over each character in the joint short flags string
        for (( i=0; i<length; i++ )); do
            local flag="${joint_flags:i:1}"  # Extract the current character (flag)
            _PARAMS_+=("-$flag")  # Add the individual flag to the _PARAMS_ array
        done
    }

    # set default grouping (has more than zero entries with groups? user defined)
    if [ "$(Hash.all | grep -Ei '\+[a-z]' | wc -l)" -gt 0 ]; then
        # create this group for --help and --version options
        xarg --block "Information Options"
    else
        # no user group? use this for all options
        xarg --block "Available Options"
    fi
    # set default args for any script
    _CURRENT_VERSION_=$_VERSION_

    # add support to logflags without '--' prefix
    if [ -z "$_xARGS_NO_DAHS"  ]; then 
        _arg_prefix_="--"
    fi

    # gen default help argument
    xarg --id "-h,${_arg_prefix_}help"    \
         --code "xusage --help" \
         --desc "show this help"
        #  --code "formatHelpOptions" \
         
    # gen default version argument
    xarg --id "-v,${_arg_prefix_}version" \
         --code "xusage --version" \
         --desc "print version and exit"
    
    # store arguments/params to be passed to the script
    _PARAMS_=()
    
    # search for xrun args 
    while [ "$1" != "" ]; do
        # function to force script to receive at last one param/arg
        case "$1" in
            --xapp-data)
                shift; xsetHome
            ;;
            --xrequire-one | --xrequire_one | --require-one | --notNull)  
                shift; _ARGS_REQUIRED=true
            ;;
            --xreject-unknown | --reject-unknow | --xreject-unknow)
                shift
                __runARGS_case_options+="*) xusage --reject-unknow \$1 ;; \n"
            ;;
            --xversion-full | --xversionrc)
                shift; _CURRENT_VERSION_=$_VERSIONRC_
            ;;
            --xdebug | --xsdebug) 
                shift; _ARGS_DEBUG=true; 
            ;;
            --xcolors)
                shift; use colors;
            ;;
            --xscolors) 
                shift; xsColors; exit 0;
            ;;
            --xhelp)
                use utils
                [ -z "$RED" ] && use colors
                local _help_viewer=$(xsys.path bat less more cat)
                shift; xrunHelp | $_help_viewer
            ;;
            --xlib-dirs | --xlibs)
                shift;
                [ -z "$RED" ] && use colors
                echo -e "\n${YELLOW}xSHELL LIB directories:${RESET}\n"
                for dir in "${xSHELL_DIRS[@]}"; do
                    echo -e "${GREEN}  \`-> '${dir}${RESET})"
                done
                echo
                exit
            ;;
            *)
                _PARAMS_+=("$1")
                shift
        esac
    done
    
    # Save all arguments (except the pala lib xshell reserves)
    _ARGS_=(${_PARAMS_[@]})

    # Check for joint short flags and expand them
    for arg in "${_PARAMS_[@]}"; do
        # Check if the argument is a joint short flag (e.g., -abc)
        if [[ "$arg" =~ ^-[a-zA-Z]{2,}$ ]]; then
            handleJointShortFlags "${arg:1}"  # Call the function to handle the joint short flags
            unset _PARAMS_[$arg]  # Remove the joint short flag from the _PARAMS_ array
        fi
    done

    generateCase "${_PARAMS_[@]}"

    [ -n "$_ARGS_DEBUG" ] && xrunDebug "${xRUN_ARGS[@]}";
}
# Validate if $xarg variable contains a value and run the code block
# Usage: xcase <value> <code_block>
xcase(){
    local value="$1"; shift
    local code_block="$@"
    if [[ "$xarg" =~ $value ]]; then
        eval "$code_block"
    fi
}

# internal helper function to set default values
# Usage: .xs <argument>
# `-> argument can be:
#   --init: initialize script variables
#   --require-value <value> <var_name>: require a value for a variable
#   --require-one <args>: require at least one argument
#   --hl <char>: prints a horizontal line with the given character
.xs(){
    # define version of script
    xsVersion(){
        # set app version (dynamic from header comments or static)
        [ -z "$_VERSION_" ] && _VERSION_="$(head -n 20 "$0" | \
            grep '# Version:' -m1 | \
            tr -d ' ' | \
            cut -d ':' -f2 | \
            cut -d '.' -f1-3 \
        )"
        # get release candidate 
        xs_release_candidate="$(head -n 20 "$0" | \
            grep '# Version:' -m1 | \
            tr -d ' ' | \
            cut -d ':' -f2 | \
            cut -d '.' -f4 \
        )"

        _VERSIONRC_="$_VERSION_-rc$xs_release_candidate"
        [ -z "$_VERSION_" ] && _VERSION_='0.0.1'
    }

    # define when script was created
    xsCreated(){
        # set app version (dynamic from header comments or static)
        [ -z "$_CREATED_AT_" ] && _CREATED_AT_="$(head -n 20 "$0" | \
            grep '# Created:' -m1 | \
            tr -d ' ' | \
            cut -d ':' -f2 | \
            cut -d ',' -f2 | \
            cut -d '-' -f1 | \
            cut -d '/' -f1 \
        )"
        # not found date in header comments, try filestats
        [ -z "$_CREATED_AT_" ] && \
            _CREATED_AT_="$(stat "$0" | \
                grep Birth  | \
                cut -d ' ' -f3 | \
                cut -d '.' -f1 | \
                cut -d '-' -f1 \
            )"
        # still null? set as unknown, to be filed later
        [ -z "$_CREATED_AT_" ] && _CREATED_AT_='<unknown>'
    }

    # define when script was updated
    xsUpdated(){
        # set app version (dynamic from header comments or static)
        [ -z "$_UPDATED_AT_" ] && _UPDATED_AT_="$(head -n 20 "$0" | \
            grep '# Last Modified:' -m1 | \
            tr -d ' ' | \
            cut -d ':' -f2 | \
            cut -d ',' -f2 | \
            cut -d '-' -f1 | \
            tr -d '/'
        )"
        # [ -z "$_UPDATED_AT_" ] && _UPDATED_AT_="$(head -n 20 "$0" | \
        #     grep '# Last Modified:' -m1 | \
        #     cut -d ',' -f2 | \
        #     tr -d ' ' | \
        #     tr -d ':' | \
        #     tr -d ',' | \
        #     tr -d '-' | \
        #     tr -d '/'
        # )"
            # cut -d '/' -f1 \
        # not found date in header comments, try filestats
        [ -z "$_UPDATED_AT_" ] && \
            _UPDATED_AT_="$(stat "$0" | \
                grep Birth  | \
                cut -d ' ' -f3 | \
                cut -d '.' -f1 | \
                cut -d '-' -f1 \
            )"
        # still null? set as unknown, to be filed later
        [ -z "$_UPDATED_AT_" ] && _UPDATED_AT_='<unknown>'
    }

    # define author of script
    xsAuthorName(){
        [ -z "$_AUTHOR_NAME_" ] && _AUTHOR_NAME_=$(
            head -n 20 "$0" | \
            grep '# Author.:' -m1 | \
            cut -d ':' -f2 |\
            cut -d ',' -f1 |\
            cut -c2-
        )
        # not found author in header comments, try get by git config
        [ -z "$_AUTHOR_NAME_" ] && _AUTHOR_NAME_=$(git config --global user.name)
        # [ -z "$_AUTHOR_NAME_" ] && _AUTHOR_NAME_=$(git config --global user.email)
        [ -z "$_AUTHOR_NAME_" ] && _AUTHOR_NAME_=$(git config --global author.name)
        # [ -z "$_AUTHOR_NAME_" ] && _AUTHOR_NAME_=$(git config --global author.email)
        # still null? try by $USER variable
        [ -z "$_AUTHOR_NAME_" ] && _AUTHOR_NAME_="$USER"
        # null? set as unknown, to be filled in later
        [ -z "$_AUTHOR_NAME_" ] && _AUTHOR_NAME_='<unknown>'
    }

    # define author email
    xsAuthorMail(){
        [ -z "$_AUTHOR_MAIL_" ] && _AUTHOR_MAIL_=$(
            head -n 20 "$0" | \
            grep '# Author.:' -m1 | \
            cut -d ':' -f2 |\
            cut -d ',' -f2 |\
            tr -d '(' | tr -d ')' | tr -d ' '
        )
        # not found author in header comments, try get by git config
        [ -z "$_AUTHOR_MAIL_" ] && _AUTHOR_MAIL_=$(git config --global user.email)
        [ -z "$_AUTHOR_MAIL_" ] && _AUTHOR_MAIL_=$(git config --global author.email)
        # null? set as unknown, to be filled in later
        [ -z "$_AUTHOR_MAIL_" ] && _AUTHOR_MAIL_='<unknown>'
    }

    case "${1}" in
        --init)
            shift;
            xsVersion; xsCreated; xsUpdated; xsAuthorName; xsAuthorMail
        ;;
        --require-value)
            shift;
            test -z "$1" && { xusage --field-error "$2"; } 
        ;;
        --require-one)
            shift;
            test -z "$1" && xusage --missing-param; 
        ;;
        --hl | --horizontal-line)
            shift;
            xrequirements seq tput
            for i in $(seq 1 "$(($(tput cols)-3))"); do echo -n "$1"; done
        ;;
    esac
}

# ~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~·~·~·~·~·~·~·~~·~·~·~·~·~~·~·~·~·~·~·~·~
# initialize var 'xarg'
xarg=''

# define current_cmd at start
xcmd=main
args_hash="${xcmd}-args"
groups_hash="${xcmd}-groups"

# hash to save app params
Hash.new -t "$args_hash"
Hash.new -t "$groups_hash"

# Hash.put "$args_hash" "$param_id" "$param_text";;

block=''