Text::Wigwam::Library::Comparators

• NAME
• Description
• Usage
• Directives
  • #and arg1 arg2
  • #cmp arg1 arg2
  • #eq arg1 arg2
  • #ge arg1 arg2
  • #gt arg1 arg2
  • #in arg1 arg2
  • #le arg1 arg2
  • #lt arg1 arg2
  • #ne arg1 arg2
  • #ni arg1 arg2
  • #not arg
  • #or arg1 arg2
  • #regex string regex
  • #grep string array
  • #sgrep string array
  • #xor arg1 arg2

NAME

Text::Wigwam::Library::Comparators #and, #cmp, #eq, #ge, #gt, #in, #le, #lt, #ne, #ni, #not, #or, #regex, #grep, #sgrep, #xor

Description

This library provides directives which are useful for comparing and testing values.

Usage

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::Comparators qw/:all/;

 package Text::Wigwam::Directives::another::arbitrary::branch;
 # import selectively
 use Text::Wigwam::Library::Comparators(
  qw/ :and :cmp :eq :ge :gt :in :le :lt :ne :ni :not :or :xor /
 );

Directives

#and arg1 arg2

Returns the value of arg1 if it's false, otherwise returns the value of arg2.

 [!! #and 1 2 /* output: 2 */ !!]

The #and directive's short-circuit behavior can be used to perform some simple in-line logic functions.

[!!
 #define params < 1 1 0 1 0 1 0 0 1 >
 #define true_count 0
 #while params
   #push list
     #and
      #shift params
      #incr true_count
 #join ", " list
 /* output:
  1, 2, 0, 3, 0, 4, 0, 0, 5
 */ !!]

#cmp arg1 arg2

Returns a signed value which represents how arg1 compares to arg2. Zero is equal, -1 is less than, +1 is greater than.

 [!!
  #given #cmp x y {
    #when 0  "x and y are equal"
    #when 1  "x is greater than y"
    #when -1 "x is less than y"
  }
 !!]

#eq arg1 arg2

Returns true if arg1 is equal to arg2.

 [!!
  #if #eq { "b" "a" "r" } "bar" { "bar equals \"bar\"" }
  /* output:
   bar equals "bar"
  */
 !!]

Numeric values are auto-detected, and the appropriate comparison operation is performed on the arguments.

 [!! #if #eq 1 "1.00" "True" /* output: True */ !!]

#ge arg1 arg2

Returns true if arg1 is greater than or equal to arg2.

 [!! #if #ge grades.[student].gpa requirements.gpa.pass "Failing" !!]

Numeric values are auto-detected, and the appropriate comparison operation is performed on the arguments.

 [!! #if #ge "0.10" "1.0E-1" "True" /* output: True */ !!]

#gt arg1 arg2

Returns true if arg1 is greater than arg2.

 [!!
  #if #gt #reactor::actual_temp reactor.limits.max {
   "Shutting down!"
   #reactor::shutdown
  }
  /* Note: Please don't use Wigwam to control a nuclear reactor. Thx! */
 !!]

Numeric values are auto-detected, and the appropriate comparison operation is performed on the arguments.

 [!! #if #gt 1 "1.0E-1" "True" /* output: True */ !!]

#in arg1 arg2

Performs a non case-sensitive search for arg2 within arg1 and returns true if it was found.

 [!! #if #in ENV.REMOTE_ADDR "^10\.1\.0\." "Local IP" !!]

#le arg1 arg2

Returns true if arg1 is less than or equal to arg2.

 [!!
  #if #le "foo" "fuu" "foo is less than or equal to fuu"
  /* output:
   foo is less than or equal to fuu
  */
 !!]

Numeric values are auto-detected, and the appropriate comparison operation is performed on the arguments.

 [!! #if #le "001.0E-1" "0.1" "True" /* output: True */ !!]

#lt arg1 arg2

Returns true if arg1 is less than arg2.

 [!!
  #if #lt "aardvark" "bismuth" { "aardvark is less than bismuth" }
  /* output:
   aardvark is less than bismuth
  */
 !!]

Numeric values are auto-detected, and the appropriate comparison operation is performed on the arguments.

 [!! #if #lt 1E-1 "1.00" "True" /* output: True */ !!]

#ne arg1 arg2

Returns true if arg1 is not equal to arg2.

 [!!
  #if #ne "foo" "bar" { '"foo" does not equal "bar"' }
  /* output:
   "foo" does not equal "bar"
  */
 !!]

Numeric values are auto-detected, and the appropriate comparison operation is performed on the arguments.

 [!! #if #ne 100 "+1.00E2" "Different" #else "Same" /* output: Same */ !!]

#ni arg1 arg2

Performs a non case-sensitive search for arg2 within arg1 and returns true if it was not found.

 [!! #if #ni ENV.REMOTE_ADDR "^10\.1\.0\." "Remote IP" !!]

#not arg

Returns the negated logical value of arg.

 [!! #if #not #xor a b "a and b are logically identical" !!]

#or arg1 arg2

Returns arg1 and destroys arg2 if arg1 is true. Otherwise, returns arg2.

 [!! #or 0 3 /* output: 3 */ !!]

The #or directive provides "short-circuit" behavior which is useful for subverting #if/#else blocks in some simpler logic situations, as demonstrated below.

 [!!
  #define foo "bar"
  #define quux #or foo "bazz"
  'foo is "' foo '", and quux is "' quux '"'
  /* output:
   foo is "bar", and quux is "bar"
  */
 !!]

#regex string regex

Performs the regex on string and returns a list of results when called in array context. Otherwise, returns a boolean value which represents whether or not the pattern matched.

 [!! #join ", " #grep 'f.' < fe fi fo fum > /* scalar context */ !!]
 [!! #params < path fname > #regex filespec '^(.*\\/)(.*)$' !!]

#grep string array

Returns a list of values from array that match regular expression string.

#sgrep string array

Returns a list of values from array that match regular expression string and replaces each match with value captured by the regex.

#xor arg1 arg2

Returns true if arg1 and arg2 are logically different, in that one argument evaluates to true, and the other evaluates to false.

 [!!
  #define answers ( 1 0 1 0 1 0 1 0 )
  #define quiz    ( 1 1 0 1 1 0 1 1 )
  #define prob 0
  #while #lt prob @answers {
    prob " is " #ifelse #xor answers:[prob] quiz:[prob] "Wrong\n" "Correct\n"
    #inc prob
  }
 /* output:
   0 is Correct
   1 is Wrong
   2 is Wrong
   3 is Wrong
   4 is Correct
   5 is Correct
   6 is Correct
   7 is Wrong
 */
 !!]