.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Color::ANSI::Util 3pm"
.TH Color::ANSI::Util 3pm 2024-03-02 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Color::ANSI::Util \- Routines for dealing with ANSI colors
.SH VERSION
.IX Header "VERSION"
This document describes version 0.165 of Color::ANSI::Util (from Perl distribution Color-ANSI-Util), released on 2024\-02\-23.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\& use Color::ANSI::Util qw(
\&     ansifg
\&     ansibg
\& );
\&
\& say ansifg("f0c010"); # => "\ee[33;1m" (on 16\-color terminal)
\&                       # => "\ee[38;5;11m" (on 256\-color terminal)
\&                       # => "\ee[38;2;240;192;16m" (on 24\-bit\-color terminal)
\&
\& say ansibg("ff5f87"); # => "\ee[47m" (on 16\-color terminal)
\&                       # => "\ee[48;5;7m" (on 256\-color terminal)
\&                       # => "\ee[48;2;255;95;135m" (on 24\-bit\-color terminal)
.Ve
.PP
There are a bunch of other exportable functions too, mostly for converting
between RGB and ANSI color (16/256/24bit color depth).
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides routines for dealing with ANSI colors. The two main
functions are \f(CW\*(C`ansifg\*(C'\fR and \f(CW\*(C`ansibg\*(C'\fR. 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.
.PP
Keywords: xterm, xterm\-256color, terminal
.SH BUGS/NOTES
.IX Header "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.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS ansi16_to_rgb
.IX Subsection "ansi16_to_rgb"
Usage:
.PP
.Vb 1
\& ansi16_to_rgb($color) \-> color::rgb24
.Ve
.PP
Convert ANSI\-16 color to RGB.
.PP
Returns 6\-hexdigit, e.g. 'ff00cc'.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::ansi16\fR
.Sp
(No description)
.PP
Return value:  (color::rgb24)
.SS ansi256_to_rgb
.IX Subsection "ansi256_to_rgb"
Usage:
.PP
.Vb 1
\& ansi256_to_rgb($color) \-> color::rgb24
.Ve
.PP
Convert ANSI\-256 color to RGB.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::ansi256\fR
.Sp
(No description)
.PP
Return value:  (color::rgb24)
.SS rgb_to_ansi16
.IX Subsection "rgb_to_ansi16"
Usage:
.PP
.Vb 1
\& rgb_to_ansi16($color) \-> color::ansi16
.Ve
.PP
Convert RGB to ANSI\-16 color.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (color::ansi16)
.SS rgb_to_ansi16_bg_code
.IX Subsection "rgb_to_ansi16_bg_code"
Usage:
.PP
.Vb 1
\& rgb_to_ansi16_bg_code($color) \-> str
.Ve
.PP
Convert RGB to ANSI\-16 color escape sequence to change background color.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (str)
.SS rgb_to_ansi16_fg_code
.IX Subsection "rgb_to_ansi16_fg_code"
Usage:
.PP
.Vb 1
\& rgb_to_ansi16_fg_code($color) \-> str
.Ve
.PP
Convert RGB to ANSI\-16 color escape sequence to change foreground color.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (str)
.SS rgb_to_ansi24b_bg_code
.IX Subsection "rgb_to_ansi24b_bg_code"
Usage:
.PP
.Vb 1
\& rgb_to_ansi24b_bg_code($color) \-> str
.Ve
.PP
Convert RGB to ANSI 24bit\-color escape sequence to change background color.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (str)
.SS rgb_to_ansi24b_fg_code
.IX Subsection "rgb_to_ansi24b_fg_code"
Usage:
.PP
.Vb 1
\& rgb_to_ansi24b_fg_code($color) \-> str
.Ve
.PP
Convert RGB to ANSI 24bit\-color escape sequence to change foreground color.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (str)
.SS rgb_to_ansi256
.IX Subsection "rgb_to_ansi256"
Usage:
.PP
.Vb 1
\& rgb_to_ansi256($color) \-> color::ansi256
.Ve
.PP
Convert RGB to ANSI\-256 color.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (color::ansi256)
.SS rgb_to_ansi256_bg_code
.IX Subsection "rgb_to_ansi256_bg_code"
Usage:
.PP
.Vb 1
\& rgb_to_ansi256_bg_code($color) \-> str
.Ve
.PP
Convert RGB to ANSI\-256 color escape sequence to change background color.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (str)
.SS rgb_to_ansi256_fg_code
.IX Subsection "rgb_to_ansi256_fg_code"
Usage:
.PP
.Vb 1
\& rgb_to_ansi256_fg_code($color) \-> str
.Ve
.PP
Convert RGB to ANSI\-256 color escape sequence to change foreground color.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (str)
.SS rgb_to_ansi_bg_code
.IX Subsection "rgb_to_ansi_bg_code"
Usage:
.PP
.Vb 1
\& rgb_to_ansi_bg_code($color) \-> str
.Ve
.PP
Convert RGB to ANSI color escape sequence to change background color.
.PP
Autodetect terminal capability and can return either empty string, 16\-color,
256\-color, or 24bit\-code.
.PP
Which color depth used is determined by \f(CW\*(C`COLOR_DEPTH\*(C'\fR 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}\fIbg\fR\fBcode()\fR.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (str)
.SS rgb_to_ansi_fg_code
.IX Subsection "rgb_to_ansi_fg_code"
Usage:
.PP
.Vb 1
\& rgb_to_ansi_fg_code($color) \-> str
.Ve
.PP
Convert RGB to ANSI color escape sequence to change foreground color.
.PP
Autodetect terminal capability and can return either empty string, 16\-color,
256\-color, or 24bit\-code.
.PP
Color depth used is determined by \f(CW\*(C`COLOR_DEPTH\*(C'\fR 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}\fIfg\fR\fBcode()\fR.
.PP
This function is not exported by default, but exportable.
.PP
Arguments ('*' denotes required arguments):
.IP \(bu 4
\&\fR\f(CB$color\fR\fB\fR* => \fIcolor::rgb24\fR
.Sp
(No description)
.PP
Return value:  (str)
.SS "ansi16fg($rgb) => STR"
.IX Subsection "ansi16fg($rgb) => STR"
Alias for \fBrgb_to_ansi16_fg_code()\fR.
.SS "ansi16bg($rgb) => STR"
.IX Subsection "ansi16bg($rgb) => STR"
Alias for \fBrgb_to_ansi16_bg_code()\fR.
.SS "ansi256fg($rgb) => STR"
.IX Subsection "ansi256fg($rgb) => STR"
Alias for \fBrgb_to_ansi256_fg_code()\fR.
.SS "ansi256bg($rgb) => STR"
.IX Subsection "ansi256bg($rgb) => STR"
Alias for \fBrgb_to_ansi256_bg_code()\fR.
.SS "ansi24bfg($rgb) => STR"
.IX Subsection "ansi24bfg($rgb) => STR"
Alias for \fBrgb_to_ansi24b_fg_code()\fR.
.SS "ansi24bbg($rgb) => STR"
.IX Subsection "ansi24bbg($rgb) => STR"
Alias for \fBrgb_to_ansi24b_bg_code()\fR.
.SS "rgb_to_ansi_fg_code($rgb) => STR"
.IX Subsection "rgb_to_ansi_fg_code($rgb) => STR"
.SS "ansifg($rgb) => STR"
.IX Subsection "ansifg($rgb) => STR"
Alias for \fBrgb_to_ansi_fg_code()\fR.
.SS "ansibg($rgb) => STR"
.IX Subsection "ansibg($rgb) => STR"
Alias for \fBrgb_to_ansi_bg_code()\fR.
.ie n .SS "ansi_reset( [ $conditional ])"
.el .SS "ansi_reset( [ \f(CW$conditional\fP ])"
.IX Subsection "ansi_reset( [ $conditional ])"
Returns "\ee[0m", which is the ANSI escape sequence to reset color. Normally you
print this sequence after you print colored text.
.PP
If \f(CW$conditional\fR is set to true, then \fBansi_reset()\fR will return "" if color is
disabled.
.SH ENVIRONMENT
.IX Header "ENVIRONMENT"
.SS NO_COLOR
.IX Subsection "NO_COLOR"
Can be used to explicitly disable color. See <https://no\-color.org> for more
details.
.PP
Observed by: ansi{fg,bg}.
.SS "COLOR => bool"
.IX Subsection "COLOR => bool"
Can be used to explicitly disable color by setting it to 0.
.PP
Observed by: ansi{fg,bg}.
.SS "COLOR_DEPTH => INT"
.IX Subsection "COLOR_DEPTH => INT"
Can be used to explicitly set color depth instead of trying to detect
appropriate color depth.
.PP
Observed by: ansi{fg,bg}.
.SH HOMEPAGE
.IX Header "HOMEPAGE"
Please visit the project's homepage at <https://metacpan.org/release/Color\-ANSI\-Util>.
.SH SOURCE
.IX Header "SOURCE"
Source repository is at <https://github.com/perlancar/perl\-Color\-ANSI\-Util>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Term::ANSIColor
.PP
<http://en.wikipedia.org/wiki/ANSI_escape_code>
.SH AUTHOR
.IX Header "AUTHOR"
perlancar <perlancar@cpan.org>
.SH CONTRIBUTOR
.IX Header "CONTRIBUTOR"
Steven Haryanto <stevenharyanto@gmail.com>
.SH CONTRIBUTING
.IX Header "CONTRIBUTING"
To contribute, you can send patches by email/via RT, or send pull requests on
GitHub.
.PP
Most of the time, you don't need to build the distribution yourself. You can
simply modify the code, then test via:
.PP
.Vb 1
\& % prove \-l
.Ve
.PP
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.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2024, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013 by perlancar <perlancar@cpan.org>.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH BUGS
.IX Header "BUGS"
Please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Color\-ANSI\-Util>
.PP
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.