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

1 files changed, 21 insertions, 17 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