view release on metacpan or  search on metacpan

lib/Macro/Micro.pm  view on Meta::CPAN

use strict;
use warnings;
package Macro::Micro 0.055;
# ABSTRACT: really simple templating for really simple templates

use Carp ();

#pod =head1 SYNOPSIS
#pod
#pod   use Macro::Micro;
#pod
#pod   my $expander = Macro::Micro->new;
#pod
#pod   $expander->register_macros(
#pod     ALIGNMENT => "Lawful Good",
#pod     HEIGHT    => sub {
#pod       my ($macro, $object, $stash) = @_;
#pod       $stash->{race}->avg_height;
#pod     },
#pod   );
#pod
#pod   $expander->expand_macros_in($character, { race => $human_obj });
#pod
#pod   # character is now a Lawful Good, 5' 6" human
#pod
#pod =head1 DESCRIPTION
#pod
#pod This module performs very basic expansion of macros in text, with a very basic
#pod concept of context and lazy evaluation.
#pod
#pod =method new
#pod
#pod   my $mm = Macro::Micro->new(%arg);
#pod
#pod This method creates a new Macro::Micro object.
#pod
#pod There is only one valid argument:
#pod
#pod   macro_format - this is the format for macros; see the macro_format method
#pod
#pod =cut

my $DEFAULT_MACRO_FORMAT = qr/(?<!\\)([\[<] (\w+) [>\]])/x;

sub new {
  my ($class, %arg) = @_;

  my $self = bless { } => $class;

  $arg{macro_format} = $DEFAULT_MACRO_FORMAT unless $arg{macro_format};

  $self->macro_format($arg{macro_format});

  return $self;
}

#pod =method macro_format
#pod
#pod   $mm->macro_format( qr/.../ );
#pod
#pod This method gets or sets the macro format regexp for the expander.
#pod
#pod The format must be a reference to a regular expression, and should have two
#pod capture groups.  The first should return the entire string to be replaced in
#pod the text, and the second the name of the macro found.
#pod
#pod The default macro format is:  C<< qr/([\[<] (\w+) [>\]])/x >>
#pod
#pod In other words: a probably-valid-identiifer inside angled or square backets.
#pod
#pod =cut

sub macro_format {
  my $self = shift;

  return $self->{macro_format} unless @_;

  my $macro_format = shift;
  Carp::croak "macro format must be a regexp reference"
    unless ref $macro_format eq 'Regexp';

  $self->{macro_format} = $macro_format;
}

#pod =method register_macros
#pod
#pod   $mm->register_macros($name => $value, ... );
#pod
#pod This method register one or more macros for later expansion.  The macro names
#pod must be either strings or a references to regular expression.  The values may
#pod be either strings or references to code.
#pod
#pod These macros may later be used for expansion by C<L</expand_macros>>.
#pod
#pod =cut

sub register_macros {
  my ($self, @macros) = @_;

  for (my $i = 0; $i < @macros; $i += 2) {
    my ($name, $value) = @macros[ $i, $i+1 ];
    Carp::croak "macro value must be a string or code reference"
      if (ref $value) and (ref $value ne 'CODE');

    if (not ref $name) {
      $self->{macro}{$name} = $value;
    } elsif (ref $name eq 'Regexp') {
      $self->{macro_regexp}{$name} = [ $name, $value ];