Skip to content

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]}" "${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

  • {SEE:BUILD_DEBUG}

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

  • {SEE:BUILD_DEBUG}

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

  • {SEE:bashFunctionComment}
  • {SEE:decorate}
  • read
  • printf
  • {SEE:returnCodeString}
  • {SEE:helpArgument}
  • {SEE:bashDocumentation}
  • {SEE:__bashDocumentationCached}

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}

{__bashDocumentationCached}

{__usageMessage}

{__usageMessageStyle}

🛠️ Tools · ⬅ Top