Text::Wigwam::Library::Iterators

NAME
Description
Usage
Directives

NAME

Text::Wigwam::Library::Iterators #break, #continue, #first, #foreach, #last, #repeat, #while

Description

This library provides directives relating to looping constructs.

The directives within this library can be imported into specific branches of the directive tree (which transcends from Text::Wigwam::Directives) via plug-ins or modules using one of the following techniques.

 package Text::Wigwam::Directives::some::arbitrary::branch;
 # import everything
 use Text::Wigwam::Library::Iterators( q/:all/ );

 package Text::Wigwam::Directives::another::arbitrary::branch;
 # import selectively
 use Text::Wigwam::Library::Iterators(
  qw/ :break :continue :for :foreach :repeat :while /
 );

Directives

#break

Breaks out of a #foreach, #repeat, or #while loop.

 [!!
  #foreach var < a b 0 c d > {
      #unless var #break
     var
  }
  /* output:
   ab
  */
 !!]

#continue

Skips the current iteration of a #foreach, #repeat, or #while loop.

 [!!
  #foreach var < a b 0 c "" d > {
      #unless var #continue
     var
  }
  /* output:
   abcd
  */
 !!]

#foreach var array block

For each element of array, the current element's value is stored in var and block is executed. The concatenated results of each block execution is returned.

 [!!
  #define array < 3 . 1 4 1 5 9 6 >
  #foreach digit array {
     digit
  }
  /* output:
    3.141596
  */
 !!]

The loop can be terminated using the #break directive within block, or an iteration can be skipped using #continue.

#first

Returns true during the first iteration of a #foreach loop. Alternatively, you could simply access the global directly via :first.

 [!!
  #foreach item < one two three four >{
     #if #first "<UL>"
     "<LI>" item
     #if #last "</UL>"
  }
  /* Output:
   <UL><LI>one<LI>two<LI>three<LI>four</UL>
  */
 !!]

#last

Returns true during the final iteration of a #foreach loop. Alternatively, you can simply access the global directly via :last.

 [!!
  #foreach item < milk cheese eggs waffles wd40 >{
     #if #first { "Ingredients: " item }
     #elsif #last { " and " item "." }
     #else { ", " item }
  }
  /* output:
   Ingredients: milk, cheese, eggs, waffles and wd40.
  */
 !!]

#repeat num block

Begins a loop of a fixed number of iterations which is dictated by num. Supports #break and #continue within block.

 [!!
  #repeat 20 { "-" }
  /* output:
   --------------------
  */
 !!]

The iteration count can be retrieved within the block via the :repeat global.

 [!!
  #repeat 20 { :repeat "-" }
  /* output:
   0-1-2-3-4-5-6-7-8-9-10-11-12-13-14-15-16-17-18-19-
  */
 !!]

#while cond block

Continuously executes block so long as cond evaluates to true prior to each iteration. Returns the concatenated results of each iteration.

 [!!
  #define array ( 0 1 2 3 4 )
  #while array #shift array
  /* output:
   01234
  */
 !!]

The #break directive can be used within block to end the loop, and #continue can be used to interrupt the current iteration.

 [!!
  #define array ( 4 9 3 8 2 7 1 0 6 5 )
  #while array {
     #define num #shift array
     #unless num #break
     #if #lt num 4 #continue
     num
  /* output:
   4987
  */
  }
 !!]