tclreadline - gnu readline for the tcl scripting language

       Johannes Zellner, <johannes@zellner.org>

       Citing the readline manual:  It's too big and too slow.

       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.4.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::readlineaddstring
            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::readlinecompletestring
            Returns 1 if string is a complete tcl command and 0 otherwise.

       ::tclreadline::readlinecustomcompleter [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::readlinebuiltincompleter), the
            builtin completer is called.   tclreadline::readlinecustomcompleter  simply  returns  the  current
            custom  completer  if  called  w/o  string. To turn of custom completion, call tclreadline::readlinecustomcompleter 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::readlinebuiltincompleter [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::readlinebuiltincompleter  returns  the  current
            custom completer (also, if called w/o the bool argument).

       ::tclreadline::readlineeofchar [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::readlineeof returns
            the current eof script.

       ::tclreadline::readlineinitializehistoryfile
            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::readlinereadprompt
            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::readlineread
            raises an error if an error occurs while evaluating a script completer.

       ::tclreadline::readlinewritehistoryfile
            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::readlinereset-terminal [terminalName]
            Without  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 without argument might not work if tclreadline was compiled with an older version of
            libreadline.

       ::tclreadline::readlinehistoryexpansion [bool]
            Enable or disable history expansion. With no argument, returns the current value.

       ::tclreadline::readlinebell
            Ring the terminal bell, obeying the setting of bell-style -- audible or visible.

       ::tclreadline::text
            Return the current input.

       ::tclreadline::readlineupdate
            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.

       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>

       David Engel <dlengel@home.com>, <david@debian.org>

       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::readlineread 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 be 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....

tclreadline  comes  with  a  BSD  type  license.   The  read-only variable tclreadline::license holds the
       complete license statement.

Johannes Zellner                                      2.4.0                                    tclreadline(3tcl)

       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.

       tclreadline - gnu readline for the tcl scripting language

       The official tclreadline web site at:

           https://github.com/flightaware/tclreadline/

::tclreadline::readlinecommand [options]

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.4.0".

       tclreadline::patchLevel (read-only)
            Holds the patch level string "2.4.0".

       tclreadline::library (read-only)
            Holds the library directory string.

       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.