NAME

Macro::Micro - really simple templating for really simple templates

VERSION

version 0.055

SYNOPSIS

  use Macro::Micro;

  my $expander = Macro::Micro->new;

  $expander->register_macros(
    ALIGNMENT => "Lawful Good",
    HEIGHT    => sub {
      my ($macro, $object, $stash) = @_;
      $stash->{race}->avg_height;
    },
  );

  $expander->expand_macros_in($character, { race => $human_obj });

  # character is now a Lawful Good, 5' 6" human

DESCRIPTION

This module performs very basic expansion of macros in text, with a very basic concept of context and lazy evaluation.

PERL VERSION

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

METHODS

new

  my $mm = Macro::Micro->new(%arg);

This method creates a new Macro::Micro object.

There is only one valid argument:

  macro_format - this is the format for macros; see the macro_format method

macro_format

  $mm->macro_format( qr/.../ );

This method gets or sets the macro format regexp for the expander.

The format must be a reference to a regular expression, and should have two capture groups. The first should return the entire string to be replaced in the text, and the second the name of the macro found.

The default macro format is: qr/([\[<] (\w+) [>\]])/x

In other words: a probably-valid-identiifer inside angled or square backets.

register_macros

  $mm->register_macros($name => $value, ... );

This method register one or more macros for later expansion. The macro names must be either strings or a references to regular expression. The values may be either strings or references to code.

These macros may later be used for expansion by "expand_macros".

clear_macros

  $mm->clear_macros;

This method clears all registered macros.

get_macro

  my $macro = $mm->get_macro($macro_name);

This returns the currently-registered value for the named macro. If the given macro name is not registered exactly, the name is checked against any regular expression macros that are registered. The first of these to match is returned.

At present, the regular expression macros are checked in an arbitrary order.

expand_macros

  my $rewritten = $mm->expand_macros($text, \%stash);

This method returns the result of rewriting the macros found the text. The stash is a set of data that may be used to expand the macros.

The text is scanned for content matching the expander's "macro_format". If found, the macro name in the found content is looked up with "get_macro". If a macro is found, it is used to replace the found content in the text.

A macros whose value is text is expanded into that text. A macros whose value is code is expanded by calling the code as follows:

  $replacement = $macro_value->($macro_name, $text, \%stash);

Macros are not expanded recursively.

expand_macros_in

  $mm->expand_macros_in($object, \%stash);

This rewrites the content of $object in place, using the expander's macros and the provided stash of data.

At present, only scalar references can be rewritten in place. In the future, there will be a system to define how various classes of objects should be rewritten in place, such as email messages.

string_expander

  my $string_expander = $mm->string_expander($stash);

  my $rewritten_text = $string_expander->($original_text);

This method returns a closure which will expand the macros in text passed to it using the expander's macros and the passed-in stash.

fast_expander is provided as an alias for legacy code.

macro_expander

  my $macro_expander = $mm->macro_expander(\%stash);

This method returns a coderef that can be called as follows:

  $macro_expander->($macro_string, $macro_name);

It should return the string to be used to replace the macro string that was found.

study

  my $template = $expander->study($text);

Given a string, this returns an object which can be used as an argument to expand_macros. Macro::Micro will find and mark the locations of macros in the text so that calls to expand the macros will not need to search the text.

AUTHOR

Ricardo SIGNES <cpan@semiotic.systems>

CONTRIBUTORS

• Hans Dieter Pearcey <hdp@cpan.org>

• Ricardo SIGNES <rjbs@codesimply.com>

• Ricardo Signes <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2005 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.