================
Colors Utilities
================

.. default-domain:: bash

.. file:: colors.bsh

Collection of named colors and color functions

By sourcing this file and running color_setup, all the basic colors and styles are made available in a terminal. Additional functions such as FG and BG give access to arbitrary colors by index. Some terminals support up to 256 colors, as :func:`number_colors` indicates.

.. seealso::
  :func:`color_setup` :func:`FG` :func:`BG` :func:`number_colors`

.. rubric:: Bugs

Having variables with color codes in them can make looking at "set", "declare/typeset", or "bash -xv" very noisy, as colors aren't cleared from line to line in bash

.. note::
  Per git-sh-prompt/git-prompt.sh: If setting ``PS1`` or ``PROMPT_COMMAND`` you must add \[ and \] around colors to prevent issues with command line editing/browsing/completion!

.. var:: CSI

The Control Sequence Introducer, ``$'\x1b['`` aka ``$'\e['``

.. function:: color_setup

Set up variables and functions for colors and styles
Sets the values for the 8 basic colors (BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, and WHITE), and styles (BOLD, DIM, ITALIC, UNDERLINE, BLINK, OVERLINE, HIDDEN and STRIKETHROUGH) and RESET, RESET_<style name>. In addition, LIGHT_<color>, <color>_BG, LIGHT_<color>_BG, and <color> are all set.
``COLOR_NAMES`` is set to an array of 8 basic color names and the array ``COLORS`` is set to the color codes for those 8 colors by default.

.. rubric:: Example

.. code-block:: bash

  color_setup
  echo "This is ${RED}red text${RESET}."

.. note::
  This is automatically called by sourcing :file:`colors.bsh`

.. seealso::
  :func:`FG` :func:`BG` :func:`number_colors`

.. function:: get_color

:Arguments: ``$1`` - Key value
:Output: *stdout* - The printable color code

Retrieve a color from the color map

:func:`get_color` acts as a circular dictionary of colors

.. rubric:: Example

.. code-block:: bash

  color_setup
  if (( "$(number_colors)" < 88 )); then
    COLORS=("${RED}" "${GREEN}" "${YELLOW}" "${MAGENTA}" "${CYAN}" "${WHITE}")
  else
    COLORS=($(FG {9..15} 19 28 38 48 68 94 126 244))
  fi
  get_color first; echo "This is the first${RESET} color"
  get_color second; echo "This is the second${RESET} color"
  get_color first; echo "This is still the same first${RESET} color"

.. note::
  The act of calling :func:`get_color` echoes out the color code. So just calling :func:`get_color` will change the terminal color. If this is not desired, redirect stdout to /dev/null

  get_color ness > /dev/null

  The color database is stored in ``COLOR_DB_NAMES`` (keys) and ``COLOR_DB_COLORS`` (values) and pull from the color pool ``COLORS``

.. rubric:: Bugs

The color database can't be updated when executed in a subshell. This only matters the first time a key is used. For example:

.. code-block:: bash

  COLORS=($(FG {9..15} 19 28 38 48 68 94 126 244))

  echo "This will $(get_color something)not${RESET} work"
  echo "This will $(get_color something2)not${RESET} work"
  # The same color will appear twice

  get_color something > /dev/null
  get_color something2 > /dev/null
  echo "This will $(get_color something)so${RESET} work"
  echo "This will $(get_color something2)so${RESET} work"

.. function:: FG

:Arguments: ``$1[...]`` - 1 or more color numbers
:Output: *stdout* - The printable color code(s)

Retrieve foreground color code by index number

88/256 color support

.. function:: BG

:Arguments: ``$1[...]`` - 1 or more color numbers
:Output: *stdout* - The printable color code(s)

Retrieve background color code by index number

88/256 color support

.. function:: FG_24

:Arguments: ``$1`` - Red value from 0 to 255. Default: 0
            ``$2`` - Green value from 0 to 255. Default: 0
            ``$3`` - Blue value from 0 to 255. Default: 0
:Output: *stdout* - The printable color code(s)

Retrieve foreground color code by RGB value

24-bit color support

.. function:: BG_24

:Arguments: ``$1`` - Red value from 0 to 255. Default: 0
            ``$2`` - Green value from 0 to 255. Default: 0
            ``$3`` - Blue value from 0 to 255. Default: 0
:Output: *stdout* - The printable color code(s)

Retrieve background color code by RGB value

24-bit color support

.. function:: number_colors

:Output: *stdout* - The number of supported colors. Typically 8, 15, 16, 52, 88, or 256

Ask the terminal emulator how many colors it supports

.. function:: color_demo1

Print out matrix of 8 Basic colors and all styles

Useful for determining which features the terminal emulator supports

.. function:: color_demo2

Print out matrix of 256 foreground colors

Useful for determining which features the terminal emulator supports

.. function:: color_demo3

Print out matrix of 256 background colors

Useful for determining which features the terminal emulator supports