Usage Functions

Usage refers to displaying an error which shows the proper usage of a program to the user or controlling program.

Essentially a usage function is a error handler and should adhere to that interface, which is two arguments:

returnCode - UnsignedInteger. Required. The return code to handle. Can be 0 or greater,
message ... - String. Optioal. Message to display.

The most basic error handler is {SEE:returnMessage}, which can be used as a default when you do not want to define your own.

Error handlers are internally written as the function name with an underscore prefix:

myFunction() {
    ...
}   
_myFunction() {
    # You can add custom handling code here if desired.
    # __IDENTICAL__ bashDocumentation 1
    bashDocumentation "${BASH_SOURCE[0]}" "${FUNCNAME[0]#_}" "$@"
    # You can add additional handling code here if desired.
}

Usage formatting

`bashDocumentation`

Universal error handler for functions (with formatting)

Arguments

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

Debugging settings

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

fast-usage - bashDocumentation 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.

`bashDocumentationMarkdown`

Output documentation for a function in Markdown format

Usage

bashDocumentationMarkdown functionName [ --help ]

Output documentation for a function in Markdown format

Arguments

functionName - String. Required. The function which actually defines our usage syntax. Documentation is extracted from this function, regardless.
--help - Flag. Optional. Display this help.

Return codes

0 - Success
1 - Environment error
2 - Argument error

`bashSimpleDocumentation`

Output a simple error message for a function

Usage

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

Output a simple error message for a function

Arguments

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

Return codes

0 - Success
1 - Environment error
2 - Argument error

Environment

`executableRequire`

Check that one or more binaries are installed

Usage

executableRequire usageFunction binary

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

1 - If any binary is not available within the current path

`environmentRequire`

Requires environment variables to be set and non-blank

Usage

environmentRequire usageFunction [ environmentVariable ]

Requires environment variables to be set and non-blank

Arguments

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

Return codes

0 - All environment variables are set and non-empty
1 - If any environmentVariable variables are not set or are empty.

Argument validation

For argument validation, use validate.

Internal Functions

`__functionSettings`

Load cached function comment values

Usage

__functionSettings [ home ] [ functionName ] [ generatePath ]

Load cached function comment values

Arguments

home - Directory. BUILD_HOME
functionName - String. Function to fetch settings for
generatePath - Boolean. Optional. Pass in true to just generate the file path and not require the file to exist.

Return codes

0 - Success
1 - Environment error
2 - Argument error

Environment

{SEE:BUILD_DOCUMENTATION_PATH.sh}

`__bashDocumentationCached`

Display cached usage for a function

Usage

__bashDocumentationCached handler [ home ] [ functionName ] [ returnCode ] [ message ... ]

Display cached usage for a function

Arguments

handler - Function. Required.
home - Directory. BUILD_HOME
functionName - String. Function to display usage for
returnCode - UnsignedInteger. Optional. Exit code to display. Defaults to 0 - no error.
message ... - String. Optional. Display this message which describes why exitCode occurred.

Return codes

0 - Success
1 - Environment error
2 - Argument error

Environment

{SEE:BUILD_HOME.sh} {SEE:BUILD_COLORS.sh} {SEE:BUILD_DOCUMENTATION_PATH.sh}

`__usageMessage`

Output the message for usage consistently

Usage

__usageMessage [ returnCode ] [ message ... ]

Output the message for usage consistently

Arguments

returnCode - UnsignedInteger. Optional. Exit code to possibly display with message.
message ... - String. Optional. Display this message which describes why exitCode occurred.

Return codes

0 - Success
1 - Environment error
2 - Argument error

`__usageMessageStyle`

Style usage messages

Usage

__usageMessageStyle returnCode

Format arguments using the usage message return code to style output. - 0 - meaning no error, style is info - 1 - Environment error, style is error - 2 - Argument error, style is red - * - All additional errors, style is orange

Arguments

returnCode - UnsignedInteger. Required. Return code to use as the basis for styling output.

Return codes

0 - Success
1 - Environment error
2 - Argument error

🛠️ Tools · ⬅ Top