mingw/html/lib/Term/Cap.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Term::Cap - Perl termcap interface</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Term::Cap - Perl termcap interface</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <ul>
  26
  27                 <li><a href="#methods">METHODS</a></li>
  28         </ul>
  29
  30         <li><a href="#examples">EXAMPLES</a></li>
  31         <li><a href="#copyright_and_license">COPYRIGHT AND LICENSE</a></li>
  32         <li><a href="#author">AUTHOR</a></li>
  33         <li><a href="#see_also">SEE ALSO</a></li>
  34 </ul>
  35 <!-- INDEX END -->
  36
  37 <hr />
  38 <p>
  39 </p>
  40 <h1><a name="name">NAME</a></h1>
  41 <p>Term::Cap - Perl termcap interface</p>
  42 <p>
  43 </p>
  44 <hr />
  45 <h1><a name="synopsis">SYNOPSIS</a></h1>
  46 <pre>
  47     require Term::Cap;
  48     $terminal = Tgetent Term::Cap { TERM =&gt; undef, OSPEED =&gt; $ospeed };
  49     $terminal-&gt;Trequire(qw/ce ku kd/);
  50     $terminal-&gt;Tgoto('cm', $col, $row, $FH);
  51     $terminal-&gt;Tputs('dl', $count, $FH);
  52     $terminal-&gt;Tpad($string, $count, $FH);</pre>
  53 <p>
  54 </p>
  55 <hr />
  56 <h1><a name="description">DESCRIPTION</a></h1>
  57 <p>These are low-level functions to extract and use capabilities from
  58 a terminal capability (termcap) database.</p>
  59 <p>More information on the terminal capabilities will be found in the
  60 termcap manpage on most Unix-like systems.</p>
  61 <p>
  62 </p>
  63 <h2><a name="methods">METHODS</a></h2>
  64 <p>The output strings for <strong>Tputs</strong> are cached for counts of 1 for performance.
  65 <strong>Tgoto</strong> and <strong>Tpad</strong> do not cache.  <code>$self-&gt;{_xx}</code> is the raw termcap
  66 data and <code>$self-&gt;{xx}</code> is the cached version.</p>
  67 <pre>
  68     print $terminal-&gt;Tpad($self-&gt;{_xx}, 1);</pre>
  69 <p><strong>Tgoto</strong>, <strong>Tputs</strong>, and <strong>Tpad</strong> return the string and will also
  70 output the string to $FH if specified.</p>
  71 <dl>
  72 <dt><strong><a name="item_tgetent"><strong>Tgetent</strong></a></strong>
  73
  74 <dd>
  75 <p>Returns a blessed object reference which the user can
  76 then use to send the control strings to the terminal using <strong>Tputs</strong>
  77 and <strong>Tgoto</strong>.</p>
  78 </dd>
  79 <dd>
  80 <p>The function extracts the entry of the specified terminal
  81 type <em>TERM</em> (defaults to the environment variable <em>TERM</em>) from the
  82 database.</p>
  83 </dd>
  84 <dd>
  85 <p>It will look in the environment for a <em>TERMCAP</em> variable.  If
  86 found, and the value does not begin with a slash, and the terminal
  87 type name is the same as the environment string <em>TERM</em>, the
  88 <em>TERMCAP</em> string is used instead of reading a termcap file.  If
  89 it does begin with a slash, the string is used as a path name of
  90 the termcap file to search.  If <em>TERMCAP</em> does not begin with a
  91 slash and name is different from <em>TERM</em>, <strong>Tgetent</strong> searches the
  92 files <em>$HOME/.termcap</em>, <em>/etc/termcap</em>, and <em>/usr/share/misc/termcap</em>,
  93 in that order, unless the environment variable <em>TERMPATH</em> exists,
  94 in which case it specifies a list of file pathnames (separated by
  95 spaces or colons) to be searched <strong>instead</strong>.  Whenever multiple
  96 files are searched and a tc field occurs in the requested entry,
  97 the entry it names must be found in the same file or one of the
  98 succeeding files.  If there is a <code>:tc=...:</code> in the <em>TERMCAP</em>
  99 environment variable string it will continue the search in the
 100 files as above.</p>
 101 </dd>
 102 <dd>
 103 <p>The extracted termcap entry is available in the object
 104 as <code>$self-&gt;{TERMCAP}</code>.</p>
 105 </dd>
 106 <dd>
 107 <p>It takes a hash reference as an argument with two optional keys:</p>
 108 </dd>
 109 <dl>
 110 <dt><strong><a name="item_ospeed">OSPEED</a></strong>
 111
 112 <dd>
 113 <p>The terminal output bit rate (often mistakenly called the baud rate)
 114 for this terminal - if not set a warning will be generated
 115 and it will be defaulted to 9600.  <em>OSPEED</em> can be be specified as
 116 either a POSIX termios/SYSV termio speeds (where 9600 equals 9600) or
 117 an old DSD-style speed ( where 13 equals 9600).</p>
 118 </dd>
 119 </li>
 120 <dt><strong><a name="item_term">TERM</a></strong>
 121
 122 <dd>
 123 <p>The terminal type whose termcap entry will be used - if not supplied it will
 124 default to $ENV{TERM}: if that is not set then <strong>Tgetent</strong> will croak.</p>
 125 </dd>
 126 </li>
 127 </dl>
 128 <p>It calls <code>croak</code> on failure.</p>
 129 <dt><strong><a name="item_tpad"><strong>Tpad</strong></a></strong>
 130
 131 <dd>
 132 <p>Outputs a literal string with appropriate padding for the current terminal.</p>
 133 </dd>
 134 <dd>
 135 <p>It takes three arguments:</p>
 136 </dd>
 137 <dl>
 138 <dt><strong><a name="item__string"><strong>$string</strong></a></strong>
 139
 140 <dd>
 141 <p>The literal string to be output.  If it starts with a number and an optional
 142 '*' then the padding will be increased by an amount relative to this number,
 143 if the '*' is present then this amount will me multiplied by $cnt.  This part
 144 of $string is removed before output/</p>
 145 </dd>
 146 </li>
 147 <dt><strong><a name="item__cnt"><strong>$cnt</strong></a></strong>
 148
 149 <dd>
 150 <p>Will be used to modify the padding applied to string as described above.</p>
 151 </dd>
 152 </li>
 153 <dt><strong><a name="item__fh"><strong>$FH</strong></a></strong>
 154
 155 <dd>
 156 <p>An optional filehandle (or IO::Handle ) that output will be printed to.</p>
 157 </dd>
 158 </li>
 159 </dl>
 160 <p>The padded $string is returned.</p>
 161 <dt><strong><a name="item_tputs"><strong>Tputs</strong></a></strong>
 162
 163 <dd>
 164 <p>Output the string for the given capability padded as appropriate without
 165 any parameter substitution.</p>
 166 </dd>
 167 <dd>
 168 <p>It takes three arguments:</p>
 169 </dd>
 170 <dl>
 171 <dt><strong><a name="item__cap"><strong>$cap</strong></a></strong>
 172
 173 <dd>
 174 <p>The capability whose string is to be output.</p>
 175 </dd>
 176 </li>
 177 <dt><strong><strong>$cnt</strong></strong>
 178
 179 <dd>
 180 <p>A count passed to Tpad to modify the padding applied to the output string.
 181 If $cnt is zero or one then the resulting string will be cached.</p>
 182 </dd>
 183 </li>
 184 <dt><strong><strong>$FH</strong></strong>
 185
 186 <dd>
 187 <p>An optional filehandle (or IO::Handle ) that output will be printed to.</p>
 188 </dd>
 189 </li>
 190 </dl>
 191 <p>The appropriate string for the capability will be returned.</p>
 192 <dt><strong><a name="item_tgoto"><strong>Tgoto</strong></a></strong>
 193
 194 <dd>
 195 <p><strong>Tgoto</strong> decodes a cursor addressing string with the given parameters.</p>
 196 </dd>
 197 <dd>
 198 <p>There are four arguments:</p>
 199 </dd>
 200 <dl>
 201 <dt><strong><strong>$cap</strong></strong>
 202
 203 <dd>
 204 <p>The name of the capability to be output.</p>
 205 </dd>
 206 </li>
 207 <dt><strong><a name="item__col"><strong>$col</strong></a></strong>
 208
 209 <dd>
 210 <p>The first value to be substituted in the output string ( usually the column
 211 in a cursor addressing capability )</p>
 212 </dd>
 213 </li>
 214 <dt><strong><a name="item__row"><strong>$row</strong></a></strong>
 215
 216 <dd>
 217 <p>The second value to be substituted in the output string (usually the row
 218 in cursor addressing capabilities)</p>
 219 </dd>
 220 </li>
 221 <dt><strong><strong>$FH</strong></strong>
 222
 223 <dd>
 224 <p>An optional filehandle (or IO::Handle ) to which the output string will be
 225 printed.</p>
 226 </dd>
 227 </li>
 228 </dl>
 229 <p>Substitutions are made with $col and $row in the output string with the
 230 following <code>sprintf()</code> line formats:</p>
 231 <pre>
 232  %%   output `%'
 233  %d   output value as in printf %d
 234  %2   output value as in printf %2d
 235  %3   output value as in printf %3d
 236  %.   output value as in printf %c
 237  %+x  add x to value, then do %.</pre>
 238 <pre>
 239  %&gt;xy if value &gt; x then add y, no output
 240  %r   reverse order of two parameters, no output
 241  %i   increment by one, no output
 242  %B   BCD (16*(value/10)) + (value%10), no output</pre>
 243 <pre>
 244  %n   exclusive-or all parameters with 0140 (Datamedia 2500)
 245  %D   Reverse coding (value - 2*(value%16)), no output (Delta Data)</pre>
 246 <p>The output string will be returned.</p>
 247 <dt><strong><a name="item_trequire"><strong>Trequire</strong></a></strong>
 248
 249 <dd>
 250 <p>Takes a list of capabilities as an argument and will croak if one is not
 251 found.</p>
 252 </dd>
 253 </li>
 254 </dl>
 255 <p>
 256 </p>
 257 <hr />
 258 <h1><a name="examples">EXAMPLES</a></h1>
 259 <pre>
 260     use Term::Cap;</pre>
 261 <pre>
 262     # Get terminal output speed
 263     require POSIX;
 264     my $termios = new POSIX::Termios;
 265     $termios-&gt;getattr;
 266     my $ospeed = $termios-&gt;getospeed;</pre>
 267 <pre>
 268     # Old-style ioctl code to get ospeed:
 269     #     require 'ioctl.pl';
 270     #     ioctl(TTY,$TIOCGETP,$sgtty);
 271     #     ($ispeed,$ospeed) = unpack('cc',$sgtty);</pre>
 272 <pre>
 273     # allocate and initialize a terminal structure
 274     $terminal = Tgetent Term::Cap { TERM =&gt; undef, OSPEED =&gt; $ospeed };</pre>
 275 <pre>
 276     # require certain capabilities to be available
 277     $terminal-&gt;Trequire(qw/ce ku kd/);</pre>
 278 <pre>
 279     # Output Routines, if $FH is undefined these just return the string</pre>
 280 <pre>
 281     # Tgoto does the % expansion stuff with the given args
 282     $terminal-&gt;Tgoto('cm', $col, $row, $FH);</pre>
 283 <pre>
 284     # Tputs doesn't do any % expansion.
 285     $terminal-&gt;Tputs('dl', $count = 1, $FH);</pre>
 286 <p>
 287 </p>
 288 <hr />
 289 <h1><a name="copyright_and_license">COPYRIGHT AND LICENSE</a></h1>
 290 <p>Please see the README file in distribution.</p>
 291 <p>
 292 </p>
 293 <hr />
 294 <h1><a name="author">AUTHOR</a></h1>
 295 <p>This module is part of the core Perl distribution and is also maintained
 296 for CPAN by Jonathan Stowe &lt;<a href="mailto:jns@gellyfish.com">jns@gellyfish.com</a>&gt;.</p>
 297 <p>
 298 </p>
 299 <hr />
 300 <h1><a name="see_also">SEE ALSO</a></h1>
 301 <p><code>termcap(5)</code></p>
 302 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 303 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 304 <big><strong><span class="block">&nbsp;Term::Cap - Perl termcap interface</span></strong></big>
 305 </td></tr>
 306 </table>
 307
 308 </body>
 309
 310 </html>