Text::Wigwam::Library::Conditionals

NAME
Description
Usage
Directives

NAME

Text::Wigwam::Library::Conditionals #given, #when, #switch, #case, #default, #unless, #if, #elsif, #else, #ifelse

Description

This library provides directives which are useful for performing logical operations.

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::Conditionals( q/:all/ );

 package Text::Wigwam::Directives::another::arbitrary::branch;
 # import selectively
 use Text::Wigwam::Library::Conditionals(
  qw/ :given :when :switch :case :default :unless :if :elsif :else :ifelse /
 );

Directives

#given expr block

Begins a #given/#when tree which returns the second argument of the first #when expression that contains a match to #given's expr value within its list. If the block contains a #default statement, it will only be processed if no #when statements matched.

 [!!
  #define action "take"
  #given action {
     #when "take" "taken"
     #when "give" "given"
     #default "no action"
  }
  /* output: taken */
 !!]

This provides an alternative to #If/#Elsif/#Else trees.

#when list block

The #when directive is used inside of a #given block to match a value in list to a block. Should an item in the list evaluate to the value specified by the encompassing #given directive's expression, the block is executed by the #given directive and further processing of block is terminated.

 [!!
  #given #random 1 20 {
    #when ( 2 3 5 7 11 13 17 19 ) { :given " is a prime number" }
    #default { :given " is a boring number" }
  }
 !!]

#switch expr block

Begins a #switch/#case tree which returns the concatenated results of all #case expressions within its block that contain a match for expr's value. Unlike #given/#when, no implied break occurs when a match is made, though you may explicitly invoke #break to interrupt any further processing of the tree. If the block contains a #default statement, it will only be processed if no #case statements matched.

  [!!
  #define group.A ( 1 2 3 4 5 6 )
  #define group.B ( 5 6 7 8 9 0 )
  #switch #assign guess #random 0 10 {
    #case group.A #push grouplist "A"
    #case group.B #push grouplist "B"
    #default #throw { "Invalid guess: " guess }
  }
  guess " is a member of group(s): " #join ", " grouplist
  !!]

#case list block

The #case directive is used inside of a #switch block to match a value in list to a block. Should an item in the list evaluate to the value specified by the encompassing #switch directive's expression, the block is executed and its results are added to the queue. The tree continues to process until the end of the block is reached, unless explicitly interrupted, such as with #break.

#default block

Specifies a default expression for a #given/#when or #switch/#case tree which is executed in the event that all #when or #case conditions within the block fail to match.

 [!!
  #define selection "X"
  "You've selected "
  #given selection {
     #when "A" "Apple"
     #when "B" "Banana"
     #when "C" "Cantelope"
    #default { selection ", which is not on the menu" }
  }
  /* output:
   You've selected X, which is not on the menu
  */
 !!]

#unless cond block

The reverse logic version of the #if directive.

 [!!
   #unless 1 'this will not execute'
   #else 'This will'
 !!]

#if cond block

Executes block only if cond evaluates to true.

 [!! #if 0 "output nothing" !!]
 [!! #if 1 "this is output" !!]

Can be used in conjunction with #elsif and #else.

 [!!
  #if 0 "not processed"
  #elsif 0 "not processed"
  #else "This prevails"
  /* output:
   This prevails
  */
 !!]

Unlimited nesting is supported.

 [!!
   #if 1 {
    #if 0 "no" #else "prevails"
   }
   #else "no"
   /* outputs: prevails */
 !!]

 [!!
  #if 1 {
     #if 0 {
         #if 1 "No"
     }
     #else "prevails"
  }
  #else "Nope"
  /* output: prevails */
 !!]

#elsif cond block

Executes block if all preceding #if and #elsif conditions within the common block scope have failed and if cond evaluates true.

 [!!
  #if 0 "noway"
  #elsif 1 {
     #if 0 "no"
     #elsif 0 "unlikely"
     #else "prevails"
  }
  #else "nope"
  /* output: prevails */
 !!]

#else block

Executes block if all preceding #if & #elsif expressions within the common block scope have failed.

 [!!
  #if 1 {
     #if 0 "no"
     #else "prevails"
  }
  #else "nope"
  /* output: prevails */
 !!]

#ifelse cond block1 block2

If cond evaluates to true, block2 is destroyed and the results of block1 are returned. Otherwise, block1 is destroyed and the results of block2 are returned.

The following example assigns ( 1 2 3 4 5 ) to the array variable.

 [!! #define array #ifelse 0 ( 1 2 3 4 5 ) ( 6 7 8 9 ) !!]