--- name: "Color::ANSI::Util" section: "3pm" platform: "linux" package: "libcolor-ansi-util-perl" version: "0.165-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Color::ANSI::Util" --- # Color::ANSI::Util(3pm) Routines for dealing with ANSI colors ## NAME Color::ANSI::Util - Routines for dealing with ANSI colors ## VERSION This document describes version 0.165 of Color::ANSI::Util (from Perl distribution Color-ANSI-Util), released on 2024-02-23. ## SYNOPSIS ``` use Color::ANSI::Util qw( ansifg ansibg ); say ansifg("f0c010"); # => "\e[33;1m" (on 16-color terminal) # => "\e[38;5;11m" (on 256-color terminal) # => "\e[38;2;240;192;16m" (on 24-bit-color terminal) say ansibg("ff5f87"); # => "\e[47m" (on 16-color terminal) # => "\e[48;5;7m" (on 256-color terminal) # => "\e[48;2;255;95;135m" (on 24-bit-color terminal) ``` There are a bunch of other exportable functions too, mostly for converting between RGB and ANSI color (16/256/24bit color depth). ## DESCRIPTION This module provides routines for dealing with ANSI colors. The two main functions are `"ansifg"` and `"ansibg"`. With those functions, you can specify colors in RGB and let it output the correct ANSI color escape code according to the color depth support of the terminal (whether 16-color, 256-color, or 24bit). There are other functions to convert RGB to ANSI in specific color depths, or reverse functions to convert from ANSI to RGB codes. Keywords: xterm, xterm-256color, terminal ## BUGS/NOTES Algorithm for finding closest indexed color from RGB color currently not very efficient. Probably can add some threshold square distance, below which we can shortcut to the final answer. ## FUNCTIONS ### ansi16\_to\_rgb Usage: ``` ansi16_to_rgb($color) -> color::rgb24 ``` Convert ANSI-16 color to RGB. Returns 6-hexdigit, e.g. 'ff00cc'. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::ansi16* (No description) Return value: (color::rgb24) ### ansi256\_to\_rgb Usage: ``` ansi256_to_rgb($color) -> color::rgb24 ``` Convert ANSI-256 color to RGB. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::ansi256* (No description) Return value: (color::rgb24) ### rgb\_to\_ansi16 Usage: ``` rgb_to_ansi16($color) -> color::ansi16 ``` Convert RGB to ANSI-16 color. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (color::ansi16) ### rgb\_to\_ansi16\_bg\_code Usage: ``` rgb_to_ansi16_bg_code($color) -> str ``` Convert RGB to ANSI-16 color escape sequence to change background color. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (str) ### rgb\_to\_ansi16\_fg\_code Usage: ``` rgb_to_ansi16_fg_code($color) -> str ``` Convert RGB to ANSI-16 color escape sequence to change foreground color. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (str) ### rgb\_to\_ansi24b\_bg\_code Usage: ``` rgb_to_ansi24b_bg_code($color) -> str ``` Convert RGB to ANSI 24bit-color escape sequence to change background color. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (str) ### rgb\_to\_ansi24b\_fg\_code Usage: ``` rgb_to_ansi24b_fg_code($color) -> str ``` Convert RGB to ANSI 24bit-color escape sequence to change foreground color. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (str) ### rgb\_to\_ansi256 Usage: ``` rgb_to_ansi256($color) -> color::ansi256 ``` Convert RGB to ANSI-256 color. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (color::ansi256) ### rgb\_to\_ansi256\_bg\_code Usage: ``` rgb_to_ansi256_bg_code($color) -> str ``` Convert RGB to ANSI-256 color escape sequence to change background color. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (str) ### rgb\_to\_ansi256\_fg\_code Usage: ``` rgb_to_ansi256_fg_code($color) -> str ``` Convert RGB to ANSI-256 color escape sequence to change foreground color. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (str) ### rgb\_to\_ansi\_bg\_code Usage: ``` rgb_to_ansi_bg_code($color) -> str ``` Convert RGB to ANSI color escape sequence to change background color. Autodetect terminal capability and can return either empty string, 16-color, 256-color, or 24bit-code. Which color depth used is determined by `"COLOR_DEPTH"` environment setting or from Term::Detect::Software if that module is available). In other words, this function automatically chooses rgb\_to\_ansi{24b,256,16}*bg***code()**. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (str) ### rgb\_to\_ansi\_fg\_code Usage: ``` rgb_to_ansi_fg_code($color) -> str ``` Convert RGB to ANSI color escape sequence to change foreground color. Autodetect terminal capability and can return either empty string, 16-color, 256-color, or 24bit-code. Color depth used is determined by `"COLOR_DEPTH"` environment setting or from Term::Detect::Software if that module is available. In other words, this function automatically chooses rgb\_to\_ansi{24b,256,16}*fg***code()**. This function is not exported by default, but exportable. Arguments ('\*' denotes required arguments): - • **$color**\* =\> *color::rgb24* (No description) Return value: (str) ### ansi16fg($rgb) =\> STR Alias for **rgb\_to\_ansi16\_fg\_code()**. ### ansi16bg($rgb) =\> STR Alias for **rgb\_to\_ansi16\_bg\_code()**. ### ansi256fg($rgb) =\> STR Alias for **rgb\_to\_ansi256\_fg\_code()**. ### ansi256bg($rgb) =\> STR Alias for **rgb\_to\_ansi256\_bg\_code()**. ### ansi24bfg($rgb) =\> STR Alias for **rgb\_to\_ansi24b\_fg\_code()**. ### ansi24bbg($rgb) =\> STR Alias for **rgb\_to\_ansi24b\_bg\_code()**. ### rgb\_to\_ansi\_fg\_code($rgb) =\> STR ### ansifg($rgb) =\> STR Alias for **rgb\_to\_ansi\_fg\_code()**. ### ansibg($rgb) =\> STR Alias for **rgb\_to\_ansi\_bg\_code()**. ### ansi\_reset( \[ $conditional \]) Returns "\\e\[0m", which is the ANSI escape sequence to reset color. Normally you print this sequence after you print colored text. If `$conditional` is set to true, then **ansi\_reset()** will return "" if color is disabled. ## ENVIRONMENT ### NO\_COLOR Can be used to explicitly disable color. See \ for more details. Observed by: ansi{fg,bg}. ### COLOR =\> bool Can be used to explicitly disable color by setting it to 0. Observed by: ansi{fg,bg}. ### COLOR\_DEPTH =\> INT Can be used to explicitly set color depth instead of trying to detect appropriate color depth. Observed by: ansi{fg,bg}. ## HOMEPAGE Please visit the project's homepage at \. ## SOURCE Source repository is at \. ## SEE ALSO Term::ANSIColor \ ## AUTHOR perlancar \ ## CONTRIBUTOR Steven Haryanto \ ## CONTRIBUTING To contribute, you can send patches by email/via RT, or send pull requests on GitHub. Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via: ``` % prove -l ``` If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me. ## COPYRIGHT AND LICENSE This software is copyright (c) 2024, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013 by perlancar \. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. ## BUGS Please report any bugs or feature requests on the bugtracker website \ When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.