Term::Detect::Software - Detect terminal (emulator) software and its capabilities
This document describes version 0.227 of Term::Detect::Software (from Perl distribution Term-Detect-Software), released on 2024-02-10.
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";
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.
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.
KONSOLE_DBUS_SERVICE
KONSOLE_DBUS_SESSION
XTERM_VERSION
COLORTERM
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).
konsole
xterm
gnome-terminal
rxvt
pterm
xvt
windows
cygwin
st
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).
xfce4-terminal
guake
mlterm
lxterminal
mrxvt
putty
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.
Just like detect_terminal() but will cache the result. Can be used by applications or modules to avoid repeating detection process.
detect_terminal()
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.
max_colors
See "PERL_TERM_DETECT_SOFTWARE_ENGINE".
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.
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.
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.
Please visit the project's homepage at https://metacpan.org/release/Term-Detect-Software.
Source repository is at https://github.com/perlancar/perl-Term-Detect-Software.
Term::Terminfo
Term::Encoding
perlancar <perlancar@cpan.org>
Steven Haryanto <stevenharyanto@gmail.com>
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.
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.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Term-Detect-Software
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.
To install Term::Detect::Software, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Term::Detect::Software
CPAN shell
perl -MCPAN -e shell install Term::Detect::Software
For more information on module installation, please visit the detailed CPAN module installation guide.