NAME¶

SYNOPSIS¶

::tclreadline::readline command [options]

 

 

DESCRIPTION¶

COMMANDS¶

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

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

    if {$tcl_interactive} {
        package require tclreadline
        ::tclreadline::Loop
    }

    $if tclreadline
    "\C-xp": "puts $env(PATH)"
    $endif

BUGS¶

SEE ALSO¶

AUTHOR¶

CONTRIBUTIONS, SUGGESTIONS AND PATCHES¶

DEBIAN PACKAGE¶

DISCLAIMER¶