Skip to content

Sugar Extensions

🛠️ Tools · ⬅ Top

Usage Sugar

See Sugar Core first.

This groupings of functions are related to a usage function to handle errors:

  • __usage code handler command ... - Run command ..., and if it fails invoke handler with code and command arguments.
  • catchEnvironment handler command ... - Run command ... and if it fails invoke handler with an environment error.
  • catchArgument handler command ... - Run command ... and if it fails invoke handler with an argument error.
  • throwEnvironment handler message ... - Run handler with an environment error and message ... arguments.
  • throwArgument handler message ... - Run handler with an argument error and message ... arguments.

handler argument signature is:

`handler` `exitCode` `message ...`

This is universally used throughout.

Usage Sugar References

execute

Run binary and output failed command upon error

Usage

execute binary ...

Run binary and output failed command upon error

Arguments

  • binary ... - Required. Executable. Any arguments are passed to binary.

Return codes

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

Requires

returnMessage

catchReturn

Run binary and catch errors with handler

Usage

catchReturn handler binary ...

Run binary and catch errors with handler

Arguments

  • handler - Required. Function. Error handler.
  • binary ... - Required. Executable. Any arguments are passed to binary.

Return codes

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

Requires

returnArgument

catchCode

Run command, handle failure with handler with code and command

Usage

catchCode code handler command ...

Run command, handle failure with handler with code and command as error

Arguments

  • code - Required. UnsignedInteger. Exit code to return
  • handler - Required. Function. Failure command, passed remaining arguments and error code.
  • command - Required. String. Command to run.

Return codes

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

Requires

isUnsignedInteger returnArgument isFunction isCallable

catchEnvironment

Run command, upon failure run handler with an environment error

Usage

catchEnvironment handler command ...

Run command, upon failure run handler with an environment error

Arguments

  • handler - Required. Function. Failure command
  • command - Required. Command to run.

Return codes

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

catchEnvironmentQuiet

Run handler with an environment error

Usage

catchEnvironmentQuiet handler quietLog command ...

Run handler with an environment error

Arguments

  • handler - Required. Function. Failure command
  • quietLog - Required. File. File to output log to temporarily for this command. If quietLog is - then creates a temporary file for the command which is deleted automatically.
  • command ... - Required. Callable. Thing to run and append output to quietLog.

Return codes

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

Requires

isFunction returnArgument buildFailed debuggingStack throwEnvironment

catchArgument

Run command, upon failure run handler with an argument error

Usage

catchArgument handler command

Run command, upon failure run handler with an argument error

Arguments

  • handler - Required. Function. Failure command
  • command - Required. Command to run.

Return codes

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

throwEnvironment

Run handler with an environment error

Usage

throwEnvironment handler [ message ]

Run handler with an environment error

Arguments

  • handler - Required. Function. Failure command
  • message - Optional. Error message to display.

Return codes

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

throwArgument

Run handler with an argument error

Usage

throwArgument handler [ message ]

Run handler with an argument error

Arguments

  • handler - Required. Function. Failure command
  • message - Optional. Error message to display.

Return codes

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

muzzle

Suppress stdout without piping. Handy when you just want a

Usage

muzzle command [ ... ]

Suppress stdout without piping. Handy when you just want a behavior not the output.

Writes to standard output

  • No output from stdout ever from this function

Arguments

  • command - Required. Callable. Thing to muzzle.
  • ... - Optional. Arguments. Additional arguments.

Examples

muzzle pushd "$buildDir"
catchEnvironment "$handler" phpBuild || returnUndo $? muzzle popd || return $?

Return codes

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

mapReturn

map a return value from one value to another

Usage

mapReturn [ --help ] [ value ] [ from ] [ to ] [ ... ]

map a return value from one value to another

Arguments

  • --help - Optional. Flag. Display this help.
  • value - Integer. A return value.
  • from - Integer. When value matches from, instead return to
  • to - Integer. The value to return when from matches value
  • ... - Additional from-to pairs can be passed, first matching value is used, all values will be examined if none match

Return codes

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

convertValue

map a value from one value to another given from-to

Usage

convertValue [ --help ] [ value ] [ from ] [ to ] [ ... ]

map a value from one value to another given from-to pairs

Prints the mapped value to stdout

Arguments

  • --help - Optional. Flag. Display this help.
  • value - String. A value.
  • from - String. When value matches from, instead print to
  • to - String. The value to print when from matches value
  • ... - Additional from-to pairs can be passed, first matching value is used, all values will be examined if none match

Return codes

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

Handling arguments and stdin similarly

executeInputSupport

Support arguments and stdin as arguments to an executor

Usage

executeInputSupport [ executor ... -- ] [ -- ] [ ... ]

Support arguments and stdin as arguments to an executor

Arguments

  • executor ... -- - The command to run on each line of input or on each additional argument. Arguments to prefix the final variable argument can be supplied prior to an initial --.
  • -- - Alone after the executor forces stdin to be ignored. The -- flag is also removed from the arguments passed to the executor.
  • ... - Any additional arguments are passed directly to the executor

Return codes

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

Deprecated Logging

_deprecated

Logs all deprecated functions to application root in a file

Usage

_deprecated command ...

Logs all deprecated functions to application root in a file called .deprecated

Arguments

  • function - Required. String. Function which is deprecated.

Examples

_deprecated "${FUNCNAME[0]}"

Return codes

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

Requires

printf date