Skip to content

Sugar Core

🛠️ Tools · ⬅ Top

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 Functions References

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 or true. Is this a boolean? (true or false) Return Code: 0 - if value is a boolean Return Code: 1 - if value is not a boolean

Arguments

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

Return codes

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

Requires

usageDocument printf

booleanChoose

Boolean selector

Usage

booleanChoose testValue [ trueChoice ] [ falseChoice ]

Boolean selector

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 returnArgument 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 - (127) 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.

Return Code: 0 - success

Arguments

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

Return codes

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

Requires

usageDocument printf

returnCodeString

Output the exit code as a string

Usage

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

Output the exit code as a string

Writes to standard output

exitCodeToken, one per line

Arguments

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

Return codes

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

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.

Arguments

  • exitCode - Required. Integer. Exit code to return.
  • item - 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 returnArgument throwEnvironment usageDocument throwArgument

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.

Arguments

  • --help - Optional. Flag. Display this help.
  • code - Required. UnsignedInteger. Exit code to return.
  • undoFunction - 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

isPositiveInteger catchArgument decorate execute usageDocument

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) Return Code: exitCode

Arguments

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

Return codes

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

Requires

isUnsignedInteger printf returnMessage

returnEnvironment

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

Usage

returnEnvironment [ message ... ]

Return environment error code. Outputs message ... to stderr. Return Code: 1

Arguments

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

Return codes

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

Requires

returnMessage

returnArgument

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

Usage

returnArgument [ message ... ]

Return argument error code. Outputs message ... to stderr. Return Code: 2

Arguments

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

Return codes

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

Requires

returnMessage

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

executeEcho

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

Usage

executeEcho command ...

Output the command ... to stdout prior to running, then execute it Return Code: Any

Arguments

  • command ... - Any command and arguments to run.

Return codes

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

Requires

printf decorate execute __decorateExtensionQuote __decorateExtensionEach

returnThrow

Run handler with a passed return code

Usage

returnThrow returnCode handler [ message ... ]

Run handler with a passed return code

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

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

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

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