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

FreeBSD Manual Pages

  
 
  

home | help
Text::Xslate::Manual::User3Contributed Perl DocumeText::Xslate::Manual::FAQ(3)

NAME
       Text::Xslate::Manual::FAQ - Frequently asked questions and answers

DESCRIPTION
       This manual page	lists FAQs, which we've	heard for now.

QUESTIONS
   General
       How do you pronounce 'Xslate'?

       We read it "/eks-leit/".

       What 'Xslate' stands for?

       It stands for XS	template, a template engine written in XS, although
       pure Perl implementations are also provided.

       What are	'Kolon', 'Metakolon', and 'TTerse' ?

       Xslate supports multiple	template syntaxes. Kolon is the	default
       syntax, Metakolon is suitable to	output Kolon templates,	and TTerse is
       compatible with Template-Toolkit	2. You can specify the template	syntax
       by passing "syntax" option to the Text::Xslate constructor.

	   my $tx = Text::Xslate->new(
	       syntax => 'TTerse', # by	moniker
	   );

	   my $tx = Text::Xslate->new(
	       syntax => 'Text::Xslate::Syntax::TTerse', # by fully qualified name
	   );

       What version of perl does Xslate	require?

       Xslate is tested	on perl	v5.8.1.	No special settings should be
       required.

       How can I install the pure-Perl version of Xslate?

       Pass "PUREPERL_ONLY=1" to Makefile.PL, which requests the Xslate	build
       system not to make XS parts.

       Note that "cpanm	1.7" supports "--pp" option to install pure-Perl
       alternatives, so	you can	type "cpanm --pp Text::Xslate".

       What optimizations does Xslate employs?

       Here are	some optimizations worth noting	that makes Text::Xslate	run so
       fast, in	no particular order:

       Pre-compiled templates
	   Text::Xslate	is among the template engines that pre-compile the
	   templates.  This is similar to, say,	Template::Toolkit, but
	   Text::Xslate	compiles the templates to C structures and stores them
	   as binary data.

       Built on	top of a virtual machine
	   Text::Xslate	is built on top	of virtual machine that	executes
	   bytecode, and this virtual machine is fine-tuned specifically for
	   template processing.

	   The virtual machine also employs optimizations such as direct-
	   threading style coding to shave off any extra milliseconds that the
	   engine might	take otherwise

       Custom byte codes for oft-used operations
	   Some	operations which are used very often are optimized into	its
	   own byte code. For example (as described elsewhere) Text::Xslate
	   automatically escapes HTML unless you tell it not to. Text::Xslate
	   implements this process which involves escaping the string while
	   appending the result	to the output buffer in	C, as a	custom byte
	   code. This lets you avoid the penalties usually involved in such
	   operations.

       Pre-allocation of output	buffers
	   One of the main things to consider to reduce	performance
	   degradation while processing	a template is to avoid the number of
	   calls to "malloc()".	 One of	the tricks that	Text::Xslate employs
	   to reduce the number	of calls to "malloc()" is to pre-allocate the
	   output buffer in an intelligent manner: For example,	Text::Xslate
	   assumes that	most templates will be rendered	to be about the	same
	   as the previous run,	so when	a template is rendered it uses the
	   size	allocated for the previous rendering as	an approximation of
	   how much space the current rendering	will require. This allows you
	   to greatly reduce the number	of "malloc()" calls required to	render
	   a template.

       How can I throw errors in functions and/or methods?

       Handle warnings by "warn_handler" and raises exceptions if needed.

       That's because Xslate catches exceptions	in templates and emits them as
       warnings.

   Configuration
       When I create the Xslate	instance?

       Xslate instances	are reusable and creating the instance costs somewhat
       so you're recommended to	reuse them as much as possible.	 That is, you
       should make the instance	global.

       Consider	a PSGI application:

	   # create Xslate here, not in	psgi_app();
	   my $xslate =	Text::Xslate->new(...);

	   sub psgi_app	{
	       my($env)	= @_;
	       # use $xslate and create	$response
	       return $response;
	   }
	   return \&psgi_app; #	as a PSGI app

       Don't create the	instance in each request. It's less efficient.

       How can I change	instance attributes dynamically?

       Instance	attributes, e.g. "include_path", "function", or	"syntax", are
       immutable, so you cannot	change them dynamically.

       Instead,	you can	create multiple	instances by different options.
       instance	in order to avoid conflicts with cache directories.

       For example:

	   my %common_config = ( cache_dir => $dir, module => \@module );
	   my %xslate =	(
	       ja => Text::Xslate->new(	path =>	[ $template_ja ], %common_config ),
	       en => Text::Xslate->new(	path =>	[ $template_en ], %common_config ),
	       ro => Text::Xslate->new(	path =>	[ $template_ro ], %common_config ),
	   );
	   $xslate{$lang}->render(...);

   Templates
       How can I changes template tags?

       Use "start_tag",	"end_tag", and "line_start" options to "new" method,
       which can be joined together with "syntax" option:

	   my $tx = Text::Xslate->new(
	       syntax	  => 'TTerse',
	       tag_start  => '{{',
	       tag_end	  => '}}',
	       line_start => undef,
	   );
	   print $tx->render_string('Hello, {{lang}} world!', {	lang =>	'Xslate' });

       Note that you'd better to avoid symbols which can be used for
       operators.

       How can I iterate over HASH references?

       Convert HASH references into ARRAY references because "for" methods can
       deal with just ARRAY references.

	   : # in Kolon
	   : # iterate $hash by	keys
	   : for $hash.keys() -> $key {
	       <: $key :>
	   : }
	   : # by values
	   : for $hash.values()	-> $value {
	       <: $value :>
	   : }
	   : # by key-value pairs
	   : for $hash.kv() -> $pair {
	       <: $pair.key :>=<: $pair.value :>
	   : }

       Note that the above methods return ARRAY	references sorted by the keys.

       How can I use Template-Toolkit virtual methods and filters?

       Xslate itself does not support these methods and	filters, but there are
       modules on CPAN that implement them.

       Text::Xslate::Bridge::TT2 provides almost all the TT methods and
       filters,	but it requires	Template-Toolkit installed.

       Text::Xslate::Bridge::TT2Like provides the same features	as
       "T::X::Bridge::TT2", and	it does	not require the	Template-Toolkit
       runtime.

       These bridge modules are	useful not only	for TTerse users, but also for
       Kolon users.

       How can I (write|get) plugins?

       It is unlikely to need to write plugins for Xslate, because Xslate
       allows you to export any	functions to templates.	Any function-based
       modules are available by	the "module" option.

       Xslate also allows you to call methods for object instances, so you can
       use any object-oriented modules,	except for classes which only provide
       class methods (they need	wrappers).

       If you want to add methods to builtin data types	(nil, scalars, arrays
       and hashes), you	can write bridge modules. See Text::Xslate::Bridge for
       details.

       How to limit while-loop like Template-Toolkit?

       While Template-Toolkit has a loop counter to prevent runaway "WHILE"
       loop, Xslate has	no arbitrary limitation.

       Instead,	you can	use "alarm()" to limit any runaway code:

	   eval	{
	       local $SIG{ALRM}	= sub {	die @_ };
	       alarm(1); # set timeout
	       $tx->render('<: while true { } :>', \%vars);
	   };
	   if($@ =~ /\b	ALRM \b/xms) {
	       # timeout!
	   }

       Does Xslate process text	strings, or binary strings?

       (The meaning of text string and binary string is	that of	Perl, see
       perlunifaq.)

       Xslate assumes template files to	be encoded in "UTF-8" by default, so
       the output is a text string and template	parameters, including values
       which registered	functions return, must be text strings.

       However,	if you want to process binary strings, you can do so by
       passing ":bytes"	to "input_layer", although it's	not recommended.

       Why doesn't I cannot access $object.attr	like TT2?

       Template-Toolkit	allows objects (i.e. blessed references) to access its
       element if the object has no accessor methods, i.e. "[% object.attr %]"
       might mean "$object->{attr}". This behavior breaks encapsulation	and
       hides typos, so Xslate doesn't allow such fallbacks.

       If you want to access object attributes,	define the accessors of	them,
       or prepare values as a non-object before	calling	"render()".

       Can I load macros in other template files?

       Not yet.	Currently Xslate doesn't support external macros.

   Functions, filters and macros
       Where are the list of builtin functions?

       See Text::Xslate::Manual::Builtin.

       How can I use macros as a callback to high-level	functions?

       Macros are objects that overload	"&{}", the CODE	dereference operator,
       so all you have to do is	to call	them simply, but don't check their
       types because they are not a real CODE reference.

	   my $tx = Text::Xslate->new(
	       function	=> {
		   count => sub	{
		       my($a, $cb) = @_;
		       # Don't check the type of $cb!
		       return scalar grep { $cb->($_) }	@{$a};
		   },
	       },
	   );

	   print $tx->render_string('<:	count($a, -> $x	{ $x >=	50 }) :>',
	       { a => [	0 .. 100 ] },
	   ); #	=> 50

   Web Application Frameworks
       How can I use Xslate in $my_favorite_WAF?

       There are bridges that integrate	Xslate into WAFs:

       o   Catalyst::View::Xslate for Catalyst

       o   MojoX::Renderer::Xslate for Mojolicious

       o   Tiffany for general usage

       There are WAFs which adopt Xslate as the	default	template engine:

       o   Amon2

       o   Pickles

       Where are examples which	use Xslate in Catalyst?

       There is	a real-world project that uses Xslate with Catalyst.

       <https://github.com/duckduckgo/community-platform>

       Initializing Xslate:
       <https://github.com/duckduckgo/community-platform/blob/master/lib/DDGC.pm#L268>

       Working on: <https://dukgo.com/>

       Enjoy!

   Development and support
       How can I colorize Xslate templates?

       For "vim" user, there is	xslate.vim for Kolon:

       <https://github.com/motemen/xslate-vim>

       For "emacs" user, there are plugins:

       <https://github.com/samvtran/kolon-mode>

       <https://github.com/yoshiki/tx-mode>

       Where can I ask questions?

       The mailing list	is recommended to ask questions.

       <http://groups.google.com/group/xslate>

       If you find a bug or have a request, creating github issues is better
       because those tickets are less likely to	disappear than the ports in
       the mailing list.

       <https://github.com/xslate/p5-Text-Xslate/issues>

       I found a bug! What can I do for	you?

       Please make a minimal test case to show the problem clearly.  The code
       is the common language both I and you speak fluently ;)

SEE ALSO
       Text::Xslate

       Text::Xslate::Manual

       Text::Xslate::Manual::Cookbook

perl v5.32.1			  2017-01-19	  Text::Xslate::Manual::FAQ(3)

NAME | DESCRIPTION | QUESTIONS | SEE ALSO

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

home | help