NAME
    XTerm::Util - Utility routines for xterm-compatible terminal (emulator)s

VERSION
    This document describes version 0.006 of XTerm::Util (from Perl
    distribution XTerm-Util), released on 2019-11-27.

SYNOPSIS
     use XTerm::Util qw(
         get_term_fgcolor
         get_term_bgcolor
         set_term_fgcolor
         set_term_bgcolor
         term_fgcolor_is_dark
         term_fgcolor_is_light
         term_bgcolor_is_dark
         term_bgcolor_is_light
     );

     # when you're on a black background
     say get_term_bgcolor(); # => "000000"

     # when you're on a dark purple background
     say get_term_bgcolor(); # => "310035"

     # set terminal background to dark blue
     set_term_bgcolor("00002b");

DESCRIPTION
    Keywords: xterm, xterm-256color, terminal

COMPATIBILITY NOTES
    Versions of software tested:

        MATE Terminal (1.20.2)
        GNOME Terminal (3.23.)
        Konsole (18.12.3)
        XTerm (330)
        LXTerminal (0.2.0)
        rxvt (2.7.10)

     |                                   | mate  | gnome | konsole | xterm | lxterm | rxvt |
     |-----------------------------------+-------+-------+---------+-------+--------+------|
     | Getting terminal background color | no 1) | no 1) | yes     | yes   | no     | no   |
     | Getting terminal foreground color | no 1) | no 1) | no 2)   | yes   | no     | no   |
     | Setting terminal background color | yes   | yes   | yes     | yes   | no     | no   |
     | Setting terminal foreground color | yes   | yes   | yes     | yes   | no     | no   |

     1) cannot be captured
     2) terminal does not respond back

FUNCTIONS
  get_term_bgcolor
    Usage:

     get_term_bgcolor(%args) -> any

    Get terminal background color.

    Get the terminal's current background color (in 6-hexdigit format e.g.
    000000 or ffff33), or undef if unavailable. This routine tries the
    following mechanisms, from most useful to least useful, in order. Each
    mechanism can be turned off via argument.

    *query_terminal*. Querying the terminal is done via sending the
    following xterm control sequence:

     \e]11;?\a

    (or \e]11;?\017). A compatible terminal will issue back the same
    sequence but with the question mark replaced by the RGB code, e.g.:

     \e]11;rgb:0000/0000/0000\a

    *read_colorfgbg*. Some terminals like Konsole set the environment
    variable "COLORFGBG" containing 16-color color code for foreground and
    background, e.g.: "15;0".

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   query_terminal => *bool* (default: 1)

    *   read_colorfgbg => *bool* (default: 1)

    Return value: (any)

  get_term_fgcolor
    Usage:

     get_term_fgcolor(%args) -> any

    Get terminal text (foreground) color.

    Get the terminal's current text (foreground) color (in 6-hexdigit format
    e.g. 000000 or ffff33), or undef if unavailable. This routine tries the
    following mechanisms, from most useful to least useful, in order. Each
    mechanism can be turned off via argument.

    *query_terminal*. Querying the terminal is done via sending the
    following xterm control sequence:

     \e]10;?\a

    (or \e]10;?\017). A compatible terminal will issue back the same
    sequence but with the question mark replaced by the RGB code, e.g.:

     \e]10;rgb:0000/0000/0000\a

    *read_colorfgbg*. Some terminals like Konsole set the environment
    variable "COLORFGBG" containing 16-color color code for foreground and
    background, e.g.: "15;0".

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   query_terminal => *bool* (default: 1)

    *   read_colorfgbg => *bool* (default: 1)

    Return value: (any)

  set_term_bgcolor
    Usage:

     set_term_bgcolor($rgb, $stderr) -> any

    Set terminal background color.

    Set terminal background color. This prints the following xterm control
    sequence to STDOUT (or STDERR, if ~stderr~ is set to true):

     \e]11;#123456\a

    where *123456* is the 6-hexdigit RGB color code.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   $rgb* => *color::rgb24*

    *   $stderr => *true*

    Return value: (any)

  set_term_fgcolor
    Usage:

     set_term_fgcolor($rgb, $stderr) -> any

    Set terminal background color.

    Set terminal background color. This prints the following xterm control
    sequence to STDOUT (or STDERR, if ~stderr~ is set to true):

     \e]11;#123456\a

    where *123456* is the 6-hexdigit RGB color code.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   $rgb* => *color::rgb24*

    *   $stderr => *true*

    Return value: (any)

  term_bgcolor_is_dark
    Usage:

     term_bgcolor_is_dark(%args) -> [status, msg, payload, meta]

    Check if terminal background color is dark.

    This is basically get_term_bgcolor + rgb_is_dark.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   query_terminal => *bool* (default: 1)

    *   quiet => *bool*

    *   read_colorfgbg => *bool* (default: 1)

    Returns an enveloped result (an array).

    First element (status) is an integer containing HTTP status code (200
    means OK, 4xx caller error, 5xx function error). Second element (msg) is
    a string containing error message, or 'OK' if status is 200. Third
    element (payload) is optional, the actual result. Fourth element (meta)
    is called result metadata and is optional, a hash that contains extra
    information.

    Return value: (any)

  term_bgcolor_is_light
    Usage:

     term_bgcolor_is_light(%args) -> [status, msg, payload, meta]

    Check if terminal background color is light.

    This is basically get_term_bgcolor + rgb_is_light.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   query_terminal => *bool* (default: 1)

    *   quiet => *bool*

    *   read_colorfgbg => *bool* (default: 1)

    Returns an enveloped result (an array).

    First element (status) is an integer containing HTTP status code (200
    means OK, 4xx caller error, 5xx function error). Second element (msg) is
    a string containing error message, or 'OK' if status is 200. Third
    element (payload) is optional, the actual result. Fourth element (meta)
    is called result metadata and is optional, a hash that contains extra
    information.

    Return value: (any)

  term_fgcolor_is_dark
    Usage:

     term_fgcolor_is_dark(%args) -> [status, msg, payload, meta]

    Check if terminal text (foreground) color is dark.

    This is basically get_term_fgcolor + rgb_is_dark.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   query_terminal => *bool* (default: 1)

    *   quiet => *bool*

    *   read_colorfgbg => *bool* (default: 1)

    Returns an enveloped result (an array).

    First element (status) is an integer containing HTTP status code (200
    means OK, 4xx caller error, 5xx function error). Second element (msg) is
    a string containing error message, or 'OK' if status is 200. Third
    element (payload) is optional, the actual result. Fourth element (meta)
    is called result metadata and is optional, a hash that contains extra
    information.

    Return value: (any)

  term_fgcolor_is_light
    Usage:

     term_fgcolor_is_light(%args) -> [status, msg, payload, meta]

    Check if terminal text (foreground) color is light.

    This is basically get_term_fgcolor + rgb_is_light.

    This function is not exported.

    Arguments ('*' denotes required arguments):

    *   query_terminal => *bool* (default: 1)

    *   quiet => *bool*

    *   read_colorfgbg => *bool* (default: 1)

    Returns an enveloped result (an array).

    First element (status) is an integer containing HTTP status code (200
    means OK, 4xx caller error, 5xx function error). Second element (msg) is
    a string containing error message, or 'OK' if status is 200. Third
    element (payload) is optional, the actual result. Fourth element (meta)
    is called result metadata and is optional, a hash that contains extra
    information.

    Return value: (any)

ENVIRONMENT
  COLORFGBG
HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/XTerm-Util>.

SOURCE
    Source repository is at <https://github.com/perlancar/perl-XTerm-Util>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=XTerm-Util>

    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.

SEE ALSO
    Color::ANSI::Util

    XTerm control sequence:
    <http://invisible-island.net/xterm/ctlseqs/ctlseqs.html>, or
    <http://www.xfree86.org/4.7.0/ctlseqs.html>

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2019, 2018 by perlancar@cpan.org.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.