.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Text::Xslate::Manual::FAQ 3pm" .TH Text::Xslate::Manual::FAQ 3pm "2018-11-02" "perl v5.28.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Text::Xslate::Manual::FAQ \- Frequently asked questions and answers .SH "DESCRIPTION" .IX Header "DESCRIPTION" This manual page lists FAQs, which we've heard for now. .SH "QUESTIONS" .IX Header "QUESTIONS" .SS "General" .IX Subsection "General" \fIHow do you pronounce 'Xslate'?\fR .IX Subsection "How do you pronounce 'Xslate'?" .PP We read it \f(CW\*(C`/eks\-leit/\*(C'\fR. .PP \fIWhat 'Xslate' stands for?\fR .IX Subsection "What 'Xslate' stands for?" .PP It stands for \fI\s-1XS\s0 template\fR, a template engine written in \s-1XS,\s0 although pure Perl implementations are also provided. .PP \fIWhat are 'Kolon', 'Metakolon', and 'TTerse' ?\fR .IX Subsection "What are 'Kolon', 'Metakolon', and 'TTerse' ?" .PP 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 \&\f(CW\*(C`syntax\*(C'\fR option to the Text::Xslate constructor. .PP .Vb 3 \& my $tx = Text::Xslate\->new( \& syntax => \*(AqTTerse\*(Aq, # by moniker \& ); \& \& my $tx = Text::Xslate\->new( \& syntax => \*(AqText::Xslate::Syntax::TTerse\*(Aq, # by fully qualified name \& ); .Ve .PP \fIWhat version of perl does Xslate require?\fR .IX Subsection "What version of perl does Xslate require?" .PP Xslate is tested on perl v5.8.1. No special settings should be required. .PP \fIHow can I install the pure-Perl version of Xslate?\fR .IX Subsection "How can I install the pure-Perl version of Xslate?" .PP Pass \f(CW\*(C`PUREPERL_ONLY=1\*(C'\fR to \fIMakefile.PL\fR, which requests the Xslate build system not to make \s-1XS\s0 parts. .PP Note that \f(CW\*(C`cpanm 1.7\*(C'\fR supports \f(CW\*(C`\-\-pp\*(C'\fR option to install pure-Perl alternatives, so you can type \f(CW\*(C`cpanm \-\-pp Text::Xslate\*(C'\fR. .PP \fIWhat optimizations does Xslate employs?\fR .IX Subsection "What optimizations does Xslate employs?" .PP Here are some optimizations worth noting that makes Text::Xslate run so fast, in no particular order: .IP "Pre-compiled templates" 4 .IX Item "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. .IP "Built on top of a virtual machine" 4 .IX Item "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 \fIspecifically\fR for template processing. .Sp The virtual machine also employs optimizations such as direct-threading style coding to shave off any extra milliseconds that the engine might take otherwise .IP "Custom byte codes for oft-used operations" 4 .IX Item "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 \s-1HTML\s0 unless you tell it not to. Text::Xslate implements this process which involves escaping the string \fIwhile\fR 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. .IP "Pre-allocation of output buffers" 4 .IX Item "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 \f(CW\*(C`malloc()\*(C'\fR. One of the tricks that Text::Xslate employs to reduce the number of calls to \&\f(CW\*(C`malloc()\*(C'\fR 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 \f(CW\*(C`malloc()\*(C'\fR calls required to render a template. .PP \fIHow can I throw errors in functions and/or methods?\fR .IX Subsection "How can I throw errors in functions and/or methods?" .PP Handle warnings by \f(CW\*(C`warn_handler\*(C'\fR and raises exceptions if needed. .PP That's because Xslate catches exceptions in templates and emits them as warnings. .SS "Configuration" .IX Subsection "Configuration" \fIWhen I create the Xslate instance?\fR .IX Subsection "When I create the Xslate instance?" .PP 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. .PP Consider a \s-1PSGI\s0 application: .PP .Vb 2 \& # 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 \e&psgi_app; # as a PSGI app .Ve .PP Don't create the instance in each request. It's less efficient. .PP \fIHow can I change instance attributes dynamically?\fR .IX Subsection "How can I change instance attributes dynamically?" .PP Instance attributes, e.g. \f(CW\*(C`include_path\*(C'\fR, \f(CW\*(C`function\*(C'\fR, or \f(CW\*(C`syntax\*(C'\fR, are immutable, so you cannot change them dynamically. .PP Instead, you can create multiple instances by different options. instance in order to avoid conflicts with cache directories. .PP For example: .PP .Vb 7 \& my %common_config = ( cache_dir => $dir, module => \e@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(...); .Ve .SS "Templates" .IX Subsection "Templates" \fIHow can I changes template tags?\fR .IX Subsection "How can I changes template tags?" .PP Use \f(CW\*(C`start_tag\*(C'\fR, \f(CW\*(C`end_tag\*(C'\fR, and \f(CW\*(C`line_start\*(C'\fR options to \f(CW\*(C`new\*(C'\fR method, which can be joined together with \f(CW\*(C`syntax\*(C'\fR option: .PP .Vb 7 \& my $tx = Text::Xslate\->new( \& syntax => \*(AqTTerse\*(Aq, \& tag_start => \*(Aq{{\*(Aq, \& tag_end => \*(Aq}}\*(Aq, \& line_start => undef, \& ); \& print $tx\->render_string(\*(AqHello, {{lang}} world!\*(Aq, { lang => \*(AqXslate\*(Aq }); .Ve .PP Note that you'd better to avoid symbols which can be used for operators. .PP \fIHow can I iterate over \s-1HASH\s0 references?\fR .IX Subsection "How can I iterate over HASH references?" .PP Convert \s-1HASH\s0 references into \s-1ARRAY\s0 references because \f(CW\*(C`for\*(C'\fR methods can deal with just \s-1ARRAY\s0 references. .PP .Vb 10 \& : # 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 :> \& : } .Ve .PP Note that the above methods return \s-1ARRAY\s0 references sorted by the keys. .PP \fIHow can I use Template-Toolkit virtual methods and filters?\fR .IX Subsection "How can I use Template-Toolkit virtual methods and filters?" .PP Xslate itself does not support these methods and filters, but there are modules on \s-1CPAN\s0 that implement them. .PP Text::Xslate::Bridge::TT2 provides almost all the \s-1TT\s0 methods and filters, but it requires Template-Toolkit installed. .PP Text::Xslate::Bridge::TT2Like provides the same features as \&\f(CW\*(C`T::X::Bridge::TT2\*(C'\fR, and it does not require the Template-Toolkit runtime. .PP These bridge modules are useful not only for TTerse users, but also for Kolon users. .PP \fIHow can I (write|get) plugins?\fR .IX Subsection "How can I (write|get) plugins?" .PP 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 \f(CW\*(C`module\*(C'\fR option. .PP 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). .PP 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. .PP \fIHow to limit while-loop like Template-Toolkit?\fR .IX Subsection "How to limit while-loop like Template-Toolkit?" .PP While Template-Toolkit has a loop counter to prevent runaway \f(CW\*(C`WHILE\*(C'\fR loop, Xslate has no arbitrary limitation. .PP Instead, you can use \f(CW\*(C`alarm()\*(C'\fR to limit \fBany\fR runaway code: .PP .Vb 8 \& eval { \& local $SIG{ALRM} = sub { die @_ }; \& alarm(1); # set timeout \& $tx\->render(\*(Aq<: while true { } :>\*(Aq, \e%vars); \& }; \& if($@ =~ /\eb ALRM \eb/xms) { \& # timeout! \& } .Ve .PP \fIDoes Xslate process text strings, or binary strings?\fR .IX Xref "utf8 UTF-8 utf8 flagged string unicode" .IX Subsection "Does Xslate process text strings, or binary strings?" .PP (The meaning of \fItext string\fR and \fIbinary string\fR is that of Perl, see perlunifaq.) .PP Xslate assumes template files to be encoded in \f(CW\*(C`UTF\-8\*(C'\fR by default, so the output is a text string and template parameters, including values which registered functions return, \fBmust\fR be text strings. .PP However, if you want to process binary strings, you can do so by passing \&\f(CW\*(C`:bytes\*(C'\fR to \f(CW\*(C`input_layer\*(C'\fR, although it's not recommended. .PP \fIWhy doesn't I cannot access \f(CI$object\fI.attr like \s-1TT2\s0?\fR .IX Subsection "Why doesn't I cannot access $object.attr like TT2?" .PP Template-Toolkit allows objects (i.e. blessed references) to access its element if the object has no accessor methods, i.e. \f(CW\*(C`[% object.attr %]\*(C'\fR might mean \f(CW\*(C`$object\->{attr}\*(C'\fR. This behavior breaks encapsulation and hides typos, so Xslate doesn't allow such fallbacks. .PP If you want to access object attributes, define the accessors of them, or prepare values as a non-object before calling \f(CW\*(C`render()\*(C'\fR. .PP \fICan I load macros in other template files?\fR .IX Subsection "Can I load macros in other template files?" .PP Not yet. Currently Xslate doesn't support external macros. .SS "Functions, filters and macros" .IX Subsection "Functions, filters and macros" \fIWhere are the list of builtin functions?\fR .IX Subsection "Where are the list of builtin functions?" .PP See Text::Xslate::Manual::Builtin. .PP \fIHow can I use macros as a callback to high-level functions?\fR .IX Subsection "How can I use macros as a callback to high-level functions?" .PP Macros are objects that overload \f(CW\*(C`&{}\*(C'\fR, the \s-1CODE\s0 dereference operator, so all you have to do is to call them simply, but don't check their types because they are not a \fIreal\fR \s-1CODE\s0 reference. .PP .Vb 9 \& my $tx = Text::Xslate\->new( \& function => { \& count => sub { \& my($a, $cb) = @_; \& # Don\*(Aqt check the type of $cb! \& return scalar grep { $cb\->($_) } @{$a}; \& }, \& }, \& ); \& \& print $tx\->render_string(\*(Aq<: count($a, \-> $x { $x >= 50 }) :>\*(Aq, \& { a => [ 0 .. 100 ] }, \& ); # => 50 .Ve .SS "Web Application Frameworks" .IX Subsection "Web Application Frameworks" \fIHow can I use Xslate in \f(CI$my_favorite_WAF\fI?\fR .IX Subsection "How can I use Xslate in $my_favorite_WAF?" .PP There are bridges that integrate Xslate into WAFs: .IP "\(bu" 4 Catalyst::View::Xslate for Catalyst .IP "\(bu" 4 MojoX::Renderer::Xslate for Mojolicious .IP "\(bu" 4 Tiffany for general usage .PP There are WAFs which adopt Xslate as the default template engine: .IP "\(bu" 4 Amon2 .IP "\(bu" 4 Pickles .PP \fIWhere are examples which use Xslate in Catalyst?\fR .IX Subsection "Where are examples which use Xslate in Catalyst?" .PP There is a real-world project that uses Xslate with Catalyst. .PP .PP Initializing Xslate: .PP Working on: .PP Enjoy! .SS "Development and support" .IX Subsection "Development and support" \fIHow can I colorize Xslate templates?\fR .IX Subsection "How can I colorize Xslate templates?" .PP For \f(CW\*(C`vim\*(C'\fR user, there is \fIxslate.vim\fR for Kolon: .PP .PP For \f(CW\*(C`emacs\*(C'\fR user, there are plugins: .PP .PP .PP \fIWhere can I ask questions?\fR .IX Subsection "Where can I ask questions?" .PP The mailing list is recommended to ask questions. .PP .PP 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. .PP .PP \fII found a bug! What can I do for you?\fR .IX Subsection "I found a bug! What can I do for you?" .PP Please make a minimal test case to show the problem clearly. The code is the common language both I and you speak fluently ;) .SH "SEE ALSO" .IX Header "SEE ALSO" Text::Xslate .PP Text::Xslate::Manual .PP Text::Xslate::Manual::Cookbook