mingw/html/lib/Term/ReadLine.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::ReadLine - Perl interface to various C&lt;readline&gt; packages.
   6 If no real package is found, substitutes stubs instead of basic functions.</title>
   7 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   8 <link rev="made" href="mailto:" />
   9 </head>
  10
  11 <body style="background-color: white">
  12 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  13 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  14 <big><strong><span class="block">&nbsp;Term::ReadLine - Perl interface to various C&lt;readline&gt; packages.
  15 If no real package is found, substitutes stubs instead of basic functions.</span></strong></big>
  16 </td></tr>
  17 </table>
  18
  19 <p><a name="__index__"></a></p>
  20 <!-- INDEX BEGIN -->
  21
  22 <ul>
  23
  24         <li><a href="#name">NAME</a></li>
  25         <li><a href="#synopsis">SYNOPSIS</a></li>
  26         <li><a href="#description">DESCRIPTION</a></li>
  27         <li><a href="#minimal_set_of_supported_functions">Minimal set of supported functions</a></li>
  28         <li><a href="#additional_supported_functions">Additional supported functions</a></li>
  29         <li><a href="#exports">EXPORTS</a></li>
  30         <li><a href="#environment">ENVIRONMENT</a></li>
  31         <li><a href="#caveats">CAVEATS</a></li>
  32 </ul>
  33 <!-- INDEX END -->
  34
  35 <hr />
  36 <p>
  37 </p>
  38 <h1><a name="name">NAME</a></h1>
  39 <p>Term::ReadLine - Perl interface to various <a href="#item_readline"><code>readline</code></a> packages.
  40 If no real package is found, substitutes stubs instead of basic functions.</p>
  41 <p>
  42 </p>
  43 <hr />
  44 <h1><a name="synopsis">SYNOPSIS</a></h1>
  45 <pre>
  46   use Term::ReadLine;
  47   my $term = new Term::ReadLine 'Simple Perl calc';
  48   my $prompt = &quot;Enter your arithmetic expression: &quot;;
  49   my $OUT = $term-&gt;OUT || \*STDOUT;
  50   while ( defined ($_ = $term-&gt;readline($prompt)) ) {
  51     my $res = eval($_);
  52     warn $@ if $@;
  53     print $OUT $res, &quot;\n&quot; unless $@;
  54     $term-&gt;addhistory($_) if /\S/;
  55   }</pre>
  56 <p>
  57 </p>
  58 <hr />
  59 <h1><a name="description">DESCRIPTION</a></h1>
  60 <p>This package is just a front end to some other packages. It's a stub to
  61 set up a common interface to the various ReadLine implementations found on
  62 CPAN (under the <code>Term::ReadLine::*</code> namespace).</p>
  63 <p>
  64 </p>
  65 <hr />
  66 <h1><a name="minimal_set_of_supported_functions">Minimal set of supported functions</a></h1>
  67 <p>All the supported functions should be called as methods, i.e., either as</p>
  68 <pre>
  69   $term = new Term::ReadLine 'name';</pre>
  70 <p>or as</p>
  71 <pre>
  72   $term-&gt;addhistory('row');</pre>
  73 <p>where $term is a return value of Term::ReadLine-&gt;new().</p>
  74 <dl>
  75 <dt><strong><a name="item_readline"><code>ReadLine</code></a></strong>
  76
  77 <dd>
  78 <p>returns the actual package that executes the commands. Among possible
  79 values are <code>Term::ReadLine::Gnu</code>, <code>Term::ReadLine::Perl</code>,
  80 <code>Term::ReadLine::Stub</code>.</p>
  81 </dd>
  82 </li>
  83 <dt><strong><a name="item_new"><code>new</code></a></strong>
  84
  85 <dd>
  86 <p>returns the handle for subsequent calls to following
  87 functions. Argument is the name of the application. Optionally can be
  88 followed by two arguments for <code>IN</code> and <code>OUT</code> filehandles. These
  89 arguments should be globs.</p>
  90 </dd>
  91 </li>
  92 <dt><strong><a name="item_readline"><code>readline</code></a></strong>
  93
  94 <dd>
  95 <p>gets an input line, <em>possibly</em> with actual <a href="#item_readline"><code>readline</code></a>
  96 support. Trailing newline is removed. Returns <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> on <code>EOF</code>.</p>
  97 </dd>
  98 </li>
  99 <dt><strong><a name="item_addhistory"><code>addhistory</code></a></strong>
 100
 101 <dd>
 102 <p>adds the line to the history of input, from where it can be used if
 103 the actual <a href="#item_readline"><code>readline</code></a> is present.</p>
 104 </dd>
 105 </li>
 106 <dt><strong><a name="item_in_2c_out"><code>IN</code>, <code>OUT</code></a></strong>
 107
 108 <dd>
 109 <p>return the filehandles for input and output or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> if <a href="#item_readline"><code>readline</code></a>
 110 input and output cannot be used for Perl.</p>
 111 </dd>
 112 </li>
 113 <dt><strong><a name="item_minline"><code>MinLine</code></a></strong>
 114
 115 <dd>
 116 <p>If argument is specified, it is an advice on minimal size of line to
 117 be included into history.  <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> means do not include anything into
 118 history. Returns the old value.</p>
 119 </dd>
 120 </li>
 121 <dt><strong><a name="item_findconsole"><code>findConsole</code></a></strong>
 122
 123 <dd>
 124 <p>returns an array with two strings that give most appropriate names for
 125 files for input and output using conventions <code>&quot;&lt;$in&quot;</code>, <code>&quot;&gt;out&quot;</code>.</p>
 126 </dd>
 127 </li>
 128 <dt><strong><a name="item_attribs">Attribs</a></strong>
 129
 130 <dd>
 131 <p>returns a reference to a hash which describes internal configuration
 132 of the package. Names of keys in this hash conform to standard
 133 conventions with the leading <code>rl_</code> stripped.</p>
 134 </dd>
 135 </li>
 136 <dt><strong><a name="item_features"><code>Features</code></a></strong>
 137
 138 <dd>
 139 <p>Returns a reference to a hash with keys being features present in
 140 current implementation. Several optional features are used in the
 141 minimal interface: <code>appname</code> should be present if the first argument
 142 to <a href="#item_new"><code>new</code></a> is recognized, and <code>minline</code> should be present if
 143 <a href="#item_minline"><code>MinLine</code></a> method is not dummy.  <code>autohistory</code> should be present if
 144 lines are put into history automatically (maybe subject to
 145 <a href="#item_minline"><code>MinLine</code></a>), and <a href="#item_addhistory"><code>addhistory</code></a> if <a href="#item_addhistory"><code>addhistory</code></a> method is not dummy.</p>
 146 </dd>
 147 <dd>
 148 <p>If <a href="#item_features"><code>Features</code></a> method reports a feature <code>attribs</code> as present, the
 149 method <a href="#item_attribs"><code>Attribs</code></a> is not dummy.</p>
 150 </dd>
 151 </li>
 152 </dl>
 153 <p>
 154 </p>
 155 <hr />
 156 <h1><a name="additional_supported_functions">Additional supported functions</a></h1>
 157 <p>Actually <code>Term::ReadLine</code> can use some other package, that will
 158 support a richer set of commands.</p>
 159 <p>All these commands are callable via method interface and have names
 160 which conform to standard conventions with the leading <code>rl_</code> stripped.</p>
 161 <p>The stub package included with the perl distribution allows some
 162 additional methods:</p>
 163 <dl>
 164 <dt><strong><a name="item_tkrunning"><code>tkRunning</code></a></strong>
 165
 166 <dd>
 167 <p>makes Tk event loop run when waiting for user input (i.e., during
 168 <a href="#item_readline"><code>readline</code></a> method).</p>
 169 </dd>
 170 </li>
 171 <dt><strong><a name="item_ornaments"><code>ornaments</code></a></strong>
 172
 173 <dd>
 174 <p>makes the command line stand out by using termcap data.  The argument
 175 to <a href="#item_ornaments"><code>ornaments</code></a> should be 0, 1, or a string of a form
 176 <code>&quot;aa,bb,cc,dd&quot;</code>.  Four components of this string should be names of
 177 <em>terminal capacities</em>, first two will be issued to make the prompt
 178 standout, last two to make the input line standout.</p>
 179 </dd>
 180 </li>
 181 <dt><strong><a name="item_newtty"><code>newTTY</code></a></strong>
 182
 183 <dd>
 184 <p>takes two arguments which are input filehandle and output filehandle.
 185 Switches to use these filehandles.</p>
 186 </dd>
 187 </li>
 188 </dl>
 189 <p>One can check whether the currently loaded ReadLine package supports
 190 these methods by checking for corresponding <a href="#item_features"><code>Features</code></a>.</p>
 191 <p>
 192 </p>
 193 <hr />
 194 <h1><a name="exports">EXPORTS</a></h1>
 195 <p>None</p>
 196 <p>
 197 </p>
 198 <hr />
 199 <h1><a name="environment">ENVIRONMENT</a></h1>
 200 <p>The environment variable <code>PERL_RL</code> governs which ReadLine clone is
 201 loaded. If the value is false, a dummy interface is used. If the value
 202 is true, it should be tail of the name of the package to use, such as
 203 <code>Perl</code> or <code>Gnu</code>.</p>
 204 <p>As a special case, if the value of this variable is space-separated,
 205 the tail might be used to disable the ornaments by setting the tail to
 206 be <code>o=0</code> or <code>ornaments=0</code>.  The head should be as described above, say</p>
 207 <p>If the variable is not set, or if the head of space-separated list is
 208 empty, the best available package is loaded.</p>
 209 <pre>
 210   export &quot;PERL_RL=Perl o=0&quot;     # Use Perl ReadLine without ornaments
 211   export &quot;PERL_RL= o=0&quot;         # Use best available ReadLine without ornaments</pre>
 212 <p>(Note that processing of <code>PERL_RL</code> for ornaments is in the discretion of the
 213 particular used <code>Term::ReadLine::*</code> package).</p>
 214 <p>
 215 </p>
 216 <hr />
 217 <h1><a name="caveats">CAVEATS</a></h1>
 218 <p>It seems that using Term::ReadLine from Emacs minibuffer doesn't work
 219 quite right and one will get an error message like</p>
 220 <pre>
 221     Cannot open /dev/tty for read at ...</pre>
 222 <p>One possible workaround for this is to explicitly open /dev/tty like this</p>
 223 <pre>
 224     open (FH, &quot;/dev/tty&quot; )
 225       or eval 'sub Term::ReadLine::findConsole { (&quot;&amp;STDIN&quot;, &quot;&amp;STDERR&quot;) }';
 226     die $@ if $@;
 227     close (FH);</pre>
 228 <p>or you can try using the 4-argument form of Term::ReadLine-&gt;new().</p>
 229 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 230 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 231 <big><strong><span class="block">&nbsp;Term::ReadLine - Perl interface to various C&lt;readline&gt; packages.
 232 If no real package is found, substitutes stubs instead of basic functions.</span></strong></big>
 233 </td></tr>
 234 </table>
 235
 236 </body>
 237
 238 </html>