Table of Contents
tclreadline - gnu readline for the tcl scripting
language
- ::tclreadline::readline command [options ]
-
The tclreadline 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
::tclreadline::readline read command has to be called explicitly.
The advantage of tclreadline 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.
tclreadline is basically a shared library and
a few tcl scripts which are accessed with the tcl package require command.
Therefore tclreadline should work with all common extensions like blt,
itcl, itk, tix ... .
If you want to use tclreadline
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 FILES .
For the functionality
of the GNU readline you should refer to the readline's documentation.
The following list will give all commands, which are currently implemented
in the shared lib (e.g. libtclreadline@TCLREADLINE_VERSION@.so). Additional
commands were introduced in a startup script tclreadlineSetup.tcl , 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
::tclreadline:: .
- ::tclreadline::readline add string
- adds a string
to the completer. If the string contains white spaces, each of the words
will be completed consecutively when hitting <Tab>. Example:
::tclreadline::readline
add "button pathName ?options?"
typing but<Tab> will complete to button.
Hitting <Tab> again will complete to "button pathName". ...
- ::tclreadline::readline
complete string
- returns 1 if string is a complete tcl command and
0 otherwise.
- ::tclreadline::readline customcompleter [string ]
- Register
the proc string 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 tclreadline::readline
builtincompleter ), the builtin completer is called. tclreadline::readline
customcompleter simply returns the current custom completer if called
w/o string . To turn of custom completion, call tclreadline::readline customcompleter
with an empty string .
Example: % puts $b<TAB> will call the custom
completer with the four arguments "$b" , "5" , "8" and "puts $b" . 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.
- ::tclreadline::readline builtincompleter [bool ]
- 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. tclreadline::readline
builtincompleter returns the current custom completer (also, if called
w/o the bool argument).
- ::tclreadline::readline eofchar [script ]
- 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. tclreadline::readline eof
returns the current eof script.
- ::tclreadline::readline initialize
historyfile
- initialize the tclreadline interface and read the history
from the historyfile . On succes an empty string is returned. This command
has to be called before any other tclreadline commands.
- ::tclreadline::readline
read prompt
- prints the prompt to stdout and enters the tclreadline
event loop. Both readline and X events are processed. Returns the (eventually
history-expanded) input string. tclreadline::readline read rises an error,
if an error occurs while evaluating a script completer.
- ::tclreadline::readline
write historyfile
- writes the history to the historyfile . This command
is called automatically from the internal routine ::tclreadline::Exit.
If the variable tclreadline::historyLength is non-negative, the historyfile
will be truncated to hold only this number lines.
- ::tclreadline::readline
reset-terminal [terminalName ]
- 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.
- ::tclreadline::readline bell
- Ring the terminal bell, obeying the setting of bell-style -- audible or
visible.
- ::tclreadline::Print [yes / no ]
- 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 ::tclreadline::Print
is called w/o arguments, it returns the current setting.
- ::tclreadline::Loop
[historyfile ]
- 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<TAB>" -- and command completion -- try "puts [in<TAB>". If the optional argument
historyfile is given, this file will be used for reading and writing
the command history instead of the default .tclsh-history . ::tclreadline::Loop
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).
- ::tclreadline::prompt1
- 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:
package require tclreadline
namespace eval tclreadline {
proc prompt1 {} {
return "[clock format [clock seconds]]> "
}
}
::tclreadline::Loop
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.
tclreadline defines the following variables
in the namespace ::tclreadline : (for backwards compatiblity the global
variables tclreadline_version, tclreadline_patchLevel and tclreadline_library
are still present).
- tclreadline::version (read-only)
- holds the version
string "@TCLREADLINE_VERSION@".
- tclreadline::patchLevel (read-only)
- holds the patch level string "@TCLREADLINE_VERSION@.@TCLREADLINE_PATCHLEVEL@".
- tclreadline::library (read-only)
- holds the library string "@TCLREADLINE_LIBRARY@".
- tclreadline::license (read-only)
- holds a BSD license statement.
- tclreadline::historyLength
- 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 tclreadline::write .
the
.tclshrc file in the HOME directory, which is read on tclsh startup. Alternatively,
the name of this initialization file might be .wishrc ... depending on what
interpreter you use. These files should typically contain something like
if {$tcl_interactive} {
package require tclreadline
::tclreadline::Loop
}
which will enter the tclreadline main loop.
the .tclsh-history
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 <cntrl-c> no history is written. For the future it is
planned to set up a signal handler, which will write the history on <ctrl-c>
before exiting.
the .inputrc 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 tclreadline
. Additionally the .inputrc might hold conditional settings for the implementation
name tclreadline . Example of some lines in your .inputrc:
$if tclreadline
"\C-xp": "puts $env(PATH)"
$endif
For further documentation please refer to the gnu readline documentation.
citing the readline manual: It's too big and too slow.
The official tclreadline web site at:
http://www.zellner.org/tclreadline/
Johannes Zellner, <johannes@zellner.org>
Magnus Eriksson <magnus.eriksson@netinsight.se>, Les
Johnson <les@infolabs.com>, Harald Kirsch <kir@iitb.fhg.de>, Christian Krone
<krischan@sql.de>, Larry W. Virden <lvirden@cas.org>, David Engel <dlengel@home.com>
<david@debian.org>, Matthew Clarke <Matthew_Clarke@mindlink.bc.ca>
David Engel <dlengel@home.com>, <david@debian.org>
tclreadline comes with a BSD type license. The read-only variable tclreadline::license
holds the complete license statement.
Table of Contents