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


version 0.055


  use Macro::Micro;

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

    ALIGNMENT => "Lawful Good",
    HEIGHT    => sub {
      my ($macro, $object, $stash) = @_;

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

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


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


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.



  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


  $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.


  $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".



This method clears all registered macros.


  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.


  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.


  $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.


  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.


  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.


  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.


Ricardo SIGNES <>


  • Hans Dieter Pearcey <>

  • Ricardo SIGNES <>

  • Ricardo Signes <>


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.