NAME
Term::Detect::Software - Detect terminal (emulator) software and its
capabilities
VERSION
This document describes version 0.227 of Term::Detect::Software (from
Perl distribution Term-Detect-Software), released on 2024-02-10.
SYNOPSIS
use Term::Detect::Software qw(detect_terminal detect_terminal_cached);
my $res = detect_terminal();
die "Not running under terminal!" unless $res->{emulator_engine};
say "Emulator engine: ", $res->{emulator_engine};
say "Emulator software: ", $res->{emulator_software};
say "Unicode support? ", $res->{unicode} ? "yes":"no";
say "Boxchars support? ", $res->{box_chars} ? "yes":"no";
say "Color depth: ", $res->{color_depth};
say "Inside emacs? ", $res->{inside_emacs} ? "yes":"no";
DESCRIPTION
This module uses several heuristics to find out what terminal (emulator)
software the current process is running in, and its
capabilities/settings. This module complements other modules such as
Term::Terminfo and Term::Encoding.
FUNCTIONS
detect_terminal() => HASHREF
Return a hashref containing information about running terminal
(emulator) software and its capabilities/settings.
Detection method is tried from the easiest/cheapest (e.g. checking
environment variables) or by looking at known process names in the
process tree. Terminal capabilities is determined using heuristics.
Currently Konsole and Konsole-based terminals (like Yakuake) can be
detected through existence of environment variables
"KONSOLE_DBUS_SERVICE" or "KONSOLE_DBUS_SESSION". xterm is detected
through "XTERM_VERSION". XFCE's Terminal is detected using "COLORTERM".
The other software are detected via known process names.
Terminal capabilities and settings are currently determined via
heuristics. Probing terminal configuration files might be performed in
the future.
Result:
* emulator_engine => STR
Possible values: "konsole", "xterm", "gnome-terminal", "rxvt",
"pterm" (PuTTY), "xvt", "windows" (CMD.EXE), "cygwin", "st"
(suckless.org's terminal emulator), or empty string (if not detected
running under terminal).
* emulator_software => STR
Either: "xfce4-terminal", "guake", "gnome-terminal", "mlterm",
"lxterminal", "rxvt", "mrxvt", "putty", "xvt", "windows" (CMD.EXE),
"st" (suckless.org's terminal emulator), or empty string (if not
detected running under terminal).
* color_depth => INT
Either 0 (does not support ANSI color codes), 16, 256, or 16777216
(2**24).
* default_bgcolor => STR (6-hexdigit RGB)
For example, any xterm is assumed to have white background (ffffff)
by default, while Konsole is assumed to have black (000000). Better
heuristics will be done in the future.
* unicode => BOOL
Whether terminal software supports Unicode/wide characters. Note
that you should also check encoding, e.g. using Term::Encoding.
* box_chars => BOOL
Whether terminal supports box-drawing characters.
detect_terminal_cached([$flag]) => ANY
Just like detect_terminal() but will cache the result. Can be used by
applications or modules to avoid repeating detection process.
FAQ
What is this module for? Why not Term::Terminfo or Term::Encoding?
This module was first written for Text::ANSITable so that the latter can
provide good defaults when displaying formatted and colored tables,
especially on popular terminal emulation software like Konsole (KDE's
default terminal), gnome-terminal (GNOME's default), Terminal (XFCE's
default), xterm, rxvt.
This module works by trying to figure out the terminal emulation
software because the information provided by Term::Terminfo and
Term::Encoding are sometimes not specific enough. For example,
Term::Encoding can return utf-8 when running under rxvt, but since the
software currently lacks Unicode support we shouldn't display Unicode
characters. Another example is color depth: Term::Terminfo currently
doesn't recognize Konsole's 24bit color support and only gives
"max_colors" 256.
Which terminal software are detected?
See "PERL_TERM_DETECT_SOFTWARE_ENGINE".
Why is my terminal software not detected?
By default, some software are not detected because the heuristics to do
so is considered rather costly. This includes detecting gnome-terminal,
rxvt, mrxvt, st, pterm/putty, xvt via checking process name, because
listing all processes and their details costs tens to hundreds of
milliseconds. See "PERL_TERM_DETECT_SOFTWARE_CHECK_PS" to enable it.
ENVIRONMENT
PERL_TERM_DETECT_SOFTWARE_CHECK_PS
By default, some software are not detected because the heuristics to do
so is considered rather costly. This includes detecting gnome-terminal,
rxvt, mrxvt, st, pterm/putty, xvt via checking process name, because
listing all processes and their details costs tens to hundreds of
milliseconds. To enable this checking, set this environment variable to
true and install the optional dependency Proc::Find::Parents.
PERL_TERM_DETECT_SOFTWARE_ENGINE
String. Explicitly instruct Term::Detect::Software to use a specific
engine, instead of heuristically trying to detect. This is useful for
testing or for avoiding sometimes costly detection.
List of supported engines:
konsole
xterm
cygwin
linux # linux virtual console
gnome-terminal
windows # windows command prompt
dumb # dumb/generic, e.g. run under CGI or something like that
rxvt
st
putty
xvt
For more details on the capabilities of each engine, currently please
peruse the source code.
HOMEPAGE
Please visit the project's homepage at
SOURCE
Source repository is at
SEE ALSO
Term::Terminfo
Term::Encoding
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTOR
Steven Haryanto <stevenharyanto@gmail.com>
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, 2023, 2020, 2019, 2015, 2014, 2013
by perlancar <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.
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.