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 [returnMessage](../tools/sugar-core.md#returnmessage) - Return passed in integer return code and output message to ([source](https://github.com/zesk/build/blob/main/bin/build/tools/example.sh#L143)), 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]}" "${NOT-FUNCNAME[0]#_}" "$@"
    # You can add additional handling code here if desired.
}

Usage formatting

`bashDocumentation`

Universal function documentation

Arguments

functionDefinitionFile - File. Required. The file in which the function is defined. If you don't know, use __bashDocumentation_FindFunctionDefinitions or __bashDocumentation_FindFunctionDefinition. (Both SLOW!)
functionName - String. Required. The function which actually defines our usage syntax. Documentation is extracted from this function, regardless.
returnCode - Integer. Required. The return code to output.
message - String. Optional. A message to output relating to the return code.

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
usage-cache-skip - Skip all caching and generate from scratch
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 Debugging Flag – CommaDelimitedList. Constant for turning debugging on during build to find errors

Usage formatting

`bashDocumentation`

Universal function documentation

Arguments

functionDefinitionFile - File. Required. The file in which the function is defined. If you don't know, use __bashDocumentation_FindFunctionDefinitions or __bashDocumentation_FindFunctionDefinition. (Both SLOW!)
functionName - String. Required. The function which actually defines our usage syntax. Documentation is extracted from this function, regardless.
returnCode - Integer. Required. The return code to output.
message - String. Optional. A message to output relating to the return code.

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
usage-cache-skip - Skip all caching and generate from scratch
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 Debugging Flag – CommaDelimitedList. Constant for turning debugging on during build to find errors

`bashDocumentationMarkdown`

Output documentation for a function in Markdown format

Usage

bashDocumentationMarkdown functionName [ --help ]

Output documentation for a function in Markdown format

Location: bin/build/tools/usage.sh

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`

Simpler bashDocumentation

Usage

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

Output a simple error message for a function.

Location: bin/build/tools/usage.sh

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

Requires

bashFunctionComment - Output the comment for a function in a file (source)
decorate - decorate text using colors and styles (source)
read
printf
returnCodeString - Output the exit code as a string (source)
helpArgument - Simple help argument handler. (source)
bashDocumentation - Universal function documentation (source)

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

Location: bin/build/tools/usage.sh

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

Location: bin/build/tools/usage.sh

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

Location: bin/build/tools/usage.sh

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

BUILD_DOCUMENTATION_PATH Build Documentation Path List – DirectoryList. Search path for documentation settings file.

`__bashDocumentationCached`

Display cached usage for a function

Usage

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

Display cached usage for a function

Location: bin/build/tools/usage.sh

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

BUILD_HOME Build Home Directory – Directory. BUILD_HOME is . when this code is installed - at BUILD_COLORS Build Colors Flag – Boolean. If true then colors are shown, blank means guess the BUILD_DOCUMENTATION_PATH Build Documentation Path List – DirectoryList. Search path for documentation settings file.

Requires

decorateThemed - Applies the current theme to text rendered using `decorateThemelessMode` (source)
catchEnvironment - Run `command`, upon failure run `handler` with an environment error (source)
decorate - decorate text using colors and styles (source)

`__usageMessage`

Output the message for usage consistently

Usage

__usageMessage [ returnCode ] [ message ... ]

Output the message for usage consistently

Location: bin/build/tools/usage.sh

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

Requires

decorate - decorate text using colors and styles (source)
returnCodeString - Output the exit code as a string (source)

`__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

Location: bin/build/install.sample.sh

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