loops (17oct12)

git-svn-id: svn://tug.org/texlive/trunk@28002 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 76 insertions, 23 deletions

diff --git a/Master/texmf-dist/doc/latex/loops/README b/Master/texmf-dist/doc/latex/loops/README
index 6eaa9719cbf..ca4a68a07e6 100644
--- a/Master/texmf-dist/doc/latex/loops/README
+++ b/Master/texmf-dist/doc/latex/loops/README
@@ -1,14 +1,16 @@
 This is the README file for the 'loops' package.
 
-*** Location: latex/macros
-
 AUTHOR
 
 Ahmed Musa
 
 VERSION
 
-Version 1.0, September 2012.
+Version 1.1, October 2012.
+
+LOCATION ON CTAN
+
+macros/latex/contrib/loops/
 
 LICENSE
 
@@ -21,6 +23,11 @@ is provided 'as it is', without warranty of any kind, either
 expressed or implied, including, but not limited to, the implied
 warranties of merchantability and fitness for any particular purpose.
 
+NOTE
+
+Non-LaTeX users can use the \newforeach macro (and some other
+looping macros) by loading the file skeyval-for.tex. These exclude
+\foxloop or \foreachfox, which are available only in loops.sty.
 
 SUMMARY
 
@@ -173,7 +180,7 @@ The looping macros include:
     terminate the loop prematurely (ie, before exhausting
     the list).
 
-    \skvnewregister\count\nr\nr=\tw@
+    \newcount\nr\nr=\tw@
     \def\do#1{%
       \let\noexpand#1%
       \expandafter\noexpand\csname\skvremovescape{#1}@%
@@ -183,6 +190,32 @@ The looping macros include:
     \show\x -> \let\cmda\cmda@ii \let\cmdb\cmdb@ii
 
 
+\skvgenloop:
+
+    \skvgenloop{<parser>}{<list>}{<1.parameter.callback>}
+
+    \skvgenloop is non-expandable but it takes any arbitrary
+    list separator (parser). In the case of non-separated (nsv/tsv)
+    lists, <parser> can be empty. The list is not normalized prior to
+    parsing, and it is not possible to terminate the loop prematurely
+    (ie, before exhausting the list).
+
+    Here, <1.parameter.callback> is not a macro, unlike the
+    <1.parameter.callback.macro> for \skvfor.
+
+    \newcount\nr\nr=\tw@
+    \def\stack{}
+    \skvgenloop{,}{\cmda,\cmdb}{%
+      \edef\stack{%
+        \unexpanded\expandafter{\stack}%
+        \let\noexpand#1%
+        \expandafter\noexpand\csname\skvremovescape{#1}@%
+        \romannumeral\nr\endcsname
+      }%
+    }
+    \show\stack
+
+
 \skvcommaloop, \skvecommaloop, \skvcommaparse, \skvkvparse:
 
     \skvcommaloop{<list>}<holder-cmd>{<callback>}
@@ -274,13 +307,18 @@ The looping macros include:
     restore the values of holder macros and some other internal
     parameters/quantities.
 
-    There is a long list of options, ie, keys in <options>,
-    available for \newforeach and \foxloop. Also, there are many
-    internal macros that can be accessed by the user. A few of them
-    are \interruptforeach, \foreachcurrentitem, \foreachnextitem,
+    There is a long list of options/keys in <options>, available for 
+    \newforeach and \foxloop. For example, key 'reverse list' allows users 
+    to automatically reverse their lists prior to processing.
+    
+    Also, there are many internal macros that can be accessed by the user. 
+    A few of them are
+    
+    \interruptforeach, \foreachcurrentitem, \foreachnextitem,
     \foreachitemcount, \foreachprevitem, \prependtobeginforeach,
     \appendtobeginforeach, \prependtoendforeach, \appendtoendforeach,
     \ifforeachlastitem, \foreachnestdepth, \foreachlistremainder.
+    
     \foreachitemcount counts the items as the loop progresses.
     It is depth dependent, ie, it can be called to access the
     number of items processed on each depth of nesting of
@@ -353,6 +391,26 @@ The looping macros include:
     need to manually expand the holder macros \x,\y,\z in the callbacks,
     as I have seen some TikZ users do.
 
+    Here is an example that uses parameters:
+
+    \newforeach \x [
+      item counter = \xc,
+      exit when = \ifskvstreq#1\with b\then\fi,
+    ] in {a,b,c} do {%
+      \newforeach [
+        count in = \yc all \y satisfying \ifnum\y>2\fi,
+        loop stopper = \ifnum\y>3\fi
+      ] \y in {1,2,3,4,5} {%
+        \skvcsdef{#1##1}{Items: #1, ##1}%
+      }%
+    }
+    \begin{document}
+    Numbers: {\tt\string\xc}: \xc, {\tt\string\yc}: \yc
+    \par\skvcsuse{a1}
+    \par\skvcsuse{e10}
+    \end{document}
+
+
     \newforeach found a bug in PGF's \foreach, as reported at
     <http://tex.stackexchange.com/questions/72707/an-unexpected-
     outcome-from-pgfs-foreach>. However, \newforeach itself
@@ -365,17 +423,18 @@ The looping macros include:
     \foxloop*[<options>]{<listcmd>}{<parametered.callback>}
 
     \foxloop does everything that \newforeach does, but, in addition,
-    it can process nsv/tsv (non-separated lists). It can auto-complete
-    ellipsis lists (ie, lists with '...'), but this feature is
-    available only for csv lists and not for nsv lists.
+    it can process nsv/tsv (non-separated, tokenwise, lists). It can
+    auto-complete ellipsis lists (ie, lists with '...'), but this
+    feature is available only for csv lists and not for tsv lists.
 
     1.  One important characteristic of \foxloop is that it doesn't use
         holder macros (eg, \x/\y), but instead it uses parameter
         characters directly. So it doesn't accept/expect holder macros.
-    2.  That means that if the argument isn't simple (ie, #1), then it
-        has to be specified as the value of the key/option 'arg' (eg,
-        arg=#1/#2).
-    3.  Note that \foxloop doesn't expect any optional 'in' or 'do'.
+    2.  That means that if the argument isn't simple (ie, if it isn't #1),
+        then it has to be specified as the value of the key/option 'arg'
+        (eg, arg=#1/#2).
+    3.  Note that \foxloop doesn't expect any optional 'in' or 'do' in the
+        argument list.
     4.  Unlike \newforeach, \foxloop doesn't recognize the semicolon
         (;) as a callback terminator. In fact, the callback for \foxloop
         should ideally be always enclosed in balanced braces. PGF
@@ -434,8 +493,8 @@ The looping macros include:
     \end{multicols}
     \end{document}
 
-    
-    % Example credit: Heiko Oberdiek
+
+    % Example credit: Heiko Oberdiek.
     \makeatletter
     \let\do\newdimen\do\DimWD\do\DimHT\do\DimDP
     \newcommand*{\DimBox}[1]{%
@@ -474,10 +533,4 @@ The looping macros include:
     \end{document}
 
 
-NOTE
-
-Non-LaTeX users can use the \newforeach macro (and some other
-looping macros) by loading the file skeyval-for.tex.
-
-
 % End of readme file of loops.sty 
\ No newline at end of file