Skip to content

Color Tools

⬅ Parent

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

Color Mode

Zesk Build supports customizations of all decoration colors to custom values.

colorScheme

Set the terminal color scheme to the specification

Usage

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

Set the terminal color scheme to the specification

Reads standard input

Scheme definition with colorName=colorValue on each line

Arguments

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

Return codes

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

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.

Writes to standard output

Decorated text

Arguments

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

Return codes

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

Environment

  • __BUILD_COLORS - String. Cached color lookup.
  • BUILD_COLORS - Boolean. If true then colors are shown, blank means guess the value, false means no colors
  • Boolean. Colors enabled (true or false).
  • BUILD_COLORS_MODE - String. light or dark
  • String. Color mode (light or dark). This is going to be deprecated.

Requires

isFunction returnArgument awk catchEnvironment usageDocument executeInputSupport __help

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 - Optional. Flag. Display this help.

Return codes

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

decorateStyle

Fetch

Usage

decorateStyle style [ newFormat ]

Fetch

Arguments

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

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 decoration argument1 argument2 ...

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

Arguments

  • style - String. Required. The style to decorate each element.
  • -- - 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

Requires

decorate printf

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 - Optional. Number of characters to format the value for spacing. Uses environment variable BUILD_PAIR_WIDTH if not set.
  • name - Required. Name to output
  • value ... - Optional. One or more Values to output as values for name (single line)

Return codes

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

Environment

decorate wrap

Prefix output lines with a string

Usage

decorate wrap [ --fill ] [ prefix [ suffix ... ] ] < fileToWrapLines

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.

Return Code: 0 - stdout contains input wrapped with text Return Code: 1 - Environment error Return Code: 2 - Argument error

Arguments

  • prefix - String. Required. Prefix each line with this text
  • suffix - String. Required. Prefix each line with this text

Examples

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

Return codes

  • 0 - Success
  • 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

Requires

printf decorate

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

Bold Colors

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

Extensions

  • decorate pair name value
  • decorate pair 40 name value
  • decorate each code item1 item2
  • decorate each --count code item1 item2 item3
  • decorate each --index code item1 item2 item3
  • decorate size 100

Creating extensions

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

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

Additional commands

consoleColorMode

Set colors to deal with dark or light-background consoles

Usage

consoleColorMode [ --dark ] [ --light ]

Set colors to deal with dark or light-background consoles

Arguments

  • --help - Optional. Flag. Display this help.
  • --dark - Optional. Flag. Dark mode for darker backgrounds.
  • --light - Optional. Flag. Light mode for lighter backgrounds.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • BUILD_COLORS_MODE - Output the color mode when it is changed

Return codes

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

Environment

clearLine

Clear a line in the console

Usage

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

Arguments

  • none

Examples

clearLine

Return codes

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

Environment

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

statusMessage

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

Usage

statusMessage command ...

Output a status message

This is intended for messages on a line which are then overwritten using clearLine

Clears the line and outputs a message using a command. Meant to show status but not use up an output line for it.

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

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

Examples

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

Return codes

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

Environment

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

hasColors

Sets the environment variable BUILD_COLORS if not set, uses TERM

Usage

hasColors

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

Return Code: 0 - Console or output supports colors Return Code: 1 - Colors are likely not supported by console

Arguments

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

Return codes

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

Environment

  • BUILD_COLORS - Boolean. If true then colors are shown, blank means guess the value, false means no colors
  • Optional. Boolean. Whether the build system will output ANSI colors.

Requires

isPositiveInteger tput

hasConsoleAnimation

Does the console support animation?

Usage

hasConsoleAnimation

Does the console support animation? Return Code: 0 - Supports console animation Return Code: 1 - Does not support console animation

Arguments

  • none

Return codes

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

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 - Optional. Flag. Display this help.

Return codes

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

colorSampleCodes

Alternate color output

Usage

colorSampleCodes [ --help ]

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

Arguments

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

Return codes

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

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

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

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.

Reads standard input

list:UnsignedInteger

Arguments

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

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 - Optional. Flag. 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 - Optional. Flag. Display this help.

Return codes

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

Requires

bc catchEnvironment read usageArgumentUnsignedInteger packageWhich __colorNormalize

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.

Reads standard input

list:colors

Arguments

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

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

Reads standard input

3 integer values [ Optional ]

Arguments

  • --help - Optional. Flag. 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)

Return codes

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