tclreadline(3tcl)														 tclreadline(3tcl)

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 ::tclread-
       line::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 tclread-
       line 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 some-
       thing 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 possi-
	    ble 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  com-
	    pleter,  or the custom completer returned an empty	string. The builtin completer is on by default.  tclreadline::readline builtincom-
	    pleter 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  some-
	    thing  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 tclread-
	    line::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 ::tclread-
	    line::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 installa-
       tion 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  tclread-
       line_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.

Johannes Zellner						       2.1.0							 tclreadline(3tcl)