Provided by: tcl-tclreadline_2.1.0-12_amd64 
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 string "/usr/share/tcltk/tclreadline2.1.0".
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:
http://www.zellner.org/tclreadline/
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.