1Cap(3)                User Contributed Perl Documentation               Cap(3)
2
3
4

NAME

6       Term::Cap - Perl termcap interface
7

SYNOPSIS

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

DESCRIPTION

17       These are low-level functions to extract and use capabilities from a
18       terminal capability (termcap) database.
19
20       More information on the terminal capabilities will be found in the
21       termcap manpage on most Unix-like systems.
22
23   METHODS
24       The output strings for Tputs are cached for counts of 1 for
25       performance.  Tgoto and Tpad do not cache.  "$self->{_xx}" is the raw
26       termcap data and "$self->{xx}" is the cached version.
27
28           print $terminal->Tpad($self->{_xx}, 1);
29
30       Tgoto, Tputs, and Tpad return the string and will also output the
31       string to $FH if specified.
32
33       Tgetent
34           Returns a blessed object reference which the user can then use to
35           send the control strings to the terminal using Tputs and Tgoto.
36
37           The function extracts the entry of the specified terminal type TERM
38           (defaults to the environment variable TERM) from the database.
39
40           It will look in the environment for a TERMCAP variable.  If found,
41           and the value does not begin with a slash, and the terminal type
42           name is the same as the environment string TERM, the TERMCAP string
43           is used instead of reading a termcap file.  If it does begin with a
44           slash, the string is used as a path name of the termcap file to
45           search.  If TERMCAP does not begin with a slash and name is
46           different from TERM, Tgetent searches the files $HOME/.termcap,
47           /etc/termcap, and /usr/share/misc/termcap, in that order, unless
48           the environment variable TERMPATH exists, in which case it
49           specifies a list of file pathnames (separated by spaces or colons)
50           to be searched instead.  Whenever multiple files are searched and a
51           tc field occurs in the requested entry, the entry it names must be
52           found in the same file or one of the succeeding files.  If there is
53           a ":tc=...:" in the TERMCAP environment variable string it will
54           continue the search in the files as above.
55
56           The extracted termcap entry is available in the object as
57           "$self->{TERMCAP}".
58
59           It takes a hash reference as an argument with two optional keys:
60
61           OSPEED
62             The terminal output bit rate (often mistakenly called the baud
63             rate) for this terminal - if not set a warning will be generated
64             and it will be defaulted to 9600.  OSPEED can be specified as
65             either a POSIX termios/SYSV termio speeds (where 9600 equals
66             9600) or an old DSD-style speed ( where 13 equals 9600).
67
68           TERM
69             The terminal type whose termcap entry will be used - if not
70             supplied it will default to $ENV{TERM}: if that is not set then
71             Tgetent will croak.
72
73           It calls "croak" on failure.
74
75       Tpad
76           Outputs a literal string with appropriate padding for the current
77           terminal.
78
79           It takes three arguments:
80
81           $string
82             The literal string to be output.  If it starts with a number and
83             an optional '*' then the padding will be increased by an amount
84             relative to this number, if the '*' is present then this amount
85             will be multiplied by $cnt.  This part of $string is removed
86             before output/
87
88           $cnt
89             Will be used to modify the padding applied to string as described
90             above.
91
92           $FH
93             An optional filehandle (or IO::Handle ) that output will be
94             printed to.
95
96           The padded $string is returned.
97
98       Tputs
99           Output the string for the given capability padded as appropriate
100           without any parameter substitution.
101
102           It takes three arguments:
103
104           $cap
105             The capability whose string is to be output.
106
107           $cnt
108             A count passed to Tpad to modify the padding applied to the
109             output string.  If $cnt is zero or one then the resulting string
110             will be cached.
111
112           $FH
113             An optional filehandle (or IO::Handle ) that output will be
114             printed to.
115
116           The appropriate string for the capability will be returned.
117
118       Tgoto
119           Tgoto decodes a cursor addressing string with the given parameters.
120
121           There are four arguments:
122
123           $cap
124             The name of the capability to be output.
125
126           $col
127             The first value to be substituted in the output string ( usually
128             the column in a cursor addressing capability )
129
130           $row
131             The second value to be substituted in the output string (usually
132             the row in cursor addressing capabilities)
133
134           $FH
135             An optional filehandle (or IO::Handle ) to which the output
136             string will be printed.
137
138           Substitutions are made with $col and $row in the output string with
139           the following sprintf() line formats:
140
141            %%   output `%'
142            %d   output value as in printf %d
143            %2   output value as in printf %2d
144            %3   output value as in printf %3d
145            %.   output value as in printf %c
146            %+x  add x to value, then do %.
147
148            %>xy if value > x then add y, no output
149            %r   reverse order of two parameters, no output
150            %i   increment by one, no output
151            %B   BCD (16*(value/10)) + (value%10), no output
152
153            %n   exclusive-or all parameters with 0140 (Datamedia 2500)
154            %D   Reverse coding (value - 2*(value%16)), no output (Delta Data)
155
156           The output string will be returned.
157
158       Trequire
159           Takes a list of capabilities as an argument and will croak if one
160           is not found.
161

EXAMPLES

163           use Term::Cap;
164
165           # Get terminal output speed
166           require POSIX;
167           my $termios = POSIX::Termios->new;
168           $termios->getattr;
169           my $ospeed = $termios->getospeed;
170
171           # Old-style ioctl code to get ospeed:
172           #     require 'ioctl.pl';
173           #     ioctl(TTY,$TIOCGETP,$sgtty);
174           #     ($ispeed,$ospeed) = unpack('cc',$sgtty);
175
176           # allocate and initialize a terminal structure
177           my $terminal = Term::Cap->Tgetent({ TERM => undef, OSPEED => $ospeed });
178
179           # require certain capabilities to be available
180           $terminal->Trequire(qw/ce ku kd/);
181
182           # Output Routines, if $FH is undefined these just return the string
183
184           # Tgoto does the % expansion stuff with the given args
185           $terminal->Tgoto('cm', $col, $row, $FH);
186
187           # Tputs doesn't do any % expansion.
188           $terminal->Tputs('dl', $count = 1, $FH);
189
191       Copyright 1995-2015 (c) perl5 porters.
192
193       This software is free software and can be modified and distributed
194       under the same terms as Perl itself.
195
196       Please see the file README in the Perl source distribution for details
197       of the Perl license.
198

AUTHOR

200       This module is part of the core Perl distribution and is also
201       maintained for CPAN by Jonathan Stowe <jns@gellyfish.co.uk>.
202
203       The code is hosted on Github: https://github.com/jonathanstowe/Term-Cap
204       please feel free to fork, submit patches etc, etc there.
205

SEE ALSO

207       termcap(5)
208
209
210
211perl v5.36.0                      2023-02-13                            Cap(3)
Impressum