Skip to content

Usage Functions

🛠️ Tools · ⬅ Top

The concept of a "usage" function is one that fails, and displays a reasonable error to the user or controlling program.

Essentially a usage function is a failure handler. If you need a simple usage function use returnMessage.

Usage formatting

usageDocument

Universal error handler for functions (with formatting)

Arguments

  • functionDefinitionFile - Required. File. The file in which the function is defined. If you don't know, use __bashDocumentation_FindFunctionDefinitions or __bashDocumentation_FindFunctionDefinition.
  • functionName - Required. String. The function which actually defines our usage syntax. Documentation is extracted from this function, regardless.
  • exitCode - Required. Integer. The function which actually defines our usage syntax. Documentation is extracted from this function, regardless.
  • message - Optional. String. A message.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • fast-usage - usageDocument does not output formatted help for performance reasons
  • handler - For all --help and any function which uses usageTemplate to output documentation (upon error), the stack will be displayed

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • BUILD_DEBUG - Add fast-usage to make this quicker when you do not care about usage/failure.

usageDocumentSimple

Output a simple error message for a function

Usage

usageDocumentSimple [ --help ] source function returnCode [ message ... ]

Output a simple error message for a function

Arguments

  • --help - Optional. Flag. Display this help.
  • source - File. Required. File where documentation exists.
  • function - String. Required. Function to document.
  • returnCode - UnsignedInteger. Required. Exit code to return.
  • message ... - Optional. String. Message to display to the user.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Requires

bashFunctionComment decorate read printf returnCodeString __help usageDocument

Environment

usageRequireBinary

Check that one or more binaries are installed

Usage

usageRequireBinary usageFunction binary

Return Code: 1 - If any binary is not available within the current path Requires the binaries to be found via which

Runs handler on failure

Arguments

  • usageFunction - Required. bash function already defined to output handler
  • binary - Required. Binary which must have a which path.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageRequireEnvironment

Requires environment variables to be set and non-blank

Usage

usageRequireEnvironment usageFunction [ environmentVariable ]

Requires environment variables to be set and non-blank Return Code: 0 - All environment variables are set and non-empty Return Code: 1 - If any environmentVariable variables are not set or are empty.

Arguments

  • usageFunction - Required. bash function already defined to output handler
  • environmentVariable - Optional. String. One or more environment variables which should be set and non-empty.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Argument check: File System

All functions prefixed with usageArgument will be replaced with validate in the next major release.

usageArgumentExists

Validates a value is not blank and exists in the

Usage

usageArgumentExists usageFunction variableName variableValue [ noun ]

Validates a value is not blank and exists in the file system Upon success, outputs the file name Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to file or directory

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentFile

Validates a value is not blank and is a file.

Usage

usageArgumentFile usageFunction variableName variableValue [ noun ]

Validates a value is not blank and is a file. Upon success, outputs the file name Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Value to test.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to file

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentRealFile

Validates a value is not blank and is a file

Usage

usageArgumentRealFile usageFunction variableName variableValue [ noun ]

Validates a value is not blank and is a file and does realPath on it. Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Value to test.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to file

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Validates a value is not blank and is a link

Usage

usageArgumentLink usageFunction variableName variableValue [ noun ]

Validates a value is not blank and is a link Upon success, outputs the file name Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Path to a link file.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to link

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentFileDirectory

Validates a value is not blank and is a file

Usage

usageArgumentFileDirectory usageFunction variableName variableValue [ noun ]

Validates a value is not blank and is a file path with a directory that exists. Upon success, outputs the file name. Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to file

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentDirectory

Validates a value is not blank and is a directory.

Usage

usageArgumentDirectory usageFunction variableName variableValue [ noun ]

Validates a value is not blank and is a directory. Upon success, outputs the directory name trailing slash stripped. Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to directory

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentDirectoryList

Validates a value as a directory search list. Upon success,

Usage

usageArgumentDirectoryList usageFunction variableName variableValue [ noun ]

Validates a value as a directory search list. Upon success, outputs the entire list, cleans up any invalid values or trailing characters. Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to directory list

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentRealDirectory

Validates a value is not blank and is a directory

Usage

usageArgumentRealDirectory usageFunction variableName variableValue [ noun ]

Validates a value is not blank and is a directory and does realPath on it. Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to directory

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentRemoteDirectory

A remote path is one which exists in another file

Usage

usageArgumentRemoteDirectory handler argument

A remote path is one which exists in another file system Return Code: 2 - Always

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Argument Environment Files

usageArgumentLoadEnvironmentFile

Validates a value is not blank and is an environment

Usage

usageArgumentLoadEnvironmentFile usageFunction variableName variableValue [ noun ]

Validates a value is not blank and is an environment file which is loaded immediately.

Return Code: 2 - Argument error Return Code: 0 - Success Upon success, outputs the file name to stdout, outputs a console message to stderr

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to file

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Argument Application paths

usageArgumentApplicationFile

Validates a value as an application-relative file. Upon success, outputs

Usage

usageArgumentApplicationFile usageFunction variableName variableValue [ noun ]

Validates a value as an application-relative file. Upon success, outputs relative path. Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Value to test.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to directory list

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentApplicationDirectory

Validates a value as an application-relative directory. Upon success, outputs

Usage

usageArgumentApplicationDirectory usageFunction variableName variableValue [ noun ]

Validates a value as an application-relative directory. Upon success, outputs relative path. Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to directory list

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentApplicationDirectoryList

Validates a value as an application-relative directory search list. Upon

Usage

usageArgumentApplicationDirectoryList usageFunction variableName variableValue [ noun ]

Validates a value as an application-relative directory search list. Upon success, outputs the entire list, cleans up any invalid values or trailing characters. Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to directory list

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Argument check: Strings

usageArgumentEmptyString

Do not require argument to be non-blank

Usage

usageArgumentEmptyString handler argument [ value ]

Do not require argument to be non-blank Return Code: 0 - Always

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.
  • value - Optional. String, Value to output.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentString

Require an argument to be non-blank

Usage

usageArgumentString handler argument [ value ]

Require an argument to be non-blank Return Code: 2 - If value is blank Return Code: 0 - If value is non-blank

Arguments

  • handler - Required. Function. Usage function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.
  • value - Optional. String, Value which should be non-blank otherwise an argument error is thrown.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentEnvironmentVariable

Validates a value is ok for an environment variable name

Usage

usageArgumentEnvironmentVariable usageFunction variableName variableValue [ noun ]

Validates a value is ok for an environment variable name Upon success, outputs the name Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Environment variable name.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to environment variable

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Argument check: Number and Simple Types

usageArgumentBoolean

Require an argument to be a boolean value

Usage

usageArgumentBoolean handler argument [ value ]

Require an argument to be a boolean value Return Code: 2 - If value is not a boolean Return Code: 0 - If value is a boolean

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.
  • value - Optional. String, Value which should be non-blank otherwise an argument error is thrown.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentNumber

Validates a value is a number

Usage

usageArgumentNumber usageFunction variableName variableValue [ noun ]

Validates a value is a number Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to integer

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentInteger

Validates a value is an integer

Usage

usageArgumentInteger usageFunction variableName variableValue [ noun ]

Validates a value is an integer Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to integer

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentPositiveInteger

Validates a value is an unsigned integer and greater than

Usage

usageArgumentPositiveInteger usageFunction variableName variableValue [ noun ]

Validates a value is an unsigned integer and greater than zero (NOT zero) Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to unsigned integer

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentUnsignedInteger

Validates a value is an unsigned integer

Usage

usageArgumentUnsignedInteger usageFunction variableName variableValue [ noun ]

Validates a value is an unsigned integer Return Code: 2 - Argument error Return Code: 0 - Success

Arguments

  • usageFunction - Required. Function. Run if handler fails
  • variableName - Required. String. Name of variable being tested
  • variableValue - Required. String. Required only in that if it's blank, it fails.
  • noun - Optional. String. Noun used to describe the argument in errors, defaults to unsigned integer

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Argument check: Functional

usageArgumentCallable

Require an argument to be a callable

Usage

usageArgumentCallable handler argument [ value ]

Require an argument to be a callable Return Code: 2 - If value is not isCallable Return Code: 0 - If value is isCallable

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.
  • value - Optional. String, Value which should be callable otherwise an argument error is thrown.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentFunction

Require an argument to be a function

Usage

usageArgumentFunction handler argument [ value ]

Require an argument to be a function Return Code: 2 - If value is not isFunction Return Code: 0 - If value is isFunction

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.
  • value - Optional. String, Value which should be a function otherwise an argument error is thrown.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentExecutable

Require an argument to be a executable

Usage

usageArgumentExecutable handler argument [ value ]

Require an argument to be a executable Return Code: 2 - If value is not isExecutable Return Code: 0 - If value is isExecutable

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.
  • value - Optional. String, Value which should be executable otherwise an argument error is thrown.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Complex String Types

usageArgumentURL

Require an argument to be a URL

Usage

usageArgumentURL handler argument [ value ]

Require an argument to be a URL Return Code: 0 - If value is urlValid Return Code: 2 - If value is not urlValid

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.
  • value - Optional. String, Value which should be a URL otherwise an argument error is thrown.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentDate

A remote path is one which exists in another file

Usage

usageArgumentDate handler argument

A remote path is one which exists in another file system Return Code: 2 - Always

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentSecret

Secrets are things which should be kept secret

Usage

usageArgumentSecret handler argument

Secrets are things which should be kept secret

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Lists

usageArgumentArray

Placeholder for array types

Usage

usageArgumentArray handler argument

Placeholder for array types

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentColonDelimitedList

List delimited with colons :

Usage

usageArgumentColonDelimitedList handler argument

List delimited with colons :

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentCommaDelimitedList

List delimited with commas ,

Usage

usageArgumentCommaDelimitedList handler argument

List delimited with commas ,

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentList

List delimited with spaces

Usage

usageArgumentList handler argument

List delimited with spaces

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

usageArgumentArguments

Placeholder for additional arguments

Usage

usageArgumentArguments handler argument [ value ... ]

Placeholder for additional arguments

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.
  • value ... - Optional. Arguments. Additional arguments.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Types

usageArgumentFlag

List delimited with colons :

Usage

usageArgumentFlag handler argument

List delimited with colons :

Arguments

  • handler - Required. Function. handler function to call upon failure.
  • argument - Required. String. Name of the argument used in error messages.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error