User Contributed Perl Documentation          lib::Text::Macros(3)



NAME
    Text::Macros.pm - an object-oriented text macro engine

SYNOPSIS
    use Text::Macros;

     # poetic:
     my $macro_expander = new Text::Macros qw( {{ }} );
     $text = expand_macros $macro_expander $data_object, $text;

     # noisy:
     $macro_expander = Text::Macros->new( "\Q[[", "\Q]]", 1 );
     print $macro_expander->expand_macros( $data_object, $text );


DESCRIPTION
    Typical usage might look like this:

     my $template = <<EOF;
       To: [[ RecipientEmail ]]
       From: [[ SenderEmail ]]
       Subject: Payment Past Due on Account # [[ AccountNum ]]

       Dear [[ RecipientName ]]:
       Your payment of [[ PaymentAmount ]] is [[ DaysPastDue ]] days past due.
     EOF

     # get a data object from somewhere, e.g.:
     my $data_object = $database->get_record_object( 'acctnum' => $account_num );

     # make a macro expander:
     my $macro_expander = Text::Macros->new( "\Q[[", "\Q]]" );

     # expand the macros in the template:
     my $email_text = $macro_expander->expand_macros( $data_object, $template );


    To support this, a "data object" would need to exist which
    would need to define methods which will be used as macro
    names, e.g. like this:

     package RecordObject;
     sub RecipientEmail { $_[0]->{'RecipientEmail'} }
     sub SenderEmail    { $_[0]->{'SenderEmail'}    }
     sub AccountNum     { $_[0]->{'AccountNum'}     }
     sub RecipientName  { $_[0]->{'RecipientName'}  }
     sub PaymentAmount  { $_[0]->{'PaymentAmount'}  }
     sub DaysPastDue    { $_[0]->{'DaysPastDue'}    }


    Alternatively, the data object class might have AUTOLOAD
    defined, for example like this:



perl 5.005, patch 60Last change: 26/Oct/1999                    1






User Contributed Perl Documentation          lib::Text::Macros(3)



     package RecordObject;
     sub AUTOLOAD {
      my $self = shift;
      my $name = $AUTOLOAD;
      $name =~ s/.*:://;
      $self->{$name}
     }


    If this is the case, then the macro expander should be
    instructed not to assert that the macro names encountered
    are valid for the object -- since CAN might fail, even
    though the calls will be handled by AUTOLOAD.  To do this,
    pass a true value for the third value to the constructor:

     my $macro_expander = Text::Macros->new( "\Q[[", "\Q]]", 1 );


    Macros can take arguments.  Any strings which occur inside
    the macro text after the macro name will be passed as
    arguments to the macro method call.  By default, the macro
    name and any arguments are all separated by newlines.  You
    can override this behavior; see the documentation of
    parse_args, below.

    Example:

     $macro_expander = new Macros qw( {{ }} );

     print $macro_expander->expand_macros( $cgi_query,
       "You entered {{ param
        Name }} as your name."
     );


    This will replace the substring

     {{ param
     Name }}

    with the result of calling

     $cgi_query->param("Name")


    (Obviously this example is a little contrived.)

METHODS







perl 5.005, patch 60Last change: 26/Oct/1999                    2






User Contributed Perl Documentation          lib::Text::Macros(3)



    The Constructor

     Text::Macros->new( $open_delim, $close_delim, $no_CAN_check, $parse_args_cr );


    The delimiters are regular expressions; this gives you the
    greatest power in determining how macros are to be detected
    in the text.  But it means that if you simply want them to
    be considered literal strings, then you must quotemeta them.

    Since the macro expander will be calling object methods, you
    have an option:  do you want any encountered macro names to
    be required to be valid for the given object?  Or do you
    have some kind of autoloading in effect, which will handle
    undefined methods?

    If you have some kind of autoloading, pass a true value for
    the third argument to new().  If you want the expander to
    assert CAN for each method, pass false (the default).

    The fourth argument, $parse_args_cr, is a reference to a sub
    which implements your macro argument parsing policy.  See
    the section on parse_args, below.

    The Main Method: Expand Macros

     $text = $macro_expander->expand_macros( $data_object, $text );


    The $data_object argument is not an object of the Macros
    package.  Rather, this is the object upon which the macro
    will be called as a method.

    expand_macros() returns the result of replacing all the
    macros it finds with their appropriate expansions.  Note
    that recursion can occur; that is, if the expansion of a
    macro results in text which also contains a valid macro,
    that new macro will also be expanded.  The text will be
    scanned for macros, and those macros will be expanded, until
    none are found.

    A Utility Method: Call Macro

     $macro_expander->call_macro( $data_object, $macro_name, @arguments );


    This is used internally by expand_macros(), but you can call
    it directly if you wish.

    Essentially all this does is this:

     $macro_expander->call_macro( $data_object, $macro_name, @arguments );



perl 5.005, patch 60Last change: 26/Oct/1999                    3






User Contributed Perl Documentation          lib::Text::Macros(3)



    results in the call:

     $data_object->$macro_name( @arguments );


    All the macros supported by the data object can be
    predefined, or you might have some kind of autoloading
    mechanism in place for it.  If you have autoloading in
    effect, you should have passed a true value as the third
    argument to new().  If you pass false (the default), the
    call_macro() will check to see that the object CAN do the
    method; and if it can't an exception will be thrown.

    Note: data objects' macro methods must return a string.
    They can take any number of arguments, which will all be
    strings.

    Parsing the Macro Arguments: parse_args

    This is used internally by expand_macros().

    expand_macros tries to call the sub which was passed by
    reference as the fourth argument to new(), if there was one.
    If no such coderef was given to the constructor, then
    expand_macros calls the parse_args method in the
    Text::Macros class, which implements the default behavior of
    splitting the arg text on newlines, triming off
    leading/trailing whitespace, and then dropping any list
    elements which are '' (empty strings).

    To implement some behavior other than the default, you may
    derive a class from Text::Macros which overrides parse_args.
    The parse_args method takes the Text::Macros object
    reference as the first arg (as usual), and the macro text as
    the second argument.  This is all the text between the
    delimiters, as it occurs in the template text.  This method
    is responsible for extracting the macro name and the values
    of any arguments from the macro text.  It is advisable that
    the parse_args routine strip any leading and trailing
    whitespace from the argument values.  (It happens
    automatically for the macro name, though, so you needn't
    worry about that.)

    Example:

     package MyMacroParser;
     @ISA = qw( Text::Macros );
     sub parse_args {
        my( $self, $macro_text ) = @_;
        # return a list of args extracted from $macro_text...
     }




perl 5.005, patch 60Last change: 26/Oct/1999                    4






User Contributed Perl Documentation          lib::Text::Macros(3)



    And then, of course, you would instantiate a MyMacroParser
    rather than a Text::Macros.  Everything else about its usage
    would be identical.

    If you prefer, you can redefine the Text::Macros::parse_args
    sub directly. That might look something like this:

     *Text::Macros::parse_args = sub {
        my( $self, $macro_text ) = @_;
        # return a list of args extracted from $macro_text...
     };


    Alternatively, you may pass a code reference as the fourth
    argument to new().  The arguments to and results from this
    sub are the same as for the parse_args method, as described
    above, even though it is not (necessarily) a method itself.

    The precedence is this: if a sub was passed to new(), that
    is called; if not, the parse_args() of the derived class is
    called, if defined; if not, the parse_args() of the base
    class (Text::Macros) is called.

EXAMPLES
    Brief examples of all these usage techniques can be found in
    the test script, test.pl, which accompanies this
    distribution.  Any questions can be directed to the author
    via email.

AUTHOR
    [email protected] (John Porter)

COPYRIGHT
    This module is free software; you may redistribute it and/or
    modify it under the same terms as Perl itself.




















perl 5.005, patch 60Last change: 26/Oct/1999                    5

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.