view release on metacpan or  search on metacpan

lib/Decl/Semantics/Macro.pm  view on Meta::CPAN

package Decl::Semantics::Macro;

use warnings;
use strict;

use base qw(Decl::Node);
use Data::Dumper;

=head1 NAME

Decl::Semantics::Macro - defines or instantiates a macro.

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.01';


=head1 SYNOPSIS

The C<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.

=head2 defines(), tags_defined()

Called by Decl::Semantics during import, to find out what xmlapi tags this plugin claims to implement.

=cut
sub defines { ('define', 'express', '<=') }
our %build_handlers = ();
sub tags_defined { Decl->new_data(<<EOF); }
define
express
<=
EOF

=head2 build_payload ()

The C<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.

=cut
sub build_payload {
   my ($self) = @_;
   
   if ($self->code || $self->bracket) {  # Handle basic code macros.
      Decl::Semantics::Code::build_macro_payload($self);
   }
   $self->build_children();
   if ($self->is('define'))  { $self->build_define;  return; }
   if ($self->is('<='))      { $self->build_inplace; return; }
   if ($self->is('express')) { $self->build_express; return; }
   
   $self->{force_text} = 1;  # We don't want any of our children built; they're treated as text.
   $self->instantiate;
   1;
}

=head2 build_define - defining a macro

Actually, definition of a macro doesn't do a lot.  All the good stuff happens at instantiation.

=cut

sub build_define {
   my ($self) = @_;
   my $macroname = $self->name;
   $self->{instantiated} = 0;
   $self->root()->{macro_definitions}->{$macroname} = $self;
   $self->root()->register_builder (ref ($self), $self->parameter('domain', 'core'), Decl->new_data(<<"   EOF"));
      $macroname
   EOF
}

=head2 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