MAN page from Old RedHat 6.X perl-Text-MacroScript-1.34-6.i386.rpm

MacroScript

Section: User Contributed Perl Documentation (3)
Updated: perl 5.005, patch 03
Index

NAME

Text::MacroScript - A macro pre-processor with embedded perl capability

SYNOPSIS

    use Text::MacroScript ;

    # new() for macro processing

    my $Macro = new Text::MacroScript ;    while( <> ) {        print $Macro->expand( $_ ) if $_ ;    }

    # Canonical use (the filename improves error messages):    my $Macro = new Text::MacroScript ;    while( <> ) {        print $Macro->expand( $_, $ARGV ) if $_ ;    }

    # new() for embedded macro processing

    my $Macro = new Text::MacroScript( -embedded => 1 ) ;     # Delimiters default to <: and :>    # or    my $Macro = new Text::MacroScript( -opendelim => '[[', -closedelim => ']]' ) ;    while( <> ) {        print $Macro->expand_delimited( $_, $ARGV ) if $_ ;    }

    # Create a macro object and create initial macros/scripts from the file(s)    # given:    my $Macro = new Text::MacroScript(                     -file => [ 'local.macro', '~/.macro/global.macro' ]                     ) ;

    # Create a macro object and create initial macros/scripts from the    # definition(s) given:    my $Macro = new Text::MacroScript(                    -macro => [                            [ 'MAX_INT' => '32767' ],                        ],                    -script => [                        [ 'DHM2S' =>                             [                                 my $s = (#0*24*60*60)+(#1*60*60)+(#2*60) ;                                "#0 days, #1 hrs, #2 mins = $s secs"                             ],                        ],                    -variable => [ '*MARKER*' => 0 ],                    ) ;

    # We may of course use any combination of the options.

    my $Macro = new Text::MacroScript( -comment => 1 ) ; # Create the %%[] macro.

    # define()

    $Macro->define( -macro, $macroname, $macrobody ) ;

    $Macro->define( -script, $scriptname, $scriptbody ) ;

    $Macro->define( -variable, $variablename, $variablebody ) ;

    # undefine()

    $Macro->undefine( -macro, $macroname ) ;

    $Macro->undefine( -script, $scriptname ) ;

    $Macro->undefine( -variable, $variablename ) ;

    # undefine_all()

    $Macro->undefine( -macro ) ;

    $Macro->undefine( -script ) ;

    $Macro->undefine( -variable ) ;

    # list()

    @macros    = $Macro->list( -macro ) ;    @macros    = $Macro->list( -macro, -namesonly ) ;

    @scripts   = $Macro->list( -script ) ;    @scripts   = $Macro->list( -script, -namesonly ) ;

    @variables = $Macro->list( -variable ) ;    @variables = $Macro->list( -variable, -namesonly ) ;

    # load_file() - always treats the contents as within delimiters if we are    # doing embedded processing.

    $Macro->load_file( $filename ) ;

    # expand_file() - calls expand_embedded() if we are doing embedded    # processing otherwise calls expand().

    $Macro->expand_file( $filename ) ;    @expanded = $Macro->expand_file( $filename ) ;

        # expand()

    $expanded = $Macro->expand( $unexpanded ) ;    $expanded = $Macro->expand( $unexpanded, $filename ) ;

    # expand_embedded()

    $expanded = $Macro->expand_embedded( $unexpanded ) ;    $expanded = $Macro->expand_embedded( $unexpanded, $filename ) ;

This bundle also includes the macro and macrodir scripts which allows usto expand macros without having to use/understand Text::MacroScript.pm,although you will have to learn the handful of macro commands available andwhich are documented here and in macro. macro provides moredocumentation on the embedded approach.

The macroutil.pl library supplied provides some functions which you maychoose to use in HTML work for example.

DESCRIPTION

Define macros, scripts and variables in macro files or directly in text files.

Commands may appear in separate macro files which are loaded in either via thetext files they process (e.g. via the %LOAD command), or may be embeddeddirectly in text files. Almost every command that can appear in a file has anequivalent object method so that programmers may achieve the same things incode as can be achieved by macro commands in texts; there are also additionalmethods which have no command equivalents.

Most the examples given here use the macro approach. However this module nowdirectly supports an embedded approach and this is now documented. Althoughyou may specify your own delimiters where shown in examples we use the defaultdelimiters of >: and :< throughout.

Public methods

    new         class   object    get         class   object    define              object    undefine            object    list                object    undefine_all        object    load_file           object    expand_file         object    expand              object    expand_embedded     object

Summary of Commands

These commands may appear in separate `macro' files, and/or in the body offiles. Wherever a macroname or scriptname is encountered it will be replacedby the body of the macro or the result of the evaluation of the script usingany parameters that are given.

Note that if we are using an embedded approach commands, macro names andscript names should appear between delimiters. (Except when we %LOAD sincethis assumes the whole file is `embedded'.)

    %DEFINE macroname [macro body]

    %DEFINE macroname    multi-line    macro body    #0, #1 are the first and second parameters if any used    %END_DEFINE

    %UNDEFINE macroname

    %UNDEFINE_ALL   # Undefine all macros

    %DEFINE_SCRIPT scriptname [script body]

    %DEFINE_SCRIPT scriptname    multi-line    script body    arbitrary perl    optional parameters are in @Param, although #0, etc may be used    any variables are in %Var, although #varname may be used    %END_DEFINE

    %UNDEFINE scriptname

    %UNDEFINE_ALL_SCRIPT

    %DEFINE_VARIABLE variablename [variable value]

    %UNDEFINE variablename

    %UNDEFINE_ALL_VARIABLE

    %LOAD[path/filename]    # Instantiate macros/scripts/variables in this                            # file, but discard the text

    %INCLUDE[path/filename] # Instantiate macros/scripts/variables in this                            # file and output the resultant text

    %REQUIRE[path/filename] # Make Perl require a file e.g. of functions,                            # modules, etc. which can then be accessed within                            # scripts.      %CASE [condition]       # Provides #ifdef-type functionality    %END_CASE

Thus, in the body of a file we may have, for example:

    %DEFINE &B [Billericky Rickety Builders]    Some arbitrary text.    We are writing to complain to the &B about the shoddy work they did.

If we are taking the embedded approach the example above might become:

    <:%DEFINE BB [Billericky Rickety Builders]:>    Some arbitrary text.    We are writing to complain to the <:BB:> about the shoddy work they did.

When using an embedded approach we don't have to make the macro or script nameunique within the text, (although each must be distinct from each other),since the delimiters are used to signify them. However since expansion appliesrecursively it is still wise to make names distinctive.

Macro systems vs embedded systems

Macro systems read all the text, substituting anything which matches a macroname with the macro's body (or script name with the result of the execution ofthe script). This makes macro systems slower (they have to check formacro/script names everywhere, not just in a delimited section) and more risky(if we choose a macro/script name that normally occurs in the text we'll endup with a mess) than embedded systems. On the other hand because they work onthe whole text not just delimited bits, macro systems can perform processingthat embedded systems can't. Macro systems are used extensively, for examplethe CPP, C pre-processor, with its #DEFINE's, etc.

Essentially, embedded systems print all text until they hit an openingdelimiter. They then execute any code up until the closing delimiter. The textthat results replaces everything between and including the delimeters. Theythen carry on printing text until they hit an opening delimeter and so onuntil they've finished processing all the text. This module now provides bothapproaches.

Creating macro objects with `new()`

For macro processing:

    my $Macro = Text::MacroScript->new ;

For embedded macro processing:

    my $Macro = Text::MacroScript->new( -embedded => 1 ) ;     # Delimiters default to <: and :>

Or specify your own delimiters:

my $Macro = Text::MacroScript->new( -opendelim => `[[', -closedelim => `]]' ) ;

Or specify one delimiter to use for both (probably not wise):

    my $Macro = Text::MacroScript->new( -opendelim => '%%' ) ;     # -closedelim defaults to -opendelim, e.g. %% in this case

The full list of options that may be specified at object creation:

-comment optional integer; 1 = create the %%[] comment macro; default 0.

-file optional array reference of strings; read macros and scripts from thefile(s) given - they are %LOADed so are treated as already embedded if weare doing embedded processing. Default is a reference to an empty array.

-macro optional array reference of macros, in the form:

    my $Macro = Text::MacroScript->new(                    -macro => [                        ["name1"=>"body1"],                        ["name2"=>"body2"],                        ["name3"=>"body3"],                    ],                    ) ;

Default is a reference to an empty array.

-script optional array reference of scripts, in the form:

    my $Macro = Text::MacroScript->new(                    -script => [                        ["name1"=>"body1"],                        ["name2"=>"body2"],                        ["name3"=>"body3"],                    ],                    ) ;

Default is a reference to an empty array.

-variable optional array reference of variables, in the form:

    my $Macro = Text::MacroScript->new(                    -variable => [                        ["name1"=>"value1"],                        ["name2"=>"value2"],                        ["name3"=>"value3"],                    ],                    ) ;

Default is a reference to an empty array.

-embedded optional integer, 1 = use embedded processing; 0 = use macroprocessing. Default is 0. If set to 1 then the delimiters become <: and :>unless otherwise specified.

-opendelim optional string, default is undef unless -embedded is 1 inwhich case default is <: if -opendelim is undefined or the empty string.

-closedelim optional string, default is undef unless -embedded is 1 inwhich case default is :> if -closedelim is undefined or the empty stringand -opendelim is <: or -opendelim if -opendelim is not <:.

Defining Macros with `%DEFINE` and `define()`

In files we would write:

    %DEFINE MAC [The Mackintosh Macro]

The equivalent method call is:

    $Macro->define( -macro, 'MAC', 'The Mackintosh Macro' ) ;

We can call our macro anything, excluding white-space characters and [,although [ is not advised. So a name like %*&! is fine - indeed names whichcould not normally appear in the text are recommended to avoid having thewrong thing substituted. We should also avoid calling macros, scripts orvariables names beginning with #. All names are case-sensitive.

Note that if we define a macro and then a script with the same name thescript will effectively replace the macro.

We can have parameters (for macros and scripts), e.g.:

    %DEFINE *P [The forename is #0 and the surname is #1]

Parameters used in the source text can contain square brackets since macrowill grab up to the last square bracket on the line. The only thing we can'tpass are `|'s since these are used to separate parameters. White-space betweenthe macro name and the [ is optional in definitions but not allowed in thesource text.

Parameters are named #0, #1, etc. There is a limit of 100 parameters, i.e.#0..#99, and we must use all those we specify. In the example above we mustuse *P[param1|param2], e.g. *P[Jim|Hendrix]; if we don'tText::MacroScript.pm will croak. Note that macro names and their parametersmust all be on the same line (although this is relaxed if you use paragraphmode).

Because we use # to signify parameters if you require text that consists of a# followed by digits then you should escape the #, e.g.

    %DEFINE *GRAY[<font color="\#121212">#0</font>]

We can use as many more parameters than we need, for example add a third todocument: *P[Jim|Hendrix|Musician] will become `The forename is Jim and thesurname is Hendrix', just as in the previous example; the third parameter,`Musician', will simply be thrown away.

If we take an embedded approach we might write this example thus:

    <:%DEFINE P [The forename is #0 and the surname is #1]:>

and in the text, <:P[Jim|Hendrix]:> will be transformed appropriately.

If we define a macro, script or variable and later define the same name thelater definition will replace the earlier one. This is useful for making localmacro definitions over-ride global ones, simply by loading the global onesfirst.

Although macros can have plain textual names like this:

    %DEFINE MAX_INT [32767]

It is generally wise to use a prefix and/or suffix to make sure we don'texpand something unintentionally, e.g.

    %DEFINE $MAX_INT [65535]

Macro expansion is no respector of quoted strings or anything else - if the name matches the expansion will take place!

Multi-line definitions are permitted (here's an example I use with the louttypesetting language):

    %DEFINE SCENE    @Section        @Title {#0}    @Begin    @PP    @Include {#1}    @End @Section    %END_DEFINE

This allows us to write the following in our lout files:

    SCENE[ The title of the scene | scene1.lt ]

which is a lot shorter than the definition.

The body of a macro may not contain a literal null. If you really need onethen use a script and represent the null as chr(0).

Converting a macro to a script

This can be achieved very simply. For a one line macro simply enclose thebody between qq{ and }, e.g.

    %DEFINE $SURNAME [Baggins]

becomes

    %DEFINE_SCRIPT $SURNAME [qq{Baggins}]

For a multi-line macro use a here document, e.g.

    %DEFINE SCENE    @Section        @Title {#0}    @Begin    @PP    @Include {#1}    @End @Section    %END_DEFINE

becomes

    %DEFINE_SCRIPT SCENE    <<__EOT__    \@Section        \@Title {#0}    \@Begin    \@PP    \@Include {#1}    \@End \@Section    __EOT__    %END_DEFINE

Note that the @s had to be escaped because they have a special meaning inperl.

Defining Scripts with `%DEFINE_SCRIPT` and `define()`

Instead of straight textual substitution, we can have some perl executed(after any parameters have been replaced in the perl text):

    %DEFINE_SCRIPT *ADD ["#0 + #1 = " . (#0 + #1)]

or by using the equivalent method call:

    $Macro->define( -script, '*ADD', '"#0 + #1 = " . (#0 + #1)' ) ;

These would be used as *ADD[5|11] in the text which would be output as:

    These would be used as 5 + 11 = 16 in the text...

In script definitions we can use an alternative way of passing parametersinstead of or in addition to the #0 syntax.

This is particularly useful if we want to take a variable number of parameterssince the #0 etc syntax does not provide for this. An array called @Paramis available to our perl code that has any parameters. This allows thingslike the following to be achieved:

    %DEFINE_SCRIPT ^PEOPLE    # We don't use the name hash number params but read straight from the    # array:    my $a = "friends and relatives are " ;    $a .= join ", ", @Param ;    $a ;    %END_DEFINE

The above would expand in the following text:

    Her ^PEOPLE[Anna|John|Zebadiah].

to
Her friends and relatives are Anna, John, Zebadiah.

In addition to having access to the parameters either using the #0 syntax orthe @Param array, we can also access any variables that have been definedusing %DEFINE_VARIABLE (see later). These are accessible either using#variablename similarly to the #0 parameter syntax, or via the %Var hash.Although we can change both @Param and %Var elements in our script,the changes to @Param only apply within the script whereas changes to%Var apply from that point on globally.

Note that if you require a literal # followed by digits in a script body thenyou must escape the # like this \#.

Macro names can be any length and consist of any characters (includingnon-printable which is probably only useful within code), except white-spaceand [, although ] is not recommended and a leading # should be avoided.

Here's a simple date-stamp style:

    %DEFINE_SCRIPT *DATESTAMP    {        my( $d, $m, $y ) = (localtime( time ))[3..5] ;        $m++ ;        $m = "0$m" if $m < 10 ;        $d = "0$d" if $d < 10 ;        $y += 1900 ;        "#0 on $y/$m/$d" ;    }    %END_DEFINE

If we wanted to add the above in code we'd have to make sure the $variablesweren't interpolated:

    $Macro->define( -script, '*DATESTAMP', <<'__EOT__' ) ;    {        my( $d, $m, $y ) = (localtime( time ))[3..5] ;        $m++ ;        $m = "0$m" if $m < 10 ;        $d = "0$d" if $d < 10 ;        $y += 1900 ;        "#0 on $y/$m/$d" ;    }    __EOT__ Here's (a somewhat contrived example of) how the above would be used:

    <HTML>    <HEAD><TITLE>Test Page</TITLE></HEAD>    <BODY>    *DATESTAMP[Last Updated]<P>    This page is up-to-date and will remain valid until *DATESTAMP[midnight]    </BODY>    </HTML>

Thus we could have a file, test.html.m containing:

    %DEFINE_SCRIPT *DATESTAMP    {        my( $d, $m, $y ) = (localtime( time ))[3..5] ;        $m++ ;        $m = "0$m" if $m < 10 ;        $d = "0$d" if $d < 10 ;        $y += 1900 ;        "#0 on $y/$m/$d" ;    }    %END_DEFINE    <HTML>    <HEAD><TITLE>Test Page</TITLE></HEAD>    <BODY>    *DATESTAMP[Last Updated]<P>    This page is up-to-date and will remain valid until *DATESTAMP[midnight]    </BODY>    </HTML>

which when expanded, either in code using $Macro->expand(), or using thesimple macro utility supplied with Text::MacroScript.pm:

    [1]% macro test.html.m > test.html

test.html will contain just this:

    <HTML>    <HEAD><TITLE>Test Page</TITLE></HEAD>    <BODY>    Last Updated on 1999/08/21<P>    This page is up-to-date and will remain valid until midnight on 1999/08/21    </BODY>    </HTML>

Of course in practice we wouldn't want to define everything in-line like this.See %LOAD later for an alternative.

This example written in embedded style might be written thus:

    <:    %DEFINE_SCRIPT DATESTAMP    {        my( $d, $m, $y ) = (localtime( time ))[3..5] ;        $m++ ;        $m = "0$m" if $m < 10 ;        $d = "0$d" if $d < 10 ;        $y += 1900 ;        "#0 on $y/$m/$d" ;    }    %END_DEFINE    :>    <HTML>    <HEAD><TITLE>Test Page</TITLE></HEAD>    <BODY>    <!-- Note how the parameter must be within the delimiters. -->    <:DATESTAMP[Last Updated]:><P>    This page is up-to-date and will remain valid until <:DATESTAMP[midnight]:>    </BODY>    </HTML>

For more (and better) HTML examples see the example file html.macro.

The body of a script may not contain a literal null. If you really need onethen represent the null as chr(0).

Defining Variables with `%DEFINE_VARIABLE` and `define()`

We can also define variables:

    %DEFINE_VARIABLE &*! [89.1232]

or in code:

    $Macro->define( -variable, '&*!', 89.1232 ) ;

Note that there is no multi-line version of %DEFINE_VARIABLE.

All current variables are available inside %DEFINE_SCRIPT scripts in the %Varhash:

    %DEFINE_SCRIPT *TEST1    $a = '' ;    while( my( $key, $val ) each( %Var ) ) {        $a .= "$key = $val\n" ;    }    $a ;    %END_DEFINE

Here's another example:

    %DEFINE_VARIABLE XCOORD[256]
    %DEFINE_VARIABLE YCOORD[112]
        :
    The X coord is *SCALE[X|16] and the Y coord is *SCALE[Y|16]

    %DEFINE_SCRIPT *SCALE
    my $coord = shift @Param ;
    my $scale = shift @Param ;
    my $val   = $Var{$coord} ;
    $val %= scale ; # Scale it
    $val ;
    %END_DEFINE
        Variables may be modified within script %DEFINEs, e.g.

    %DEFINE_VARIABLE VV[Foxtrot]    # VV eq 'Foxtrot'    # other text    # Here we use the #variable synax:    %DEFINE_SCRIPT VV[#VV='Alpha']    # VV eq 'Alpha' - note that we *must* refer to the script (as we've done    # on the line following) for it to execute.    # other text    # Here we use perl syntax:    %DEFINE_SCRIPT VV[$Var{'VV'}='Tango']    # VV eq 'Tango' - note that we *must* refer to the script (as we've done    # on the line following) for it to execute.

As we can see variables support the #variable syntax similarly to parameterswhich support #0 etc and ara available in scripts via the @Param array.Note that changing parameters within a script only apply within the script;whereas changing variables in the %Var hash in a script changes them fromthat point on globally.

Variables are also used with %CASE (covered later).

Loading and including files with `%LOAD` and `load_file()`, and `%INCLUDE` and `expand_file()`

Although we can define macros directly in the files that require them it is oftenmore useful to define them separately and include them in all those that needthem.

One way of achieving this is to load in the macros/scripts first and thenprocess the file(s). In code this would be achieved like this:

    $Macro->load_file( $macro_file ) ; # Loads definitions only, ignores any                                       # other text. If working in embedded                                       # mode the file is treated as if                                       # wrapped in delimiters.    $Macro->expand_file( $file ) ;     # Expands definitions (and instantiates                                       # any definitions that appear in the                                       # file); output is to the current                                       # output filehandle.    my @expanded = $Macro->expand_file( $file ) ; # Output to array.

From the command line it would be achieved thus:

    [2]% macro -f ~/.macro/html.macros test.html.m > test.html

One disadvantage of this approach, especially if we have lots of macro files,is that we can easily forget which macro files are required by which textfiles. One solution to this is to go back to %DEFINEing in the text filesthemselves, but this would lose reusability. The answer to both these problemsis to use the %LOAD command which loads the definitions from the named file atthe point it appears in the text file:

    %LOAD[~/.macro/html.macros]    <HTML>    <HEAD><TITLE>Test Page Again</TITLE></HEAD>    <BODY>    *DATESTAMP[Last Updated]<P>    This page will remain valid until *DATESTAMP[midnight]    </BODY>    </HTML>

The above text has the same output but we don't have to remember or explicitlyload the macros. In code we can simply do this:

    my @expanded = $Macro->expand_file( $file ) ;

or from the command line:

    [3]% macro test.html.m > test.html

    At the beginning of our lout typesetting files we might put this line:

    %LOAD[local.macros]

The first line of the local.macros file is:

    %LOAD[~/.macro/lout.macros]

So this loads both global macros then local ones (which if they have the samename will of course over-ride).

This saves repeating the %DEFINE definitions in all the files and makesmaintenance easier.

%LOAD loads perl scripts and macros, but ignores any other text. Thus we canuse %LOAD, or its method equivalent load_file(), on any file, and itwill only ever instantiate macros and scripts and produce no output. When weare using embedded processing any file %LOADed is treated as if wrapped indelimiters.

If we want to include the entire contents of another file, and perform macroexpansion on that file then use %INCLUDE, e.g.

    %INCLUDE[/path/to/file/with/scripts-and-macros-and-text]

The %INCLUDE command will instantiate any macros and scripts it encountersand include all other lines of text (with macro/script expansion) in theoutput stream.

Macros and scripts are expanded in the following order:1. scripts (longest named first, shortest named last)2. macros (longest named first, shortest named last)

Requiring files using `%REQUIRE`

We often want our scripts to have access to a bundle of functions that we havecreated or that are in other modules. This can now be achieved by:

    %REQUIRE[/path/to/mylibrary.pl]

An example library macroutil.pl is provided with examples of usage inhtml.macro.

There is no equivalent object method because if we're writing code we can`use' or `require' as needed and if we're writing macros then we use%REQUIRE.

Skipping text using `%CASE` and `%END_CASE`

It is possible to selectively skip parts of the text.

    %CASE[0]    All the text here will be discarded.    No matter how much there is.    This is effectively a `comment' case.    %END_CASE

The above is useful for multi-line comments.

We can also skip selectively. Here's an if...then:

    %CASE[#OS eq 'Linux']    Skipped if the condition is FALSE.     %END_CASE

The condition can be any perl fragment. We can use previously definedvariables either using the #variable syntax as shown above or using theexported perl name, thus in this case either #OS, or %Var{'OS'}whichever we prefer.

If the condition is true the text is output with macro/script expansion asnormal; if the condition is false the text is skipped.

The if...then...else structure:

    %DEFINE_VARIABLE OS[Linux]

    %CASE[$Var{'OS'} eq 'Linux']    Linux specific stuff.    %CASE[#OS ne 'Linux']    Non-linux stuff - note that both references to the OS variable are    identical in the expression (#OS is converted internally to $Var{'0S'} so    the eval sees the same code in both cases    %END_CASE

Although nested %CASEs are not supported we can get the same functionality(and indeed more versatility because we can use full perl expressions), e.g.:

    %DEFINE_VARIABLE TARGET[Linux]

    %CASE[#TARGET eq 'Win32' or #TARGET eq 'DOS']    Win32/DOS stuff.    %CASE[#TARGET eq 'Win32']    Win32 only stuff.    %CASE[#TARGET eq 'DOS']    DOS only stuff.    %CASE[#TARGET eq 'Win32' or #TARGET eq 'DOS']    More Win32/DOS stuff.    %END_CASE

Although macro doesn't support nested %CASE's we can still representlogic like this:

    if cond1 then        if cond2            do cond1 + cond2 stuff        else            do cond1 stuff        end if    else        do other stuff    end if

By `unrolling' the expression and writing something like this:

    %CASE[#cond1 and #cond2]        do cond1 + cond2 stuff    %CASE[#cond1 and (not #cond2)]        do cond1 stuff    %CASE[(not #cond1) and (not #cond2)]        do other stuff    %END_CASE

In other words we must fully specify the conditions for each case.

We can use any other macro/script command within %CASE commands, e.g.%DEFINEs, etc., as well as have any text that will be macro/script expandedas normal.

Undefining with `%UNDEFINE` and `undefine()`

Macros and scripts may be undefined in files:

    %UNDEFINE *P    %UNDEFINE_SCRIPT *DATESTAMP    %UNDEFINE_VARIABLE &*!

and in code:

    $Macro->undefine( -macro, '*P' ) ;     $Macro->undefine( -script, '*DATESTAMP' ) ;     $Macro->undefine( -variable, '&*!' ) ;

All macros, scripts and variables can be undefined:

    %UNDEFINE_ALL    %UNDEFINE_ALL_SCRIPT    %UNDEFINE_ALL_VARIABLE

    $Macro->undefine_all( -macro ) ;    $Macro->undefine_all( -script ) ;    $Macro->undefine_all( -variable ) ;

One use of undefining everything is to ensure we get a clean start. We mighthead up our files thus:

    %UNDEFINE_ALL    %UNDEFINE_ALL_SCRIPT    %UNDEFINE_ALL_VARIABLE    %LOAD[mymacros]    text goes here

Listing macros, scripts and variables with `list()`

We can list the macros, scripts and variables in code with list:

    $Macro->list( -macro ) ;

This will print the macros currently defined to the current file handle - ifthere is one. If used in an array context will provide the list one macro perarray element:

    @macros = $Macro->list( -macro ) ;

    # Just give us the macro names:    @macros = $Macro->list( -macro, -nameonly ) ;

There are equivalents for scripts and variables:

    @scripts   = $Macro->list( -script ) ;    @variables = $Macro->list( -variable ) ;

Commenting

Generally the text files that we process are in formats that supportcommenting, e.g. HTML:

    <!-- This is an HTML comment -->

Sometimes however we want to put comments in our macro source files that won'tend up in the output files. One simple way of achieving this is to define amacro whose body is empty; when its called with any number of parameters (ourcomments), their text is thrown away:

    %DEFINE %%[]

which is used like this in texts:

    The comment comes %%[Here | [anything] put here will disappear]here!

The output of the above will be:

    The comment comes here!

We can add the definition in code:

    $Macro->define( -macro, '%%', '' ) ;

Or the macro can be added automatically for us when we create the Macroobject:

    my $Macro = new Text::MacroScript( -comment => 1 ) ;     # All other options may be used too of course.

However the easiest way to comment is to use %CASE:

    %CASE[0]    This unconditionally skips text up until the end marker since the    condition is always false.    %END_CASE

IMPORTABLE FUNCTIONS

In version 1.25 I introduced some useful importable functions. These have nowbeen removed from the module. Instead I supply a perl library macroutil.plwhich has these functions (abspath, relpath, today) since Text::MacroScriptcan now `require' in any library file you like using the %REQUIREdirective.

EXAMPLES

I now include a sample html.macro file for use with HTML documents. It usesthe macrodir program (supplied). The macro examples include macros whichuse relpath and also two macros which will include `new' and `updated'images up until a specified expiry date using variables.

(Also see DESCRIPTION.)

BUGS

Lousy error reporting for embedded perl in most cases.

AUTHOR

Mark Summerfield. I can be contacted as <summerAATTperlpress.com> -please include the word `macroscript' in the subject line.

COPYRIGHT

This module may be used/distributed/modified under the LGPL.

Index

NAME
SYNOPSIS
DESCRIPTION
Public methods
Summary of Commands
Macro systems vs embedded systems
Creating macro objects with new()
Defining Macros with %DEFINE and define()
Defining Scripts with %DEFINE_SCRIPT and define()
Defining Variables with %DEFINE_VARIABLE and define()
Loading and including files with %LOAD and load_file(), and %INCLUDE and expand_file()
Requiring files using %REQUIRE
Skipping text using %CASE and %END_CASE
Undefining with %UNDEFINE and undefine()
Listing macros, scripts and variables with list()
Commenting
IMPORTABLE FUNCTIONS
EXAMPLES
BUGS
AUTHOR
COPYRIGHT

This document was created byman2html,using the manual pages.

MacroScript

NAME

SYNOPSIS

DESCRIPTION

Public methods

Summary of Commands

Macro systems vs embedded systems

Creating macro objects with new()

Defining Macros with %DEFINE and define()

Defining Scripts with %DEFINE_SCRIPT and define()

Defining Variables with %DEFINE_VARIABLE and define()

Loading and including files with %LOAD and load_file(), and %INCLUDE and expand_file()

Requiring files using %REQUIRE

Skipping text using %CASE and %END_CASE

Undefining with %UNDEFINE and undefine()

Listing macros, scripts and variables with list()

Commenting

IMPORTABLE FUNCTIONS

EXAMPLES

BUGS

AUTHOR

COPYRIGHT

Index

Creating macro objects with `new()`

Defining Macros with `%DEFINE` and `define()`

Defining Scripts with `%DEFINE_SCRIPT` and `define()`

Defining Variables with `%DEFINE_VARIABLE` and `define()`

Loading and including files with `%LOAD` and `load_file()`, and `%INCLUDE` and `expand_file()`

Requiring files using `%REQUIRE`

Skipping text using `%CASE` and `%END_CASE`

Undefining with `%UNDEFINE` and `undefine()`

Listing macros, scripts and variables with `list()`