=pod

=head1 NAME

Text::PSP - Perl extension implementing a JSP-like templating system.

=head1 SYNOPSIS

  use Text::PSP;
  
  my $psp_engine = Text::PSP->new(
	template_root	=> 'templates',
	work_dir	=> '/tmp/psp_work',
  );
  my $template_object = $psp_engine->template('/home/joost/templates/index.psp');
  my @out = $template_object->run(@arguments);

  print @out;

=head1 DESCRIPTION

The Text::PSP system consists of 3 modules: L<Text::PSP>, L<Text::PSP::Parser|Text::PSP::Parser> and L<Text::PSP::Template|Text::PSP::Template>. The parser creates perl modules from the input files, which are subclasses of Text::PSP::Template. Text::PSP is the module overseeing the creation and caching of the templates.

You can use the basics of the JSP system:

	<% 
		my $self = shift;
		# code mode
		my @words = qw(zero one two three);
	%>
		Hello, World - this is text mode
	<%=
		map { $i++ . ' = ' . $_ } @words
	%>
		That was an expression 
	<%!
		# define mode
		sub method {
			return "method called";
		}
	%>
	<%= $self->method %>
		And insert mode again

	includes
	<%@file include="some/page.psp"%>

	and includes that search for a file upwards to the template
	root
	<%@file find="header.psp"%>

For a complete description of the template constructs, see L<Text::PSP::Syntax>.

=head1 METHODS

=head2 new

Instantiates a new Text::PSP object.

Takes two named parameters: template_root and work_dir.

template_root: the root directory for the template files. No templates outside the template_root can be run by this Text::PSP object.

work_dir: the directory in which to store the translated templates.

	my $psp = Text::PSP->new( 
		template_root => './templates',
		work_dir      => './work',
	);


=head2 template

Get a template object from a template file. This will translate the template file into a Text::PSP::Template module if needed.

	my $template = $psp->template("index.psp");

=head2 find_template

Similar to the C<template()> method, but searches for a file starting at the specified path, working up to the template_root.

The returned template object will behave as if it really were in the specified path, regardless of the real location of the template in the file system, so for instance any C<include> and C<find> directives will work from that path.

	my $template = $psp->find_template("some/path/index.psp");

=head2 clear_workdir

This will remove the entire content of the work directory, cleaning up disk space and forcing new calls to C<< $psp->template() >> to recompile the template file.

=head1 AUTHOR

Joost Diepenmaat, jdiepen@cpan.org 

=head1 SEE ALSO

L<Text::PSP::Syntax>, L<Text::PSP::Template>.

