STDLIB Complete Function Reference
Index
stdlib.array.assert.is_array
Asserts that a variable is an array.
Arguments
$1 (string): The name of the variable to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.array.assert.is_contains
Asserts that an array contains a value.
Arguments
$1 (string): The value to assert is present.
$2 (string): The name of the array.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.array.assert.is_empty
Asserts that an array is empty.
Arguments
$1 (string): The name of the array to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.array.assert.is_equal
Asserts that two arrays are equal.
Arguments
$1 (string): The name of the first array to compare.
$2 (string): The name of the second array to compare.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.array.assert.not_array
Asserts that a variable is not an array.
Arguments
$1 (string): The name of the variable to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.array.assert.not_contains
Asserts that an array does not contain a value.
Arguments
$1 (string): The value to assert is NOT present.
$2 (string): The name of the array.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.array.assert.not_empty
Asserts that an array is not empty.
Arguments
$1 (string): The name of the array to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.array.assert.not_equal
Asserts that two arrays are not equal.
Arguments
$1 (string): The name of the first array to compare.
$2 (string): The name of the second array to compare.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.array.get.last
Gets the last element of an array.
Arguments
$1 (string): The name of the array.
Variables set
STDLIB_ARRAY_BUFFER (string): The last element of the array.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The last element of the array.
Output on stderr
The error message if the operation fails.
stdlib.array.get.length
Gets the length of an array.
Arguments
$1 (string): The name of the array.
Variables set
STDLIB_ARRAY_BUFFER (integer): The length of the array.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The length of the array.
Output on stderr
The error message if the operation fails.
stdlib.array.get.longest
Gets the length of the longest element in an array.
Arguments
$1 (string): The name of the array.
Variables set
STDLIB_ARRAY_BUFFER (integer): The length of the longest element.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The length of the longest element.
Output on stderr
The error message if the operation fails.
stdlib.array.get.shortest
Gets the length of the shortest element in an array.
Arguments
$1 (string): The name of the array.
Variables set
STDLIB_ARRAY_BUFFER (integer): The length of the shortest element.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The length of the shortest element.
Output on stderr
The error message if the operation fails.
stdlib.array.make.from_file
Creates an array from a file using a separator.
Arguments
$1 (string): The name of the array to create.
$2 (string): The separator character.
$3 (string): The path to the source file.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.make.from_string
Creates an array from a string using a separator.
Arguments
$1 (string): The name of the array to create.
$2 (string): The separator character.
$3 (string): The source string.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.make.from_string_n
Creates an array by repeating a string a specified number of times.
Arguments
$1 (string): The name of the array to create.
$2 (integer): The number of times to repeat the string.
$3 (string): The string to repeat.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.map.fn
Maps a function over each element of an array.
Arguments
$1 (string): The name of the function to apply to each element.
$2 (string): The name of the array to process.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
Any output from the mapped function.
Output on stderr
The error message if the operation fails.
stdlib.array.map.format
Maps a format string over each element of an array and prints the result.
Arguments
$1 (string): A valid printf format string.
$2 (string): The name of the array to process.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The formatted elements of the array.
Output on stderr
The error message if the operation fails.
stdlib.array.mutate.append
Appends a string to each element of an array.
Arguments
$1 (string): The string to append.
$2 (string): The name of the array to modify.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.mutate.filter
Filters an array in place using a filter function.
Arguments
$1 (string): The name of the filter function.
$2 (string): The name of the array to modify.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.mutate.fn
Replaces each element of an array with the output of a function.
Arguments
$1 (string): The name of the function to apply to each element.
$2 (string): The name of the array to modify.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.mutate.format
Replaces each element of an array with a formatted version.
Arguments
$1 (string): A valid printf format string.
$2 (string): The name of the array to modify.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.mutate.insert
Inserts a string into an array at a specified index.
Arguments
$1 (string): The string to insert.
$2 (integer): The index at which to insert the string.
$3 (string): The name of the array to modify.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.mutate.prepend
Prepends a string to each element of an array.
Arguments
$1 (string): The string to prepend.
$2 (string): The name of the array to modify.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.mutate.remove
Removes an element from an array at a specified index.
Arguments
$1 (integer): The index of the element to remove.
$2 (string): The name of the array to modify.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.mutate.reverse
Reverses the elements of an array in place.
Arguments
$1 (string): The name of the array to modify.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.query.is_array
Checks if a variable is an array.
Arguments
$1 (string): The name of the variable to check.
Exit codes
0: If the variable is an array.
1: If the variable is not an array.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.query.is_contains
Checks if an array contains a value.
Arguments
$1 (string): The value to query for.
$2 (string): The name of the array to query.
Exit codes
0: If the array contains the value.
1: If the array does not contain the value.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.query.is_empty
Checks if an array is empty.
Arguments
$1 (string): The name of the array to check.
Exit codes
0: If the array is empty.
1: If the array is not empty.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.array.query.is_equal
Checks if two arrays are equal.
Arguments
$1 (string): The name of the first array to compare.
$2 (string): The name of the second array to compare.
Exit codes
0: If the arrays are equal.
1: If the arrays are not equal.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.fn.args.require
Validates the presence and number of arguments for a function.
STDLIB_ARGS_CALLER_FN_NAME string keyword: A string presented as the name of the calling function in logging messages (default=”${FUNCNAME[1]}”).
STDLIB_ARGS_NULL_SAFE_ARRAY array keyword: An array of argument indexes that are null safe, meaning they can be empty values (default=()).
STDLIB_ARGS_NULL_SAFE_ALL_BOOLEAN boolean keyword: A boolean that indicates all arguments are null safe, meaning they can be empty values (default=”0”).
Arguments
$1 (integer): The number of required arguments.
$2 (integer): The number of optional arguments.
… (array): The list of argument values to check.
Exit codes
0: If the operation succeeded.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.fn.assert.is_builtin
Asserts that a command is a bash builtin.
Arguments
$1 (string): The command name to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.fn.assert.is_fn
Asserts that a function name is defined.
Arguments
$1 (string): The function name to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.fn.assert.is_valid_name
Asserts that a string is a valid function name.
Arguments
$1 (string): The string to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.fn.assert.not_builtin
Asserts that a command is not a bash builtin.
Arguments
$1 (string): The command name to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.fn.assert.not_fn
Asserts that a function name is not defined.
Arguments
$1 (string): The function name to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.fn.derive.assertion
Creates an assertion from an existing query function.
Arguments
$1 (string): The name of the query function to derive this assertion from.
$2 (string): The message key to display on error, with the passed value as an argument.
$3 (string): (optional, default=s/.query./.assert./g) The name of the new assertion function.
Exit codes
0: If the operation succeeded.
123: If a variable reserved for use by the BASH stdlib has been assigned an invalid value.
124: If a global variable has been assigned an invalid value.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.fn.derive.clone
Clones an existing function to a new name.
Arguments
$1 (string): The name of the function to clone.
$2 (string): The name for the new function clone.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.fn.derive.pipeable
Creates a pipeable version of an existing function.
STDLIB_PIPEABLE_STDIN_SOURCE_SPECIFIER string keyword: A string used to specify the position of stdin in the arguments (default=’-‘).
Arguments
$1 (string): The name of the function to make pipeable.
$2 (integer): The number of arguments the function requires.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.fn.derive.var
Creates a version of a function that reads from and writes to a variable.
Arguments
$1 (string): The name of the source function.
$2 (string): (optional, default=”${1}_var”) The name of the new target function.
$3 (integer): (optional, default=-1) The argument index for the variable’s existing value.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.fn.keyword.assert.is_valid_with
Checks if a keyword’s value is valid against a validation function.
STDLIB_KW_SOURCE_VAR string keyword: An optional variable name that can be used as a source for validation (logging will still attribute the value to the argument provided keyword) (default=””).
Arguments
$1 (string): The validation function to run.
$2 (string): The name of the keyword to perform validation on.
$3 (string): (optional, default=”value”) Controls whether the ‘name’ or ‘value’ of the keyword is passed to the validation function.
Exit codes
0: If the keyword passes the validation function.
1: If the keyword fails the validation check.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.fn.keyword.query.is_valid_with
Checks if a keyword’s value is valid against a validation function.
STDLIB_KW_SOURCE_VAR string keyword: An optional variable name that can be used as a source for validation (default=””).
Arguments
$1 (string): The validation function to run.
$2 (string): The name of the keyword to perform validation on.
$3 (string): (optional, default=”value”) Controls whether the ‘name’ or ‘value’ of the keyword is passed to the validation function.
Exit codes
0: If the keyword passes the validation function.
1: If the keyword fails the validation check.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.fn.query.is_builtin
Checks if a command is a bash builtin.
Arguments
$1 (string): The command name to check.
Exit codes
0: If the command is a builtin.
1: If the command is not a builtin.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.fn.query.is_fn
Checks if a function name is defined.
Arguments
$1 (string): The function name to check.
Exit codes
0: If the function is defined.
1: If the function is not defined.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.fn.query.is_valid_name
Checks if a string is a valid function name.
Arguments
$1 (string): The string to check.
Exit codes
0: If the name is valid.
1: If the name is invalid.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.io.lock.acquire
Acquires a named exclusive execution lock, or waits until able to do so.
STDLIB_LOCK_PERMISSION_OCTAL string keyword: An octal file system permission value for the created lock (default=”0700”).
STDLIB_LOCK_POLLING_INTERVAL string keyword: A decimal value for the number of seconds the process will wait before retrying lock acquisition (default=”0.1”).
STDLIB_LOCK_QUIET_FAILURE_BOOLEAN boolean keyword: A boolean to disable errors messages on a lock acquisition failure (default=0).
STDLIB_LOCK_WAIT_SECONDS integer keyword: An integer for the number of seconds the process will wait for the lock to become available. To create an infinite wait, use a negative value. (default=30).
STDLIB_LOCK_WORKSPACE string global: A string for the name of a managed temporary directory which has been allocated for lock operations (default=””).
Arguments
$1 (string): A unique alpha-numeric, underscored name for this lock.
Exit codes
0: If the lock was successfully acquired.
1: If the lock could not be acquired.
123: If a variable reserved for use by the BASH stdlib has been assigned an invalid value.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.io.lock.release
Releases a named exclusive execution lock.
STDLIB_LOCK_WORKSPACE string global: A string for the name of a managed temporary directory which has been allocated for lock operations (default=””).
Arguments
$1 (string): A unique alpha-numeric name for this lock.
Exit codes
0: If the lock was successfully released.
1: If the lock could not be released.
123: If a variable reserved for use by the BASH stdlib has been assigned an invalid value.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.io.lock.with
Runs a command with a named exclusive execution lock. A lock workspace is allocated as needed.
STDLIB_LOCK_PERMISSION_OCTAL string keyword: An octal file system permission value for the created lock (default=”0700”).
STDLIB_LOCK_POLLING_INTERVAL string keyword: A decimal value for the number of seconds the process will wait before retrying lock acquisition (default=”0.1”).
STDLIB_LOCK_QUIET_FAILURE_BOOLEAN boolean keyword: A boolean to disable errors messages on a lock acquisition failure (default=0).
STDLIB_LOCK_WAIT_SECONDS integer keyword: An integer for the number of seconds the process will wait for the lock to become available. To create an infinite wait, use a negative value. (default=30).
STDLIB_LOCK_WORKSPACE string global: A string for the name of a managed temporary directory which has been allocated for lock operations (default=””).
STDLIB_LOCK_WORKSPACE_PERMISSION_OCTAL string keyword: An octal file system permission value for the created workspace folder (if allocation is performed) (default=”0700”).
Arguments
$1 (string): A unique alpha-numeric name for this lock.
… (string): The command or function and any arguments that will be executed with this execution lock.
Exit codes
0: If the lock was successfully acquired.
1: If the time out elapsed without the lock becoming available.
123: If a variable reserved for use by the BASH stdlib has been assigned an invalid value.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.io.lock.workspace_allocate
Creates a temporary folder dedicated for execution locking, and handles it’s clean up.
STDLIB_LOCK_WORKSPACE string global: A string for the name of a managed temporary directory which has been allocated for lock operations (default=””).
STDLIB_LOCK_WORKSPACE_PERMISSION_OCTAL string keyword: An octal file system permission value for the created workspace folder (default=”0700”).
STDLIB_HANDLER_EXIT_FN_ARRAY array global: An array used to store exit handler functions (default=()).
Function has no arguments.
Variables set
STDLIB_LOCK_WORKSPACE (string): The name of a managed temporary directory which has been allocated for lock operations.
Exit codes
0: If the workspace was successfully allocated.
1: If the workspace could not be allocated.
123: If a variable reserved for use by the BASH stdlib has been assigned an invalid value.
125: If an invalid keyword has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.io.path.assert.is_exists
Asserts that a path exists.
Arguments
$1 (string): The path to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.io.path.assert.is_file
Asserts that a path is a file.
Arguments
$1 (string): The path to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.io.path.assert.is_file_empty
Asserts that a path is an empty file (length of 0 bytes).
Arguments
$1 (string): The path to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.io.path.assert.is_folder
Asserts that a path is a folder.
Arguments
$1 (string): The path to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.io.path.assert.not_exists
Asserts that a path does not exist.
Arguments
$1 (string): The path to check.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.io.path.query.is_exists
Checks if a path exists.
Arguments
$1 (string): The path to check.
Exit codes
0: If the path exists.
1: If the path does not exist.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.io.path.query.is_file
Checks if a path is a file.
Arguments
$1 (string): The path to check.
Exit codes
0: If the path is a file.
1: If the path is not a file.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.io.path.query.is_file_empty
Checks if a path is an empty file (length of 0 bytes).
Arguments
$1 (string): The path to check.
Exit codes
0: If the path is an empty file.
1: If the path is not an empty file.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.io.path.query.is_folder
Checks if a path is a folder.
Arguments
$1 (string): The path to check.
Exit codes
0: If the path is a folder.
1: If the path is not a folder.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.io.stdin.confirmation
Prompts the user for a confirmation (Y/n).
Arguments
$1 (string): (optional, default=STDIN_DEFAULT_CONFIRMATION_PROMPT) The prompt to display.
Exit codes
0: If the user confirmed with ‘Y’.
1: If the user declined with ‘n’.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Input on stdin
The user input character.
Output on stdout
The prompt and a newline after input.
Output on stderr
The error message if the operation fails.
stdlib.io.stdin.pause
Pauses the script until the user presses a key.
Arguments
$1 (string): (optional, default=STDIN_DEFAULT_PAUSE_PROMPT) The prompt to display.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Input on stdin
The user input character.
Output on stdout
The prompt.
Output on stderr
The error message if the operation fails.
stdlib.io.stdin.prompt
Prompts the user for a value and saves it to a variable.
STDLIB_STDIN_PASSWORD_MASK_BOOLEAN boolean keyword: Indicates if the input should be masked, i.e. for passwords (default=”0”).
Arguments
$1 (string): The variable name to save the input to.
$2 (string): (optional, default=STDIN_DEFAULT_VALUE_PROMPT) The prompt to display.
Exit codes
0: If the operation succeeded.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Input on stdin
The user input.
Output on stdout
The prompt.
Output on stderr
The error message if the operation fails.
stdlib.logger.error
Logs an error message.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: A prefix identifying the calling function (default=”${FUNCNAME[2]}”).
STDLIB_THEME_LOGGER_ERROR string global: The colour to use for the message (default=”LIGHT_RED”).
Arguments
$1 (string): The message to log.
Exit codes
0: If the operation succeeded.
Output on stderr
The error message.
stdlib.logger.error_pipe
A derivative of stdlib.logger.error that can read from stdin.
Arguments
$1 (string): (optional, default=”-”) The message to log, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
Input on stdin
The message to log.
Output on stderr
The error message.
stdlib.logger.info
Logs an informational message.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: A prefix identifying the calling function (default=”${FUNCNAME[2]}”).
STDLIB_THEME_LOGGER_INFO string global: The colour to use for the message (default=”WHITE”).
Arguments
$1 (string): The message to log.
Exit codes
0: If the operation succeeded.
Output on stdout
The informational message.
stdlib.logger.info_pipe
A derivative of stdlib.logger.info that can read from stdin.
Arguments
$1 (string): (optional, default=”-”) The message to log, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
Input on stdin
The message to log.
Output on stdout
The informational message.
stdlib.logger.notice
Logs a notice message.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: A prefix identifying the calling function (default=”${FUNCNAME[2]}”).
STDLIB_THEME_LOGGER_NOTICE string global: The colour to use for the message (default=”GREY”).
Arguments
$1 (string): The message to log.
Exit codes
0: If the operation succeeded.
Output on stdout
The notice message.
stdlib.logger.notice_pipe
A derivative of stdlib.logger.notice that can read from stdin.
Arguments
$1 (string): (optional, default=”-”) The message to log, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
Input on stdin
The message to log.
Output on stdout
The notice message.
stdlib.logger.success
Logs a success message.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: A prefix identifying the calling function (default=”${FUNCNAME[2]}”).
STDLIB_THEME_LOGGER_SUCCESS string global: The colour to use for the message (default=”GREEN”).
Arguments
$1 (string): The message to log.
Exit codes
0: If the operation succeeded.
Output on stdout
The success message.
stdlib.logger.success_pipe
A derivative of stdlib.logger.success that can read from stdin.
Arguments
$1 (string): (optional, default=”-”) The message to log, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
Input on stdin
The message to log.
Output on stdout
The success message.
stdlib.logger.traceback
Prints a traceback of the current function calls.
Function has no arguments.
Exit codes
0: If the operation succeeded.
Output on stdout
The traceback information.
stdlib.logger.warning
Logs a warning message.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: A prefix identifying the calling function (default=”${FUNCNAME[2]}”).
STDLIB_THEME_LOGGER_WARNING string global: The colour to use for the message (default=”YELLOW”).
Arguments
$1 (string): The message to log.
Exit codes
0: If the operation succeeded.
Output on stderr
The warning message.
stdlib.logger.warning_pipe
A derivative of stdlib.logger.warning that can read from stdin.
Arguments
$1 (string): (optional, default=”-”) The message to log, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
Input on stdin
The message to log.
Output on stderr
The warning message.
stdlib.security.get.euid
Gets the effective user ID.
Function has no arguments.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The effective user ID.
stdlib.security.get.gid
Gets the group ID for a given group name.
Arguments
$1 (string): The group name.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The group ID.
stdlib.security.get.uid
Gets the user ID for a given username.
Arguments
$1 (string): The username.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The user ID.
stdlib.security.get.unused_uid
Gets the next available (unused) user ID.
Function has no arguments.
Exit codes
0: If an unused UID was found.
1: If an unused UID was not found.
127: If the wrong number of arguments were provided.
Output on stdout
The unused user ID.
stdlib.security.path.assert.has_group
Asserts that a path has the specified group ownership.
Arguments
$1 (string): The path to check.
$2 (string): The required group name.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The informational message if the assertion fails.
Output on stderr
The error message if the assertion fails.
stdlib.security.path.assert.has_owner
Asserts that a path has the specified user ownership.
Arguments
$1 (string): The path to check.
$2 (string): The required user name.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The informational message if the assertion fails.
Output on stderr
The error message if the assertion fails.
stdlib.security.path.assert.has_permissions
Asserts that a path has the specified octal permissions.
Arguments
$1 (string): The path to check.
$2 (string): The required octal permission value.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The informational message if the assertion fails.
Output on stderr
The error message if the assertion fails.
stdlib.security.path.assert.is_secure
Asserts that a filesystem path is secure by checking its owner, group, and permissions.
Arguments
$1 (string): The filesystem path to check.
$2 (string): The required owner name.
$3 (string): The required group name.
$4 (string): The required octal permission value.
Exit codes
0: If the assertion succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.security.path.make.dir
Creates a directory and sets its owner, group, and permissions.
Arguments
$1 (string): The path to the directory to create.
$2 (string): The owner name to set.
$3 (string): The group name to set.
$4 (string): The octal permission value to set.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.security.path.make.file
Creates a file and sets its owner, group, and permissions.
Arguments
$1 (string): The path to the file to create.
$2 (string): The owner name to set.
$3 (string): The group name to set.
$4 (string): The octal permission value to set.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.security.path.query.has_group
Checks if a path has the specified group ownership.
Arguments
$1 (string): The path to check.
$2 (string): The required group name.
Exit codes
0: If the path has the specified group ownership.
1: If the path does not have the specified group ownership.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.security.path.query.has_owner
Checks if a path has the specified user ownership.
Arguments
$1 (string): The path to check.
$2 (string): The required user name.
Exit codes
0: If the path has the specified user ownership.
1: If the path does not have the specified user ownership.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.security.path.query.has_permissions
Checks if a path has the specified octal permissions.
Arguments
$1 (string): The path to check.
$2 (string): The required octal permission value.
Exit codes
0: If the path has the specified permissions.
1: If the path does not have the specified permissions.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.security.path.query.is_secure
Checks if a filesystem path is secure by checking its owner, group, and permissions.
Arguments
$1 (string): The filesystem path to check.
$2 (string): The required owner name.
$3 (string): The required group name.
$4 (string): The required octal permission value.
Exit codes
0: If the path is secure.
1: If the path is not secure.
127: If the wrong number of arguments were provided.
stdlib.security.path.secure
Secures a filesystem path by setting its owner, group, and permissions.
Arguments
$1 (string): The filesystem path to secure.
$2 (string): The owner name to set.
$3 (string): The group name to set.
$4 (string): The octal permission value to set.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.security.user.assert.is_root
Asserts that the current user is the root user.
Function has no arguments.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.security.user.query.is_root
Checks if the current user is the root user.
Function has no arguments.
Exit codes
0: If the current user is root.
1: If the current user is not root.
127: If the wrong number of arguments were provided.
stdlib.setting.colour.disable
Disables terminal colours.
Function has no arguments.
Exit codes
0: If the operation succeeded.
stdlib.setting.colour.enable
Enables terminal colours.
STDLIB_COLOUR_SILENT_FALLBACK_BOOLEAN boolean global: Disables the error message on failure (default=”0”).
Function has no arguments.
Exit codes
0: If the operation succeeded.
1: If the operation failed.
Output on stderr
The error message if the operation fails.
stdlib.setting.colour.state.disabled
Sets all colour variables to empty strings to disable colours.
Function has no arguments.
Variables set
STDLIB_COLOUR_NC (string): The no-colour escape sequence.
STDLIB_COLOUR_BLACK (string): The black escape sequence.
STDLIB_COLOUR_RED (string): The red escape sequence.
STDLIB_COLOUR_GREEN (string): The green escape sequence.
STDLIB_COLOUR_YELLOW (string): The yellow escape sequence.
STDLIB_COLOUR_BLUE (string): The blue escape sequence.
STDLIB_COLOUR_PURPLE (string): The purple escape sequence.
STDLIB_COLOUR_CYAN (string): The cyan escape sequence.
STDLIB_COLOUR_WHITE (string): The white escape sequence.
STDLIB_COLOUR_GREY (string): The grey escape sequence.
STDLIB_COLOUR_LIGHT_RED (string): The light red escape sequence.
STDLIB_COLOUR_LIGHT_GREEN (string): The light green escape sequence.
STDLIB_COLOUR_LIGHT_YELLOW (string): The light yellow escape sequence.
STDLIB_COLOUR_LIGHT_BLUE (string): The light blue escape sequence.
STDLIB_COLOUR_LIGHT_PURPLE (string): The light purple escape sequence.
STDLIB_COLOUR_LIGHT_CYAN (string): The light cyan escape sequence.
STDLIB_COLOUR_LIGHT_WHITE (string): The light white escape sequence.
Exit codes
0: If the operation succeeded.
stdlib.setting.colour.state.enabled
Sets all colour variables to their respective escape sequences.
Function has no arguments.
Variables set
STDLIB_COLOUR_NC (string): The no-colour escape sequence.
STDLIB_COLOUR_BLACK (string): The black escape sequence.
STDLIB_COLOUR_RED (string): The red escape sequence.
STDLIB_COLOUR_GREEN (string): The green escape sequence.
STDLIB_COLOUR_YELLOW (string): The yellow escape sequence.
STDLIB_COLOUR_BLUE (string): The blue escape sequence.
STDLIB_COLOUR_PURPLE (string): The purple escape sequence.
STDLIB_COLOUR_CYAN (string): The cyan escape sequence.
STDLIB_COLOUR_WHITE (string): The white escape sequence.
STDLIB_COLOUR_GREY (string): The grey escape sequence.
STDLIB_COLOUR_LIGHT_RED (string): The light red escape sequence.
STDLIB_COLOUR_LIGHT_GREEN (string): The light green escape sequence.
STDLIB_COLOUR_LIGHT_YELLOW (string): The light yellow escape sequence.
STDLIB_COLOUR_LIGHT_BLUE (string): The light blue escape sequence.
STDLIB_COLOUR_LIGHT_PURPLE (string): The light purple escape sequence.
STDLIB_COLOUR_LIGHT_CYAN (string): The light cyan escape sequence.
STDLIB_COLOUR_LIGHT_WHITE (string): The light white escape sequence.
Exit codes
0: If the operation succeeded.
stdlib.setting.colour.state.theme
Sets the default theme colours for the logger.
Function has no arguments.
Variables set
STDLIB_THEME_LOGGER_ERROR (string): The colour for error messages.
STDLIB_THEME_LOGGER_WARNING (string): The colour for warning messages.
STDLIB_THEME_LOGGER_INFO (string): The colour for info messages.
STDLIB_THEME_LOGGER_NOTICE (string): The colour for notice messages.
STDLIB_THEME_LOGGER_SUCCESS (string): The colour for success messages.
Exit codes
0: If the operation succeeded.
stdlib.setting.theme.get_colour
Gets the name of a colour variable from the theme.
STDLIB_COLOUR_ string global: A prefix used for all theme colour variables (default=”STDLIB_COLOUR_”).
STDLIB_COLOUR_NULL string global: A default value for null or missing colours (default=””).
Arguments
$1 (string): The name of the colour.
Exit codes
0: If the operation succeeded.
Output on stdout
The name of the colour variable.
Output on stderr
The error message if the operation fails.
stdlib.setting.theme.load
Loads the theme colours.
Function has no arguments.
Exit codes
0: If the operation succeeded.
stdlib.string.args.join
Joins the given arguments into a string by using the given delimiter.
Arguments
$1 (string): The delimiter string used to join the arguments (an empty string is a valid argument).
… (array): A list of input strings to join together.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The joined string.
Output on stderr
The error message if the operation fails.
stdlib.string.args.join_pipe
A derivative of stdlib.string.lines.join that can read from stdin.
Arguments
$1 (string): The delimiter string used to join the arguments.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The strings to process (separated by newlines).
Output on stdout
The joined string.
Output on stderr
The error message if the operation fails.
stdlib.string.args.join_var
A derivative of stdlib.string.lines.join that can write to a variable.
Arguments
$1 (string): The name of the variable to write to.
$2 (string): The delimiter string used to join the arguments (an empty string is a valid argument).
… (array): A list of input strings to join together.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The joined string.
Output on stderr
The error message if the operation fails.
stdlib.string.assert.is_alpha
Asserts that a string contains only alphabetic characters.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_alpha_numeric
Asserts that a string contains only alphanumeric characters.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_boolean
Asserts that a string is a boolean (0 or 1).
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_char
Asserts that a string is a single character.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_decimal
Asserts that a string is a valid decimal.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_decimal_positive
Asserts that a string is a valid positive decimal.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_digit
Asserts that a string contains only digits.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_empty
Asserts that a value is a non-empty string.
Arguments
$1 (string): The value to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_integer
Asserts that a string is an integer.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_integer_with_range
Asserts that a string is an integer within a specified range.
Arguments
$1 (integer): The range start point.
$2 (integer): The range end point.
$3 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_octal_permission
Asserts that a string is a valid octal permission (3 or 4 digits).
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_regex_match
Asserts that a string matches a regular expression.
Arguments
$1 (string): The regular expression to use.
$2 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_snake_case
Asserts that a string is in snake case.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.is_snake_case_upper
Asserts that a string is in upper snake case.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.net.is_ipv4
Asserts that a string is a valid ipv4 address.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.net.is_ipv6
Asserts that a string is a valid ipv6 address.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.not_empty
Asserts that a value is not a non-empty string.
Arguments
$1 (string): The value to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.assert.not_equal
Asserts that two strings are not equal.
Arguments
$1 (string): The first string to compare.
$2 (string): The second string to compare.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.string.colour
Colours a string and prints it with a newline.
Arguments
$1 (string): The name of the colour to use.
$2 (string): The string to colour.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The coloured string with a newline.
Output on stderr
The error message if the operation fails.
stdlib.string.colour_n
Colours a string and prints it without a newline.
STDLIB_COLOUR_NC string global: The no-colour escape sequence (default=”\e[0m”).
Arguments
$1 (string): The name of the colour to use.
$2 (string): The string to colour.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The coloured string without a newline.
Output on stderr
The error message if the operation fails.
stdlib.string.colour_n_pipe
A derivative of stdlib.string.colour_n that can read from stdin.
Arguments
$1 (string): The name of the colour to use.
$2 (string): (optional, default=”-”) The string to colour, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The string to colour.
Output on stdout
The coloured string without a newline.
Output on stderr
The error message if the operation fails.
stdlib.string.colour_pipe
A derivative of stdlib.string.colour that can read from stdin.
Arguments
$1 (string): The name of the colour to use.
$2 (string): (optional, default=”-”) The string to colour, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The string to colour.
Output on stdout
The coloured string with a newline.
Output on stderr
The error message if the operation fails.
stdlib.string.colour_var
A derivative of stdlib.string.colour_n that can read from and write to a variable.
Arguments
$1 (string): The name of the colour to use.
$2 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.colour.substring
Colours the first occurrence of a substring in a string.
STDLIB_COLOUR_NC string global: The no-colour escape sequence (default=”\e[0m”).
Arguments
$1 (string): The name of the colour to use.
$2 (string): The substring to colour.
$3 (string): The source string.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The string with the first occurrence of the substring coloured.
Output on stderr
The error message if the operation fails.
stdlib.string.colour.substring_pipe
A derivative of stdlib.string.colour.substring that can read from stdin.
Arguments
$1 (string): The name of the colour to use.
$2 (string): The substring to colour.
$3 (string): (optional, default=”-”) The source string, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The source string.
Output on stdout
The string with the first occurrence of the substring coloured.
Output on stderr
The error message if the operation fails.
stdlib.string.colour.substring_var
A derivative of stdlib.string.colour.substring that can read from and write to a variable.
Arguments
$1 (string): The name of the colour to use.
$2 (string): The substring to colour.
$3 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.colour.substrings
Colours all occurrences of a substring in a string.
STDLIB_COLOUR_NC string global: The no-colour escape sequence (default=”\e[0m”).
Arguments
$1 (string): The name of the colour to use.
$2 (string): The substring to colour.
$3 (string): The source string.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The string with all occurrences of the substring coloured.
Output on stderr
The error message if the operation fails.
stdlib.string.colour.substrings_pipe
A derivative of stdlib.string.colour.substrings that can read from stdin.
Arguments
$1 (string): The name of the colour to use.
$2 (string): The substring to colour.
$3 (string): (optional, default=”-”) The source string, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The source string.
Output on stdout
The string with all occurrences of the substring coloured.
Output on stderr
The error message if the operation fails.
stdlib.string.colour.substrings_var
A derivative of stdlib.string.colour.substrings that can read from and write to a variable.
Arguments
$1 (string): The name of the colour to use.
$2 (string): The substring to colour.
$3 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.justify.left
Left-justifies a string to a specified width.
Arguments
$1 (integer): The column width to justify to.
$2 (string): The string to justify.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The left-justified string.
Output on stderr
The error message if the operation fails.
stdlib.string.justify.left_pipe
A derivative of stdlib.string.justify.left that can read from stdin.
Arguments
$1 (integer): The column width to justify to.
$2 (string): (optional, default=”-”) The string to justify, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The string to justify.
Output on stdout
The left-justified string.
Output on stderr
The error message if the operation fails.
stdlib.string.justify.left_var
A derivative of stdlib.string.justify.left that can read from and write to a variable.
Arguments
$1 (integer): The column width to justify to.
$2 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.justify.right
Right-justifies a string to a specified width.
Arguments
$1 (integer): The column width to justify to.
$2 (string): The string to justify.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The right-justified string.
Output on stderr
The error message if the operation fails.
stdlib.string.justify.right_pipe
A derivative of stdlib.string.justify.right that can read from stdin.
Arguments
$1 (integer): The column width to justify to.
$2 (string): (optional, default=”-”) The string to justify, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The string to justify.
Output on stdout
The right-justified string.
Output on stderr
The error message if the operation fails.
stdlib.string.justify.right_var
A derivative of stdlib.string.justify.right that can read from and write to a variable.
Arguments
$1 (integer): The column width to justify to.
$2 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.lines.join
Joins lines in a string by removing a delimiter.
STDLIB_LINE_BREAK_DELIMITER string keyword: A line break char sequence which is replaced to join the string (default=$’\n’).
Arguments
$1 (string): The string to process.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The joined string.
Output on stderr
The error message if the operation fails.
stdlib.string.lines.join_pipe
A derivative of stdlib.string.lines.join that can read from stdin.
Arguments
$1 (string): (optional, default=”-”) The string to process, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The string to process.
Output on stdout
The joined string.
Output on stderr
The error message if the operation fails.
stdlib.string.lines.join_var
A derivative of stdlib.string.lines.join that can read from and write to a variable.
Arguments
$1 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.lines.map.fn
Maps a function over each line of a string.
STDLIB_LINE_BREAK_DELIMITER string keyword: A line break char to split the string with for processing (default=$’\n’).
Arguments
$1 (string): The name of the function to apply to each line.
$2 (string): The input string to process.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The mapped lines.
Output on stderr
The error message if the operation fails.
stdlib.string.lines.map.fn_pipe
A derivative of stdlib.string.lines.map.fn that can read from stdin.
STDLIB_LINE_BREAK_DELIMITER string keyword: A line break char to split the string with for processing (default=$’\n’).
Arguments
$1 (string): The name of the function to apply to each line.
$2 (string): (optional, default=”-”) The input string to process, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Input on stdin
The input string to process.
Output on stdout
The mapped lines.
Output on stderr
The error message if the operation fails.
stdlib.string.lines.map.fn_var
A derivative of stdlib.string.lines.map.fn that can read from and write to a variable.
STDLIB_LINE_BREAK_DELIMITER string keyword: A line break char to split the string with for processing (default=$’\n’).
Arguments
$1 (string): The name of the function to apply to each line.
$2 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.lines.map.format
Maps a format string over each line of a string.
STDLIB_LINE_BREAK_DELIMITER string keyword: A line break char to split the string with for processing (default=$’\n’).
Arguments
$1 (string): A valid printf format string.
$2 (string): The input string to process.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The formatted lines.
Output on stderr
The error message if the operation fails.
stdlib.string.lines.map.format_pipe
A derivative of stdlib.string.lines.map.format that can read from stdin.
STDLIB_LINE_BREAK_DELIMITER string keyword: A line break char to split the string with for processing (default=$’\n’).
Arguments
$1 (string): A valid printf format string.
$2 (string): (optional, default=”-”) The input string to process, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The input string to process.
Output on stdout
The formatted lines.
Output on stderr
The error message if the operation fails.
stdlib.string.lines.map.format_var
A derivative of stdlib.string.lines.map.format that can read from and write to a variable.
STDLIB_LINE_BREAK_DELIMITER string keyword: A line break char to split the string with for processing (default=$’\n’).
Arguments
$1 (string): A valid printf format string.
$2 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.pad.left
Pads a string on the left with a specified number of spaces.
Arguments
$1 (integer): The number of spaces to pad with.
$2 (string): The string to pad.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The padded string.
Output on stderr
The error message if the operation fails.
stdlib.string.pad.left_pipe
A derivative of stdlib.string.pad.left that can read from stdin.
Arguments
$1 (integer): The number of spaces to pad with.
$2 (string): (optional, default=”-”) The string to pad, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The string to pad.
Output on stdout
The padded string.
Output on stderr
The error message if the operation fails.
stdlib.string.pad.left_var
A derivative of stdlib.string.pad.left that can read from and write to a variable.
Arguments
$1 (integer): The number of spaces to pad with.
$2 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.pad.right
Pads a string on the right with a specified number of spaces.
Arguments
$1 (integer): The number of spaces to pad with.
$2 (string): The string to pad.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The padded string.
Output on stderr
The error message if the operation fails.
stdlib.string.pad.right_pipe
A derivative of stdlib.string.pad.right that can read from stdin.
Arguments
$1 (integer): The number of spaces to pad with.
$2 (string): (optional, default=”-”) The string to pad, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The string to pad.
Output on stdout
The padded string.
Output on stderr
The error message if the operation fails.
stdlib.string.pad.right_var
A derivative of stdlib.string.pad.right that can read from and write to a variable.
Arguments
$1 (integer): The number of spaces to pad with.
$2 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.query.has_char_n
Checks if a string has a specific character at a specific index.
Arguments
$1 (string): The character to check for.
$2 (integer): The index to check at.
$3 (string): The string to check.
Exit codes
0: If the character is at the index.
1: If the character is not at the index.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.has_substring
Checks if a string contains a substring.
Arguments
$1 (string): The substring to check for.
$2 (string): The string to check.
Exit codes
0: If the string contains the substring.
1: If the string does not contain the substring.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_alpha
Checks if a string contains only alphabetic characters.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string contains only alphabetic characters.
1: If the string contains non-alphabetic characters.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_alpha_numeric
Checks if a string contains only alphanumeric characters.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string contains only alphanumeric characters.
1: If the string contains non-alphanumeric characters.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_boolean
Checks if a string is a boolean (0 or 1).
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is a boolean.
1: If the string is not a boolean.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_char
Checks if a string is a single character.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is a single character.
1: If the string is not a single character.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_decimal
Checks if a string is a valid decimal.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is a valid decimal.
1: If the string is not a decimal.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_decimal_positive
Checks if a string is a valid positive decimal.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is a valid positive decimal.
1: If the string is not a positive decimal.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_digit
Checks if a string contains only digits.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string contains only digits.
1: If the string contains non-digit characters.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_empty
Checks if a value is an empty string.
Arguments
$1 (string): The value to check.
Exit codes
0: If the value is an empty string.
1: If the value is a non empty string.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_integer
Checks if a string is an integer.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is an integer.
1: If the string is not an integer.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_integer_with_range
Checks if a string is an integer within a specified range.
Arguments
$1 (integer): The range start point.
$2 (integer): The range end point.
$3 (string): The string to check.
Exit codes
0: If the string is an integer within the range.
1: If the string is not an integer within the range.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_octal_permission
Checks if a string is a valid octal permission (3 or 4 digits).
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is a valid octal permission.
1: If the string is not a valid octal permission.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_regex_match
Checks if a string matches a regular expression.
Arguments
$1 (string): The regular expression to use.
$2 (string): The string to check.
Exit codes
0: If the string matches the regular expression.
1: If the string does not match the regular expression.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_snake_case
Checks if a string is in snake case.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is valid snake case.
1: If the string is not valid snake case.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.is_snake_case_upper
Checks if a string is in upper snake case.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is valid upper snake case.
1: If the string is not valid upper snake case.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.net.is_ipv4
Checks if a string is a valid ipv4 address.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is a valid ipv4 address.
1: If the string is not a valid ipv4 address.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.net.is_ipv6
Checks if a string is a valid ipv6 address.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is a valid ipv6 address.
1: If the string is not a valid ipv6 address.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.not_empty
Checks if a value is not an empty string.
Arguments
$1 (string): The value to check.
Exit codes
0: If the value is not an empty string.
1: If the value is an empty string.
127: If the wrong number of arguments were provided.
stdlib.string.query.ends_with
Checks if a string ends with a specified substring.
Arguments
$1 (string): The substring to check for.
$2 (string): The string to check.
Exit codes
0: If the string ends with the substring.
1: If the string does not end with the substring.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.first_char_is
Checks if the first character of a string is a specified character.
Arguments
$1 (string): The character to check for.
$2 (string): The string to check.
Exit codes
0: If the first character matches.
1: If the first character does not match.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.last_char_is
Checks if the last character of a string is a specified character.
Arguments
$1 (string): The character to check for.
$2 (string): The string to check.
Exit codes
0: If the last character matches.
1: If the last character does not match.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.query.starts_with
Checks if a string starts with a specified substring.
Arguments
$1 (string): The substring to check for.
$2 (string): The string to check.
Exit codes
0: If the string starts with the substring.
1: If the string does not start with the substring.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.string.trim.left
Trims leading whitespace from a string.
Arguments
$1 (string): The string to trim.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The trimmed string.
Output on stderr
The error message if the operation fails.
stdlib.string.trim.left_pipe
A derivative of stdlib.string.trim.left that can read from stdin.
Arguments
$1 (string): (optional, default=”-”) The string to trim, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The string to trim.
Output on stdout
The trimmed string.
Output on stderr
The error message if the operation fails.
stdlib.string.trim.left_var
A derivative of stdlib.string.trim.left that can read from and write to a variable.
Arguments
$1 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.trim.right
Trims trailing whitespace from a string.
Arguments
$1 (string): The string to trim.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stdout
The trimmed string.
Output on stderr
The error message if the operation fails.
stdlib.string.trim.right_pipe
A derivative of stdlib.string.trim.right that can read from stdin.
Arguments
$1 (string): (optional, default=”-”) The string to trim, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Input on stdin
The string to trim.
Output on stdout
The trimmed string.
Output on stderr
The error message if the operation fails.
stdlib.string.trim.right_var
A derivative of stdlib.string.trim.right that can read from and write to a variable.
Arguments
$1 (string): The name of the variable to read from and write to.
Exit codes
0: If the operation succeeded.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.string.wrap
Wraps text to a specified width with padding.
STDLIB_LINE_BREAK_FORCE_CHAR string keyword: A char that ‘forces’ a line break in the output text (default=”*”).
STDLIB_WRAP_PREFIX string keyword: A string to insert when wrapping text (default=””).
Arguments
$1 (integer): The left-side padding.
$2 (integer): The right-side wrap limit.
$3 (string): The text to wrap.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The wrapped text.
Output on stderr
The error message if the operation fails.
stdlib.string.wrap_pipe
A derivative of stdlib.string.wrap that can read from stdin.
Arguments
$1 (integer): The left-side padding.
$2 (integer): The right-side wrap limit.
$3 (string): (optional, default=”-”) The text to wrap, by default this function reads from stdin.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Input on stdin
The text to wrap.
Output on stdout
The wrapped text.
Output on stderr
The error message if the operation fails.
stdlib.trap.create.cleanup_fn
Creates a cleanup function that removes filesystem objects.
Arguments
$1 (string): The name of the cleanup function to create.
$2 (string): The name of the array tracking filesystem objects to cleanup.
$3 (boolean): (optional, default=”0”) Whether to perform recursive deletes.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.trap.create.handler
Creates a trap handler function and a registration function.
Arguments
$1 (string): The name of the handler function to create.
$2 (string): The name of the array to store registered handler functions.
Exit codes
0: If the operation succeeded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the operation fails.
stdlib.trap.fn.cleanup_on_exit
A handler function that removes files when called (by default this handler is registered to the exit signal).
STDLIB_CLEANUP_FN_TARGETS_ARRAY array global: An array used to store file names targeted by the cleanup_on_exit function (default=()).
Function has no arguments.
Exit codes
0: If the operation succeeded.
stdlib.trap.handler.err.fn
A handler function that is invoked on an error trap.
STDLIB_HANDLER_ERR_FN_ARRAY array global: An array containing a list of functions that are run on error (default=()).
Function has no arguments.
Exit codes
0: If the operation succeeded.
stdlib.trap.handler.err.fn.register
Adds a function to the error handler, which will be invoked (without args) during an error.
Function has no arguments.
Variables set
STDLIB_HANDLER_ERR_FN_ARRAY (array): An array containing a list of functions that are run on error.
Exit codes
0: If the operation succeeded.
stdlib.trap.handler.exit.fn
A handler function that is invoked on an exit trap.
STDLIB_HANDLER_EXIT_FN_ARRAY array global: An array containing a list of functions that are run on an exit call (default=(“stdlib.trap.fn.cleanup_on_exit”)).
Function has no arguments.
Exit codes
0: If the operation succeeded.
stdlib.trap.handler.exit.fn.register
Adds a function to the exit handler, which will be invoked (without args) during an exit call.
Function has no arguments.
Variables set
STDLIB_HANDLER_EXIT_FN_ARRAY (array): An array containing a list of functions that are run on an exit call.
Exit codes
0: If the operation succeeded.
stdlib.var.assert.is_empty
Asserts that a variable is an empty value (unset variables, empty arrays, empty associative arrays, empty strings and empty integers).
Arguments
$1 (string): The name of the variable to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.var.assert.is_set
Asserts that a variable is set.
Arguments
$1 (string): The name of the variable to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.var.assert.is_valid_name
Asserts that a string is a valid variable name.
Arguments
$1 (string): The string to check.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.var.assert.is_valid_with
Asserts a variable’s value is valid against a validation function.
STDLIB_VALIDATION_SOURCE_VAR string keyword: An optional variable name that can be used as a source for validation (logging will still attribute the value to the argument provided variable name) (default=””).
Arguments
$1 (string): The validation function to run.
$2 (string): The name of the variable containing the value to perform validation on.
$3 (string): (optional, default=”value”) Controls whether the ‘name’ or ‘value’ of the variable is passed to the validation function.
Exit codes
0: If the assertion succeeded.
1: If the assertion failed.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.var.global.assert.is_valid_with
Asserts a global variable’s value is valid against a validation function.
STDLIB_VALIDATION_SOURCE_VAR string keyword: An optional variable name that can be used as a source for validation (logging will still attribute the value to the argument provided variable name) (default=””).
Arguments
$1 (string): The validation function to run.
$2 (string): The name of the global variable containing the value to perform validation on.
$3 (string): (optional, default=”value”) Controls whether the ‘name’ or ‘value’ of the variable is passed to the validation function.
Exit codes
0: If the global variable passes the validation function.
1: If the global variable fails the validation check.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stderr
The error message if the assertion fails.
stdlib.var.query.is_empty
Checks if a variable is an empty value (unset variables, empty arrays, empty associative arrays, empty strings and empty integers).
Arguments
$1 (string): The name of the variable to check.
Exit codes
0: If the variable is an empty value.
1: If the variable is not an empty value.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.var.query.is_set
Checks if a variable is set.
Arguments
$1 (string): The name of the variable to check.
Exit codes
0: If the variable is set.
1: If the variable is not set.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.var.query.is_valid_name
Checks if a string is a valid variable name.
Arguments
$1 (string): The string to check.
Exit codes
0: If the string is a valid variable name.
1: If the string is not a valid variable name.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
stdlib.var.query.is_valid_with
Checks if a variable’s value is valid against a validation function.
STDLIB_VALIDATION_SOURCE_VAR string keyword: An optional variable name that can be used as a source for validation (default=””).
Arguments
$1 (string): The validation function to run.
$2 (string): The name of the variable containing the value to perform validation on.
$3 (string): (optional, default=”value”) Controls whether the ‘name’ or ‘value’ of the variable is passed to the validation function.
Exit codes
0: If the variable passes the validation function.
1: If the variable fails the validation check.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.