tclreadline
[ home ] [ development ] [ cvs ] [ license ]
Description
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.

Usage
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.

Features

Commands
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?"
::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.

download / locations
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.

Requirements
The configure / make / make install sequence should normally do the rest.


© johannes@zellner.org
LAST MODIFICATION: "Fri May 7 02:07:58 1999 (joze)"
[ home ] [ development ] [ cvs ] [ license ]