Next: Text::Wigwam::Library::Character | Previous: Text::Wigwam::Globals | [Table of Contents] | [Text::Wigwam Index] |
Text::Wigwam::Library::Assignment #alias, #assign, #define, #local, #my, #localize, #parameters, #params, #undefine,
This library provides directives that deal with assigning values to variables.
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 / );
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.
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 */ !!]
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" !!]
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 */ !!]
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" !!]
Declares a list of variables as local.
[!! #localize < lvar1 lvar2 lvar3 > !!]
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 */ "e < Confucius 'To see the right and not to do it is cowardice.' > /* Pass the macro some named parameters (hash) */ "e %< 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." */ !!]
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?" !!]
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 */ !!]