TIP#127 Implementation. Thanks to Michael Schlenker for his implementation work

2 files changed, 41 insertions, 32 deletions

diff --git a/doc/lsearch.n b/doc/lsearch.n
index 302a1f5..b2129aa 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -6,10 +6,10 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lsearch.n,v 1.14 2003/03/17 14:21:40 dkf Exp $
+'\" RCS: @(#) $Id: lsearch.n,v 1.15 2003/10/14 13:38:57 dkf Exp $
 '\" 
 .so man.macros
-.TH lsearch n 8.4 Tcl "Tcl Built-In Commands"
+.TH lsearch n 8.5 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -23,18 +23,14 @@ lsearch \- See if a list contains a particular element
 This command searches the elements of \fIlist\fR to see if one
 of them matches \fIpattern\fR.  If so, the command returns the index
 of the first matching element
-.VS 8.4
 (unless the options \fB\-all\fR or \fB\-inline\fR are specified.)
-.VE 8.4
 If not, the command returns \fB\-1\fR.  The \fIoption\fR arguments
 indicates how the elements of the list are to be matched against
 \fIpattern\fR and it must have one of the following values:
 .TP
 \fB\-all\fR
-.VS 8.4
 Changes the result to be the list of all matching indices (or all
 matching values if \fB\-inline\fR is specified as well.)
-.VE 8.4
 .TP
 \fB\-ascii\fR
 The list elements are to be examined as Unicode strings (the name is
@@ -61,22 +57,26 @@ element using the same rules as the \fBstring match\fR command.
 The list elements are sorted in increasing order.  This option is only
 meaningful when used with \fB\-sorted\fR.
 .TP
+\fB\-index\fR\0\fIindexList\fR
+.VS 8.5
+This option is designed for use when searching within nested lists.
+The \fIindexList\fR gives a path of indices (much as might be used
+with the \fBlsearch\fR command) within each element to allow the
+location of the term being matched against.
+.VE 8.5
+.TP
 \fB\-inline\fR
-.VS 8.4
 The matching value is returned instead of its index (or an empty
 string if no value matches.)  If \fB\-all\fR is also specified, then
 the result of the command is the list of all values that matched.
-.VE 8.4
 .TP
 \fB\-integer\fR
 The list elements are to be compared as integers.  This option is only
 meaningful when used with \fB\-exact\fR or \fB\-sorted\fR.
 .TP
 \fB\-not\fR
-.VS 8.4
 This negates the sense of the match, returning the index of the first
 non-matching value in the list.
-.VE 8.4
 .TP
 \fB\-real\fR
 The list elements are to be compared as floating-point values.  This
@@ -96,13 +96,20 @@ option is mutually exclusive with \fB\-glob\fR and \fB\-regexp\fR, and
 is treated exactly like \fB-exact\fR when either \fB\-all\fR, or
 \fB\-not\fR is specified.
 .TP
-\fB\-start\fR \fIindex\fR
-.VS 8.4
+\fB\-start\fR\0\fIindex\fR
 The list is searched starting at position \fIindex\fR.  If \fIindex\fR
 has the value \fBend\fR, it refers to the last element in the list,
 and \fBend\-\fIinteger\fR refers to the last element in the list minus
 the specified integer offset.
-.VE 8.4
+.TP
+\fB\-subindices\fR
+.VS 8.5
+If this option is given, the index result from this command (or every
+index result when \fB\-all\fR is also specified) will be a complete
+path (suitable for use with \fBlindex\fR or \fBlset\fR) within the
+overall list to the term found.  This option has no effect unless the
+\fI\-index\fR is also specified, and is just a convenience short-cut.
+.VE 8.5
 .PP
 If \fIoption\fR is omitted then it defaults to \fB\-glob\fR.  If more
 than one of \fB\-exact\fR, \fB\-glob\fR, \fB\-regexp\fR, and
@@ -113,7 +120,6 @@ last takes precedence.  If more than one of \fB\-increasing\fR and
 \fB\-decreasing\fR is specified, the option specified last takes
 precedence.
 
-.VS 8.4
 .SH EXAMPLES
 .CS
 lsearch {a b c d e} c => 2
@@ -123,14 +129,12 @@ lsearch -inline -not {a20 b35 c47} b* => a20
 lsearch -all -inline -not {a20 b35 c47} b* => a20 c47
 lsearch -all -not {a20 b35 c47} b* => 0 2
 lsearch -start 3 {a b c a b c} c => 5
+lsearch -index 1 -all {{a abc} {b bcd} {c cde}} *bc* => {a abc} {b bcd}
 .CE
-.VE 8.4
 
 .SH "SEE ALSO"
-.VS 8.4
 foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), 
 lset(n), lsort(n), lrange(n), lreplace(n)
-.VE
 
 .SH KEYWORDS
 list, match, pattern, regular expression, search, string
diff --git a/doc/lsort.n b/doc/lsort.n
index 1af8dc6..217c094 100644
--- a/doc/lsort.n
+++ b/doc/lsort.n
@@ -7,7 +7,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lsort.n,v 1.13 2003/03/17 14:21:41 dkf Exp $
+'\" RCS: @(#) $Id: lsort.n,v 1.14 2003/10/14 13:38:58 dkf Exp $
 '\" 
 .so man.macros
 .TH lsort n 8.3 Tcl "Tcl Built-In Commands"
@@ -65,32 +65,39 @@ This is the default.
 \fB\-decreasing\fR
 Sort the list in decreasing order (``largest'' items first).
 .TP 20
-\fB\-index\0\fIindex\fR
+\fB\-index\0\fIindexList\fR
 If this option is specified, each of the elements of \fIlist\fR must
 itself be a proper Tcl sublist.  Instead of sorting based on whole
-sublists, \fBlsort\fR will extract the \fIindex\fR'th element from
-each sublist and sort based on the given element.  The keyword
-\fBend\fP is allowed for the \fIindex\fP to sort on the last sublist
-element,
-.VS 8.4
-and \fBend-\fIindex\fR sorts on a sublist element offset from
-the end.
-.VE
+sublists, \fBlsort\fR will extract the \fIindexList\fR'th element from
+each sublist
+.VS 8.5
+(as if the overall element and the \fIindexList\fR were passed to
+\fBlindex\fR) and sort based on the given element.  The keyword
+\fBend\fP is allowed for each element of the \fIindexList\fR to sort
+on the last sublist element, and \fBend-\fIindex\fR sorts on a sublist
+element offset from the end.
+.VE 8.5
 For example,
 .RS
 .CS
 lsort -integer -index 1 {{First 24} {Second 18} {Third 30}}
 .CE
 returns \fB{Second 18} {First 24} {Third 30}\fR, and
-.VS 8.4
 '\"
 '\" This example is from the test suite!
 '\"
 .CS
 lsort -index end-1 {{a 1 e i} {b 2 3 f g} {c 4 5 6 d h}}
 .CE
-returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR.
-.VE
+returns \fB{c 4 5 6 d h} {a 1 e i} {b 2 3 f g}\fR,
+.VS 8.5
+and
+.CS
+lsort -index {0 1} {{{b i g} 12345} {{d e m o} 34512} {{c o d e} 54321}}
+.CE
+returns \fB{{d e m o} 34512} {{b i g} 12345} {{c o d e} 54321}\fR
+(because \fBe\fR sorts before \fBi\fR which sorts before \fBo\fR.)
+.VE 8.5
 This option is much more efficient than using \fB\-command\fR
 to achieve the same effect.
 .RE
@@ -186,10 +193,8 @@ More complex sorting using a comparison function:
 .CE
 
 .SH "SEE ALSO"
-.VS 8.4
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
 lset(n), lrange(n), lreplace(n)
-.VE
 
 .SH KEYWORDS
 element, list, order, sort