Man page updates for command rename from 'mapeach' to 'lmap'.

1 files changed, 91 insertions, 0 deletions

diff --git a/doc/lmap.n b/doc/lmap.n
new file mode 100644
index 0000000..7deb7f9
--- /dev/null
+++ b/doc/lmap.n
@@ -0,0 +1,91 @@
+'\"
+'\" Copyright (c) 2012 Trevor Davel
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+.so man.macros
+.TH lmap n "" Tcl "Tcl Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+lmap \- Iterate over all elements in one or more lists and collect results
+.SH SYNOPSIS
+\fBlmap \fIvarname list body\fR
+.br
+\fBlmap \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBlmap\fR command implements a loop where the loop
+variable(s) take on values from one or more lists, and the loop returns a list
+of results collected from each iteration.
+.PP
+In the simplest case there is one loop variable, \fIvarname\fR,
+and one list, \fIlist\fR, that is a list of values to assign to \fIvarname\fR.
+The \fIbody\fR argument is a Tcl script.
+For each element of \fIlist\fR (in order
+from first to last), \fBlmap\fR assigns the contents of the
+element to \fIvarname\fR as if the \fBlindex\fR command had been used
+to extract the element, then calls the Tcl interpreter to execute
+\fIbody\fR.  If execution of the body completes normally then the result of the
+body is appended to an accumulator list. \fBlmap\fR returns the accumulator
+list.
+
+.PP
+In the general case there can be more than one value list
+(e.g., \fIlist1\fR and \fIlist2\fR),
+and each value list can be associated with a list of loop variables
+(e.g., \fIvarlist1\fR and \fIvarlist2\fR).
+During each iteration of the loop
+the variables of each \fIvarlist\fR are assigned
+consecutive values from the corresponding \fIlist\fR.
+Values in each \fIlist\fR are used in order from first to last,
+and each value is used exactly once.
+The total number of loop iterations is large enough to use
+up all the values from all the value lists.
+If a value list does not contain enough
+elements for each of its loop variables in each iteration,
+empty values are used for the missing elements.
+.PP
+The \fBbreak\fR and \fBcontinue\fR statements may be
+invoked inside \fIbody\fR, with the same effect as in the \fBfor\fR
+and \fBforeach\fR commands. In these cases the body does not complete normally
+and the result is not appended to the accumulator list.
+.SH EXAMPLES
+.PP
+Zip lists together:
+.PP
+.CS
+'\" Maintainers: notice the tab hacking below!
+.ta 3i
+set list1 {a b c d}
+set list2 {1 2 3 4}
+set zipped [\fBlmap\fR a $list1 b $list2 {list $a $b}] 
+# The value of zipped is "{a 1} {b 2} {c 3} {d 4}"
+.CE
+.PP
+Filter a list:
+.PP
+.CS
+set values {1 2 3 4 5 6 7 8}
+proc isGood {n} { expr { ($n % 2) == 0 } }
+set goodOnes [\fBlmap\fR x $values {expr {[isGood $x] ? $x : [continue]}}]
+# The value of goodOnes is "2 4 6 8"
+.CE
+.PP
+Take a prefix from a list:
+.PP
+.CS
+set values {8 7 6 5 4 3 2 1}
+proc isGood {n} { expr { $n > 3 } }
+set prefix [\fBlmap\fR x $values {expr {[isGood $x] ? $x : [break]}}] 
+# The value of prefix is "8 7 6 5 4"
+.CE
+
+.SH "SEE ALSO"
+for(n), while(n), break(n), continue(n), foreach(n)
+
+.SH KEYWORDS
+foreach, iteration, list, loop, map