shMate

Integer value of current debug level. Defaults to 0.

Integer controlling colorful logging. Not set by default i.e. auto detect.

Path to log file. If set, console log will be duplicated to the log file.

Setting this to nonempty string makes logging print this value instead of actual timestamp.

Log file permissions. Ignored if the log file already exists.

Setting this to positive integer indicates the log message contains ANSI escape sequences needed to be processed when logging to console or needed to be removed if logging to file. Should be used on demand as local variable.

Setting this to positive integer disables logging to file and final CRLF sequence in console log is replaced with single carriage return. Useful for logging progress messages. The message should be one-liner. Should be used on demand as local variable.

Regular expression to match ANSI escape sequence.

Fully qualified host name.

Integer value of AUDIT log level.

Integer value of DEBUG log level.

Integer value of ASSERT log level.

Integer value of current debug level.

Log file line ending character sequence accepted by printf command.

Log file line format accepted by printf command.

Console log line ending character sequence accepted by printf command.

Console log line format accepted by printf command.

Changes terminal color scheme to grayed out.

Disables terminal colors.

Asserts all <file_paths> are a readable files.

Asserts all <file_paths> are a writable files.

Logs concatenated <messages> in ASSERT level.

Logs concatenated <messages> in DEBUG level.

Logs concatenated <messages> in INFO level.

Logs concatenated <messages> in WARNING level.

Alias for shmate_log_warning.

Logs concatenated <messages> in ERROR level.

Logs concatenated <messages> in PENDING level.

Logs concatenated <messages> in SUCCESS level.

Logs concatenated <messages> in FAILURE level.

Alias for shmate_log_failure.

Logs deprecated symbols.

Logs <command> and <command_args> in AUDIT level.

Logs <command> execution in AUDIT level and runs the <command> with <command_args>.

Logs concatenated <messages> in FAILURE level and terminates the program with <exit_code>.

Checks if all the <optional_tools> are found on PATH. Returns non-zero value if not. See shmate_assert_tools for loud version.

Checks if all the <required_tools> are found on PATH. If not, logs message in ERROR level and returns non-zero value. See shmate_check_tools for silent version.

Assert successful execution (zero exit code) of the last executed command. If non-zero exit code has been returned, <messages> are concatenated and logged in ERROR level. Returns the same exit code as the last executed command.

Same as shmate_assert but logs in DEBUG level.

Same as shmate_assert but logs in WARNING level.

Logs concatenated <messages> in PENDING level. Puts the logged message on stack, so it can be taken by shmate_loud_assert and shmate_fail_assert. Must always be coupled with shmate_loud_assert or shmate_fail_assert to take logged message off stack.

Similar to shmate_assert, but on successful execution of the last command logs concatenated messages in SUCCESS level.

If no <messages> are given, takes the message off stack (put there by shmate_pending_assert). If <exit_code> is given, it overrides the returned exit code.

If no <messages> are given behaves like shmate_loud_assert, otherwise behaves like shmate_assert. If the last command failed, logs message in FAILURE level and terminates the program.

If <exit_code> is given, it overrides the returned exit code.

Path to directory where shMate is installed. Must be set, unless all of SHMATE_BIN_DIR, SHMATE_CONF_DIR, SHMATE_LIB_DIR are set.

Path to directory containing shMate executable files. Defaults to ${SHMATE_INSTALL_DIR}/bin.

Path to directory containing shMate configuration files. Defaults to ${SHMATE_INSTALL_DIR}/etc/shmate.

Path to directory containing shMate library files. Defaults to ${SHMATE_INSTALL_DIR}/lib/shmate.

Setting this to positive integer disables printing of failure message upon non-zero exit code.

Timestamp format accepted by date command. Defaults to %Y-%m-%dT%H:%M:%SZ or %Y-%m-%dT%H:%M:%S if SHMATE_TIMESTAMP_LOCAL is a positive integer.

Setting this to positive integer makes all timestamps in local time zone instead of UTC.

Setting this to nonempty string makes shmate_current_timestamp print this value instead of actual timestamp.

Kernel version, useful to detect platform.

true if run on Linux platform.

true if run on BSD platform.

true if run on Windows platform.

Function name used by shmate_main. Defaults to main. It is highly recommended to use the default whenever possible.

Function name or prefix used by shmate_exit_help. Defaults to help. It is highly recommended to use the default whenever possible.

Function prefix used by shmate_task. Defaults to task. It is highly recommended to use the default whenever possible.

Variable set by shmate_getopts function. Contains name of the option currently being processed.

Variable set by shmate_task function. Contains name of the task currently being processed.

Timestamp format accepted by date command.

Handler called just before exit. It should never be called manually, but can be implemented in caller’s script.

It may or may not have access to stdin, stdout, stderr depending on the platform.

Handler called just before shmate_cleanup. It should never be called manually, but can be implemented in caller’s script. The returned value is passed to shmate_cleanup and is the final exit code of the script (in most cases returning unaltered <exit_code> is desired).

It does have access to stdin, stdout, stderr.

Handler called just before shmate_cleanup after receiving terminating signal (e.g. HUP, TERM, USR2). It should never be called manually, but can be implemented in caller’s script. The non-zero return value is passed to shmate_cleanup and is the final exit code of the script (in most cases returning unaltered <exit_code> is desired). The zero return value means the signal has been handled. To exit program with zero shmate_exit must be called explicitly.

It does have access to stdin, stdout, stderr.

Exits with given <exit_code> or zero if not specified. Must always be used instead of plain exit. Calls shmate_on_exit and shmate_cleanup handlers.

Prints help message end exits with given <exit_code> or zero if not specified. The message is printed to stdout on zero <exit_code> or stderr otherwise. The help function printing the message must be defined beforehand. If shmate_getopts_task is set, i.e. shmate_task function has been called beforehand, the help_${shmate_getopts_task} function is used instead of help.

Help function prefix can be changed by setting shmate_function_help variable before including the library.

Prints concatenated <messages> to stderr.

Prints concatenated <messages> to stderr and terminates the program with <exit_code>.

Like ordinary exec, but calls shmate_cleanup handler beforehand.

Similar to ordinary getopts, but it always uses the shmate_getopts_option variable to store current option name. Automatically adds -h option handler and uses shmate_exit_help if -h option is given or if options are invalid.

Recommended entry point for all scripts using shMate library. Calls the main function defined in the calling script. Must be used in the last not empty line in the calling script.

Main function name can be changed by setting shmate_function_main variable before including the library.

Delegates execution of <task> to function task_<task>. The function task_<task> must be defined beforehand. All <task_args> are passed along to the task function.

Task function prefix can be changed by setting shmate_function_task variable before including the library.

Converts the <name> to lowercase and converts non-word characters to underscores. Then checks if function <prefix>_<name>_<suffix> (or <prefix>_<name> if <suffix> is not given) exists. Prints the function’s name if found. Returns non-zero otherwise.

Just like ordinary echo but adds single quotes for every argument. Multiple flags must be specified as single option i.e. '-ne', not '-n' '-e'.

Just like ordinary grep but ignoring error if no lines were found (never returns 1). Useful for filtering and simpler than sed for this purpose.

Prints every <string> in separate line. If <string> equals '-' prints stdin instead. '-' can only be used once.

Like ordinary shmate_string_cat, but all <strings> and the whole stdin (if '-' is provided) are buffered and then printed as one.

Prints every <string> as is, i.e., one after another. If <string> equals '-' prints stdin instead. '-' can only be used once.

Executes <command> with <command_args> providing <input_string> to command as stdin.

Reads every line of input and returns success if all the given <strings> are equal to at least one of the lines.

Reads every line of input and prints only lines equal to any of the given <strings>.

Reads every line of input and prints only lines NOT equal to all the given <strings>.

Reads all lines of input and prints them in inverse order.

Converts <string> to valid shell variable name.

Converts <date> to ISO 8601 date. If given, adds <days> to the date, e.g., '+1' '-23'. Requires Linux date command.

Calculates interval in seconds between two dates. Arguments can be in any format understood by 'date', although ISO 8601 is recommended. Requires Linux date command.

Calculates interval in days between two dates. Arguments can be in any format understood by 'date', although ISO 8601 is recommended. Requires Linux date command.

Reads dotenv file (or stdin) as single line of key=value pairs. Useful to export variables from dotenv file. To export all variables from not empty trusted '.env' dotenv file call:

Checks if <string> has at most one line of text.

Prints current timestamp in format specified with SHMATE_TIMESTAMP_FORMAT. Output can be fixed with SHMATE_CURRENT_TIMESTAMP.

Returns success only if <string> is not negative integer.

Wait at least this number of seconds for graceful termination before KILLing descendant processes. Defaults to 10 seconds.

Runs <command> with <command_args> as background job and prints its output to stderr.

The result of the <command> should be obtained with shmate_wait_job or with shmate_wait_job_group by passing the same <job_group_name> (only possible if <job_group_name> is not empty).

Same as shmate_run_job, but prints output of the <command> to stdout.

Same as shmate_run_job, but ignores both stdout and stderr of the <command>.

Same as shmate_run_job, but clears all of shMate variables from the <command> environment.

Same as shmate_run_muted_job, but detaches the <command> process from the caller completely, i.e. it will continue to run after calling process exits.

Runs <command> with <command_args> as guarded job running in foreground. If calling process is not already a job it becomes the guardian. The guardian is responsible for immediate graceful termination of all descendant processes upon exit including termination caused by signal.

Useful to run long-term tasks. Does not work in Windows falling back to just running the <command>.

Setting this to positive integer preserves temporary working directory. Useful for debugging.

Path to temporary working directory.