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

FreeBSD Manual Pages

  
 
  

home | help
Filter::Template(3)   User Contributed Perl Documentation  Filter::Template(3)

NAME
       Filter::Template	- a source filter for inline code templates (macros)

VERSION
       version 1.043

SYNOPSIS
	       use Filter::Template;

	       # use Filter::Template (	isa => 'SomeModule' );

	       template	max (one,two) {
		       ((one) >	(two) ?	(one) :	(two))
	       }

	       print {%	max $one, $two %}, "\n";

	       const PI	3.14159265359

	       print "PI\n";	     # Constants are expanded inside strings.
	       print "HAPPINESS\n";  # Also expanded due to naive parser.

	       enum ZERO ONE TWO
	       enum 12 TWELVE THIRTEEN FOURTEEN
	       enum + FIFTEEN SIXTEEN SEVENTEEN

	       # Prints	numbers, due to	naive parser.
	       print "ZERO ONE TWO TWELVE THIRTEEN FOURTEEN FIFTEEN SIXTEEN SEVENTEEN\n";

	       if ($expression)	{      # include
			... lines of code ...
	       }		       # include

	       unless ($expression) {  # include
		       ... lines of code ...
	       } elsif ($expression) { # include
		       ... lines of code ...
	       } else {		       # include
		       ... lines of code ...
	       }		       # include

DESCRIPTION
       Filter::Template	is a Perl source filter	that provides simple inline
       source code templates.  Inlined source code can be significantly	faster
       than subroutines, especially for	small-scale functions like accessors
       and mutators.  On the other hand, they are more difficult to maintain
       and use.	 Choose	your trade-offs	wisely.

   Templates
       Code templates are defined with the "template" statement, which looks a
       lot like	"sub".	Because	this is	a naive	source filter, however,	the
       open brace must be on the same line as the "template" keyword.
       Furthermore, the	first closing brace in column zero ends	a macro	body.

	       template	oops {
		       die "Oops";
	       }

       Templates are inserted into a program using a simple syntax that	was
       adapted from other template libraries.  It was chosen to	be compatible
       with the	Perl syntax highlighting of common text	editors.

       This inserts the	body of	"template oops".

	       {% oops %}

       Templates can have parameters.  The syntax for template parameters was
       based on	prototypes for Perl subroutines.  The two main differences are
       that parameters are named, and sigils are not used.

	       template	sum_2 (parameter_0, parameter_1) {
		       print( parameter_0 + parameter_1, "\n" );
	       }

       To insert a template with parameters, simply list the parameters	after
       the template name.

	       {% sum_2	$base, $increment %}

       At expansion time, occurrences of the parameter names within the
       template	are replaced with the source code provided in the template
       invocation.  In the previous example, "sum_2" literally expands to

	 print(	$base +	$increment, "\n" );

       and is then compiled by Perl.

   Constants and Enumerations
       Filter::Template	also defines "const" and "enum"	keywords.  They	are
       essentially simplified templates	without	parameters.

       "const" defines a constant that is replaced before compile time.
       Unlike Perl's native constants, these are not demoted to	function calls
       when Perl is run	in debugging or	profiling mode.

	       const CONSTANT_NAME     'constant value'
	       const ANOTHER_CONSTANT  23

       Enumerations are	like constants but several sequential integers can be
       defined in one statement.  Enumerations start from zero by default:

	       enum ZEROTH FIRST SECOND

       If the first parameter of an enumeration	is a number, then the
       enumerated constants will start with that value:

	       enum 10 TENTH ELEVENTH TWELFTH

       Enumerations may	not span lines,	but they can be	continued.  If the
       first enumeration parameter is the plus sign, then constants will start
       where the previous enumeration left off.

	       enum 13 THIRTEENTH FOURTEENTH  FIFTEENTH
	       enum +  SIXTEENTH  SEVENTEENTH EIGHTEENTH

   Conditional Code Inclusion (#ifdef)
       The preprocessor	supports something like	cpp's #if/#else/#endif by
       usurping	a bit of Perl's	conditional syntax.  The following conditional
       statements will be evaluated at compile time if they are	followed by
       the comment "# include":

	       if (EXPRESSION) {      #	include
		       BLOCK;
	       } elsif (EXPRESSION) { #	include
		       BLOCK;
	       } else {		      #	include
		       BLOCK;
	       }		      #	include

	       unless (EXPRESSION) {  #	include
		       BLOCK;
	       }		      #	include

       The code	in each	conditional statement's	BLOCK will be included or
       excluded	in the compiled	code depending on the outcome of its
       EXPRESSION.

       Conditional includes are	nestable, but else and elsif must be on	the
       same line as the	previous block's closing brace,	as they	are in the
       previous	example.

       Filter::Template::UseBytes uses conditional code	to define different
       versions	of a {%	use_bytes %} macro depending whether the "bytes"
       pragma exists.

IMPORTING TEMPLATES
       Filter::Template	can import templates defined by	another	class.	For
       example,	this invocation	imports	the "use_bytes"	template:

	       use Filter::Template ( isa => 'Filter::Template::UseBytes' );

       Imported	templates can be redefined in the current namespace.

       Note: If	the imported templates require additional Perl modules,	any
       code which imports them must also "use" those modules.

DEBUGGING
       Filter::Template	has three debugging constants which will only take
       effect if they are defined before the module is first used.

       To trace	source filtering in general, and to see	the resulting code and
       operations performed on each line, define:

	       sub Filter::Template::DEBUG () {	1 }

       To trace	template invocations as	they happen, define:

	       sub Filter::Template::DEBUG_INVOKE () { 1 }

       To see template,	constant, and enum definitions,	define:

	       sub Filter::Template::DEBUG_DEFINE () { 1 }

       To see warnings when a template or constant is redefined, define:

	       sub Filter::Template::DEFINE () { 1 }

CAVEATS
       Source filters are line-based, and so is	the template language.	The
       only constructs that may	span lines are template	definitions, and those
       must span lines.

       Filter::Template	does not parse perl.  The regular expressions that
       detect and replace code are simplistic and may not do the right things
       when parsing challenging	Perl syntax.  Constants	are replaced within
       strings,	for example.

       The regexp optimizer makes silly	subexpressions like /(?:|m)/.  That
       could be	done better as /m?/ or /(?:jklm)?/ if the literal is longer
       than a single character.

       The regexp optimizer does not optimize (?:x|y|z)	as character classes.

       The regexp optimizer is based on	code in	Ilya Zakharevich's Text::Trie.
       Better regexp optimizers	were released afterwards, and Filter::Template
       should use one of them.

LINKS
   BUG TRACKER
       https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=Filter-Template

   REPOSITORY
       http://github.com/rcaputo/filter-template
       http://gitorious.org/filter-template

   OTHER RESOURCES
       http://search.cpan.org/dist/Filter-Template/

SEE ALSO
       Text::Trie, PAR,	Filter::Template::UseBytes.

AUTHOR & COPYRIGHT
       Filter::Template	is Copyright 2000-2013 Rocco Caputo.  Some parts are
       Copyright 2001 Matt Cashner.  All rights	reserved.  Filter::Template is
       free software; you may redistribute it and/or modify it under the same
       terms as	Perl itself.

       Filter::Template	was previously known as	POE::Preprocessor.

perl v5.32.1			  2013-08-12		   Filter::Template(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | IMPORTING TEMPLATES | DEBUGGING | CAVEATS | LINKS | SEE ALSO | AUTHOR & COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Filter::Template&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help