FILE: "/home/joze/src/tclreadline/README"
    LAST MODIFICATION: "Sun Aug 22 18:34:26 1999 (joze)"
    LAST MODIFICATION: "Sun Aug 22 23:24:34 1999 (joze)"
    (C) 1998, 1999 by Johannes Zellner, <johannes@zellner.org>
    $Id$
    ---

    tclreadline -- gnu readline for tcl
    Copyright (C) 1999  Johannes Zellner

copy the sample.tclshrc to $HOME/.tclshrc. If you use another interpreter
like wish, you should copy the file sample.tclshrc to $HOME/.wishrc
(or whatever the manual page of your interpreter says.) If you have
installed tclreadline properly, you are just ready to start:
start your favorite interpreter. The tclreadlineSetup.tcl script
does the rest.


4. History and Changes.
-----------------------

tclreadline-0.9: (Aug 1999)

    changes:
        - tclreadline::readline customcompleter
        - tclreadline::readline builtincompleter
        - tclreadline::readline eofchar
        - variable, array and '[' command completion.

    bug fixes:
        - history entries.
        - macro mappings didn't work. (only on hitting
          mapped characters more than once.)
        - minor fixes in configure.in

tclreadline-0.8:
    minor bug fixes.

tclreadline-0.7:
    first `public release'.

 /* ==================================================================

    FILE: "/home/joze/src/tclreadline/tclreadline.c"
    LAST MODIFICATION: "Sun Aug 22 19:06:26 1999 (joze)"
    LAST MODIFICATION: "Sun Aug 22 21:26:05 1999 (joze)"
    (C) 1998, 1999 by Johannes Zellner, <johannes@zellner.org>
    $Id$
    ---

    tclreadline -- gnu readline for tcl
    Copyright (C) 1999  Johannes Zellner

{

    rl_readline_name = "tclreadline";
    rl_special_prefixes = "${";
    using_history();
    /**
     * default is " \t\n\"\\'`@$><=;|&{("
     * removed '{'.
     * removed "{(.
     */
    rl_basic_word_break_characters = " \t\n\"\\'`@$><=;|&(";
    rl_basic_word_break_characters = " \t\n\"\\'`@$><=;|&";
    if (!tclrl_eof_string)
        tclrl_eof_string = strdup("puts {}; exit");

    /*
     * try to read historyfile in home
     * directory. If this failes, this
     * is *not* an error.

.TH tclreadline n "@TCLREADLINE_VERSION@" "Johannes Zellner"

.\" (C) 1999 by Johannes Zellner
.\" FILE: "/home/joze/src/tclreadline/tclreadline.n.in"
.\" LAST MODIFICATION: "Sat Aug 21 00:33:01 1999 (joze)"
.\" LAST MODIFICATION: "Sun Aug 22 23:24:34 1999 (joze)"
.\" (C) 1998, 1999 by Johannes Zellner, <johannes@zellner.org>
.\" $Id$
.\" ---
.\"
.\" tclreadline -- gnu readline for the tcl scripting language
.\" Copyright (C) 1999  Johannes Zellner
.\"

typing but<Tab> will complete to button. Hitting <Tab> again
will complete to "button pathName".  ...

.TP 5
\fB::tclreadline::readline complete\fP \fIstring\fP
returns 1 if \fIstring\fP is a complete tcl command and 0 otherwise.

.TP 5
\fB::tclreadline::readline customcompleter\fP [\fIstring\fP]
Register the proc \fIstring\fP 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 \fBtclreadline::readline builtincompleter\fP),
the builtin completer is called.
\fBtclreadline::readline customcompleter\fP simply returns the current
custom completer if called w/o \fIstring\fP. To turn of custom
completion, call \fBtclreadline::readline customcompleter\fP with
an empty \fIstring\fP.

Example: \fB% puts $b<TAB>\fP will call the custom completer
with the four arguments \fI"$b"\fP, \fI"5"\fP, \fI"8"\fP and \fI"puts $b"\fP.
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::script_completer in
the file tclreadlineSetup.tcl.

.TP 5
\fB::tclreadline::readline builtincompleter\fP [\fIbool\fP]
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.
\fBtclreadline::readline builtincompleter\fP returns the current
custom completer (also, if called w/o the \fIbool\fP argument).

.TP 5
\fB::tclreadline::readline eofchar\fP [\fIscript\fP]
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.
\fBtclreadline::readline eof\fP returns the current eof script.

.TP 5
\fB::tclreadline::readline initialize\fP \fIhistoryfile\fP
initialize the tclreadline interface and read the history from
the \fIhistoryfile\fP. On succes an empty string is returned.
This command has to be called before any other tclreadline commands.

.SH HISTORY
This version of \fBtclreadline\fP is still a development version.
Pretty a lot of features and ideas are not implemented yet. The
reason for this is the lack of time and manpower.
So you are welcome to modify and contribute to the code.
If you have suggestions, please let me know.

#!/usr/local/bin/tclsh
# FILE: "/home/joze/src/tclreadline/tclreadlineSetup.tcl.in"
# LAST MODIFICATION: "Sat Aug 21 00:19:39 1999 (joze)"
# LAST MODIFICATION: "Sun Aug 22 22:30:43 1999 (joze)"
# (C) 1998, 1999 by Johannes Zellner, <johannes@zellner.org>
# $Id$
# ---
#
# tclreadline -- gnu readline for tcl
# Copyright (C) 1999  Johannes Zellner
#

    return -code error "invalid command name \"$name\""
}

namespace eval tclreadline:: {
    namespace export Setup Glob Loop InitCmds InitTclCmds InitTkCmds Print
}

# get the longest common completion
# e.g. str == {tcl_version tclreadline_version tclreadline_library}
# --> [tclreadline::GetCommon ${str}] == "tcl"

proc ::tclreadline::Setup {} {

#
proc tclreadline::GetCommon {str} {
    set match0 [lindex ${str} 0]
    set len0 [string length $match0]
    set no_matches [llength ${str}]
    set part ""
    for {set i 0} {$i < $len0} {incr i} {
        set char [string index $match0 $i]
        for {set j 1} {$j < $no_matches} {incr j} {
            if {$char != [string index [lindex ${str} $j] $i]} {
                break
            }
        }
        if {$j < $no_matches} {
            break
        } else {
            append part $char
        }
    }
    return ${part}
}

proc tclreadline::vars_cmds_completer {part start end line} {
    if {{$} == [string index $part 0]} {
        # variable completion. Check first, if the
        # variable starts with a plain `$' or should
        # be enclosed in braces.
        #
        if {"\{" == [string index $part 1]} {
            set var [string range $part 2 end]
            set left "\$\{"
            set right "\}"
        } else {
            set left "\$"
            set right ""
            set var [string range $part 1 end]
        }
        # check if $var is an array name, which
        # already has already a "(" somewhere inside.
        #
        if {[regexp {([^(]*)\((.*)} $var all array name]} {
            set matches [uplevel array names ${array} ${name}*]
            if {1 == [llength $matches]} { ; # unique match
                return "\$${array}(${matches})"
            } elseif {"" != ${matches}} {
                return \
                    "\$${array}([tclreadline::GetCommon ${matches}] ${matches}"
            } else {
                return ""; # nothing to complete
            }
        }
        set matches [uplevel info vars "${var}*"]
        if {1 == [llength $matches]} { ; # unique match
            # check if this unique match is an
            # array name, (whith no "(" yet).
            #
            if {[uplevel array exists $matches]} {
                return "\$${matches}( [uplevel array names $matches]"
            } else {
                return [join [list $left $matches $right] ""]
            }
        } elseif {"" != $matches} { ; # more than one matches
            return "${left}[tclreadline::GetCommon ${matches}] ${matches}"
        } else {
            return ""; # nothing to complete
        }
    } elseif {{[} == [string index $part 0]} {
        set cmd [string range $part 1 end]
        set matches [info commands "${cmd}*"]
        if {1 == [llength $matches]} { ; # unique match
            return [join [list "\[" $matches] ""]
        } elseif {"" != $matches} {
            return "${part} ${matches}"
        } else {
            return ""; # nothing to complete
        }
    } else {
        return ""
    }
    return "NOTREACHED (this is probably an error)"
}

proc ::tclreadline::Setup {} {

    uplevel #0 {

        if {[info commands ::tclreadline::readline] == ""} {
            ::tclreadline::Init
        }
        tclreadline::readline customcompleter tclreadline::vars_cmds_completer

        if {[catch {set a [::tclreadline::prompt1]}] \
            && [info nameofexecutable] != ""} {

            namespace eval ::tclreadline {
                variable prompt_string
                set base [file tail [info nameofexecutable]]