Skip to content

Sugar Core

🛠️ Tools · ⬅ Home

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)

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

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

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.

Arguments

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

Return codes

  • 0 - success

returnCodeString

Output the exit code as a string

Usage

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

Output the exit code as a string

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

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

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

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)

Arguments

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

Return codes

  • exitCode

returnEnvironment

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

Usage

returnEnvironment [ message ... ]

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

Arguments

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

Return codes

  • 1

returnArgument

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

Usage

returnArgument [ message ... ]

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

Arguments

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

Return codes

  • 2

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

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

Arguments

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

Return codes

  • Any

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

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

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

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

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

🛠️ Tools · ⬅ Top