Skip to content

Usage Functions

🛠️ Tools · ⬅ Home

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/application.sh#L107)), 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__ usageDocument 1
    usageDocument "${BASH_SOURCE[0]}" "${FUNCNAME[0]#_}" "$@"
    # You can add additional handling code here if desired.
}

Usage formatting

usageDocument

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 - 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 - 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 decorate read printf returnCodeString __help usageDocument __usageDocumentCached

Environment

usageRequireBinary

Check that one or more binaries are installed

Usage

usageRequireBinary 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

usageRequireEnvironment

Requires environment variables to be set and non-blank

Usage

usageRequireEnvironment 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 ]

Requires:

Arguments

  • home - Directory. BUILD_HOME
  • functionName - String. Function to fetch settings for

Return codes

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

Environment

  • BUILD_DOCUMENTATION_PATH - DirectoryList. Search path for documentation settings file. A colon : separated list of paths to search for function documentation settings file for __usageDocumentCached

__usageDocumentCached

Display cached usage for a function

Usage

__usageDocumentCached 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

  • BUILD_COLORS - Boolean. If true then colors are shown, blank means guess the value, false means no colors

  • BUILD_DOCUMENTATION_PATH - DirectoryList. Search path for documentation settings file. A colon : separated list of paths to search for function documentation settings file for __usageDocumentCached

Requires

decorateThemed catchEnvironment __usageMessage decorate __functionSettings

__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

Requires

decorate returnCodeString

__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