Term::Cap(3pm)

📦
version 5.42.3 · 8 versions
, in alpine 3.24

💅 Term::Cap

okay bestie, welcome to Term::Cap(3pm) — the Perl module that's literally your VIP pass to the termcap database 🎀 she's giving low-level, she's giving old-school, and she absolutely ate.

✨ NAME ✨

Term::Cap — the Perl termcap interface, no cap 💅

🌸 SYNOPSIS 🌸

require Term::Cap;
$terminal = Term::Cap->Tgetent({ TERM => undef, OSPEED => $ospeed });
$terminal->Trequire(qw/ce ku kd/);
$terminal->Tgoto('cm', $col, $row, $FH);
$terminal->Tputs('dl', $count, $FH);
$terminal->Tpad($string, $count, $FH);

💖 DESCRIPTION 💖

These are the low-level girlies — functions that pull capabilities out of a terminal capability (termcap) database and then actually use them. 🧚

If you want the deep lore on terminal capabilities themselves, check the termcap manpage on most Unix-like systems. iykyk.

🦋 METHODS

Since your girl cares about performance: the output strings for Tputs get cached for counts of 1. Tgoto and Tpad? Nope, they do not cache, they're free spirits. Also know that "$self->{_xx}" is the raw termcap data and "$self->{xx}" is the cached version:

print $terminal->Tpad($self->{_xx}, 1);

Tgoto, Tputs, and Tpad all return the string, and they'll also output the string to $FH if you specified one. double duty, iconic 💅

⭐ Tgetent

Returns a blessed object reference that you can then use to yeet control strings to the terminal via Tputs and Tgoto.

It extracts the entry for the specified terminal type TERM (which defaults to the environment variable TERM) out of the database.

So here's the search saga, bestie, pay attention:

  • It looks in the environment for a TERMCAP variable.
  • If found, and the value does not begin with a slash, and the terminal type name is the same as the environment string TERM, then the TERMCAP string is used instead of reading a termcap file. slay, shortcut 🎀
  • If it does begin with a slash, the string is used as a path name of the termcap file to search.
  • If TERMCAP does not begin with a slash and the name is different from TERM, Tgetent searches the files $HOME/.termcap, /etc/termcap, and /usr/share/misc/termcap, in that order — unless the environment variable TERMPATH exists, in which case TERMPATH specifies a list of file pathnames (separated by spaces or colons) to be searched instead.
  • Whenever multiple files are searched and a tc field occurs in the requested entry, the entry it names must be found in the same file or one of the succeeding files. no skipping ahead 🚫
  • If there's a ":tc=...:" in the TERMCAP environment variable string, it will continue the search in the files as described above.

The extracted termcap entry lives on the object at "$self->{TERMCAP}". 🫶

It takes a hash reference as an argument, with two optional keys:

  • OSPEED — the terminal output bit rate (often mistakenly called the baud rate) for this terminal. If you don't set it, a warning gets generated and it defaults to 9600. OSPEED can be given as either a POSIX termios/SYSV termio speed (where 9600 equals 9600) or an old DSD-style speed (where 13 equals 9600). cursed but valid 💀
  • TERM — the terminal type whose termcap entry will be used. If not supplied it defaults to $ENV{TERM}; if that isn't set either, Tgetent will croak. she's dramatic like that 😭
It calls "croak" on failure. periodt.

🎀 Tpad

Outputs a literal string with the appropriate padding for your current terminal.

It takes three arguments:

  • $string — the literal string to be output. If it starts with a number and an optional '*', then the padding gets increased by an amount relative to this number; and if the '*' is present, that amount is multiplied by $cnt. This part of $string is removed before output.
  • $cnt — used to modify the padding applied to the string, as described above.
  • $FH — an optional filehandle (or IO::Handle) that output gets printed to.

The padded $string is returned. 🌸

💜 Tputs

Outputs the string for the given capability, padded as appropriate, with no parameter substitution.

Three arguments, let's go:

  • $cap — the capability whose string is to be output.
  • $cnt — a count passed to Tpad to modify the padding applied to the output string. If $cnt is zero or one, then the resulting string gets cached. ✨
  • $FH — an optional filehandle (or IO::Handle) that output gets printed to.

The appropriate string for the capability is returned.

🔥 Tgoto

Tgoto decodes a cursor addressing string using the parameters you give it.

Four arguments, bestie:

  • $cap — the name of the capability to be output.
  • $col — the first value substituted into the output string (usually the column in a cursor addressing capability).
  • $row — the second value substituted into the output string (usually the row in cursor addressing capabilities).
  • $FH — an optional filehandle (or IO::Handle) that the output string gets printed to.

Substitutions are made with $col and $row in the output string using these sprintf() line formats:

 %%   output `%'
 %d   output value as in printf %d
 %2   output value as in printf %2d
 %3   output value as in printf %3d
 %.   output value as in printf %c
 %+x  add x to value, then do %.

 %>xy if value > x then add y, no output
 %r   reverse order of two parameters, no output
 %i   increment by one, no output
 %B   BCD (16*(value/10)) + (value%10), no output

 %n   exclusive-or all parameters with 0140 (Datamedia 2500)
 %D   Reverse coding (value - 2*(value%16)), no output (Delta Data)

The output string will be returned. 👑

🌈 Trequire

Takes a list of capabilities as an argument and will croak if one of them isn't found. she checks receipts, always 💅

⭐ EXAMPLES ⭐

use Term::Cap;

# Get terminal output speed
require POSIX;
my $termios = POSIX::Termios->new;
$termios->getattr;
my $ospeed = $termios->getospeed;

# Old-style ioctl code to get ospeed:
#     require 'ioctl.pl';
#     ioctl(TTY,$TIOCGETP,$sgtty);
#     ($ispeed,$ospeed) = unpack('cc',$sgtty);

# allocate and initialize a terminal structure
my $terminal = Term::Cap->Tgetent({ TERM => undef, OSPEED => $ospeed });

# require certain capabilities to be available
$terminal->Trequire(qw/ce ku kd/);

# Output Routines, if $FH is undefined these just return the string

# Tgoto does the % expansion stuff with the given args
$terminal->Tgoto('cm', $col, $row, $FH);

# Tputs doesn't do any % expansion.
$terminal->Tputs('dl', $count = 1, $FH);

Copyright 1995-2015 (c) perl5 porters.

This software is free software and can be modified and distributed under the same terms as Perl itself. 🫶

Please see the file README in the Perl source distribution for the details of the Perl license.

👑 AUTHOR 👑

This module is part of the core Perl distribution and is also maintained for CPAN by Jonathan Stowe <jns@gellyfish.co.uk>.

The code is hosted on Github: https://github.com/jonathanstowe/Term-Cap — please feel free to fork, submit patches etc, etc there. go off 💖

🌸 SEE ALSO 🌸

termcap(5)

and that's the whole page, bestie ✨ this one shipped with perl v5.42.3 and got stamped 2026-11-03 — she's dated, she's official, she's iconic, mwah 💋💅

📦 where this page comes from