| Next: Text::Wigwam::Library::Sets | Previous: Text::Wigwam::Library::Math | [Table of Contents] | [Text::Wigwam Index] |
Text::Wigwam::Library::Procedure #argc, #args, #argv, #init, #call, #exit, #expr, #include, #macro, #process, #return, #stop, #template
This library provides directives which introduce procedural capabilities.
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::Procedure( q/:all/ );
use Text::Wigwam::Help;
package Text::Wigwam::Directives::another::arbitrary::branch;
# import selectively
use Text::Wigwam::Library::Procedure(
qw /
:argc :args :argv
:init :call :exit :expr
:include :macro :proc :process
:return :template :use
/
);
Returns the number of arguments available on the argument stack.
[!!
#macro foo { #argc }
#call foo < a b c >
/* output: 3 */
!!]
Returns the argument stack, which is typically an array or a hash. You may
alternatively access the same value via the :args global variable.
Returns a single value from the argument stack specified by key.
[!!
#call #expr {
#argv 1
#argv 2
#argv 0
} < A B C > /* Output: BCA */
#call #expr {
#argv 'B'
#argv 'C'
#argv 'A'
} %< A 'Aye' B 'Bee' C 'Cee' > /* Output: BeeCeeAye */
!!]
Note that, alternatively, you could do the same thing via the global :args
variable.
[!!
#call #expr {
:args:1
:args:2
:args:0
} < A B C > /* Output: BCA */
#call #expr {
:args.B
:args.C
:args.A
} %< A 'Aye' B 'Bee' C 'Cee' > /* Output: BeeCeeAye */
!!]
Forces arg to evaluate only once for the current template. Subsequent evaluations are ignored.
[!!
#define value 0
#repeat 3 #init #inc value
value
/* Output:
1
*/
!!]
The #init directive is most useful when used as a priority directive.
Priority directives are executed before any other directives, so this can be
exploited to allow macros to be defined at the bottom the template.
[!!
&foo( 'man chu' )
##init {
#macro foo { :args:0 }
}
/* Output:
man chu
*/
!!]
Executes an expr (such as that returned by #macro, #template, #include,
#process or #expr) and passes args as arguments which can be retrieved
from within the EXPR via the #argv or #args directives.
[!! #macro greet !!> Welcome, [!! #argv 0 !!]. <!! #foreach person ( "Frank" "Joel" "Tom" "Clayton" ) #call greet( person ) /* Welcome, Frank. Welcome, Joel. Welcome, Tom. Welcome, Clayton. */ !!]
Alternatively, if the first argument is a code reference, it will be executed and passed args in dereferenced form as its arguments.
Halts processing of the current template and exits with val.
[!! #unless Query`defined #exit !!]
Halts processing of the current template and exits.
[!! #unless #defined Query.action #stop !!]
Returns arg as a macro (an EXPR type). Similar to #macro, but provides an alternative inline method for defining a macro.
[!! #define greet #expr !!> Hello, [!! :args:0 !!]. <!! #foreach person < Mike Clayton Bobo > #call greet( person ) /* output: Hello, Mike. Hello, Clayton. Hello, Bobo. */ !!]
Loads an external template specified by filename and returns it as an EXPR object which can be assigned to a variable, #call'ed, or executed on the spot. The external template will execute as if it were a macro defined within the calling template in that it will share a common varspace and be subject to the its globals.
[!! #include "foobar" !!]
Stores block into var for later execution. This var can then be used as a simple macro which is executed as if it were literally placed there, or it can be called with parameters as a subroutine via the #call directive.
[!!
#macro html_widget.input {
#parameters < name type value > /* Retrieve parameters */
!!>
<Input
name="[!! name !!]"
type="[!! type !!]"
value="[!! value !!]"
>
<!!
}
#call html_widget.input %<
name "bazz"
type "text"
value "Hey!"
>
/* output:
<Input name="bazz" type="text" value="Hey!">
*/
!!]
Replaces the text generated from the current #call'ed expression with val instead, which is then passed on by #call.
[!!
#macro foo {
"This is what would've been returned had we not used #return"
#return "foo was here!"
"We never get this far"
}
#call foo ()
/* output: foo was here! */
!!]
We can return any data type. The following example returns an array.
[!!
#macro foo {
"This is what would've been returned had we not used #return"
#return ( "foo was here!" )
}
#pop #call foo ()
/* output: foo was here! */
!!]
Loads an external template specified by filename while using hash as its varspace. Returns an EXPR object which can be assigned to a variable, #call'ed, or simply executed where it stands, as below.
[!! #process "html_header" %< title 'My Title' > !!]
Identical to the #process directive except that it requires one less argument since the template is assigned an anonymous, private varspace hash.
[!! #template "foobar" !!] This is functionally equivalent to: [!! #process "foobar"; !!]
Loads and evaluates a Perl library module if it hasn't already been loaded.
Returns nothing when called in void context, otherwise it attempts to call the
package's new constructor while passing it dereferenced args hash or
array as arguments, then returns the result.
[!!
/* void context - evaluates foo::bar if necessary, but returns nothing */
#use "foo::bar";
/* evaluates foo::bar and executes foo::bar->new( 'baz', 'qux' ) */
#define fb #use foo::bar ( 'baz' 'qux' )
!!]