STDLIB IO Function Reference

Index

stdlib.io.lock.acquire
stdlib.io.lock.release
stdlib.io.lock.with
stdlib.io.lock.workspace_allocate
stdlib.io.path.assert.is_exists
stdlib.io.path.assert.is_file
stdlib.io.path.assert.is_file_empty
stdlib.io.path.assert.is_folder
stdlib.io.path.assert.not_exists
stdlib.io.path.query.is_exists
stdlib.io.path.query.is_file
stdlib.io.path.query.is_file_empty
stdlib.io.path.query.is_folder
stdlib.io.stdin.confirmation
stdlib.io.stdin.pause
stdlib.io.stdin.prompt

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.