summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/loops/README
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-10-17 22:45:04 +0000
committerKarl Berry <karl@freefriends.org>2012-10-17 22:45:04 +0000
commitfacafbb26a0554617788e362d73e71d7b070ffa3 (patch)
tree34a4534e7b2dafc7c8e6e94ce70ba37b6949d1a7 /Master/texmf-dist/doc/latex/loops/README
parent68d1082187795028afc486f56eaf6cd303f8b79e (diff)
loops (17oct12)
git-svn-id: svn://tug.org/texlive/trunk@28002 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/loops/README')
-rw-r--r--Master/texmf-dist/doc/latex/loops/README99
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