Command Tools

command_tools.bsh

Set of functions to make using parsing and composing commands easier

get_array_from_environment
Arguments:

  • $1 - Array variable name to store values in

  • $2 - PREFIX used

  • $3 - NAME used

  • [$4] - INSTANCE used. This argument is optional. If it is not specified, than the two patterns using INSTANCE are not checked.

The purpose of this function is to gather environment values from various locations that is advantageous in many situations. Get values from array {PREFIX}_{NAME}S, values {PREFIX}_{NAME}_1…, array {PREFIX}_{INSTANCE}_{NAME}S, and values {PREFIX}_{INSTANCE}_{NAME}_1… and stores them in the variable specified by $1.

Since arrays cannot be exported, there are two different methods of getting environment variables.

parse-generic
Arguments:

$1.. - Arguments to be sent to some command

Parameters:

[arguments_with_value] - An array of command arguments that must take one argument

Output:

  • command_args - Arguments to some command, before the subcommand (run, build, do_something, etc…)

  • subcommand - The subcommand specified

  • subcommand_args - Arguments for the specified subcommand

Parse a generic command’s arguments and split up information (See OUTPUT). This supports a generic function that goes some command followed by arguments that start with - and take no additional arguments (command_args). Next an optional subcommand (subcommand) and those subcommand’s arguments (subcommand_args).

This will only work in the simplest of cases (e.g. singularity). Cases like docker and other commands that have more complicated command_args choices, a specific version of this function needs to be written to handle all the argument cases.

Typically, in the calling function, you will define all the output variables as local, so that they are captured by the calling function only.

Original command can be thought of as:

some_command "${command_args[@]}" "${subcommand}" "${subcommand_args[@]}"
compose_arguments
Arguments:

  • [$1] - Name of array that will be inserted between command_args and subcommand.

  • [$2] - Name of array that will be inserted between the subcommand and command args and.

Parameters:

  • cmd - The starting array of command arguments, starting with 0

  • command_args - Arguments to some command, before the subcommand (run, build, do_something, etc…)

  • subcommand - The subcommand specified

  • subcommand_args - Arguments for the specified subcommand

Appends arguments to the array cmd. If cmd isn’t defined at first, it is created an an empty array. If cmd is a string, it will be converted to a single element array, and then appended to.

Example

cmd=(${DRYRUN} foobar)
CMD_ARGS=(--quiet --config "/tmp/foo bar.xml")
MAGIC_ARGS=(-it --rm)
subcommand=magic
command_args=(--gpu)
subcommand_args=(--do=something)

compose_arguments CMD_ARGS MAGIC_ARGS
declare -p cmd

declare -a cmd=([0]="foobar" [1]="--gpu" [2]="--quiet" [3]="--config"
                [4]="/tmp/foo bar.xml" [5]="magic" [6]="-it" [7]="--rm"
                [8]="--do=something")

Note

Even if the arguments’ variables are a non-array variables, this will work. However they will always appear to be a single argument.

parse_args
Arguments:

  • $1 - Name of variable to store how many arguments were parsed

  • $2 - Option string, like -o or --output

  • $3 - Storage name: the name of the variable that will store the result of the argument if used. If suffix-less, treat the option as a flag without an associated argument and increment the storage for each occurrence of the flag. The storage can also be suffixed with ! to instead decrement the storage. Alternatively, the storage name can also be suffixed with a : for an option-string that has a single argument or prefixed with + for an option-string that expects and an array.

  • [ $4...$N ] - Repeat $2 and $3

  • $N+1 - Must be -- to delineate the actual arguments are being passed in next

  • [$N+2...] - The arguments to parse

Outputs:

  • $!1 - Store how many arguments are parsed after the --, in the variable name specified in $1

  • $3,$5,... - Stores the values in the corresponding variables/arrays

A simple argument parser, supporting some of the options that getopts supports

  1. Only parses until an argument is encountered that does not match an argument. This is useful for subcommand parsing

  2. Can support any arguments option, even if they do not start with -, but that is ill advised

  3. Does not support combining multiple one letter arguments into one argument

  4. Supports the : suffix notation for “has an argument”; add it to the storage name (not the option string)

  5. Does not support the :: notation for “maybe has an argument”

  6. Supports a + prefix notation on the storage variable name meaning the storage is an array, and values are appended to it.

  7. If options do not have an argument, then they are treated as a flag and set to 0 if unset and +1 for each time it is set.

  8. Also supports the ! suffix notation to decrement (instead of increment) the option-flag’s storage name

Example

Here are two examples of using parse_args
local nit_pick
local rebuild
local include_files
local args_parsed
parse_args args_parsed -n nit_pick --nit nit_pick \
                       --rebuild rebuild --no-rebuild rebuild! \
                       --include-files +include_files:
                       -- ${@+"${@}"}
shift "${args_parsed}"
### Handle parsed arguments ###
if [ "${nit_pick}" != "0" ]; then
  echo "Be pedantic"
fi
if [ "${rebuild}" -gt "0" ]; then
  echo "Force full rebuild"
elif [ "${rebuild}" -eq "0" ]; then
  echo "Incremental build"
elif [ "${rebuild}" -lt "0" ]; then
  echo "Do not build"
fi
if [ "${#include_files[@]}" != "0" ]; then
  local "${JUST_PROJECT_PREFIX}_INCLUDE_FILES"
  dynamic_set_a "${JUST_PROJECT_PREFIX}_INCLUDE_FILES" "${include_files[@]}"
fi

Note

Variables are always overwritten, even if not used. A 0 for options without arguments, and an empty string for options that take arguments indicates the option was never used. However, arrays are always appended to.

Warning

Don’t use variable names that start with __parse_args

open_web_browser

Opens a file/link with a web browser

Arguments:

$1 - The filename/link to be opened

On windows, uses the associated web browser. First tried the associated Linux web browser, google-chrome, chromium-browser, firefox, then the associated macOS web browser.