Next:
Text::Wigwam::Library::Character
Previous:
Text::Wigwam::Globals
 [Table of Contents][Text::Wigwam Index]

Text::Wigwam::Library::Assignment



NAME

Text::Wigwam::Library::Assignment #alias, #assign, #define, #local, #my, #localize, #parameters, #params, #undefine,

Description

This library provides directives that deal with assigning values to variables.

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::Assignment( qw/:all/ );

 package Text::Wigwam::Directives::another::arbitrary::branch;
 # import selectively
 use Text::Wigwam::Library::Assignment(
  qw/ :alias :assign :define :local :my :params :parameters :undefine /
 );

Directives

#alias var val

Identical to #define except that no copies of references are made before assigning val to var.

 [!! #define array1 ( 1 2 3 4 ) !!]
 [!! #alias array2 array1 !!]
 [!! #define array3 array1 !!]
 array1 contains: [!!#join ", " array1 !!]
 array2 contains: [!!#join ", " array2 !!]
 array3 contains: [!!#join ", " array3 !!]
 Altered array1 only... [!!#push array1 5!!]
 array1 contains: [!!#join ", " array1 !!]
 array2 contains: [!!#join ", " array2 !!]
 array3 contains: [!!#join ", " array3 !!]
 [!!
  /* output:
   array1 contains: 1, 2, 3, 4
   array2 contains: 1, 2, 3, 4
   array3 contains: 1, 2, 3, 4
   Altered array1 only...
   array1 contains: 1, 2, 3, 4, 5
   array2 contains: 1, 2, 3, 4, 5
   array3 contains: 1, 2, 3, 4
  */
 !!]

Both array1 and array2 in the preceding example are aliased to the same array reference, so if any changes are made to the elements of one, the changes also affect the other. On the other hand, array3 is unaffected by the changes to array1 because its value was assigned by the #define directive which generates a new reference, a copy of the original array, before assigning it to the variable array3.

#assign var val

Same as #define, except that it always returns val. This behavior is useful for in-line assignments.

 [!!
  #define array < 1 2 1 2 3 >
  #while #assign var #shift array { var }
  /* output: 12123 */
 !!]

#define var val

Assigns val to var unless val is an unblessed reference to a hash or array, in which case a copy is made, and this new reference value is stored into var instead. The #define directive does not return any value.

 [!! #define foo "Bar" !!]

#local var

Preserves the current value of var until the current template or subroutine loses scope, after which the original value or undefined state is restored to var.

 [!!
  #macro subr {
     #local var1
     #define var1 "bar"
     "var1 is " var1 " inside subr,\n"
  }
  #define var1 "foo"
  "var1 is " var1 " to start,\n"
  #call subr()
  "var1 is restored to " var1 " after the #call."
  /*
   output:
    var1 is foo to start,
    var1 is bar inside subr,
    var1 is restored to foo after the #call.
  */
 !!]

The following example demonstrates the usefulness of local variables for writing recursive subroutines in templates.

  [!!
   #define nested_hash %<
     topkey %<
         subkey1 value1
         subkey2 %< botkey bottom >
     >
   >
   #macro show_all_hash_values {
        #define #my hash #argv 0
        #foreach #my key hash`keys`sort {
                #if #is_hash hash.[key] #unshift values {
                        key " is a nested hash"
                        #call show_all_hash_values ( hash.[key] )
                }
                #else #unshift values hash.[key]
        }
   }
   #call show_all_hash_values ( nested_hash )
   #join ", " values
   /* output:
    topkey is a nested hash, subkey2 is a nested hash, bottom, value1
   */
  !!]

#my var

When #my (or its identical counterpart, #local) is called in anything other than void-context, the variable name is returned so it can be used in-line with other directives.

 [!! #define #my var "temporary value" !!]

#localize var_list

Declares a list of variables as local.

 [!!
  #localize < lvar1 lvar2 lvar3 >
 !!]

#parameters var_list

This directive merely provides a shortcut for the common task of assigning arguments to a set of localized variables. Readability is also improved because some of the monotonous details are hidden under the hood.

 [!!
   /* The following two expressions are functionally identical */
   #parameters < foo bar baz >
   #params #localize < foo bar baz > #args
 !!]

By allowing either an ordered list of arguments or named parameters, we increase flexibility.

 [!!
  #macro quote {
   #parameters < originator quotation >
   !!>
    [!! originator !!] once said, "[!! quotation !!]"
   <!!
  }

  /* Pass the macro an ordered list (array) of arguments */
  &quote <
   Confucius 'To see the right and not to do it is cowardice.'
  >

  /* Pass the macro some named parameters (hash) */
  &quote %<
   Originator 'Confucius'
   Quotation  'Everything has beauty, but not everyone sees it.'
  >
  /* output:
   Confucius once said, "To see the right and not to do it is cowardice."
   Confucius once said, "Everything has beauty, but not everyone sees it."
  */
 !!]

#params var_list values

Assigns a set of values values to a list of variables var_list. The values parameter can be either an array or a hash. When an array is provided, its elements are assigned to the var_list variables in left-to-right order.

When values is a hash, each entry in var_list will take on the value of its corresponding hash key in the values hash. The val_list to values match up is non-case-sensitive.

 [!! #params < foo bar baz > %< foo 'fu' Bar 'bawr' BAZ 'bas' > !!]

The #params directive will return the values list unless called in void context, in which case it returns nothing.

 [!! #unless #params < arg1 arg2 arg3 > @args #throw "No arguments?" !!]

#undefine var

Removes var from Wigwam's varspace.

 [!!
  #define foo "bar"
  #if #defined foo "foo is defined"
  #undefine foo
  #unless #defined foo "foo has been undefined"
  /* output:
   foo is defined
   foo has been undefined
  */
 !!]