NAME
    Text::MetaText - Perl extension implementing meta-language for
    processing "template" text files.

SYNOPSIS
        use Text::MetaText;
        my $mt = new Text::MetaText;
        print $mt->process($filename, \%vardefs);

SUMMARY OF METATEXT DIRECTIVES
        %% DEFINE variable=value %%   # define variable(s)

        %% SUBST variable  %%         # insert variable value
        %% variable %%                # short form of above

        %% BLOCK blockname %%         # define a block 'blockname'
           block text... 
        %% ENDBLOCK %%

        %% INCLUDE blockname %%       # include 'blockname' block text
        %% INCLUDE filename  %%       # include external file 'filename'

        %% INCLUDE file_or_block      # a more complete example...
           variable=value             # additional variable definition(s)
           if=condition               # conditional inclusion
           format=format_string       # printf-like format string with '%s'
           filter=fltname(params)     # post-process filter 
        %%

        %% TIME                       # current system time, as per time(2)
           format=format_string       # display format, as per strftime(3C) 
        %%

DESCRIPTION
    MetaText is a text processing and markup meta-language which can
    be used for processing "template" files. This module is a Perl 5
    extension implementing a MetaText object class which processes
    text files, interpreting and acting on the embedded MetaText
    directives within.

    Like a glorified pre-processor, MetaText can; include files,
    define and substitute variable values, execute conditional
    actions based on variables, call other perl functions or object
    methods and capture the resulting output back into the document,
    and more. It can format the resulting output of any of these
    operations in a number of ways. The objects, and inherently, the
    format and symantics of the MetaText langauge itself, are highly
    configurable.

    MetaText was originally designed to aid in the creation of html
    documents in a large web site. It remains well suited for this
    and similar tasks, being able to create web pages (dynamically
    or statically) that are consistent with each other, yet easily
    customisable:

    *   standard headers, footers and other elements can be defined in
        separate files and then inserted into web documents:

            %% INCLUDE header %%

    *   variables can be defined externally or from within a document,
        then can be substituted back into the text. This is useful
        for including your %% name %% or %% email %% address or any
        other variable, and for encoding URL's or file paths that
        can then be changed en masse. e.g.

            <img src="%% imgroot %%/foo/bar.gif">

    *   conditional actions can be made based on variable definitions,
        allowing easily and instantly customisable web pages. e.g

            %% INCLUDE higraphics/header if="higfx && userid != abw" %%

    *   blocks of text can be internally defined simplifying the
        creation of repetitive elements. e.g.

            %% BLOCK table_row %%
            <tr> <td>%% userid %%</td> <td>%% name %%</td> </tr>
            %% ENDBLOCK %%

            %% INCLUDE table_row userid=lwall  name="Larry Wall"         %%
            %% INCLUDE table_row userid=tomc   name="Tom Christiansen"   %%
            %% INCLUDE table_row userid=merlyn name="Randal L. Schwartz" %%

    *   in addition, the metapage utility is a script which can
        automatically traverse document trees, processing updated
        files to assist in web document management and other similar
        tasks.

PREREQUISITES
    MetaText requires Perl 5.004 or later. The Date::Format module
    should also be installed. This is available from CPAN (in the
    "TimeDate" distribution) as described in the following section.

OBTAINING AND INSTALLING THE METATEXT MODULE
    The MetaText module is available from CPAN. As the 'perlmod' man
    page explains:

        CPAN stands for the Comprehensive Perl Archive Network.
        This is a globally replicated collection of all known Perl
        materials, including hundreds of unbunded modules.  

        [...]

        For an up-to-date listing of CPAN sites, see
        http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .

    Within the CPAN archive, MetaText is in the "Text::" group which
    forms part of the the category:

      *) String Processing, Language Text Processing, 
         Parsing and Searching

    The module is available in the following directories:

        /modules/by-module/Text/Text-MetaText-<version>.tar.gz
        /authors/id/ABW/Text-MetaText-<version>.tar.gz

    For the latest information on MetaText or to download the latest
    pre-release/beta version of the module, consult the definitive
    reference, the MetaText Home Page:

        http://www.kfs.org/~abw/perl/metatext/

    MetaText is distributed as a single gzipped tar archive file:

        Text-MetaText-<version>.tar.gz

    Note that "<version>" represents the current MetaText Revision
    number, of the form "0.14". See the REVISION manpage below to
    determine the current version number for Text::MetaText.

    Unpack the archive to create a MetaText installation directory:

        gunzip Text-MetaText-<version>.tar.gz
        tar xvf Text-MetaText-<version>.tar

    'cd' into that directory, make, test and install the MetaText
    module:

        cd Text-MetaText-<version>
        perl Makefile.PL
        make
        make test
        make install

    The 't' sub-directory contains a number of small sample files
    which are processed by the test script (called by 'make test').
    See the README file in that directory for more information. A
    logfile (test.log) is generated to report any errors that occur
    during this process. Please note that the test suite is
    incomplete and very much in an 'alpha' state. Any further
    contributions here are welcome.

    The 'make install' will install the module on your system. You
    may need root access to perform this task. If you install the
    module in a local directory (for example, by executing "perl
    Makefile.PL LIB=~/lib" in the above - see `perldoc MakeMaker'
    for full details), you will need to ensure that the PERL5LIB
    environment variable is set to include the location, or add a
    line to your scripts explicitly naming the library location:

        use lib '/local/path/to/lib';

    The metapage utility is a script designed to automate MetaText
    processing of files. It can traverse directory trees, identify
    modified files (by comparing the time stamp of the equivalent
    file in both "source" and "destination" directories), process
    them and direct the resulting output to the appropriate file
    location in the destination tree. One can think of metapage as
    the MetaText equivalent of the Unix make(1S) utility.

    The installation process detailed above should install metapage
    in your system's perl 'installbin' directory (try `perl '-
    V:installbin'' to check this location). See the metapage
    documentation (`perldoc metapage') for more information on
    configuring and using metapage.

USING THE METATEXT MODULE
    To import and use the MetaText module the following line should
    appear in your Perl script:

        use Text::MetaText;

    MetaText is implemented using object-oriented methods. A new
    MetaText object is created and initialised using the
    Text::MetaText->new() method. This returns a reference to a new
    MetaText object.

        my $mt = Text::MetaText->new;

    A number of configuration options can be specified when creating
    a MetaText object. A reference to a hash array of options and
    their associated values should be passed as a parameter to the
    new() method.

        $my $mt = Text::MetaText->new( { 'opt1' => 'val1', 'opt2' => 'val2' } );

    The configurations options available are described in full
    below. All keywords are treated case-insensitively (i.e. "LIB",
    "lib" and "Lib" are all considered equal).

    LIB The INCLUDE directive causes the external file specified
        ("INCLUDE <file>") to be imported into the current document.
        The LIB option specifies one or more directories in which
        the file can be found. Multiple directories should be
        separated by a colon or comma. The current directory is also
        searched by default.

            my $mt = Text::MetaText->new( { LIB => "/tmp:/usr/metatext/lib" } );

    CASE
        The default behaviour for MetaText is to treat variable
        names and identifiers case insensitively. Thus, the
        following are treated identically:

            %% INCLUDE foo %%
            %% INCLUDE FOO %%

        Setting the CASE option to any non-zero value causes the
        document to be processed case sensitively.

            my $mt = Text::MetaText->new( { CASE => 1 } ); # case sensitive

        Note that the configuration options described in this
        section are always treated case insensitively regardless of
        the CASE setting.

    MAGIC
        MetaText directives are identifed in the document being
        processed as text blocks surrounded by special "magic"
        identifers. The default identifiers are a double percent
        string, "%%", for both opening and closing identifiers.
        Thus, a typical directive looks like:

            %% INCLUDE some/file %%
            
        and may be embedded within other text:

            normal text, blah, blah %% INCLUDE some/file %% more normal text

        The MAGIC option allows new identifiers to be defined. A
        single value assigned to MAGIC defines a token to be used
        for both opening and closing identifiers:

            my $mt = Text::MetaText->new( { MAGIC => '++' } );

            ++ INCLUDE file ++

        A reference to an array providing two values (elements 0 and
        1) indicates separate tokens to be used for opening and
        closing identifiers:

            my $mt = Text::MetaText->new( { MAGIC => [ '<!--', '-->' ] } );

            <!-- INCLUDE file -->

    CHOMP
        When MetaText processes a file it identifies directives and
        replaces them with the result of whatever magical process
        the directive represents (e.g. file contents for an INCLUDE,
        variable value for a SUBST, etc). Anything outside the
        directive, including newline characters, are left intact.
        Where a directive is defined that has no corresponding
        output (DEFINE, for example, which silently sets a variable
        value), the trailing newline characters can leave large
        tracts of blank lines in the output documents.

        For example:

          line 1
          %% DEFINE f="foo" %%
          %% DEFINE b="bar" %%
          line 2 

        Produces the following output:

          line 1

          line 2

        This happens because the newline characters at the end of
        the second and third lines are left intact in the output
        text.

        Setting CHOMP to any true value will remove any newline
        characters that appear immediately after a MetaText
        directive. Any characters coming between the directive and
        the newline, including whitespace, will override this
        behaviour and cause the intervening characters and newline
        to be output intact.

        With CHOMP set, the following example demonstrates the
        behaviour:

          line 1
          %% DEFINE f="foo" %%
          %% DEFINE b="bar" %%<space>
          line 2

        Produces the following output (Note that "<space>" is
        intended to represent a single space character, not the
        string "<space>" itself, although the effect would be
        identical):

          line 1
          <space>
          line 2

    FILTER
        There may be times when you may want to INCLUDE a file or
        element in a document but want to filter the contents in
        some way. You may wish to escape (i.e. prefix with a
        backslash '\') certain characters such as quotes, search for
        certain text and replace with an alternative phrase, or
        perform some other post-processing task. The FILTER option
        allows you to define one or more code blocks that can be
        called as filter functions from an INCLUDE directive. Each
        code block is given a unique name to identify it and may
        have calling parameters (parenthesised and separated by
        commas) that can be specified as part of the directive. e.g.

            %% INCLUDE foo filter="slurp(prm1, prm2, ...)" %%

        Two default filters are pre-defined: escape() and sr().
        escape() takes as a parameter a perl-like regular expression
        pattern that indicates characters that should be 'escaped'
        (i.e. prefixed by a backslash '\') in the text. For example,
        to escape any of the character class `["'\]' you would
        specify the filter as:

            %% INCLUDE foo filter="escape([\"'\\])" %%

        The second filter, sr(), takes two arguments, a search
        string and a replace string. A simple substitution is made
        on the included text. e.g.

            %% INCLUDE foo filter="sr(spam, \"processed meat\")" %%

        Note that quotes and other special metacharacters should be
        escaped within the filter string as shown in the two
        examples above.

        Additional filters can be specified by passing a reference
        to a hash array that contains the name of the filter and the
        code itself in each key/value pair. Your filter function
        should be designed to accept the name of the function as the
        first parameter, followed by a line of text to be processed.
        Any additional parameters specified in the INCLUDE directive
        follow. The filter function is called for each line of an
        INCLUDE block and should return the modified text.

        Example:

            my $mt = Text::MetaText->new( { 
                FILTER => {
                    'xyzzy' => sub { 
                         my ($filtername, $text, @params) = @_;
                         $text = # do something here...
                         $text;  # return modified text
                    }
                }
            } );

            %% INCLUDE file1 filter="xyzzy(...)" %%

        A new FILTER definition will replace any existing filter
        with the same name.

    EXECUTE
        The SUBST directive performs a simple substitution for the
        value of the named variable. In the example shown below, the
        entire directive, including the surrounding 'magic' tokens
        '%%', is replaced with the value of the variable 'foo':

            %% SUBST foo %%  (or more succinctly, %% foo %%)

        If the named variable has not been defined, MetaText can
        interpret the variable as the name of an object method in
        the current class or as a function in the main package.

        If the EXECUTE flag is set to any true value, the MetaText
        processor will interpret the variable as an object method
        and attempt to apply it to its own object instance (i.e.
        $self->$method(...)). If the method is not defined, the
        processor fails quietly (but see ROGUE below to see what can
        happen next). This allows classes to be derived from
        MetaText that implement methods that can be called (when
        EXECUTE == 1) as follows:

            %% method1 ... %%       # calls $self->method1(...);
            %% method2 ... %%       # calls $self->method2(...);

        The text returned from the method is used as a replacement
        value for the directive.

        The following pseudo-code example demonstrates this:

            package MyMetaText;
            @ISA = qw( Text::MetaText );

            sub foo { "This is method 'foo'" }  # simple return string
            sub bar { "This is method 'bar'" }  # "        "         "

            package main;

            my $mt = MyMetaText->new( { EXECUTE => 1 } );
            print $mt->process("myfile");

        which, for the file 'myfile':

            %% foo %%
            %% bar %%

        generates the following output:

            This is method 'foo'
            This is method 'bar'

        If the EXECUTE flag is set to a value > 1 and the variable
        name does not correspond to a class method, the processor
        tries to interpret the variable as a function in the main
        package. Like the example above, the processor fails
        silently if the function is not defined (but see ROGUE
        below).

        The following pseudo-code extract demonstrates this:

            my $mt = Text::MetaText->new( { EXECUTE => 2 } );
            print $mt->processs("myfile");

            sub foo { "This is function 'foo'" }  # simple return string
            sub bar { "This is fucntion 'bar'" }  # "        "         "
                
        which, for the file 'myfile':

            %% foo %%
            %% bar %%

        generates the following output:

            This is function 'foo'
            This is function 'bar'

        Any additional parameters specified in the directive are
        passed to the class method or function as a hash array
        reference. The original parameter string is also passed.
        Note that the first parameter passed to class methods is the
        MetaText (or derivative) object reference itself.

        Example:

            %% foo name="Seuss" title="Dr" %%

        causes the equivalent of (when EXECUTE is any true value):

            $self->foo(                                  # implicit $self ref
                { 'name' => 'Seuss', 'title' => 'Dr' },  # hash ref of params
                  'name="Seuss" title="Dr"' );           # parameter string

        and/or (when EXECUTE > 1):

            &main::foo(
                { 'name' => 'Seuss', 'title' => 'Dr' },  # hash ref of params
                  'name="Seuss" title="Dr"' );           # parameter string

    ROGUE
        This configuration item determines how MetaText behaves when
        it encounters a directive it does not recognise. The ROGUE
        option may contain one or more of the ROGUE keywords
        separated by any non-word character. The keywords and their
        associated meanings are:

            warn    Issue a warning (via the ERROR function, if 
                    specified) when the directive is encountered.

            delete  Delete any unrecognised directives.

        The default behaviour is to silently leave any unrecognised
        directive in the processed text.

        Example:

            my $mt = Text::MetaText->new( { ROGUE => "delete,warn" } );

    DELIMITER
        The DELIMITER item specifies the character or character
        sequence that is used to delimit lists of data. This is
        used, for example, by the "in" operator which can be used in
        evaluation conditions. e.g.

            %% INCLUDE hardenuf if="uid in abw,wrigley" %%

        In this case, the condition evaluates true if the uid
        variable contains the value "abw" or "wrigley". The default
        delimiter character is a comma.

        The example:

            my $mt = Text::MetaText->new( { DELIMITER => ":" } );

        would thus correctly process:

            %% INCLUDE hardenuf if="uid in abw:wrigley" %%

    ERROR
        The ERROR configuration item allows an alternative error
        reporting function to be specified for error handling. The
        function should expect a printf() like calling convention.

        Example:

            my $mt = Text::MetaText->new( { 
                ERROR => sub {
                    my ($format, @params) = @_;
                    printf(STDERR "ERROR: $format", @params);
                }
            } );

    DEBUG
        The DEBUG item allows an alternative debug function to be
        provided. The function should expect a printf() like calling
        convention, as per the ERROR option described above. The
        default DEBUG function sends debug messages to STDERR,
        prefixed by a debug string: 'D> '.

    DEBUGLEVEL
        The DEBUGLEVEL item specifies which, if any, of the debug
        messages are displayed during the operation of the MetaText
        object. Like the ROGUE option described above, the
        DEBUGLEVEL value should be constructed from one or more of
        the following keywords:

            none      no debugging information (default)
            info      general processing information
            config    MetaText object configuration items
            preproc   pre-processing phase
            process   processing phase
            postproc  post-processing phase
            data      additional data parameters in debug messages
            content   content of pre-processed INCLUDE blocks
            function  list functions calls as executed
            evaluate  trace conditional evaluations
            test      used for any temporary test code
            all       all of the above (excluding "none", obviously)

        Example:

            my $mt = Text::MetaText->new( { 
                DEBUGLEVEL => "preproc,process,data" 
            } );

    MAXDEPTH
        It is possible for MetaText to become stuck in an endless
        loop if a circular dependancy exists between one or more
        files. For example:

            foo:
                %% INCLUDE bar %%

            bar:
                %% INCLUDE foo %%

        To detect and avoid such conditions, MetaText allows files
        to be nested up to MAXDEPTH times. By default, this value is
        32. If you are processing a file which has nested INCLUDE
        directives to a depth greater than 32 and MetaText returns
        with a "Maximum recursion exceeded" warning, set this
        confiuration item to a higher value. e.g.

            my $mt = Text::MetaText->new( { MAXDEPTH => 42 } );

PROCESSING TEXT
    The MetaText process() method is called to process a file,
    interpreting any MetaText directives embedded within it. The
    first parameter should be the name of the file which should
    reside in the current working directory or in one of the
    directories specified in the LIB configuration option. A
    filename starting with a slash '/' is considered to be an
    absolute path. The optional second parameter may be a reference
    to a hash array containing a number of variable/value
    definitions that should be pre-defined when processing the file.

        print $mt->process("somefile", { name => "Fred" });

    If "somefile" contains:

        Hello %% name %%

    then the output generated would be:

        Hello Fred

    Pre-defining variables in this way is equivalent to using the
    DEFINE directive (described below) at the start of the INCLUDE
    file

        %% DEFINE name="Fred" %%
        Hello %% name %%

    The process() function will continue until it reaches the end of
    the file or a line containing the pattern "__END__" by itself
    ("END" enclosed by double underscores, no other characters or
    whitespace on the line). Note that the pre-processor (a private
    method which is called by process(), so feel free to forget all
    about it) *does* scan past any __END__ marker. In practice, that
    means you can define blocks *after*, but use them *before*, the
    __END__ marker. e.g.

        Martin, %% INCLUDE taunt %%

        __END__                 << processor stops here and ignores 
                                   everything following
        %% BLOCK taunt %%       << but the pre-processor has correctly 
        you Camper!                continued and parsed this block so that
        %% ENDBLOCK %%             it can be included in the main body

    produces the output:

        Martin, you Camper!

    The process() function returns a string containing the processed
    file or block output.

        my $output = $mt->process("myfile");
        print $output;

METATEXT DIRECTIVES
    A MetaText directive is a block of text in a file that is
    enclosed by the MAGIC identifiers (by default '%%'). A directive
    may span multiple lines and may include blank lines within in.
    Whitespace within a directive is generally ignored except where
    quoted as part of a specific value.

        %% DEFINE
           name    = Yorick
           age     = 30
           comment = "A fellow of infinite jest"
        %%

    The first word of the directive indicates the directive type.
    Directives may be specified in upper, lower or mixed case,
    irrespective of the CASE sensitivity flag (which affects only
    variable names). The general convention is to specify the
    directive type in UPPER CASE to aid clarity.

    The MetaText directives are:

    DEFINE
        Define the values for one or more variables

    SUBST
        Substitute the value of a named variable

    INCLUDE
        Process and include the contents of the named file or block

    BLOCK
        Define a named block which can be subsequently INCLUDE'd

    ENDBLOCK
        Marks the end of a BLOCK definition

    To improve clarity and reduce excessive, unnecessary and
    altogether undesirable verbosity, a directive block that doesn't
    start with a recognised MetaText directive is assumed to be a
    'SUBST' variable substitution. Thus,

        %% SUBST foo %%

    can be written more succinctly as

        %% foo %%

    When MetaText processes directives, it is effectively performing
    a "search and replace". The MetaText directive block is replaced
    with whatever text is appropriate for the directive specified.
    Generally speaking, MetaText does not alter any text content or
    formatting outside of directive blocks. The only exception to
    this rule is when CHOMP is turned on (see the section on "USING
    THE METATEXT MODULE") and newlines immediately following a
    directive are subsequently deleted.

  DEFINE

    The DEFINE directive allows simple variables to be assigned
    values. Multiple variables may be defined in a single DEFINE
    directive.

        %% DEFINE 
           name  = Caliban
           quote = "that, when I waked, I cried to dream again."
        %%

    Variables defined within a file or passed to the process()
    function as a hash array remain defined until the file or block
    is processed in entirety. Variable values will be inherited by
    any nested files or blocks INCLUDE'd into the file. Re-
    definitions of existing variables will persist within the file
    or block, masking any existing values, until the end of the file
    or block when the previous values will be restored.

    The following example illustrates this:

        foo:
            Hello %% name %%              # name assumes any predefined value
            %% DEFINE name=tom %%
            Hello %% name %%              # name = 'tom'
            %% INCLUDE bar name='dick' %% # name = 'dick' for "INCLUDE bar"
            Hello %% name %%              # name = 'tom'

        bar:
            Hello %% name %%              # name = 'dick'
            %% DEFINE name='harry' %%     # name = 'harry'
            Hello %% name %%

    Processing the file 'foo' as follows:

        print $mt->process('foo', { 'name' => 'nobody' });

    produces the following output (with explanatory comments added
    for clarity):

        Hello nobody                      # value from process() hash 
        Hello tom                         # from foo
        Hello dick                        # from bar
        Hello harry                       # re-defined in bar
        Hello tom                         # restored to previous value in foo

  SUBST

    A SUBST directive performs a simple variable substitution. If
    the variable is defined, its value will be inserted in place of
    the directive.

    Example:

        %% DEFINE name=Jake %%
        Hello %% SUBST name %%  

    generates the following output:

        Hello Jake

    The SUBST keyword can be omitted for brevity. Thus "%% name %%"
    is processed identically to "%% SUBST name %%".

    If the variable is undefined, the MetaText processor will,
    according to the value of the EXECUTE configuration value, try
    to execute a class method or a function in the main package with
    the same name as the SUBST variable. If EXECUTE is set to any
    true value, the processor will try to make a corresponding
    method call for the current object (that is, the current
    instantiation of the MetaText or derived class). If no such
    method exists and EXECUTE is set to any value greater than 1,
    the processor will then try to execute a function in the main
    package with the same name as the SUBST variable In either case,
    the text returned from the method or function is included into
    the current block in place of the SUBST directive (non-text
    values are automatically coerced to text strings). If neither a
    variable, method or function exists, the SUBST directive will
    either be deleted or left intact (and additionally, a warning
    may be issued), depending on the value of the ROGUE
    configuration item.

    See EXTENDING METATEXT below for more information on deriving
    MetaText classes and using EXECUTE to extend the meta-language.

    The "format" and "filter" options as described in the INCLUDE
    section below are applied to the processed SUBST result before
    being inserted back into the document.

    Some MetaText variables have a special meaning. Unless
    specifically defined otherwise, the variable(s) listed below
    generate the following output:

        TIME    The current system time in seconds since the epoch, 
                00:00:00 Jan 1 1970.  Use the "format" option to 
                specify a time/date format.

  INCLUDE

    The INCLUDE directive instructs MetaText to load and process the
    contents of the file or block specified. If the target is a
    file, it should reside in the current directory or a directory
    specified in the LIB configuration variable. Alternatively, the
    target may be a text block specified with BLOCK..ENDBLOCK
    directives (see below).

        %% INCLUDE chapter1 %%

    The target may also be a variable name and should be prefixed
    with a '$' to identify it as such. On evaluation, the value of
    the named variable will be used as the target:

    Example:

        %% DEFINE chapter=ch1 %%
        %% INCLUDE $chapter   %%  
        
    is equivalent to:

        %% INCLUDE ch1 %%

    Additional variables may be defined for substitution within the
    file:

        %% INCLUDE chapter2 bgcolor=#ffffff title="Chapter 2" %%

    The contents of the file "chapter2":

        <html><head><title>%%title%%</title></head>
        <body bgcolor="%% bgcolor %">
          ...
        </body>

    would produce the output:

        <head><title>Chapter 2</title></head>
        <body bgcolor="#ffffff">
          ...
        </body>

    Defining variables in this way is equivalent to using the DEFINE
    directive. Variables remain in scope for the lifetime of the
    file being processed and then revert to any previously defined
    values (or undefined). Any additional files processed via
    further INCLUDE directives within the file will also inherit any
    defined variable values.

    Example:

          %% INCLUDE file1 name="World" %%

    for the files:

        file1:                   # name => "World" from INCLUDE directive
            %% INCLUDE file2 %% 
      
        file2:                   # inherits "name" variable from file1
            %% INCLUDE file3 %%    

        file3:                   # inherits "name" variable from file2
            Hello %% name %%

    produces the output:

        Hello World

    The output generated by INCLUDE and SUBST directives can be
    formatted using a printf-like template. The format string should
    be specified as a "format" option in the INCLUDE or SUBST
    directive. Each line of the included text is formatted and
    concatentated to create the final output. Within the format
    string, '%s' is used to represent the text.

    For example, the 'author' element below could be used to display
    details of the author of the current document.

        author:
            File:   %% file %%
            Author: %% name %%
            Date:   %% date %%

    For inclusion in an HTML document, the text can be encapsulated
    in HTML comment tags ("<!--" and "-->") using a format string:

        %% INCLUDE author 
           file   = index.html
           name   = "Andy Wardley" 
           date   = 19-Mar-1987
           format = "<!-- %-12s -->" 
        %%

    Which produces the following output:

        <!-- File:   index.html   -->
        <!-- Author: Andy Wardley -->
        <!-- Date:   19-Mar-1987  -->

    Note that the print format is applied to each line of the
    included text. To encapsulate the element as a whole, simply
    apply the formatting outside of the INCLUDE directive:

        <!--
           %% INCLUDE author
           ...
           %%
        -->

    In these examples, the formatting is applied as if the
    replacement value/line is a character string. Any of the
    standard printf(3) format tokens can be used to coerce the value
    into a specific type.

    As mentioned in the SUBST section above, the TIME variable is
    used to represent the current system time in seconds since the
    epoch (see time(2)). The "format" option can also be employed to
    represent such values in a more user-friendly format. Any format
    string that does not contain a '%s' token is assumed to be a
    time-based value and is formatted using the time2str() function
    from the Date::Format module (distributed as part of the
    TimeDate package).

    Example:

        The date is %% TIME format="%d-%b-%y" %%

    Generates:

        The date is 19-Mar-98

    See `perldoc Date::Format' for information on the formatting
    characters available.

    The pragmatic token '%P' can be added to a format to override
    this behaviour and force the use of printf(). The '%P' token is
    otherwise ignored.

    Example:

        %% DEFINE foo=123456789  %%
        %% foo format="%d-%b-%y" %%  # "day-month-year" using time2str
        %% foo format="%d"       %%  # "day" using timestr
        %% foo format="%P%d"     %%  # decimal value using printf
        %% foo format="%s"       %%  # string value using printf
     
    Generates:

        29-Nov-73
        29
        123456789
        123456789

    Text that is inserted with an INCLUDE or SUBST directive can
    also be filtered. There are two default filters provided,
    'escape' which can be used to escape (prefix with a backslash
    '\') certain characters, and 'sr' which is used to perform
    simple search and replace actions. Other filters may be added
    with the FILTER option when creating the object (see the FILTER
    section in the section on "USING THE METATEXT MODULE", above).

    Like the 'format' option, output filters work on a line of text
    at a time. Any parameters required for the filter can be
    specified in parentheses after the filter name. The 'escape'
    filter expects a perl-style character class indicating the
    characters to escape. The 'sr' filter expects two parameters, a
    search pattern and a replacement string, separated by a comma.
    Note that parameters that include embedded spaces should be
    quoted. The quote characters themselves must also be escaped as
    they already form part of a quoted string (the filter text).
    (This way of representing parameters is admittedly far from
    ideal and may be improved in a future version.)

    Example:

        %% DEFINE text="Madam I'm Adam" %%
        %% SUBST  text filter="escape(['])"               %%
        %% SUBST  text filter="sr(Adam, \"Frank Bough\")" %%

    Generates:

        Madam I\'m Adam
        Madam I'm Frank Bough

    Conditional tests can be applied to INCLUDE blocks to determine
    if the block should evaluated or ignored. Variables and absolute
    values can be used and can be evaluated in the following ways:

        a == b       # a is equal to b
        a != b       # a is not equal to b
        a >  b       # a is greater than b
        a <  b       # a is less than b
        a => b       # a is greater than or equal to b
        a <= b       # a is less than or equal to b
        a =~ b       # a matches the perl regex pattern b
        a !~ b       # a does not match the perl regex pattern b
        a in b,c,d   # a appears in the list b, c, d (see DELIMITER)

    The items on the right of the evaluations can be absolute values
    or variable names which should be prefixed by a '$'. The items
    on the left of the evaluation are assumed to be variable names.
    There is no need to prefix these with a '$', but you can if you
    choose.

    The single equality, "a = b", is treated identically to a double
    equality "a == b" although the two traditionally represent
    different things (the first, an assignment, the second, a
    comparison). In this context, I consider the former usage
    confusing and would recommend use of the latter at all times.

    Variables without any comparison operator or operand are tested
    for a true/false value.

    Examples:

        %% INCLUDE foo if="name==fred"        %%
        %% INCLUDE foo if="$name==fred"       %%  # equivalent to above
        %% INCLUDE foo if="name==$goodguy"    %%
        %% INCLUDE foo if="hour > 10"         %%
        %% INCLUDE foo if="tonk =~ [Ss]pl?at" %%
        %% INCLUDE foo if="camper"            %%

    Multiple conditions can be joined using the following boolean
    operators

        a && b       # condition 'a' and 'b' 
        a || b       # condition 'a' or  'b' 
        a ^  b       # condition 'a' xor 'b'
        a and b      # same as "a && b" but with lower precedence
        a or  b      # same as "a || b" but with lower precedence
        a xor b      # same as "a ^  b" but with lower precedence

    Conditional equations are evaluated left to right and may
    include parentheses to explicitly set precedence.

    Examples:

        %% INCLUDE tonk     
           if="hardenuf && uid in abw,wrigley"           
        %%
        %% INCLUDE tapestry 
           if="(girly && studly < 1) || uid == neilb"    
        %%
        %% INCLUDE tapestry 
           if="($girly && $studly < 1) || $uid == neilb" 
        %%

    Note that the third example above is identical in meaning to the
    second, but explicitly prefixes variable names with '$'. This is
    optional for elements on the left hand side of comparison
    operators, but mandatory for those on the right that might
    otherwise be interpreted as absolute values.

  BLOCK..ENDBLOCK

    In some cases it is desirable to have a block of text available
    to be inserted via INCLUDE without having to define it in an
    external file. The BLOCK..ENDBLOCK directives allow this.

    A BLOCK directive with a unique identifier marks the start of a
    block definition. The block continues, including any valid
    MetaText directives, until an ENDBLOCK directive is found.

    A BLOCK..ENDBLOCK definition may appear anywhere in the file. It
    is in fact possible to INCLUDE the block before it has been
    defined as long as the block definition resides in the same
    file.

    Processing of a file stops when it encounters the __END__ marker
    on a line by itself. Blocks can be defined after this marker
    even though the contents of the file after __END__ are ignored
    by the processor.

        # include a block defined later
        %% INCLUDE greeting name=Prospero %%

        __END__
        %% BLOCK greeting %%
        Hello %% name %%
        %% ENDBLOCK %%

    This produces the following output:

        # include a block defined later
        Hello Prospero

    Additional variable definitions specified in an INCLUDE
    directive will be applied to blocks just as they would to
    external files.

    A BLOCK..ENDBLOCK definition that appears in the main part of a
    document (i.e. before, or in the absence of an __END__ line)
    will not appear in the processed output. A simple "print" flag
    added to the BLOCK directive overrides this behaviour, causing a
    copy of the BLOCK to appear in it's place:

        %% DEFINE name=Caliban %%

        %% BLOCK greeting print %%
        Hello %% name %%
        %% ENDBLOCK %%

        %% INCLUDE greeting name="Prospero" %%

    produces the following output:

        Hello Caliban

        Hello Prospero

    Conditions ("if" and "unless") can be applied to BLOCK
    directives, but they affect how and when the BLOCK itself is
    printed, rather than determining if the block gets defined or
    not. Conditionals have no effect on BLOCK directives that do not
    include a "print" flag.

EXTENDING METATEXT
    MetaText may be used as a base class for deriving other text
    processing modules. Any member function of a derived class can
    be called directly as a MetaText directive. See the EXECUTE
    configuration option for more details.

    Pseudo-code example:

        package MyMetaText;
        @ISA = qw( Text::MetaText );

        # define a new derived class method, get_name()
        sub get_name {
            my $self   = shift;
            my $params = shift;

            # return name from an ID hash, for example
            $self->{ PEOPLE }->{ $params->{'id'} } || 'nobody';
        }

        package main;

        # use the new derived class
        my $mmt = MyMetaText { EXECUTE => 1 };

        # process 'myfile'
        print $mmt->process('myfile');

    which, for a sample file, 'myfile':

        %% get_name id=foo %%
        %% get_name id=bar %%

    is equivalent to:

        print $mmt->get_name({ 'id' => 'foo' }), "\n";
        print $mmt->get_name({ 'id' => 'bar' }), "\n";

    Alternatively, a simple calling script can be written that
    defines functions that themselves can be called from within a
    document:

        my $mt = Text::MetaText->new( { EXECUTE => 2 } );

        print $mt->process("myfile");

        sub get_name {
            my $params = shift;
            $global_people->{ $params->{'id'} } || 'nobody';
        }

    Please note that the functionality provided by the EXECUTE
    option, and inherently, the extensibility possible by deriving
    MetaText sub-classes, relies in part on the operation of the
    AUTOLOAD method. Authors of derived MetaText classes should be
    aware of, and account for this, if re-defining the AUTOLOAD
    method.

WARNINGS AND ERRORS
    The following list indicates warning or error messages that
    MetaText can generate and their associated meanings.

    "Closing directive tag missing in %s"
        A MetaText directive was found that was not terminated
        before the end of the file. e.g. `%% INCLUDE something ...'
        The processor attempts to compensate, but check your source
        files and add any missing MAGIC tokens.

    "Invalid configuration parameter: %s"
        An invalid configuration parameter was identified in the
        hash array passed to Text::MetaText->new(). See the section
        on "USING THE METATEXT MODULE".

    "Invalid debug/error function"
        The debug or error handling routine specified for the ERROR
        or DEBUG configuration options was not a code reference. See
        the ERROR and/or DEBUG sections for more details.

    "Invalid debug option: %s"
        A token was specified for the DEBUGLEVEL configuration item
        which was invalid. See the DEBUGLEVEL section for a complete
        list of valid tokens.

    "Invalid roque option: %s"
        A token was specified for the ROGUE configuration item which
        was invalid. See the ROGUE section for a complete list of
        valid tokens.

    "Maximum recursion exceeded"
        The processed file had multiple INCLUDE directives that
        nested to a depth greater than MAXDEPTH (default: 32). Set
        MAXDEPTH higher to avoid this problem, or check your files
        for circular dependencies.

    "Missing directive keyword"
        A MetaText directive was identified that had no keyword or
        other content. e.g. `%% %%'

    "Text::MetaText->new expects a hash array reference"
        The new() method can accept a reference to a hash array as
        the first parameter which contains configuration variables
        and values. This error is generated if the parameter is not
        a hash array reference.

    "Unrecognise directive: %s"
        An internal error that should never happen. The pre-
        processor has identified a directive type that the processor
        then failed to recognise.

    "Unrecognised token: %s"
        A `%% SUBST <variable> %%' or `%% <variable> %%' directive
        was found for which there was no corresponding <variable>
        defined. This warning is only generated when the 'warn'
        token is set for the ROGUE option.

    "Unmatched parenthesis: %s"
        A conditional evaluation ("if" or "unless") for a directive
        is missing a closing parenthesis. e.g. `%% INCLUDE foobar
        if="(foo && bar || baz" %%'

    "%s: non-existant or invalid filter"
        An INCLUDE or SUBST directive included a "filter" option
        that refers to a non-existant filter. e.g. `%% INCLUDE foo
        filter=nosuchfilter() %%'

AUTHOR
    Andy Wardley <abw@kfs.org>

    See also:

        http://www.kfs.org/~abw/
        http://www.kfs.org/~abw/perl/metatext/

    My thanks extend to the people who have used and tested
    MetaText. In particular, the members of the Peritas Online team;
    Simon Matthews, Simon Millns and Gareth Scott; who brutally
    tested the software over a period of many months and provided
    valuable feedback, ideas and of course, bug reports. I am also
    indebted to the members of the SAS Team at Canon Research Centre
    Europe Ltd; Tim O'Donoghue, Neil Bowers, Ave Wrigley, Martin
    Portman, Channing Walton and Gareth Rees; although I'm not yet
    sure why. :-)

    I welcome bug reports, enhancement suggestions, comments,
    criticisms (hopefully constructive) and patches related to
    MetaText. I would appreciate hearing from you if you find
    MetaText particularly useful or indeed if it *doesn't* do what
    you want, for whatever reason. Hopefully this will help me make
    MetaText help you more.

    It pains me to say that MetaText comes without guarantee or
    warranty of suitability for any purpose whatsoever. That doesn't
    mean it doesn't do anything good, but just that I don't want
    some scrupulous old git to sue me because they thought I implied
    it did something it doesn't. *<sigh>*

REVISION
    $Revision: 0.15 $

COPYRIGHT
    Copyright (c) 1996-1998 Andy Wardley. All Rights Reserved.

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

SEE ALSO
    The metapage utility, the Date::Format module.