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

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

=head2 output, iterate

The C<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 C<iterate> function (normal output) is disabled for macro calls; the instantiation should do this work.

=cut

sub output { $_[0]->{output} .= $_[1] }
sub iterate { }

=head2 go

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

=cut

sub go {
   my $self = shift;
   my $instance = shift;
   my $return;

   #return unless $self->{callable};           - Note that this is specifically disabled for macro definitions.
   if ($self->{owncode} && $self->{sub}) {
      $return = &{$self->{sub}}($instance, @_);
   } else {
      foreach ($self->nodes) {
         $return = $_->go ($instance, @_);
      }
   }
   return $return;
}

=head1 AUTHOR

Michael Roberts, C<< <michael at vivtek.com> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-decl at rt.cpan.org>, or through
the web interface at L<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.

=head1 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.

=cut

1; # End of Decl::Semantics::Macro