Term::Cap
Term::Cap(3) Perl Programmers Reference Guide Term::Cap(3)
NAME
Term::Cap - Perl termcap interface
SYNOPSIS
require Term::Cap;
$terminal = Tgetent Term::Cap { 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 low-level functions to extract and use capabilities from a
terminal capability (termcap) database.
More information on the terminal capabilities will be found in the
termcap manpage on most Unix-like systems.
METHODS
The output strings for Tputs are cached for counts of 1 for per-
formance. Tgoto and Tpad do not cache. "$self->{_xx}" is the raw
termcap data and "$self->{xx}" is the cached version.
print $terminal->Tpad($self->{_xx}, 1);
Tgoto, Tputs, and Tpad return the string and will also output the
string to $FH if specified.
Tgetent
Returns a blessed object reference which the user can then use to
send the control strings to the terminal using Tputs and Tgoto.
The function extracts the entry of the specified terminal type
TERM (defaults to the environment variable TERM) from the
database.
It will look 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, the TERMCAP
string is used instead of reading a termcap file. If it does
begin with a slash, the string is used as a path name of the term-
cap file to search. If TERMCAP does not begin with a slash and
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 it 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. If there is a ":tc=...:" in the TERMCAP environment vari-
able string it will continue the search in the files as above.
The extracted termcap entry is available in the object as
"$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 not set a warning will be generated
and it will be defaulted to 9600. OSPEED can be be specified as
either a POSIX termios/SYSV termio speeds (where 9600 equals
9600) or an old DSD-style speed ( where 13 equals 9600).
TERM
The terminal type whose termcap entry will be used - if not sup-
plied it will default to $ENV{TERM}: if that is not set then
Tgetent will croak.
It calls "croak" on failure.
Tpad
Outputs a literal string with appropriate padding for the 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 will be increased by an amount
relative to this number, if the ’*’ is present then this amount
will me multiplied by $cnt. This part of $string is removed
before output/
$cnt
Will be used to modify the padding applied to string as
described above.
$FH
An optional filehandle (or IO::Handle ) that output will be
printed to.
The padded $string is returned.
Tputs
Output the string for the given capability padded as appropriate
without any parameter substitution.
It takes three arguments:
$cap
The capability whose string is to be output.
$cnt
A count passed to Tpad to modify the padding applied to the out-
put string. If $cnt is zero or one then the resulting string
will be cached.
$FH
An optional filehandle (or IO::Handle ) that output will be
printed to.
The appropriate string for the capability will be returned.
Tgoto
Tgoto decodes a cursor addressing string with the given parame-
ters.
There are four arguments:
$cap
The name of the capability to be output.
$col
The first value to be substituted in the output string ( usually
the column in a cursor addressing capability )
$row
The second value to be substituted in the output string (usually
the row in cursor addressing capabilities)
$FH
An optional filehandle (or IO::Handle ) to which the output
string will be printed.
Substitutions are made with $col and $row in the output string
with the following 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
is not found.
EXAMPLES
use Term::Cap;
# Get terminal output speed
require POSIX;
my $termios = new POSIX::Termios;
$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
$terminal = Tgetent Term::Cap { 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 AND LICENSE
Please see the README file in distribution.
AUTHOR
This module is part of the core Perl distribution and is also main-
tained for CPAN by Jonathan Stowe <jns@gellyfish.com>.
SEE ALSO
termcap(5)
perl v5.8.8 2001-09-21 Term::Cap(3)
