NAME
Decl::Semantics::Macro - defines or instantiates a macro.
VERSION
Version 0.01
SYNOPSIS
The Decl macro facility is still pretty green; it will probably go through a few iterations before I really like it.
This initial implementation provides three tags: "define" defines a named macro that can then be used anywhere and will instantiate a new node at build time based on its environment; "express" expresses a macro in situ at runtime; and "<=" defines and instantiates an anonymous macro in place, also at runtime. I'm not 100% sure that the build time/runtime distinction will be terribly significant, but more use will doubtlessly result in some places where it will be a useful one.
defines(), tags_defined()
Called by Decl::Semantics during import, to find out what xmlapi tags this plugin claims to implement.
build_payload ()
The build_payload function is then called when this object's payload is built. It handles the three tags separately, plus any defined tags we've built in the meantime.
build_define - defining a macro
Actually, definition of a macro doesn't do a lot. All the good stuff happens at instantiation.
instantiate - instantiating a macro once defined
Once a macro is defined, its name is treated just like any other tag. When this class is called to instantiate it, we build a new node based on the current environment (that is, whatever variables have already been set, including the parameters on the invocation) and macro-insert it. If the inserted result is callable, then the invocation will mark it as a proxy and execute its code on "go", while the result itself will be unmarked as callable - this ensures that the code will run at the point of the invocation, not at the eventual place of insertion of the macro result (which is at the end of the list of children of the parent - not the right place to run it).
build_inplace - defining and instantiating a macro at the same time
In-place instantiation of a "here" macro allows code to be written that expresses a macro expansion at build time.
build_express: instantiating a macro at runtime, *or* expressing a template, depending on what the expressed thing is.
output, iterate
The output function usually diverts to writing, but for macro instantiation it is the input to creating our expression. So we collect it. At the end of the instantiation, we'll evaluate it.
The iterate function (normal output) is disabled for macro calls; the instantiation should do this work.
go
The go function overrides the usual running function of nodes because we're either acting as a proxy for our macro results, or we're going to instantiate at runtime.
AUTHOR
Michael Roberts, <michael at vivtek.com>
BUGS
Please report any bugs or feature requests to bug-decl at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Decl. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
LICENSE AND COPYRIGHT
Copyright 2010 Michael Roberts.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.