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.

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

Return codes

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

Environment

  • __BUILD_DECORATE - 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).

Requires

isFunction returnArgument awk catchEnvironment usageDocument executeInputSupport __help

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

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

Usage

decorateStyle style [ newFormat ]

Fetch

Arguments

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

Return codes

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

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

Return codes

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

decorate BOLD

undocumented

Usage

decorate BOLD style [ text ... ]

No documentation for __decorateExtensionBOLD.

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.

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

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

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

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

Extensions

  • decorate BOLD style text ...
  • decorate pair [ width ] name value ...
  • decorate each [ ``--count ] [ --index ] style item1 item2 ...
  • decorate size value

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

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

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

Requires

throwArgument consoleHasAnimation catchEnvironment decorate validate consoleLineFill

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

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

Requires

isPositiveInteger tput

Usage

consoleHasAnimation

Does the console support animation?

Arguments

  • none

Return codes

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

Color tests

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

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

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

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

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

Return codes

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

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

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

Requires

bc catchEnvironment read usageArgumentUnsignedInteger packageWhich __colorNormalize

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

Return codes

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

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

Return codes

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