From facafbb26a0554617788e362d73e71d7b070ffa3 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Wed, 17 Oct 2012 22:45:04 +0000 Subject: loops (17oct12) git-svn-id: svn://tug.org/texlive/trunk@28002 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/loops/README | 99 ++++++++++++++++++++++++-------- 1 file changed, 76 insertions(+), 23 deletions(-) (limited to 'Master/texmf-dist/doc/latex/loops/README') 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{}{}{<1.parameter.callback>} + + \skvgenloop is non-expandable but it takes any arbitrary + list separator (parser). In the case of non-separated (nsv/tsv) + lists, 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{}{} @@ -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 , - 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 , 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 . However, \newforeach itself @@ -365,17 +423,18 @@ The looping macros include: \foxloop*[]{}{} \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 -- cgit v1.2.3