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 modulepml-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