Skip to content

Decoration and Console Colors

🛠️ Tools · ⬅ Home

For color console support use decorate style where style is a color name or a semantic meaning, each of which behave similarly:

Examples:

decorate green < "$file"
decorate info Starting to deploy ...

Zesk Build allows for customizations of all decoration colors to custom values allowing themes to be created.

decorate

Singular decoration function

Usage

decorate style [ text ... ]

Singular decoration function You can extend this function by writing a your own extension __decorationExtensionCustom is called for decorate custom.

Arguments

  • style - String. Required. One of: reset underline no-underline bold no-bold black black-contrast blue cyan green magenta orange red white yellow code info notice success warning error subtle label value decoration
  • text ... - String. Optional. Text to output. If not supplied, outputs a code to change the style to the new style. May contain arguments for style.

Writes to standard output

Decorated text

Return codes

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

Environment

  • __BUILD_DECORATE - String. Cached color lookup.
  • {SEE:BUILD_COLORS.sh} - Boolean. Colors enabled (true or false).

decorateInitialized

Is the decorate color system initialized yet?

Usage

decorateInitialized [ --help ]

Is the decorate color system initialized yet? Useful to set our global color environment at the top level of a script if it hasn't been initialized already.

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

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

decorations

Output a list of build-in decoration styles, one per line

Usage

decorations [ --help ]

Output a list of build-in decoration styles, one per line

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

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

decorateStyle

Get or modify a decoration style

Usage

decorateStyle style [ newFormat ]

When newFormat is blank, retrieves the format style. Otherwise sets the new style.

Arguments

  • style - String. Required. The style to fetch or replace.
  • newFormat - String. Optional. The new style formatting options as a string in the form escapeCodes label

Return codes

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

colorScheme

Set the terminal color scheme to the specification

Usage

colorScheme [ --help ] [ --handler handler ] [ --debug ]

Set the terminal color scheme to the specification

Arguments

  • --help - Flag. Optional. Display this help.
  • --handler handler - Function. Optional. Use this error handler instead of the default error handler.
  • --debug - Flag. Optional. Show additional debugging information.

Reads standard input

Scheme definition with colorName=colorValue on each line

Return codes

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

Semantic color commands

Color commands intended to convey status of messages. Try colorSampleSemanticStyles to see all colors.

  • decorate info - Informational messages
  • decorate notice - Notice messages
  • decorate warning - Warning messages
  • decorate success - Success messages
  • decorate decoration - Lines or decoration text
  • decorate error - Error messages
  • decorate label - Used for label/value pairs
  • decorate value - Used for label/value pairs
  • decorate code - Code output

Color commands

Colors vary depending on the console and the terminal. Try colorSampleStyles to see all colors.

Standard ANSI Colors

  • decorate red
  • decorate green
  • decorate cyan
  • decorate blue
  • decorate orange
  • decorate magenta
  • decorate black
  • decorate white

Text decoration

  • decorate underline
  • decorate bold

Decorate extensions

Examples:

  • decorate BOLD style text ...
  • decorate pair [ width ] name value ...
  • decorate each [ ``--count ] [ --index ] style item1 item2 ...
  • decorate size value
  • decorate big "Welcome to Zesk" | decorate box | decorate at 1 1
  • decorate pair name value ...
  • decorate wrap prefix suffix ...
  • decorate quote word ...
  • decorate file path
  • decorate link url [ text ]
  • decorate box Hello

decorate BOLD

Add bold style to another style

Usage

decorate BOLD style [ text ... ]

Add bold style to another style

Arguments

  • style - CommaDelimitedList. Required. Style arguments passed directly to decorate for each item.
  • text ... - EmptyString. Optional. Text to format. Use -- to output begin codes only.

Examples

decorate BOLD info Info is more important

Return codes

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

decorate each

Runs the following command on each subsequent argument for formatting

Usage

decorate each style [ -- ] [ --index ] [ --count ]

Runs the following command on each subsequent argument for formatting Also supports formatting input lines instead (on the same line)

Arguments

  • style - CommaDelimitedList. Required. Style arguments passed directly to decorate for each item.
  • -- - Flag. Optional. Pass as the first argument after the style to avoid reading arguments from stdin.
  • --index - Flag. Optional. Show the index of each item before with a colon. 0:first 1:second etc.
  • --count - Flag. Optional. Show the count of items in the list after the list is generated.

Examples

decorate each code -- "$@"

Return codes

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

decorate pair

Output a name value pair (decorate extension)

Usage

decorate pair [ characterWidth ] name [ value ... ]

The name is output left-aligned to the characterWidth given and colored using decorate label; the value colored using decorate value.

Arguments

  • characterWidth - UnsignedInteger. Optional. Number of characters to format the value for spacing. Uses environment variable BUILD_PAIR_WIDTH if not set.
  • name - String. Required. Name to output
  • value ... - String. Optional. One or more Values to output as values for name (single line)

Return codes

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

Environment

  • {SEE:BUILD_PAIR_WIDTH.sh}

decorate wrap

Prefix output lines with a string

Usage

decorate wrap prefix [ suffix ] [ --fill fillCharacter ]

Wrap lines with a string, useful to format output or add color codes to consoles which do not honor colors line-by-line. Intended to be used as a pipe.

Arguments

  • prefix - EmptyString. Required. Prefix each line with this text
  • suffix - String. Optional. Prefix each line with this text
  • --fill fillCharacter - Character. Optional. Fill entire line with this character.

Examples

cat "$file" | decorate wrap "CODE> " " <EOL>"
cat "$errors" | decorate wrap "    ERROR: [" "]"

Return codes

  • 0 - stdout contains input wrapped with text
  • 1 - Environment error
  • 2 - Argument error

decorate quote

Double-quote all arguments as properly quoted bash string

Usage

decorate quote

Double-quote all arguments as properly quoted bash string Mostly $ and " are problematic within a string

Arguments

  • none

Return codes

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

__decorateExtensionFile

decorate file links

Usage

__decorateExtensionFile [ --no-app ] fileName [ text ]

decorate extension for file

Arguments

  • --no-app - Flag. Optional. Do not map the application path in decoratePath
  • fileName - Required. File path to output.
  • text - String. Optional. Text to output linked to file.

Return codes

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

Environment

  • {SEE:BUILD_HOME.sh} TMPDIR HOME

decorate web links

Usage

decorate link url [ text ]

decorate extension for link

Arguments

  • url - Required. Link to output to the console.
  • text - String. Optional. Text to output linked to url.

Return codes

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

decorate size

Mostly $ and " are problematic within a string

Usage

decorate size [ size ]

Mostly $ and " are problematic within a string

Arguments

  • size - UnsignedInteger. Optional. Size to display.

Return codes

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

decorate box

Box around content

Usage

decorate box [ --type (ascii|line|double-line) ] [ --outside outsideStyle ] [ --inside insideStyle ] [ --width characterCount ] [ --size lineCount ] [ --fill fileCharacter ] [ text ... ] [ --help ]

Box around content

Arguments

--type (ascii|line|double-line)- ` - String. Optional. Line style. Defaultline---outside outsideStyle- String. Optional. Style to apply to the outside border. (Defaultdecoration) ---inside insideStyle- String. Optional. Style to apply to the inside content. (Defaultdecoration) ---width characterCount- UnsignedInteger|String. Optional. Box width. Specify "auto" to make size of content, or "console" forconsoleWidth. Defaults toconsole. ---size lineCount- UnsignedInteger. Optional. Print this many blank lines between the header and title. (Default none) ---fill fileCharacter- String. Optional. Use this character to fill empty space in the box. -text ...- String. Optional. Text to put in the box, one per line. ---help` - Flag. Optional. Display this help.

Examples

__decorateExtensionBox --style ascii "Moving ..."
__decorateExtensionBox --style line Hello
__decorateExtensionBox --style double-line "I'm sorry, Hal, I'm afraid I can't do that.

Sample Output

+==========================================================================+
| Moving ...                                                               |
+==========================================================================+
┌──────────────────────────────────────────────────────────────────────────┐
│ Hello                                                                    │
└──────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════╗
║ I'm sorry, Hal, I'm afraid I can't do that.                              ║
╚══════════════════════════════════════════════════════════════════════════╝

Return codes

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

decorate big

Display large text in the console for banners and important

Usage

decorate big text [ --bigger ]

Display large text in the console for banners and important messages BUILD_TEXT_BINARY can be figlet or toilet standard (figlet) _ _ _ _ | | () __ | |____ | | | ' | |/ || |/ _ \ \/ / __| | |_) | | (_| || | __/> <| |_ |_.__/|_|\__, ||_|\___/_/\_\\__| |___/ --bigger (figlet) _ _ _______ _ | | (_) |__ __| | | | |__ _ __ _| | _____ _| |_ | '_ \| |/ _ | |/ _ \ \/ / __| | |) | | (| | | __/> <| | |.__/||_, ||_//_\| / | |/ smblock (regular) toilet ▌ ▗ ▀▛▘ ▐ ▛▀▖▄ ▞▀▌▌▞▀▖▚▗▘▜▀ ▌ ▌▐ ▚▄▌▌▛▀ ▗▚ ▐ ▖ ▀▀ ▀▘▗▄▘▘▝▀▘▘ ▘ ▀ smmono12 (--bigger) toilet ▗▖ █ ▗▄▄▄▖ ▐▌ ▀ ▝▀█▀▘ ▐▌ ▐▙█▙ ██ ▟█▟▌ █ ▟█▙ ▝█ █▘▐███ ▐▛ ▜▌ █ ▐▛ ▜▌ █ ▐▙▄▟▌ ▐█▌ ▐▌ ▐▌ ▐▌ █ ▐▌ ▐▌ █ ▐▛▀▀▘ ▗█▖ ▐▌ ▐█▄█▘▗▄█▄▖▝█▄█▌ █ ▝█▄▄▌ ▟▀▙ ▐▙▄ ▝▘▀▘ ▝▀▀▀▘ ▞▀▐▌ ▀ ▝▀▀ ▝▀ ▀▘ ▀▀ ▜█▛▘

Arguments

  • text - String. Required. Text to output
  • --bigger - Flag. Optional. Text font size is bigger.

Return codes

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

Environment

  • {SEE:BUILD_TEXT_BINARY.sh}

decorate at

Experimental

Usage

decorate at [ x ] [ y ] [ text ... ]

Experimental Place text at a position on the console.

Arguments

  • x - Integer. Console X offset
  • y - Integer. Console Y offset
  • text ... - EmptyString. Text line to output at the x,y console location. Additional lines are placed below the previous line.

Return codes

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

decorate diff

Decoration for diff -U0

Usage

decorate diff leftStyle rightStyle

Removes most diff character decoration and replaces with colors

Arguments

  • leftStyle - String. Required. Style for left file lines
  • rightStyle - String. Required. Style for right file lines

Return codes

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

decorate expired

Utility to display key expiration Test whether the key needs to be updated

Usage

decorate expired keyDate upToDateDays [ --name name ] [ --help ]

For security one should update keys every ... number of days. f.k.a. is``UpToDate This value would be better encrypted and tied to the key itself so developers can not just update the value to avoid the security issue. This tool checks the value and checks if it is upToDateDays of today; if not this fails. It will also fail if: - upToDateDays is less than zero or greater than 366 - keyDate is empty or has an invalid value Otherwise, the tool may output a message to the console warning of pending days, and returns exit code 0 if the keyDate has not exceeded the number of days. Outputs a big text message as it gets closer.

Arguments

  • keyDate - Date. Required. Formatted like YYYY-MM-DD. Truncated at 10 characters as well.
  • upToDateDays - Integer. Required. Days that key expires after keyDate.
  • --name name - String. Optional. Name of the expiring item for error messages.
  • --help - Flag. Optional. Display this help.

Examples

if !decorate expired "$AWS_ACCESS_KEY_DATE" 90; then
  decorate big Failed, update key and reset date
  exit 99
fi

Return codes

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

Creating extensions

You can add your own decoration extension to your code by creating a function named:

  • __decorateExtensionFoo - where foo (lower case first letter) is the decoration name

Your function will be called by executeInputSupport which handles converting arguments from stdin into multiple calls to your function.

If you want to handle input from stdin on your own, create a function instead named:

  • __decorateExtensionFoo.Pure - where foo (lower case first letter) is the decoration name

This should handle reading from stdin or arguments and handle either appropriately.

Additional commands

consoleLineFill

Clear a line in the console

Usage

consoleLineFill [ textToOutput ]

Clears current line of text in the console Intended to be run on an interactive console, this clears the current line of any text and replaces the line with spaces. Intended to be run on an interactive console. Should support $(tput cols).

Arguments

  • textToOutput - String. Optional. Text to display on the new cleared line.

Return codes

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

statusMessage

Output a status message and display correctly on consoles with animation and in log files

Usage

statusMessage [ --last ] [ --first ] [ --inline ] command

Output a status message This is intended for messages on a line which are then overwritten using consoleLineFill Clears the line and outputs a message using a command. Meant to show status but not use up an output line for it. When $(consoleHasAnimation) is true: $(--first) - clears the line and outputs the message starting at the left column, no newline $(--last) - clears the line and outputs the message starting at the left column, with a newline $(--inline) - Outputs the message at the cursor without a newline When $(consoleHasAnimation) is false: $(--first) - outputs the message starting at the cursor, no newline $(--last) - outputs the message starting at the cursor, with a newline $(--inline) - Outputs the message at the cursor with a newline

Arguments

  • --last - Flag. Optional. Last message to be output, so output a newline as well at the end.
  • --first - Flag. Optional. First message to be output, only clears line if available.
  • --inline - Flag. Optional. Inline message displays with newline when animation is NOT available.
  • command - Required. Commands which output a message.

Examples

statusMessage decorate info "Loading ..."
bin/load.sh >>"$loadLogFile"
consoleLineFill

Return codes

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

Environment

  • Intended to be run on an interactive console. Should support $(tput cols).

consoleHasColors

Sets the environment variable BUILD_COLORS if not set, uses TERM

Usage

consoleHasColors [ --help ]

Sets the environment variable BUILD_COLORS if not set, uses TERM to calculate

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Console or output supports colors
  • 1 - Colors are likely not supported by console

Environment

  • {SEE:BUILD_COLORS.sh} - Boolean. Optional. Whether the build system will output ANSI colors.

consoleHasAnimation

Does the console support animation?

Usage

consoleHasAnimation

Does the console support animation?

Arguments

  • none

Return codes

  • 0 - Supports console animation
  • 1 - Does not support console animation

Color tests

colorSampleCombinations

Show combinations of foreground and background colors in the console.

Usage

colorSampleCombinations [ --help ]

Show combinations of foreground and background colors in the console.

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

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

Sample <code>colorSampleCombinations</code> output

colorSampleCodes

Alternate color output

Usage

colorSampleCodes [ --help ]

If you want to explore what colors are available in your terminal, try this.

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

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

Sample <code>colorSampleCodes</code> output

colorSampleStyles

Output colors

Usage

colorSampleStyles

Outputs sample sentences for the consoleAction commands to see what they look like.

Arguments

  • none

Return codes

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

Sample <code>colorSampleStyles</code> output

colorSampleSemanticStyles

Output colors

Usage

colorSampleSemanticStyles

Outputs sample sentences for the action commands to see what they look like.

Arguments

  • none

Return codes

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

Sample <code>colorSampleSemanticStyles</code> output

Color tools

colorFormat

Take r g b decimal values and convert them to

Usage

colorFormat [ format ] [ red ] [ green ] [ blue ] [ --help ]

Take r g b decimal values and convert them to hex color values Takes arguments or stdin values in groups of 3.

Arguments

  • format - String. Optional. Formatting string.
  • red - UnsignedInteger. Optional. Red component.
  • green - UnsignedInteger. Optional. Blue component.
  • blue - UnsignedInteger. Optional. Green component.
  • --help - Flag. Optional. Display this help.

Reads standard input

list:UnsignedInteger

Return codes

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

colorMultiply

Multiply color values by a factor and return the new

Usage

colorMultiply factor redValue greenValue blueValue [ --help ]

Multiply color values by a factor and return the new values

Arguments

  • factor - floatValue. Required. Red RGB value (0-255)
  • redValue - Integer. Required. Red RGB value (0-255)
  • greenValue - Integer. Required. Red RGB value (0-255)
  • blueValue - Integer. Required. Red RGB value (0-255)
  • --help - Flag. Optional. Display this help.

Return codes

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

Requires

  • bc

colorNormalize

Redistribute color values to make brightness adjustments more balanced

Usage

colorNormalize [ --help ]

Redistribute color values to make brightness adjustments more balanced

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

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

colorParse

Parse a color and output R G B decimal values

Usage

colorParse [ color ] [ --help ]

Parse a color and output R G B decimal values Takes arguments or stdin.

Arguments

  • color - String. Optional. Color to parse.
  • --help - Flag. Optional. Display this help.

Reads standard input

list:colors

Return codes

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

colorBrightness

Return an integer between 0 and 100

Usage

colorBrightness [ --help ] [ redValue ] [ greenValue ] [ blueValue ]

Return an integer between 0 and 100 Colors are between 0 and 255

Arguments

  • --help - Flag. Optional. Display this help.
  • redValue - Integer. Optional. Red RGB value (0-255)
  • greenValue - Integer. Optional. Red RGB value (0-255)
  • blueValue - Integer. Optional. Red RGB value (0-255)

Reads standard input

3 integer values [ Optional ]

Return codes

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

🛠️ Tools · ⬅ Top