Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MicroMason::Base(3)   User Contributed Perl Documentation  MicroMason::Base(3)

       Text::MicroMason::Base -	Abstract Template Compiler

       Create a	MicroMason object to interpret the templates:

	   use Text::MicroMason;
	   my $mason = Text::MicroMason->new();

       Use the execute method to parse and evalute a template:

	   print $mason->execute( text=>$template, 'name'=>'Dave' );

       Or compile it into a subroutine,	and evaluate repeatedly:

	   $coderef = $mason->compile( text=>$template );
	   print $coderef->('name'=>'Dave');
	   print $coderef->('name'=>'Bob');

       Templates stored	in files can be	run directly or	included in others:

	   print $mason->execute( file=>"./greeting.msn", 'name'=>'Charles');

       Text::MicroMason::Base is an abstract superclass	that provides a	parser
       and execution environment for an	extensible templating system.

   Public Methods
	     $mason = Text::MicroMason::Base->new( -Mixin1, -Mixin2, %attribs );

	   Creates a new Text::MicroMason object with mixins and attributes.

	   Arguments beginning with a dash will	be added as mixin classes.
	   Other arguments are added to	the hash of attributes.

	     $code_ref = $mason->compile( text => $template, %options );
	     $code_ref = $mason->compile( file => $filename, %options );

	   Parses the provided template	and converts it	into a new Perl

	     $result = $mason->execute(	text =>	$template, @arguments );
	     $result = $mason->execute(	file =>	$filename, @arguments );
	     $result = $mason->execute(	code =>	$code_ref, @arguments );

	     $result = $mason->execute(	$type => $source, \%options, @arguments	);

	   Returns the results produced	by the template, given the provided

       Attributes can be set in	a call to new()	and locally overridden in a
       call to compile().

	   Optional reference to a subroutine to call with each	piece of
	   template output. If this is enabled,	template subroutines will
	   return an empty string.

   Private Methods
       The following internal methods are used to implement the	public
       interface described above, and may be overridden	by subclasses and

	     $class = Text::MicroMason::Base->class( @Mixins );

	   Creates a subclass of this package that also	inherits from the
	   other classes named.	Provided by Class::MixinFactory::HasAFactory.

	     $mason = $class->create( %options );
	     $clone = $mason->create( %options );

	   Creates a new instance with the provided key	value pairs.

	   To obtain the functionality of one of the supported mixin classes,
	   use the class method	to generate the	mixed class before calling
	   create(), as	is done	by new().

	   This	class method is	called by new()	to provide key-value pairs to
	   be included in the new instance.

	     ($self, $src_type,	$src_data) = $self->prepare($src_type, $src_data, %options)

	   Called by compile(),	the prepare method allows for single-use
	   attributes and provides a hook for mixin functionality.

	   The prepare method provides a hook for mixins to normalize or
	   resolve the template	source type and	value arguments	in various
	   ways	before the template is read using one of the read_type()

	   It returns an object	reference that may be a	clone of the original
	   mason object	with various compile-time attributes applied. The
	   cloning is a	shallow	copy performed by the create() method. This
	   means that the $m object visible to a template may not be the same
	   as the MicroMason object on which compile() was originally called.

	   Please note that this clone-on-prepare behavior is subject to
	   change in future releases.

	      $perl_code = $mason->interpret( $src_type, $src_data );

	   Called by compile(),	the interpret method then calls	the read(),
	   lex(), and assemble() methods.

	     $template = $mason->read( $src_type, $src_data );

	   Called by interpret(). Calls	one of the below read_*	methods.

	     $template = $mason->read_text( $template );

	   Called by read() when the template source type is "text", this
	   method simply returns the value of the text string passed to	it.

	     ( $contents, %path_info ) = $mason->read_file( $filename );

	   Called by read() when the template source type is "file", this
	   method reads	and returns the	contents of the	named file.

	     $template = $mason->read_handle( $filehandle );

	   Called by read() when the template source type is "handle", this
	   method reads	and returns the	contents of the	filehandle passed to

	     @token_pairs = $mason->lex( $template );

	   Called by interpret(). Parses the source text and returns a list of
	   pairs of token types	and values. Loops through repeated calls to

	     ( $type, $value ) = $mason->lex_token();

	   Attempts to parse a token from the template text stored in the
	   global $_ and returns a token type and value. Returns an empty list
	   if unable to	parse further due to an	error.

	   Abstract method; must be implemented	by subclasses.

	     $perl_code	= $mason->assemble( @tokens );

	   Called by interpret(). Assembles the	parsed token series into the
	   source code for the equivalent Perl subroutine.

	   Returns a hash of text elements used	for Perl subroutine assembly.
	   Used	by assemble().

	   The assembly	template defines the types of blocks supported and the
	   order they appear in, as well as where other	standard elements
	   should go. Those other elements also	appear in the assembler	hash.

	     $code_ref = $mason->eval_sub( $perl_code );

	   Called by compile().	Compiles the Perl source code for a template
	   using eval(), and returns a code reference.

	   Called when a fatal exception has occurred.

	   Enhanced superclass method dispatch for use inside mixin class
	   methods. Allows mixin classes to redispatch to other	classes	in the
	   inheritance tree without themselves inheriting from anything.
	   Provided by Class::MixinFactory::NEXT.

   Private Functions
	     $special_characters_escaped = _printable( $source_string );

	   Converts non-printable characters to	readable form using the
	   standard backslash notation,	such as	"\n" for newline.

       You can add functionality to this module	by creating subclasses or
       mixin classes.

       To create a subclass, just inherit from the base	class or some
       dynamically-assembled class. To create your own mixin classes which can
       be combined with	other mixin features, examine the operation of the
       class() and NEXT() methods.

       Key areas for subclass writers are:

	   You can intercept and re-write template source arguments by
	   overriding this method.

	   You can support a new template source type by creating a method
	   with	a corresponding	name prefixed by "read_". It is	passed the
	   template source value and should return the raw text	to be lexed.

	   For example,	if a subclass defined a	method named read_from_db,
	   callers could compile templates by calling "->compile( from_db =>
	   'welcome-page' )".

	   Replace this	to parse a new template	syntax.	Is receives the	text
	   to be parsed	in $_ and should match from the	current	position to
	   return the next token type and its contents.

	   The assembler data structure	is used	to construct the Perl
	   subroutine for a parsed template.

	   You can support a new token type be creating	a method with a
	   corresponding name prefixed by "assemble_". It is passed the	token
	   value or contents, and should return	a new token pair that is
	   supported by	the assembler template.

	   For example,	if a subclass defined a	method named
	   assemble_sqlquery, callers could compile templates that contained a
	   "<%sqlquery>	... </%sqlquery>" block. The assemble_sqlquery method
	   could return	a "perl	=> $statements"	pair with Perl code that
	   performed some appropriate action.

	   You can wrap	or cache the results of	this method, which is the
	   primary public interface.

	   You typically should	not depend on overriding this method because
	   callers can invoke the compiled subroutines directly	without
	   calling execute.

       For an overview of this templating framework, see Text::MicroMason.

       For distribution, installation, support,	copyright and license
       information, see	Text::MicroMason::Docs::ReadMe.

perl v5.32.1			  2010-01-19		   MicroMason::Base(3)


Want to link to this manual page? Use this URL:

home | help