6 # Version undef: Thu Dec 14 20:02:42 CST 1995 by sanders@bsdi.com
7 # Version 1.00: Thu Nov 30 23:34:29 EST 2000 by schwern@pobox.com
8 # [PATCH] $VERSION crusade, strict, tests, etc... all over lib/
9 # Version 1.01: Wed May 23 00:00:00 CST 2001 by d-lewart@uiuc.edu
10 # Avoid warnings in Tgetent and Tputs
13 # support Berkeley DB termcaps
14 # should probably be a .xs module
15 # force $FH into callers package?
16 # keep $FH in object at Tgetent time?
20 Term::Cap - Perl termcap interface
25 $terminal = Tgetent Term::Cap { TERM => undef, OSPEED => $ospeed };
26 $terminal->Trequire(qw/ce ku kd/);
27 $terminal->Tgoto('cm', $col, $row, $FH);
28 $terminal->Tputs('dl', $count, $FH);
29 $terminal->Tpad($string, $count, $FH);
33 These are low-level functions to extract and use capabilities from
34 a terminal capability (termcap) database.
36 The B<Tgetent> function extracts the entry of the specified terminal
37 type I<TERM> (defaults to the environment variable I<TERM>) from the
40 It will look in the environment for a I<TERMCAP> variable. If
41 found, and the value does not begin with a slash, and the terminal
42 type name is the same as the environment string I<TERM>, the
43 I<TERMCAP> string is used instead of reading a termcap file. If
44 it does begin with a slash, the string is used as a path name of
45 the termcap file to search. If I<TERMCAP> does not begin with a
46 slash and name is different from I<TERM>, B<Tgetent> searches the
47 files F<$HOME/.termcap>, F</etc/termcap>, and F</usr/share/misc/termcap>,
48 in that order, unless the environment variable I<TERMPATH> exists,
49 in which case it specifies a list of file pathnames (separated by
50 spaces or colons) to be searched B<instead>. Whenever multiple
51 files are searched and a tc field occurs in the requested entry,
52 the entry it names must be found in the same file or one of the
53 succeeding files. If there is a C<:tc=...:> in the I<TERMCAP>
54 environment variable string it will continue the search in the
57 I<OSPEED> is the terminal output bit rate (often mistakenly called
58 the baud rate). I<OSPEED> can be specified as either a POSIX
59 termios/SYSV termio speeds (where 9600 equals 9600) or an old
60 BSD-style speeds (where 13 equals 9600).
62 B<Tgetent> returns a blessed object reference which the user can
63 then use to send the control strings to the terminal using B<Tputs>
64 and B<Tgoto>. It calls C<croak> on failure.
66 B<Tgoto> decodes a cursor addressing string with the given parameters.
68 The output strings for B<Tputs> are cached for counts of 1 for performance.
69 B<Tgoto> and B<Tpad> do not cache. C<$self-E<gt>{_xx}> is the raw termcap
70 data and C<$self-E<gt>{xx}> is the cached version.
72 print $terminal->Tpad($self->{_xx}, 1);
74 B<Tgoto>, B<Tputs>, and B<Tpad> return the string and will also
75 output the string to $FH if specified.
77 The extracted termcap entry is available in the object
78 as C<$self-E<gt>{TERMCAP}>.
82 # Get terminal output speed
84 my $termios = new POSIX::Termios;
86 my $ospeed = $termios->getospeed;
88 # Old-style ioctl code to get ospeed:
90 # ioctl(TTY,$TIOCGETP,$sgtty);
91 # ($ispeed,$ospeed) = unpack('cc',$sgtty);
93 # allocate and initialize a terminal structure
94 $terminal = Tgetent Term::Cap { TERM => undef, OSPEED => $ospeed };
96 # require certain capabilities to be available
97 $terminal->Trequire(qw/ce ku kd/);
99 # Output Routines, if $FH is undefined these just return the string
101 # Tgoto does the % expansion stuff with the given args
102 $terminal->Tgoto('cm', $col, $row, $FH);
104 # Tputs doesn't do any % expansion.
105 $terminal->Tputs('dl', $count = 1, $FH);
109 # Returns a list of termcap files to check.
110 sub termcap_path { ## private
112 # $TERMCAP, if it's a filespec
113 push(@termcap_path, $ENV{TERMCAP})
114 if ((exists $ENV{TERMCAP}) &&
115 (($^O eq 'os2' || $^O eq 'MSWin32' || $^O eq 'dos')
116 ? $ENV{TERMCAP} =~ /^[a-z]:[\\\/]/is
117 : $ENV{TERMCAP} =~ /^\//s));
118 if ((exists $ENV{TERMPATH}) && ($ENV{TERMPATH})) {
119 # Add the users $TERMPATH
120 push(@termcap_path, split(/(:|\s+)/, $ENV{TERMPATH}))
125 $ENV{'HOME'} . '/.termcap',
127 '/usr/share/misc/termcap',
130 # return the list of those termcaps that exist
131 grep(-f, @termcap_path);
134 sub Tgetent { ## public -- static method
136 my $self = bless shift, $class;
137 my($term,$cap,$search,$field,$max,$tmp_term,$TERMCAP);
138 local($termpat,$state,$first,$entry); # used inside eval
141 # Compute PADDING factor from OSPEED (to be used by Tpad)
142 if (! $self->{OSPEED}) {
143 carp "OSPEED was not set, defaulting to 9600";
144 $self->{OSPEED} = 9600;
146 if ($self->{OSPEED} < 16) {
147 # delays for old style speeds
148 my @pad = (0,200,133.3,90.9,74.3,66.7,50,33.3,16.7,8.3,5.5,4.1,2,1,.5,.2);
149 $self->{PADDING} = $pad[$self->{OSPEED}];
152 $self->{PADDING} = 10000 / $self->{OSPEED};
155 $self->{TERM} = ($self->{TERM} || $ENV{TERM} || croak "TERM not set");
156 $term = $self->{TERM}; # $term is the term type we are looking for
158 # $tmp_term is always the next term (possibly :tc=...:) we are looking for
159 $tmp_term = $self->{TERM};
160 # protect any pattern metacharacters in $tmp_term
161 $termpat = $tmp_term; $termpat =~ s/(\W)/\\$1/g;
163 my $foo = (exists $ENV{TERMCAP} ? $ENV{TERMCAP} : '');
165 # $entry is the extracted termcap entry
166 if (($foo !~ m:^/:s) && ($foo =~ m/(^|\|)${termpat}[:|]/s)) {
170 my @termcap_path = termcap_path;
172 unless (@termcap_path || $entry)
174 # last resort--fake up a termcap from terminfo
175 local $ENV{TERM} = $term;
177 $entry = `infocmp -C 2>/dev/null`;
183 croak "Can't find a valid termcap file" unless @termcap_path || $entry;
185 $state = 1; # 0 == finished
189 $first = 0; # first entry (keeps term name)
191 $max = 32; # max :tc=...:'s
194 # ok, we're starting with $TERMCAP
195 $first++; # we're the first entry
196 # do we need to continue?
197 if ($entry =~ s/:tc=([^:]+):/:/) {
199 # protect any pattern metacharacters in $tmp_term
200 $termpat = $tmp_term; $termpat =~ s/(\W)/\\$1/g;
203 $state = 0; # we're already finished
207 # This is eval'ed inside the while loop for each file
210 next if /^\\t/ || /^#/;
211 if ($_ =~ m/(^|\\|)${termpat}[:|]/o) {
213 s/^[^:]*:// if $first++;
215 while ($_ =~ s/\\\\$//) {
216 defined(my $x = <TERMCAP>) or last;
222 defined $entry or $entry = '';
226 while ($state != 0) {
228 # get the next TERMCAP
229 $TERMCAP = shift @termcap_path
230 || croak "failed termcap lookup on $tmp_term";
233 # do the same file again
234 # prevent endless recursion
235 $max-- || croak "failed termcap loop at $tmp_term";
236 $state = 1; # ok, maybe do a new file next time
239 open(TERMCAP,"< $TERMCAP\0") || croak "open $TERMCAP: $!";
244 # If :tc=...: found then search this file again
245 $entry =~ s/:tc=([^:]+):/:/ && ($tmp_term = $1, $state = 2);
246 # protect any pattern metacharacters in $tmp_term
247 $termpat = $tmp_term; $termpat =~ s/(\W)/\\$1/g;
250 croak "Can't find $term" if $entry eq '';
251 $entry =~ s/:+\s*:+/:/g; # cleanup $entry
252 $entry =~ s/:+/:/g; # cleanup $entry
253 $self->{TERMCAP} = $entry; # save it
254 # print STDERR "DEBUG: $entry = ", $entry, "\n";
256 # Precompile $entry into the object
257 $entry =~ s/^[^:]*://;
258 foreach $field (split(/:[\s:\\]*/,$entry)) {
259 if ($field =~ /^(\w\w)$/) {
260 $self->{'_' . $field} = 1 unless defined $self->{'_' . $1};
261 # print STDERR "DEBUG: flag $1\n";
263 elsif ($field =~ /^(\w\w)\@/) {
264 $self->{'_' . $1} = "";
265 # print STDERR "DEBUG: unset $1\n";
267 elsif ($field =~ /^(\w\w)#(.*)/) {
268 $self->{'_' . $1} = $2 unless defined $self->{'_' . $1};
269 # print STDERR "DEBUG: numeric $1 = $2\n";
271 elsif ($field =~ /^(\w\w)=(.*)/) {
272 # print STDERR "DEBUG: string $1 = $2\n";
273 next if defined $self->{'_' . ($cap = $1)};
276 s/\\(\d\d\d)/pack('c',oct($1) & 0177)/eg;
284 s/\^(.)/pack('c',ord($1) & 31)/eg;
287 $self->{'_' . $cap} = $_;
289 # else { carp "junk in $term ignored: $field"; }
291 $self->{'_pc'} = "\0" unless defined $self->{'_pc'};
292 $self->{'_bc'} = "\b" unless defined $self->{'_bc'};
296 # $terminal->Tpad($string, $cnt, $FH);
299 my($string, $cnt, $FH) = @_;
302 if (defined $string && $string =~ /(^[\d.]+)(\*?)(.*)$/) {
306 $decr = $self->{PADDING};
309 $string .= $self->{'_pc'} x ($ms / $decr);
312 print $FH $string if $FH;
316 # $terminal->Tputs($cap, $cnt, $FH);
317 sub Tputs { ## public
319 my($cap, $cnt, $FH) = @_;
323 $string = Tpad($self, $self->{'_' . $cap}, $cnt);
325 # cache result because Tpad can be slow
326 unless (exists $self->{$cap}) {
327 $self->{$cap} = exists $self->{"_$cap"} ?
328 Tpad($self, $self->{"_$cap"}, 1) : undef;
330 $string = $self->{$cap};
332 print $FH $string if $FH;
337 # %d output value as in printf %d
338 # %2 output value as in printf %2d
339 # %3 output value as in printf %3d
340 # %. output value as in printf %c
341 # %+x add x to value, then do %.
343 # %>xy if value > x then add y, no output
344 # %r reverse order of two parameters, no output
345 # %i increment by one, no output
346 # %B BCD (16*(value/10)) + (value%10), no output
348 # %n exclusive-or all parameters with 0140 (Datamedia 2500)
349 # %D Reverse coding (value - 2*(value%16)), no output (Delta Data)
351 # $terminal->Tgoto($cap, $col, $row, $FH);
352 sub Tgoto { ## public
354 my($cap, $code, $tmp, $FH) = @_;
355 my $string = $self->{'_' . $cap};
359 my @tmp = ($tmp,$code);
362 while ($string =~ /^([^%]*)%(.)(.*)/) {
367 $result .= sprintf("%d",shift(@tmp));
369 elsif ($code eq '.') {
371 if ($tmp == 0 || $tmp == 4 || $tmp == 10) {
373 ++$tmp, $after .= $self->{'_up'} if $self->{'_up'};
376 ++$tmp, $after .= $self->{'_bc'};
379 $result .= sprintf("%c",$tmp);
382 elsif ($code eq '+') {
383 $result .= sprintf("%c",shift(@tmp)+ord($string));
384 $string = substr($string,1,99);
387 elsif ($code eq 'r') {
392 elsif ($code eq '>') {
393 ($code,$tmp,$string) = unpack("CCa99",$string);
394 if ($tmp[$[] > $code) {
398 elsif ($code eq '2') {
399 $result .= sprintf("%02d",shift(@tmp));
402 elsif ($code eq '3') {
403 $result .= sprintf("%03d",shift(@tmp));
406 elsif ($code eq 'i') {
408 @tmp = ($code+1,$tmp+1);
414 $string = Tpad($self, $result . $string . $after, $cnt);
415 print $FH $string if $FH;
419 # $terminal->Trequire(qw/ce ku kd/);
420 sub Trequire { ## public
424 push(@undefined, $cap)
425 unless defined $self->{'_' . $cap} && $self->{'_' . $cap};
427 croak "Terminal does not support: (@undefined)" if @undefined;