The tclreadline package makes the GNU Readline library
available for interactive tcl shells. This includes history
expansion and file/command completion. Command completion for
all tcl/tk commands is provided and commmand completers for
user defined commands can be easily added.
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 consists basically of a shared library and a few tcl scripts
which are accessed with the tcl package require command. Therefore
tclreadline works together with all common extensions like
blt, itcl, itk, tix ....
Further information can be found in the README file
and the unix man page.
If you want to use tclreadline as a line interface
for developing tcl scripts, you probably don't have to read much of
the following section. Just install the package and put the following
lines to your $HOME/.tclshrc:
if {$tcl_interactive} {
package require tclreadline
::tclreadline::Loop
}
You can also customize the behaviour of tclreadline
before calling ::tclreadline::Loop, see
this example file.
The following list of commands 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
tclreadlineSetup.tcl, which lives in the tclreadline
installation directory.
(typically something like /usr/local/lib/tclreadline ..)
These commands are primarily for internal use and only partly
documented here.
- completion of commands and subcommands of all tcl/tk
commands
- completers for user defined commands can be added easily
- completion of variables
- completion of arrays and array names
- history expansion
- file and directory completion where no other rule applies
- commands are saved in a history file
Note that all commands are defined 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 write
historyfile
-
writes the history to the historyfile. This command is called
automatically from the internal routine ::tclreadline::Exit.
- ::tclreadline::Print yes / no
-
Turn on or off the normal behaviour of the tcl interpreter to
print the results of commands. By default this is turned on (`yes').
If ::tclreadline::Print is called w/o arguments, it returns
the current value. Turning off the command result printing is
especially useful when reading binary files in interactive mode.
This command is implemented in the startup file tclreadlineInit.tcl.
- ::tclreadline::Loop
-
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>".
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.
The most recent version can be accessed via anonymous cvs. This
is the preferred method. For further information look at
tclreadline's CVS
site which is hosted by
sourceforge.
From time to time a tarball is made from the actual cvs version
and put at
this ftp site.
Contributors for binary releases are welcome. If you want to
contribute, please contact me.
license
If you want to contribute to the development it is probably best if you
subscribe to the developer's mailing list.
There's also an archive
of this list.
Like everything which is free, this software depends
on volunteers and the time they spend to improve it.
As my time is limited you are invited to supply ideas,
suggestions or even patches. Please
contact me
if you want write access to the CVS repository.
- as you might have guessed, you'll need a proper tcl installation.
As tclreadline uses namespaces, you need a tcl version
number greater than 8.0. I've tested tclreadline with the
versions 8.0.3 - 8.0.5, 8.1.0, 8.1.1, 8.2.*, 8.3 and several
8.4* versions.
- Additionally you need a shared version of the
gnu readline library with a version number greater
than 2.2. tclreadline makes use of the readline
callback method, which was not implemented in early readline
versions.
- As readline uses some terminal capablity calls you need also
a shared version of either libtermcap or
libcurses / libncurses. The configure script checks,
if one of these libs is already linked against libreadline.
The reason, that you need shared libs, is that these libs are
linked dynamically with the tcl load command. (This is done
automatically by the initialization script, so normally you
don't have to care about this.)
The configure / make / make install sequence should normally
do the rest.