Provided by: tcl-tclreadline_2.1.0-12_amd64 bug

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

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

VARIABLES

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