Sugar Core

---

Sugar refers to syntactic sugar - code which makes other code more readable.

Most functions are used in the form suffixed with || return $? which takes the returned code and returns immediately from the function.

returnMessage 1 "This failed" || return $?
catchArgument "$handler" isInteger "$1" || return $?

Alternately, these can be used within an if or other compound statement but the return code should be returned to the user, typically.

Quick guide:

• isPositiveInteger value - Returns 0 if value passed is an integer, otherwise returns 1.
• isBoolean value - Returns 0 if value passed is true or false, otherwise returns 1.
• chooseBoolean testValue trueValue falseValue - Outputs trueValue when [ "$testValue" = "true" ] otherwise outputs falseValue.

Error codes:

• returnCode name ... - Exit codes. Outputs integers based on error names, one per line.
• returnCodeString integer ... - Exit strings. Reverse of returnCode.

Return errors:

• returnMessage code message ... - Return code and outputs message ... to stderr IFF code is non-zero, otherwise output message ... to stdout.
• returnEnvironment message ... - Return 1 always. Outputs message ... to stderr.
• returnArgument message ... - Return 2 always. Outputs message ... to stderr.

Run-related:

• execute command ... - Run command ... (with any arguments) and then _return if it fails.
• executeEcho command ... - Output the command ... to stdout prior to running, then execute it (helpful to debug statements within other scripts)
• catchEnvironment handler command ... - Run command ... (with any arguments) and then run handler with an environment error if it fails.

Sugar utilities

isBoolean

Boolean test

Usage

isBoolean [ --help ] [ value ]

Boolean test If you want "true-ish" use isTrue. Returns 0 if value is boolean false oHar true. Is this a boolean? (true or false)

Location: bin/build/tools/_sugar.sh

Arguments

• --help - Flag. Optional. Display this help.
• value - String. Optional. Value to check if it is a boolean.

Return codes

• 0 - if value is a boolean
• 1 - if value is not a boolean

Requires

• bashDocumentation - Universal function documentation (source)

See Also

• isTrue - True-ish (source)
• booleanParse - Parses text and determines if it's true-ish (source)

booleanChoose

Boolean selector

Usage

booleanChoose testValue [ trueChoice ] [ falseChoice ]

Boolean selector

Location: bin/build/tools/_sugar.sh

Arguments

• testValue - Boolean. Required. Test value
• trueChoice - EmptyString. Optional. Value to output when testValue is true
• falseChoice - EmptyString. Optional. Value to output when testValue is false

Return codes

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

Requires

• isBoolean - Boolean test (source)
• returnArgument - Return `argument` error code. Outputs `message ...` to `stderr`. (source)
• printf

returnCode

Print one or more return codes by name.

Usage

returnCode [ name ... ]

Print one or more return codes by name.

Known codes:

• success (0) - success!
• environment (1) - generic issue with environment
• argument (2) - issue with arguments
• assert (97) - assertion failed (ASCII 97 = a)
• identical (105) - identical check failed (ASCII 105 = i)
• leak (108) - function leaked globals (ASCII 108 = l)
• timeout (116) - timeout exceeded (ASCII 116 = t)
• exit - (120) exit function immediately (ASCII 120 = x)
• not-found - (127) command not found
• user-interrupt - (130) User interrupt (Ctrl-C)
• interrupt - (141) Interrupt signal
• internal - (253) internal errors

Unknown error code is 254, end of range is 255 which is not used. Use returnCodeString to get a string from an exit code integer.

Location: bin/build/tools/_sugar.sh

Arguments

• name ... - String. Optional. Exit code value to output.

Return codes

• 0 - success

Requires

• bashDocumentation - Universal function documentation (source)

See Also

• stackoverflow.com
• returnCodeString - Output the exit code as a string (source)

returnCodeString

Output the exit code as a string

Usage

returnCodeString [ code ... ] [ --help ]

Output the exit code as a string

Location: bin/build/tools/_sugar.sh

Arguments

• code ... - UnsignedInteger. String. Exit code value to output.
• --help - Flag. Optional. Display this help.

Writes to standard output

exitCodeToken, one per line

Return codes

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

See Also

• returnCode - Print one or more return codes by name. (source)

Cleanup

returnClean

Delete files or directories and return the same exit code

Usage

returnClean exitCode [ item ]

Delete files or directories and return the same exit code passed in.

Location: bin/build/tools/_sugar.sh

Arguments

• exitCode - Integer. Required. Exit code to return.
• item - Exists. Optional. One or more files or folders to delete, failures are logged to stderr.

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)
• throwEnvironment - Run `handler` with an environment error (source)
• bashDocumentation - Universal function documentation (source)
• throwArgument - Run `handler` with an argument error (source)
• helpArgument - Simple help argument handler. (source)

returnUndo

Run a function and preserve exit code

Usage

returnUndo [ --help ] code [ undoFunction ] [ -- ]

Run a function and preserve exit code Returns code As a caveat, your command to undo can NOT take the argument -- as a parameter.

Location: bin/build/tools/sugar.sh

Arguments

• --help - Flag. Optional. Display this help.
• code - UnsignedInteger. Required. Exit code to return.
• undoFunction - Callable. Optional. Command to run to undo something. Return status is ignored.
• -- - Flag. Optional. Used to delimit multiple commands.

Examples

local undo thing
thing=$(catchEnvironment "$handler" createLargeResource) || return $?
undo+=(-- deleteLargeResource "$thing")
thing=$(catchEnvironment "$handler" createMassiveResource) || returnUndo $? "${undo[@]}" || return $?
undo+=(-- deleteMassiveResource "$thing")

Return codes

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

Requires

• isUnsignedInteger - Is value an unsigned integer? (source)
• throwArgument - Run `handler` with an argument error (source)
• decorate - decorate text using colors and styles (source)
• execute - Run binary and output failed command upon error (source)
• bashDocumentation - Universal function documentation (source)

Fail with an error code

returnMessage

Return passed in integer return code and output message to

Usage

returnMessage exitCode [ message ... ]

Return passed in integer return code and output message to stderr (non-zero) or stdout (zero)

Location: bin/build/tools/example.sh

Arguments

• exitCode - UnsignedInteger. Required. Exit code to return. Default is 1.
• message ... - String. Optional. Message to output

Return codes

• exitCode

Requires

• isUnsignedInteger - Is value an unsigned integer? (source)
• printf
• returnMessage - Return passed in integer return code and output message to (source)

returnEnvironment

Return environment error code. Outputs message ... to stderr.

Usage

returnEnvironment [ message ... ]

Return environment error code. Outputs message ... to stderr.

Location: bin/build/tools/_sugar.sh

Arguments

• message ... - String. Optional. Message to output.

Return codes

• 1

Requires

• returnMessage - Return passed in integer return code and output message to (source)

returnArgument

Return argument error code. Outputs message ... to stderr.

Usage

returnArgument [ message ... ]

Return argument error code. Outputs message ... to stderr.

Location: bin/build/tools/_sugar.sh

Arguments

• message ... - String. Optional. Message to output.

Return codes

• 2

Requires

• returnMessage - Return passed in integer return code and output message to (source)

Run-related

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)

executeEcho

Output the command ... to stdout prior to running, then

Usage

executeEcho [ command ... ] [ --help ]

Output the command ... to stdout prior to running, then execute it

Location: bin/build/tools/_sugar.sh

Arguments

• command ... - Any command and arguments to run.
• --help - Flag. Optional. Display this help.

Return codes

• Any

Requires

• helpArgument - Simple help argument handler. (source)
• decorate - decorate text using colors and styles (source)
• execute - Run binary and output failed command upon error (source)

returnThrow

Run handler with a passed return code

Usage

returnThrow returnCode handler [ message ... ]

Run handler with a passed return code

Location: bin/build/tools/_sugar.sh

Arguments

• returnCode - Integer. Required. Return code.
• handler - Function. Required. Error handler.
• message ... - String. Optional. Error message

Return codes

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

Requires

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

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

Throw and Catch

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)

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)

---

🛠️ Tools · ⬅ Top