Sugar Extensions

Usage Sugar

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

Location: bin/build/tools/_sugar.sh

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

Requires

returnMessage - Return passed in integer return code and output message to (source)
helpArgument - Simple help argument handler. (source)

`catchReturn`

Run binary and catch errors with handler

Usage

catchReturn handler binary ...

Run binary and catch errors with handler

Location: bin/build/tools/_sugar.sh

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

Requires

returnArgument - Return `argument` error code. Outputs `message ...` to `stderr`. (source)

`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

Location: bin/build/tools/_sugar.sh

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

Requires

isUnsignedInteger - Is value an unsigned integer? (source)
returnArgument - Return `argument` error code. Outputs `message ...` to `stderr`. (source)
isFunction - Test if argument are bash functions (source)
isCallable - Test if all arguments are callable as a command (source)

`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

Location: bin/build/tools/_sugar.sh

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

Requires

catchCode - Run `command`, handle failure with `handler` with `code` and `command` (source)

`catchEnvironmentQuiet`

Run handler with an environment error

Usage

catchEnvironmentQuiet handler quietLog command ...

Run handler with an environment error

Location: bin/build/tools/sugar.sh

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

Requires

isFunction - Test if argument are bash functions (source)
returnArgument - Return `argument` error code. Outputs `message ...` to `stderr`. (source)
debuggingStack - Dump the function and include stacks and the current environment (source)
throwEnvironment - Run `handler` with an environment error (source)

`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

Location: bin/build/tools/_sugar.sh

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

Requires

catchCode - Run `command`, handle failure with `handler` with `code` and `command` (source)

`throwEnvironment`

Run handler with an environment error

Usage

throwEnvironment handler [ message ... ]

Run handler with an environment error

Location: bin/build/tools/_sugar.sh

Arguments

handler - Function. Required. Error handler.
message ... - String. Optional. Error message

Return codes

0 - Success
1 - Environment error
2 - Argument error

Requires

isFunction - Test if argument are bash functions (source)
returnArgument - Return `argument` error code. Outputs `message ...` to `stderr`. (source)
decorate - decorate text using colors and styles (source)
debuggingStack - Dump the function and include stacks and the current environment (source)

`throwArgument`

Run handler with an argument error

Usage

throwArgument handler [ message ... ]

Run handler with an argument error

Location: bin/build/tools/_sugar.sh

Arguments

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

Return codes

0 - Success
1 - Environment error
2 - Argument error

Requires

isFunction - Test if argument are bash functions (source)
returnArgument - Return `argument` error code. Outputs `message ...` to `stderr`. (source)
decorate - decorate text using colors and styles (source)
debuggingStack - Dump the function and include stacks and the current environment (source)

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

Location: bin/build/tools/sugar.sh

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

Location: bin/build/tools/sugar.sh

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

Location: bin/build/tools/sugar.sh

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

Location: bin/build/tools/_sugar.sh

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

Location: bin/build/tools/sugar.sh

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

Requires

catchReturn - Run binary and catch errors with handler (source)
bashDocumentation - Universal function documentation (source)

Deprecated Logging

{_deprecated}

🛠️ Tools · ⬅ Top