diff --git a/readme.md b/readme.md index ccd2b3255784ecdf429518349f036e81259141f3..4fe0366056510f828e064bc86365bbbe7938e35f 100644 --- a/readme.md +++ b/readme.md @@ -41,5 +41,41 @@ Due to how bash works, this will override the original passed script values. The variables called "global_args", "global_kwargs", "global_flags". +## Script Functions +See code for more detailed documentation. + +### Script Setup Functions +These execute automatically on script import. +* `normalize_terminal` - Normalizes terminal location to same directory as utils script. + * Makes it so that relative directories are handled the same, regardless of what directory user is in when starting + a script. +* `handle_args_kwargs` - Parses all passed args into 3 sets: + * `args` - Any values that do not match the other two below types. + * Ex: "True", "5", and "test". + * `flags` - Any values that start with "-". + * Interpreted as a boolean. True if present in `flags` array, False if not. + * Ex: "-a", "-b", and "-run". + * `Kwargs` - Key-value pairs, where the key comes first and starts with "--". Associated value is + * Note that the associated value must come immediately after the key. + * Ex: "--type false", "--dir ./test", and "--name Bob". + +### Directory Functions +* `get_absolute_path` - Gets absolute path of passed location. +* `get_directory_name` - Gets directory name of current terminal location or passed location. +* `parse_file_name` - Determines `file_name` and `file_extension` of passed file location. + +### User Functions +* `check_is_user` - Checks if executing user matches passed value. +* `check_is_not_user` - Checks if executing user does not match passed value. + +### String Functions +* `to_upper` - Converts passed value to be fully uppercase. +* `to_lower` - Converts passed value to be fully lowercase. + +### Other +* `display_text_colors` - Displays all text color values provided by script. +* `display_args_kwargs` - Displays all flags, args, and kwargs, as determined by `handle_args_kwargs()`. + + ## References See `documents/references.md`. diff --git a/utils.sh b/utils.sh index 968c1e387047a101672c72fa6e1c7af27d65d86c..b29329105d07fa2f168aa855bf7c6ac999caff1d 100755 --- a/utils.sh +++ b/utils.sh @@ -23,7 +23,7 @@ text_cyan="\033[1;36m" text_yellow="\033[1;33m" text_white="\033[1;37m" -# Arg and Kwarg Holder Variables. +# Arg, Kwarg, and Flag Return Variables. args=() flags=() declare -A kwargs=() @@ -50,6 +50,8 @@ file_extension="" # relative directory handling will still function the same in either case. # # Automatically called on script import. + # + # Return Variable(s): return_value ## function normalize_terminal () { cd "$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" @@ -58,18 +60,25 @@ function normalize_terminal () { ### # Handles passed values. + # # Splits into "args", "kwargs", and "flags": + # * Args are any other values that don't match below two formats. + # * Ex: "True", "5", and "test". # * Flags are any variable that starts with "-". # * These are effectively treated as booleans. True if present, false otherwise. # * Ex: "-a", "-b", and "-run". # * Kwargs are key-value pairs, where the key comes first and starts with "--". # * Note that the associated value must come immediately after the key. # * Ex: "--type false", "--dir ./test", and "--name Bob". - # * Args are any other values that don't match above formats. + # + # Ordering of provided args, kwargs, and flags should not matter, aside from kwarg keys needing a corresponding value + # as the direct next processed value. # # Note that "-h" and "--help" are handled separately, and considered to both be "help flags". # If either one is provided, then a "help_flags" global variable is set to true. # The expectation is that some kind of "display help" function will run instead of normal script functionality. + # + # Return Variable(s): help_flags, args, kwargs, flags, global_args, global_kwargs, and global_flags ## handle_args_kwargs () { local handle_kwarg=false @@ -173,6 +182,8 @@ handle_args_kwargs () { ### # Gets absolute path of passed location. + # + # Return Variable(s): return_value ## function get_absolute_path () { @@ -222,6 +233,8 @@ function get_absolute_path () { ### # Returns name of current directory. # If arg is passed, then returns base name of directory path, or parent directory of file path. + # + # Return Variable(s): return_value ## function get_directory_name () { @@ -265,6 +278,8 @@ function get_directory_name () { ### # Parses passed file, getting base file name and file extension. + # + # Return Variable(s): return_value ## function parse_file_name () { @@ -303,6 +318,8 @@ function parse_file_name () { ### # Recursive helper function for parse_file_name(). # Determines base file name and full file extension. + # + # Return Variable(s): file_name and file_extension ## function _recurse_file_extension () { local passed_value=${1} @@ -336,6 +353,8 @@ function _recurse_file_extension () { ### # Checks if current username matches passed value. # In particular, is used to check if user is sudo/root user. + # + # Return Variable(s): None ## function check_is_user () { @@ -382,6 +401,8 @@ function check_is_user () { ### # Checks if current username does not match passed value. # In particular, is used to check if user is not sudo/root user. + # + # Return Variable(s): None ## function check_is_not_user () { @@ -431,6 +452,8 @@ function check_is_not_user () { ### # Converts one or more passed args to uppercase characters. + # + # Return Variable(s): return_value ## function to_upper () { @@ -454,6 +477,8 @@ function to_upper () { ### # Convers one or more passed args to lowercase characters. + # + # Return Variable(s): return_value ## function to_lower () { @@ -481,6 +506,8 @@ function to_lower () { ### # Prints out all available text colors provided by this script. + # + # Return Variable(s): None ## function display_text_colors () { echo "" @@ -501,6 +528,8 @@ function display_text_colors () { ### # Prints out all current flags, args, and kwargs, as determined by handle_args_kwargs() function. # If function has been called multiple times, then will also print out global values. + # + # Return Variable(s): None ## function display_args_kwargs () { echo ""