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.
The following list will give all commands,
which are currently implemented in the shared lib (e.g. libtclreadline0.9.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 write historyfile
- writes the history to the historyfile . This command is called automatically
from the internal routine ::tclreadline::Exit.
- ::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
- 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: eqn not supported
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 global variable tclreadline_version holds the version number
of the tclreadline package.
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
eqn not supported
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:
eqn not supported
For further documentation please refer to the gnu readline documentation.
probably.
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>
David Engel <dlengel@home.com>, <david@debian.org>
This version of tclreadline is still a development
version. Pretty a lot of features and ideas are not implemented yet. The
reason for this is the lack of time and manpower. So you are welcome to
modify and contribute to the code. If you have suggestions, please let
me know.
tclreadline comes with the GPL (GNU General Public License).
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Table of Contents