tclreadline(n)tclreadline(n)NAMEtclreadline - gnu readline for the tcl scripting language
SYNOPSIS
::tclreadline::readline command [options]
DESCRIPTION
The tclreadline package makes the gnu readline available to the script‐
ing 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::read‐
line read command has to be called explicitly.
The advantage of tclreadline is that it uses the callback handler mech‐
anism 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 tclread‐
line should work with all common extensions like blt, itcl, itk, tix
....
COMMANDS
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 read‐
line's documentation.
The following list will give all commands, which are currently imple‐
mented in the shared lib (e.g. libtclreadline@TCLREADLINE_VERSION@.so).
Additional commands were introduced in a startup script tclreadline‐
Setup.tcl, which lives in the tclreadline installation directory.
(typically something like /usr/local/lib/tclreadline ..) These com‐
mands 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 spa‐
ces, each of the words will be completed consecutively when hit‐
ting <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 cus‐
tom 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 tclread‐
line::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 comple‐
tion, 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 com‐
pleter, or the custom completer returned an empty string. The
builtin completer is on by default. tclreadline::readline built‐
incompleter 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 his‐
toryfile 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 read‐
line's idea of the terminal settings using terminalName as the
terminal type. The form w/o argument might not work if tclread‐
line was compiled with an older version of libreadline.
::tclreadline::readline bell
Ring the terminal bell, obeying the setting of bell-style -- audi‐
ble or visible.
::tclreadline::text
Return the current input.
::tclreadline::readline update
Redraw the current input line.
::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] ]" 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.
VARIABLEStclreadline defines the following variables in the namespace ::tclread‐
line: (for backwards compatiblity the global variables tclreadline_ver‐
sion,
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 "2.1.0".
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.
FILES
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 nor‐
mally 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 .inpu‐
trc:
$if tclreadline
"\C-xp": "puts $env(PATH)"
$endif
For further documentation please refer to the gnu readline documenta‐
tion.
BUGS
citing the readline manual: It's too big and too slow.
SEE ALSO
The official tclreadline web site at:
http://www.zellner.org/tclreadline/
AUTHOR
Johannes Zellner, <johannes@zellner.org>
CONTRIBUTIONS, SUGGESTIONS AND PATCHES
Magnus Eriksson <magnus.eriksson@netinsight.se>, Les Johnson <les@info‐
labs.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>
DEBIAN PACKAGE
David Engel <dlengel@home.com>, <david@debian.org>
DISCLAIMERtclreadline comes with a BSD type license. The read-only variable
tclreadline::license holds the complete license statement.
Johannes Zellner 2.1.0 tclreadline(n)
