[Chapter 7] 7.2.64 Term::Cap - Terminal Capabilities Interface
Author: Larry Wall, Tom Christiansen & Randal L. Schwartz
Date: 1999-07-02T02:04:20Z

#

| Chapter 7 The Standard Perl Library |

### 7.2.64 Term::Cap - Terminal Capabilities Interface

    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);

These are low-level functions to extract and use capabilities from a terminal capability (termcap) database. For general information about the use of this database, see the termcap(5) manpage.

The "`new`" function of Term::Cap is `Tgetent()`, which extracts the termcap entry for the specified terminal type and returns a reference to a terminal object. If the value associated with the `TERM` key in the `Tgetent()` argument list is false or undefined, then it defaults to the environment variable `TERM`.

`Tgetent()` looks in the environment for a `TERMCAP` variable. If it finds one, and if the value does not begin with a slash and looks like a termcap entry in which the terminal type name is the same as the environment string `TERM`, then the `TERMCAP` string is used directly as the termcap entry and there is no search for an entry in a termcap file somewhere.

Otherwise, `Tgetent()` looks in a sequence of files for the termcap entry. The sequence consists of the filename in `TERMCAP`, if any, followed by either the files listed in the `TERMPATH` environment variable, if any, or otherwise the files $HOME/.termcap, /etc/termcap, and /usr/share/misc/termcap, in that order. (Filenames in `TERMPATH` may be separated by either a colon or a space.) Whenever multiple files are searched and a `tc` field occurs in the requested entry, the entry named in the `tc` field must be found in the same file or one of the succeeding files. If there is a `tc` field in the `TERMCAP` environment variable string, `Tgetent()` continues searching as indicated above.

`OSPEED` is the terminal output bit rate (often mistakenly called the baud rate). `OSPEED` can be specified as either a POSIX termios/SYSV termio speed (where 9600 equals 9600) or an old BSD-style speed (where 13 equals 9600). See the next section, "Getting Terminal Output Speed", for code illustrating how to obtain the output speed.

`Tgetent()` returns a reference to a blessed object (`$terminal` in the examples above). The actual termcap entry is available as `$terminal->{TERMCAP}`. Failure to find an appropriate termcap entry results in a call to `Carp::croak()`.

Once you have invoked `Tgetent()`, you can manage a terminal by sending control strings to it with `Tgoto()` and `Tputs()`. You can also test for the existence of particular terminal capabilities with `Trequire()`.

`Trequire()` checks to see whether the named capabilities have been specified in the terminal's termcap entry. For example, this line:

    $terminal->Trequire(qw/ce ku kd/);

checks whether the `ce` (clear to end of line), `ku` (keypad up-arrow), and `kd` (keypad down-arrow) capabilities have been defined. Any undefined capabilities will result in a listing of those capabilities and a call to `Carp::croak()`.

`Tgoto()` produces a control string to move the cursor relative to the screen. For example, to move the cursor to the fifth line and forty-fifth column on the screen, you can say:

    $row = 5; $col = 45;
    $terminal->Tgoto('cm', $row, $col, STDOUT);

The first argument in this call must always be `cm`. If a file handle is given as the final argument, then `Tgoto()` sends the appropriate control string to that handle. With or without a handle, the routine returns the control string, so you could achieve the same effect this way:

    $str = $terminal->Tgoto('cm', $row, $col);
    print STDOUT $str;

`Tgoto()` performs the necessary % interpolation on the control strings. (See the termcap(5) manpage for details.)

The `Tputs()` routine allows you to exercise other terminal capabilities. For example, the following code deletes one line at the cursor's present position, and then turns on the bold text attribute:

    $count = 1;
    $terminal->Tputs('dl', $count, $FILEHANDLE);  # delete one line
    $terminal->Tputs('md', $count, $FILEHANDLE);  # turn on bold attribute

Again, `Tputs()` returns the terminal control string, and the file handle can be omitted. The `$count` for such calls should normally be `1`, unless padding is required. (Padding involves the output of "no-op" characters in order to effect a delay required by the terminal device. It is most commonly required for hardcopy devices.) A count greater than `1` is taken to specify the amount of padding. See the termcap(5) manpage for more about padding.

`Tputs()` does not perform % interpolation. This means that the following will not work:

    $terminal->Tputs('DC', 1, $FILEHANDLE);  # delete one character (WRONG!)

If the terminal control string requires numeric parameters, then you must do the interpolation yourself:

    $str = $terminal->Tputs('DC', 1);
    $str =~ s/%d/7/;
    print STDOUT $str;        # delete seven characters

The output strings for `Tputs()` are cached for counts of 1. `Tgoto()` does not cache. `$terminal->{_``xx``}` is the raw termcap data and `$terminal->{``xx``}` is the cached version (where `xx` is the two-character terminal capability code).

#### 7.2.64.1 Getting terminal output speed

You can use the POSIX module to get your terminal's output speed for use in the `Tgetent()` call:

    require POSIX;
    my $termios = new POSIX::Termios;
    $termios->getattr;
    my $ospeed = $termios->getospeed;

The method using ioctl(2) works like this:

    require 'ioctl.pl';
    ioctl(TTY, $TIOCGETP, $sgtty);
    ($ispeed, $ospeed) = unpack('cc', $sgtty);

7.2.63 Sys::Syslog - Perl Interface to UNIX syslog(3) Calls |  | 7.2.65 Term::Complete - Word Completion Module