Peter J Jones > PML > PML

Download:
PML-0.4.1.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Source  

NAME ^

PML (PML Markup Lanuage)

SYNOPSIS ^

use PML;

my $parser = new PML;

$parser->parse('/path/to/somefile');

my $output = $parser->execute;

DESCRIPTION ^

PML is a powerful text preprocessor. It supports such things as variables, flow control and macros. After preprocessing a text file it returns the result to your Perl script. The power comes from the fact that you can even embed Perl code into the file that is getting processed.

PML was originaly designed to seperate a Perl CGI script and the HTML that it generates. What sets PML apart from other similar solutions is that it is not just a web solution using mod_perl. You can parse PML files from the command line using the supplied pml script or from within your Perl scripts using the PML Perl module.

If you do have mod_perl, you can use the supplied mod_pml Apache module to parse PML files from within the Apache web server.

EXAMPLE PML FILE ^

        <html>
                <head>
                        <title>${title}</title>
                </head>
                <body>
                @if(${title}) {
                        <h1>${title}</h1>
                }
                </body>
        </html>

DOCUMENTATION ^

Documentation is supplied with this module, in the doc directory.

      language.html: describes the language.

   pml-modules.html: tells you how to write a PML module

pml-custom-app.html: tells you how to extend PML from within your application.

USAGE ^

The following is an overview of the PML API

METHOD new

        Arguments:
                1) Class or PML Object to clone
                2) Hash Reference (Optional)

        Returns:
                1) A PML Object

        Description:
                new creates a new PML Object and returns the object
                to the caller. You can optionaly pass in a hash
                refernece, where the keys are PML variables to set
                and the values are the values to set those variables
                to.

METHOD parse

        Arguments:
                1) PML Object
                2) Filename or a reference to an array of lines

        Returns:
                1) True if parse was successful

        Description:
                parse will parse the file or array that you give
                it. If there is an error, such as a syntax error,
                parse will throw an exception via die.  Therefore
                if you want to catch the exception you should wrap
                the call to parse in an eval block and check $@.
                If $@ is true there was and error and the error
                message can be found in $@.

METHOD execute

        Arguments:
                1) PML Object
                2) A Hash Reference (Optional)

        Returns:
                1) The text in the file after processing it

        Description:
                execute will process the file and return the
                post-processed text.  You can optionaly pass in a
                reference to a hash, where the keys are PML variables
                to set and the values are the value to set them
                to.  This is a good way so talk to your text file.

                You can call execute as many times as you wish.
                Each call will start afresh at the top of the parsed
                file.

METHOD v

        Arguments:
                1) PML Object

                -- or --
                
                2) Variable Name

                -- or --

                2) Variable Name
                3) New Value

                -- or --

                2) Hash Reference

        Returns:
                1) Depends on Arguments, see below.

        Description:
                The v method allows you to get and set PML variables.
                There are a few different ways to use v, and we
                will cover them all.

                Arguments:
                        1) PML Object

                In this case, you call v with only the object, no
                arguments. This will return an array of variable
                names. This is so you can see what variables are
                defined.

                Arguments:
                        1) PML Object
                        2) Variable Name

                This time you give a name of a variable. The v
                method will return the current value of that
                variable, or undef if it is not set.

                Arguments:
                        1) PML Object
                        2) Variable Name
                        3) Value

                Here, you give a variable name and the value to
                set it to. The v method will then set the give
                variable to the value you gave it. It should return
                the same value.

                Arguments:
                        1) PML Object
                        2) Hash Reference

                To limit method calls, you can give a hash reference
                where the keys are the variable to set and the
                values are the value to set those variables to.
                Returns 1.

METHOD parse_after

        Arguments:
                1) PML Object
                2) Regular Expression String or Object

        Returns:
                1) Nothing

        Description:
                Used before the call to parse, this method will
                effect when parsing will start. When you call the
                parse method, it will search for the given regex,
                when that regex matches, parsing will begin on the
                NEXT line.

CLASS METHOD register

        Arguments:
                1) Class ie PML->register(...)
                2) A Hash, keys are described below

        Returns:
                1) An ID number to refer to your token

        Description:
                The register function is used to extend the PML
                syntax. You register a callback for a new PML
                function. When parsing the text, PML will call your
                parser-callback to assist parsing. When executing,
                PML will call your token-callback to process the
                token created by your parser-callback.

                Here is what you should pass to register:

                        parse => A callback. Defaults to using the
                                 builtin autoparser
                        token => A callback. You must give this.
                        name  => The name of the new PML function to add.
                        type  => See Types below
                
                Callbacks:

                        A callback is a reference to a subroutine like this:
                                \&myfunc  -- or -- sub{}

                        It can also be a reference to an array,
                        where the first element is a reference to
                        a subroutine and the remaining elements
                        are passed to the subroutine as arguemnts
                        after the standard arguments.

                Types:

                        The types are constants in PML.pm.

            PML->ARG_ONLY   This means that your new 
                            function will only take
                            arguments, just like the 
                            builtin @set function.

            PML->BLOCK_ONLY This means that your new 
                            function only takes a block
                            just like the builtin @perl 
                            function.

            PML->ARG_BLOCK  This means that your new 
                            function takes arguments 
                            and a block, just like the 
                            builtin @if function.

METHOD warning

        Arguments:
                1) PML Object
                2) Boolean Flag (Optional)

        Returns:
                1) Current Warning Flag

        Description:
                The warning method will set the warning flag to
                the one given, if one was given. It always returns
                the current value. If the flag is true, PML will
                print warnings to STDERR.

METHOD use_stderr

        Arguments:
                1) PML Object
                2) True to allow use of stderr, false to disallow

        Returns:
                1) Nothing

        Description:
                Sets the use_stderr flag for this object
syntax highlighting: