STDLIB FN Function Reference

Index

stdlib.fn.args.require
stdlib.fn.assert.is_builtin
stdlib.fn.assert.is_fn
stdlib.fn.assert.is_valid_name
stdlib.fn.assert.not_builtin
stdlib.fn.assert.not_fn
stdlib.fn.derive.assertion
stdlib.fn.derive.clone
stdlib.fn.derive.pipeable
stdlib.fn.derive.var
stdlib.fn.keyword.assert.is_valid_with
stdlib.fn.keyword.query.is_valid_with
stdlib.fn.query.is_builtin
stdlib.fn.query.is_fn
stdlib.fn.query.is_valid_name

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.