Skip to content

Sugar Extensions

🛠️ Tools · ⬅ Home

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 [ --help ] binary [ ... ]

Run binary and output failed command upon error

Arguments

  • --help - Flag. Optional. Display this help.
  • binary - Callable. Required. Command to run.
  • ... - Arguments. Optional. Any arguments are passed to binary.

Return codes

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

catchReturn

Run binary and catch errors with handler

Usage

catchReturn handler binary ...

Run binary and catch errors with handler

Arguments

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

Return codes

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

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 - UnsignedInteger. Required. Exit code to return
  • handler - Function. Required. Failure command, passed remaining arguments and error code.
  • command ... - Callable. Required. Command to run.
  • ... - Arguments. Optional. Arguments to command

Return codes

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

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 - String. Required. Failure command
  • command ... - Callable. Required. Command to run.
  • ... - Arguments. Optional. Arguments to command

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 - Function. Required. Failure command
  • quietLog - File. Required. 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 ... - Callable. Required. Thing to run and append output to quietLog.

Return codes

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

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 - String. Required. Failure command
  • command ... - Callable. Required. Command to run.
  • ... - Arguments. Optional. Arguments to command

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 - Function. Required. Error handler.
  • message ... - String. Optional. Error message

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 - Function. Required. Failure command
  • message ... - String. 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.

Arguments

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

Writes to standard output

  • No output from stdout ever from this function

Examples

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

Return codes

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

muzzleReturn

Suppress return codes

Usage

muzzleReturn command [ ... ]

Suppress return code without piping. Handy when using diff to generate text

Arguments

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

Examples

muzzleReturn diff -U0 "$buildDir"

Return codes

  • 0 - Always

returnMap

map a return value from one value to another

Usage

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

map a return value from one value to another

Arguments

  • --help - Flag. Optional. 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 - Flag. Optional. 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
  • ... - String. Optional. 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 [ --help ] [ executor ... -- Required. 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 `--`. ] [ -- ] [ ... ]

Support arguments and stdin as arguments to an executor

Arguments

  • --help - Flag. Optional. Display this help.
  • executor ... -- Required. 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 function

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

Arguments

  • function - String. Required. Function which is deprecated. Use ${FUNCNAME[0]} always if implemented in an old deprecated function.

Examples

_deprecated "${FUNCNAME[0]}"

Return codes

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

🛠️ Tools · ⬅ Top