File: tclreadline.n.html

package info (click to toggle)
tclreadline 1.0.3-1
links: PTS
area: main
in suites: potato
size: 468 kB
ctags: 308
sloc: tcl: 5,926; sh: 1,544; ansic: 585; makefile: 184
file content (590 lines) | stat: -rw-r--r-- 14,834 bytes
<!-- manual page source format generated by PolyglotMan v3.0.7, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->

<HTML>
<HEAD>
<TITLE>tclreadline(n) manual page</TITLE>
</HEAD>
<BODY bgcolor=white>
<A HREF="#toc">Table of Contents</A><P>
 
<!--
 
  
-->
                          
<!--
 
  
  
-->
   
<!--
 
  
-->
 
<H2><A NAME="sect0" HREF="#toc0">Name </A></H2>
tclreadline - gnu readline 
for the tcl scripting language  
<!--
 
  
-->
 
<H2><A NAME="sect1" HREF="#toc1">Synopsis </A></H2>

<DL>

<DT><B>::tclreadline::readline </B> 
<I>command </I> [<I>options </I>]  </DT>
<DD> 
<!--
 
  
  
-->
</DD>
</DL>
 
<H2><A NAME="sect2" HREF="#toc2">Description </A></H2>
 
<!--
 
  
-->
The <B>tclreadline </B> package makes 
the gnu readline available to the scripting language tcl. The primary purpose 
of the package is to facilitate the interactive script development by 
the means of word and file name completion as well as history expansion 
(well known from shells like bash).  
<!--
 
  
-->
Additionally tclreadline can also 
be used for tcl scripts which want to use a shell like input interface. 
In this case the <B>::tclreadline::readline read </B> command has to be called 
explicitly.  
<!--
 
  
-->
<P>
 
<!--
 
  
-->
The advantage of <B>tclreadline </B> is that it uses the callback 
handler mechanism of the gnu readline while it processes tcl events. This 
way X events from a wish gui will processed as well as events from the 
 tclreadline  line interface.  
<!--
 
  
-->
<P>
 
<!--
 
  
-->
<B>tclreadline </B> is basically a shared 
library and a few tcl scripts which are accessed with the tcl package 
require command. Therefore <B>tclreadline </B> should work with all common extensions 
like <B>blt, itcl, itk, tix ... </B>.  
<!--
 
  
  
-->
  
<!--
 
  
  
-->
 
<H2><A NAME="sect3" HREF="#toc3">Commands </A></H2>
 
<!--
 
  
-->
If you want to use 
<B>tclreadline </B> as a line interface for developing tcl scripts, you probably 
don't have to read this section. In this case the only thing you should 
do is to modify your .tclshrc according to the section <B>FILES </B>.  
<!--
 
  
-->
For the 
functionality of the GNU readline you should refer to the readline's documentation. 
 
<!--
 
  
-->
<P>
The following list will give all commands, which are currently implemented 
in the shared lib (e.g. libtclreadline1.0.so). Additional commands were introduced 
in a startup script <B>tclreadlineSetup.tcl </B>, which lives in the tclreadline 
installation directory. (typically something like /usr/local/lib/tclreadline 
..) These commands are primarily for internal use and not documented here. 
 
<!--
 
  
-->
Note that all commands reside in the namespace <B>::tclreadline:: </B>.  
<!--
 

  
  
-->

<DL>

<DT><B>::tclreadline::readline add </B> <I>string </I>  </DT>
<DD>adds a string to the completer. 
If the string contains white spaces, each of the words will be completed 
consecutively when hitting &lt;Tab&gt;. Example:  
<!--
 
  
-->
    ::tclreadline::readline 
add "button pathName ?options?"  
<!--
 
  
-->
typing but&lt;Tab&gt; will complete to button. 
Hitting &lt;Tab&gt; again will complete to "button pathName".  ...  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::readline 
complete </B> <I>string </I>  </DT>
<DD>returns 1 if <I>string </I> is a complete tcl command and 
0 otherwise.  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::readline customcompleter </B> [<I>string </I>]  </DT>
<DD>Register 
the proc <I>string </I> as custom completer. This proc is called with exactly 
four arguments each time completion takes place: the word to complete 
("text"), the "start" and "end" positions of this word in the line entered 
so far, and this line ("line"). The custom completion script should return 
an array of strings which is a list of completions for "text".  If there 
are no completions, it should return an empty string "".  The first entry 
in the returned list is the substitution for "text". The remaining entries 
are the possible completions. If the custom completion script returns an 
empty string and builtin completion is enabled (see <B>tclreadline::readline 
builtincompleter </B>), the builtin completer is called. <B>tclreadline::readline 
customcompleter </B> simply returns the current custom completer if called 
w/o <I>string </I>. To turn of custom completion, call <B>tclreadline::readline customcompleter 
</B> with an empty <I>string </I>.  
<!--
 
  
-->
Example: <B>% puts $b&lt;TAB&gt; </B> will call the custom 
completer with the four arguments <I>"$b" </I>, <I>"5" </I>, <I>"8" </I> and <I>"puts $b" </I>. The 
custom completer could return a string like "$bl $black $blue", which 
will complete "$b" to "$bl" (the longest match) and offer a list of two 
further matches "$black" and "$blue".  
<!--
 
  
-->
For further reference, see the 
proc tclreadline::ScriptCompleter in the file tclreadlineSetup.tcl.  
<!--
 
  

-->
</DD>

<DT><B>::tclreadline::readline builtincompleter </B> [<I>bool </I>]  </DT>
<DD>enable or disable the 
builtin completer. If the builtin completer is enabled, it will be invoked 
either if there is no custom completer, or the custom completer returned 
an empty  string. The builtin completer is on by default. <B>tclreadline::readline 
builtincompleter </B> returns the current custom completer (also, if called 
w/o the <I>bool </I> argument).  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::readline eofchar </B> [<I>script </I>] 
 </DT>
<DD>set a script which will be called, if readline returns the eof character 
(this is typically the case if CTRL-D is entered at the very beginning 
of the line). The default for this script is "puts {}; exit". Setting this 
to an empty value disables any action on eof. <B>tclreadline::readline eof 
</B> returns the current eof script.  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::readline initialize 
</B> <I>historyfile </I>  </DT>
<DD>initialize the tclreadline interface and read the history 
from the <I>historyfile </I>. On succes an empty string is returned. This command 
has to be called before any other tclreadline commands.  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::readline 
read </B> <I>prompt </I>  </DT>
<DD>prints the <I>prompt </I> to stdout and enters the tclreadline 
event loop. Both readline and X events are processed. Returns the (eventually 
history-expanded) input string. <B>tclreadline::readline read </B> rises an error, 
if an error occurs while evaluating a script completer.  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::readline 
write </B> <I>historyfile </I>  </DT>
<DD>writes the history to the <I>historyfile </I>. This command 
is called automatically from the internal routine ::tclreadline::Exit. 
If the variable <B>tclreadline::historyLength </B> is non-negative, the historyfile 
will be truncated to hold only this number lines.  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::readline 
reset-terminal </B> [<I>terminalName </I>]  </DT>
<DD>w/o argument: reset the state of the terminal 
to what it was before tclreadline was used. With argument: reinitialize 
readline's idea of the terminal settings using terminalName as the terminal 
type. The form w/o argument might not work if tclreadline was compiled 
with an older version of libreadline.  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::readline bell 
</B>  </DT>
<DD>Ring the terminal bell, obeying the setting of bell-style -- audible or 
visible.  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::Print </B> [<I>yes / no </I>]  </DT>
<DD>turns on or off the default 
behavior of tclsh to print the result of every command. This is turned 
on by default, so it will just behave as the tclsh w/o tclreadline. Turning 
off might be useful, when reading binary data for example. If <B>::tclreadline::Print 
</B> is called w/o arguments, it returns the current setting.  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::Loop 
</B> [<I>historyfile </I>]  </DT>
<DD>enter the tclreadline main loop. This command is typically 
called from the startup resource file (something .tclshrc, depending on 
the interpreter you use, see the file `sample.tclshrc'). The main loop sets 
up some completion characteristics as variable -- try something like "puts 
$b&lt;TAB&gt;" --  and command completion -- try "puts [in&lt;TAB&gt;". If the optional argument 
<I>historyfile </I> is given, this file will be used for reading and writing 
the command history instead of the default <B>.tclsh-history </B>. <B>::tclreadline::Loop 
</B> will normally not return.  If you want to write your own main loop and/or 
own custom completers, it is probably a good idea to start with tclreadline::Loop 
(see the file tclreadlineSetup.tcl).  
<!--
 
  
-->
</DD>

<DT><B>::tclreadline::prompt1 </B>  </DT>
<DD>a proc 
which is called by ::tclreadline::Loop and returns a string which will 
be displayed as the primary prompt. This prompt will be something like 
"[info nameofexecutable] [[pwd]]" possibly fancy colored. The default proc 
is defined on entering the ::tclreadline::Loop, if it is not already defined. 
So: If you define your own proc ::tclreadline::prompt1 before entering 
::tclreadline::Loop, this proc is called each time the prompt is to be 
displayed. Example:  <blockquote> <BR>
 <PRE>     package require tclreadline 
     namespace eval tclreadline { 
         proc prompt1 {} { 
             return "[clock format [clock seconds]]&gt; " 
         } 
     } 
     ::tclreadline::Loop 
  </PRE></DD>
</DL>
 </blockquote>
  
<!--
 
  
-->
Note that non-printable control characters as color control characters 
must be enclosed in literal ctrl-a / ctrl-b to tell readline the length 
of the printable prompt. See for example the variable `prompt_string' in 
the file tclreadlineSetup.tcl in your tclreadline installation directory. 
 
<!--
 
  
  
-->
  
<!--
 
  
  
-->
  
<!--
 
  
-->
 
<H2><A NAME="sect4" HREF="#toc4">Variables </A></H2>
 
<!--
 
  
-->
<I>tclreadline </I> defines the following variables 
in the namespace <I>::tclreadline </I>: (for backwards compatiblity the global 
variables tclreadline_version,  tclreadline_patchLevel and tclreadline_library 
are still present).  
<!--
 
  
-->

<DL>

<DT><B>tclreadline::version </B>  </DT>
<DD>holds the version string 
"1.0".  
<!--
 
  
-->
</DD>

<DT><B>tclreadline::patchLevel </B>  </DT>
<DD>holds the patch level string "1.0.3". 
 
<!--
 
  
-->
</DD>

<DT><B>tclreadline::library </B>  </DT>
<DD>holds the library string "/usr/local/lib/tclreadline1.0". 
 
<!--
 
  
-->
</DD>

<DT><B>tclreadline::historyLength </B>  </DT>
<DD>Number of lines, which will be written 
to the historyfile. This number is -1 by default, which means that the historyfile 
will not be truncated.  See also <B>tclreadline::write </B>.  
<!--
 
  
-->
</DD>
</DL>
 
<H2><A NAME="sect5" HREF="#toc5">Files </A></H2>
 
<!--
 
  
-->
the 
<B>.tclshrc </B> file in the HOME directory, which is read on tclsh startup. Alternatively, 
the name of this initialization file might be <B>.wishrc </B> ... depending on what 
interpreter you use. These files should typically contain something like 
 <blockquote> <BR>
 <PRE>     if {$tcl_interactive} { 
         package require tclreadline 
         ::tclreadline::Loop 
     } 
  </PRE> </blockquote>
  
<!--
 
  
-->
which will enter the tclreadline main loop.  
<!--
 
  
-->
<P>
the <B>.tclsh-history 
</B> file in the HOME directory. On startup commands will be read from this 
file. On exit, the readline history is written to this file. Note that if 
you abort tclsh with &lt;cntrl-c&gt; no history is written. For the future it is 
planned to set up a signal handler, which will write the history on &lt;ctrl-c&gt; 
before exiting.  
<!--
 
  
-->
<P>
the <B>.inputrc </B> file in the users HOME directory. This 
file is used normally for all programs which use the gnu readline (e.g. 
 bash). The `global' readline settings there will be valid also for <B>tclreadline 
</B>. Additionally the .inputrc might hold conditional settings for the implementation 
name <B>tclreadline </B>. Example of  some lines in your .inputrc:  <blockquote> <BR>
 <PRE>     $if tclreadline 
     "\C-xp": "puts $env(PATH)" 
     $endif 
  </PRE> </blockquote>
  
<!--
 
  
-->
For further documentation please refer to the gnu readline documentation. 
 
<!--
 
  
-->
 
<H2><A NAME="sect6" HREF="#toc6">Bugs </A></H2>
citing the readline manual:  It's too big and too slow.  
<!--
 
  
  

-->
 
<H2><A NAME="sect7" HREF="#toc7">See Also </A></H2>
 
<!--
 
  
  
-->
<P>
The official <B>tclreadline </B> web site at:  
<!--
 
  
-->
<P>
 <blockquote><A HREF="http://www.zellner.org/tclreadline/">http://www.zellner.org/tclreadline/</A>
 
 </blockquote>
 
<!--
 
  
  
-->
 
<H2><A NAME="sect8" HREF="#toc8">Author </A></H2>
Johannes Zellner, &lt;johannes@zellner.org&gt;  
<!--
 
  
-->
 
<H2><A NAME="sect9" HREF="#toc9">Contributions, 
Suggestions and Patches </A></H2>
Magnus Eriksson &lt;magnus.eriksson@netinsight.se&gt;, Les 
Johnson &lt;les@infolabs.com&gt;, Harald Kirsch &lt;kir@iitb.fhg.de&gt;, Christian Krone 
&lt;krischan@sql.de&gt;, Larry W. Virden &lt;lvirden@cas.org&gt;, David Engel &lt;dlengel@home.com&gt; 
&lt;david@debian.org&gt;, Matthew Clarke &lt;Matthew_Clarke@mindlink.bc.ca&gt;  
<!--
 
  
-->
 
<H2><A NAME="sect10" HREF="#toc10">Debian 
Package </A></H2>
David Engel &lt;dlengel@home.com&gt;, &lt;david@debian.org&gt;  
<!--
 
  
-->
 
<H2><A NAME="sect11" HREF="#toc11">Disclaimer </A></H2>
 

<!--
 
  
-->
This version of <B>tclreadline </B> is still a development version. Pretty 
a lot of features and ideas are not implemented yet. The reason for this 
is the lack of time and manpower. So you are welcome to modify and contribute 
to the code. If you have suggestions, please let me know.  
<!--
 
  
-->
<B>tclreadline 
</B> comes with the GPL (GNU General Public License). You should have received 
a copy of the GNU General Public License along with this program; if not, 
write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, 
Boston, MA  02111-1307, USA. <P>

<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Commands</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Variables</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Files</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Bugs</A></LI>
<LI><A NAME="toc7" HREF="#sect7">See Also</A></LI>
<LI><A NAME="toc8" HREF="#sect8">Author</A></LI>
<LI><A NAME="toc9" HREF="#sect9">Contributions, Suggestions and Patches</A></LI>
<LI><A NAME="toc10" HREF="#sect10">Debian Package</A></LI>
<LI><A NAME="toc11" HREF="#sect11">Disclaimer</A></LI>
</UL>
</BODY></HTML>