Pair Networks
PML (PML Markup Lanuage)

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