XTerm::Util - Utility routines for xterm-compatible terminal (emulator)s
This document describes version 0.006 of XTerm::Util (from Perl distribution XTerm-Util), released on 2019-11-27.
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");
Keywords: xterm, xterm-256color, terminal
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
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.
COLORFGBG
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(%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.
\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
This function is not exported.
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.
$rgb* => color::rgb24
$stderr => true
set_term_fgcolor($rgb, $stderr) -> any
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.
quiet => bool
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.
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.
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.
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.
Please visit the project's homepage at https://metacpan.org/release/XTerm-Util.
Source repository is at https://github.com/perlancar/perl-XTerm-Util.
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.
Color::ANSI::Util
XTerm control sequence: http://invisible-island.net/xterm/ctlseqs/ctlseqs.html, or http://www.xfree86.org/4.7.0/ctlseqs.html
perlancar <perlancar@cpan.org>
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.
To install XTerm::Util, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XTerm::Util
CPAN shell
perl -MCPAN -e shell install XTerm::Util
For more information on module installation, please visit the detailed CPAN module installation guide.