NAME¶
tclreadline - gnu readline for the tcl scripting language
SYNOPSIS¶
- ::tclreadline::readline command [options]
-
DESCRIPTION¶
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 ....
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 readline's
documentation.
The following list will give all commands, which are currently implemented in
the shared lib (e.g. libtclreadline2.1.0.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 success 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::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] \[[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::prompt2
- a proc which is called by ::tclreadline::Loop and returns a string which
will be displayed as the secondary prompt when interactively prompting for
continuation of an incomplete command.
VARIABLES¶
tclreadline defines the following variables in the namespace
::tclreadline: (for backwards compatibility the global variables
tclreadline_version,
tclreadline_patchLevel and tclreadline_library are still present).
- tclreadline::version (read-only)
- holds the version string "2.1.0".
- tclreadline::patchLevel (read-only)
- holds the patch level string "2.1.0".
- tclreadline::library (read-only)
- holds the library directory string.
- 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 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.
BUGS¶
citing the readline manual: It's too big and too slow.
SEE ALSO¶
The official
tclreadline web site at:
AUTHOR¶
Johannes Zellner, <johannes@zellner.org>
CONTRIBUTIONS, SUGGESTIONS AND PATCHES¶
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>
DEBIAN PACKAGE¶
David Engel <dlengel@home.com>, <david@debian.org>
DISCLAIMER¶
tclreadline comes with a BSD type license. The read-only variable
tclreadline::license holds the complete license statement.