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

VERSION
    This document describes version 0.002 of XTerm::Util (from Perl
    distribution XTerm-Util), released on 2018-09-26.

SYNOPSIS
     use XTerm::Util qw(
         get_term_bgcolor
         set_term_bgcolor
     );

     # 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

FUNCTIONS
  get_term_bgcolor
    Usage:

     my $rgb = get_term_bgcolor();

    Get the terminal's current background color, or undef if unavailable.
    This uses the following xterm control sequence:

     \e]11;?\a

    and 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

    I have tested this works on the following terminal software (and
    version) on Linux:

     MATE Terminal (1.18.2)
     GNOME Terminal (3.18.3)
     Konsole (16.04.3)

    And does not work with the following terminal software (and version) on
    Linux:

     LXTerminal (0.2.0)
     rxvt (2.7.10)

    The function will return a 6-hexdigit RGB value, e.g.:

     000000
     310035

    which you can feed to, e.g.: "set_term_bgcolor" to set background color
    of terminal, or Color::ANSI::Util's "ansibg" to produce an appropriate
    escape sequance to set background color of text.

  set_term_bgcolor
    Usage:

     set_term_bgcolor($rgb [, $stderr ]);

    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.

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

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 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.

