package Text::MiniTmpl; use warnings; use strict; use Carp; use version; our $VERSION = qv('1.1.1'); # REMINDER: update Changes # REMINDER: update dependencies in Makefile.PL use Perl6::Export::Attrs; use JSON::XS qw( encode_json ); use URI::Escape qw(); use HTML::Entities qw(); use constant UNSAFE_HTML=> '&"\'<>' . join q{},map{chr}0..8,11,12,14..31,127; use constant RAWPRE => q{$}.__PACKAGE__.'::__ .= '; use constant RAWPOST => q{}; use constant UTF8PRE => q{$}.__PACKAGE__.'::__utf8 = '; use constant UTF8POST => 'utf8::encode($'.__PACKAGE__.'::__utf8);' . q{$}.__PACKAGE__.'::__ .= $'.__PACKAGE__.'::__utf8;'; our $__; our $__utf8; our $TMPL_DIR = q{./}; my %CACHE; my ($PRE, $POST) = (UTF8PRE, UTF8POST); sub raw :Export { my ($is_raw) = @_; ($PRE, $POST) = $is_raw ? (RAWPRE, RAWPOST) : (UTF8PRE, UTF8POST); return; } sub render :Export { my ($tmpl, %p) = @_; my $path = $tmpl =~ m{\A\.?/}xms ? $tmpl : "$TMPL_DIR$tmpl"; 1 while $path =~ s{(\A|/) (?!\.\.?/) [^/]+/\.\./}{$1}xms; ## no critic(ProhibitPostfixControls) my $pkg = caller; $CACHE{$path}{$pkg} ||= tmpl2code($tmpl); return ${ $CACHE{$path}{$pkg}->(%p) }; } sub tmpl2code :Export { my ($tmpl) = @_; my $path = $tmpl =~ m{\A\.?/}xms ? $tmpl : "$TMPL_DIR$tmpl"; 1 while $path =~ s{(\A|/) (?!\.\.?/) [^/]+/\.\./}{$1}xms; ## no critic(ProhibitPostfixControls) my $dir = $path; $dir =~ s{/[^/]*\z}{/}xms; my $line = 1; my $pkg = caller; if ($pkg eq __PACKAGE__) { $pkg = caller 1; } my $e = 'package '.$pkg.'; use warnings; use strict;' . 'sub {' . 'local $'.__PACKAGE__.'::__ = q{};' . 'local $'.__PACKAGE__."::TMPL_DIR = \"\Q$dir\E\";" . 'local %_ = @_;' . "\n#line $line \"$path\"\n" ; open my $fh, '<', $path or croak "open: $!"; my $s = do { local $/ = undef; <$fh> }; close $fh or croak "close: $!"; while ( 1 ) { $e .= $s=~/\G/xmsgc ? "$1;" : $s=~/\G&~ ( (?>[^~]*) .*? ) ~&/xmsgc ? "$1;" : $s=~/\G@~ ( (?>[^~]*) .*? ) ~@/xmsgc ? $PRE."HTML::Entities::encode_entities(''.(do { $1; }), ".__PACKAGE__.'::UNSAFE_HTML);'.$POST : $s=~/\G\#~ ( (?>[^~]*) .*? ) ~\#/xmsgc ? $PRE."do { $1; };".$POST : $s=~/\G\^~ ( (?>[^~]*) .*? ) ~\^/xmsgc ? $PRE."URI::Escape::uri_escape_utf8(''.(do { $1; }));".$POST : $s=~/\G ( (?>[^<&@\#^]*) .*? ) (?= Execute PERL CODE but don't output anything. =item @~ PERL CODE ~@ Execute PERL CODE and output it result (last calculated expression) escaped using HTML::Entities::encode_entities(). =item ^~ PERL CODE ~^ Execute PERL CODE and output it result (last calculated expression) escaped using URI::Escape::uri_escape_utf8(). =item #~ PERL CODE ~# Execute PERL CODE and output it result (last calculated expression) AS IS, without any escaping. =item any other text ... ... will be output AS IS =back Example templates: To: #~ $_{email} ~# Hello, #~ $username ~#. Here is items your asked for: &~ for (@{ $_{items} }) { ~& #~ $_ ~# &~ } ~& ---cut header.html--- @~ $_{pagetitle} ~@ ---cut index.html--- #~ render('header.html', pagetitle=>'Home') ~#

Hello, @~ $_{username} ~@.

&~ # In HTML you may prefer News about @~ $_ ~@ #~ render('footer.html') ~# ---cut footer.html--- =head1 EXPORTS Nothing by default, but all documented functions can be explicitly imported. =head1 INTERFACE =over =item render( $filename, %params ) Render template from $filename with %params. This is caching wrapper around tmpl2code(), which avoid calling tmpl2code() second time for same $filename. Example: $html = render( 'template/index.html', title => $title, name => $name, ); Return STRING with rendered template. =item tmpl2code( $filename ) Read template from $filename (may be absolute or relative to current template's directory or current working directory - see L), compile it into ANON function. This function can be executed with C< ( %params ) > parameters, it will render $filename template with given C< %params > and return SCALARREF to rendered text. Example: $code = tmpl2code( 'template/index.html' ); $html = ${ $code->( title=>$title, name=>$name ) }; Return CODEREF to that function. =item raw( $is_raw ) If $is_raw TRUE disable Unicode support. To enable Unicode again call raw() with $is_raw FALSE. B When Unicode support disabled your parameters used to render template will be used in template AS IS, without attempt to encode them to UTF8. This mean you shouldn't use perl Unicode scalars in these parameters anymore. This affect only templates processed by tmpl2code() after calling raw() (beware caching effect of render()). =item encode_js( $scalar ) Encode $scalar (string or number) for inserting into JavaScript code (usually inside HTML templates). Example: Return encoded string. =item encode_js_data( $complex ) Encode $complex data structure (HASHREF, ARRAYREF, etc. - any data type supported by JSON::XS) for inserting into JavaScript code (usually inside HTML templates). Example: Return encoded string. =back =head1 SPEED AND SIZE This module implemented under 100 lines (about 3KB) of pure Perl code. And while code is terse enough, I believe it still simple and clean. While this is pure-perl module with many enough features, it's still very fast - you can do your own benchmarking using cool L module, here is results from my system: =over =item instance_reuse This test simulate standard FastCGI which read template from HDD and compile it only once (when this template requested first time), and for next requests it just render it using cached anon subroutine. Rate XS? TT 29/s - Template::Toolkit (2.22) TT_X 95/s Y Template::Toolkit (2.22) with Stash::XS HM 704/s - HTML::Mason (1.45) TeCS 738/s Y Text::ClearSilver (0.10.5.4) TeMT 1131/s - Text::MicroTemplate (0.18) TeMMHM 1173/s - Text::MicroMason (2.12) using Text::MicroMason::HTMLMason * TMTU 1357/s - Text::MiniTmpl (1.1.0) with enabled Unicode MoTe 1629/s - Mojo::Template () * TMT 2054/s - Text::MiniTmpl (1.1.0) TeClev 5966/s Y Text::Clevery (0.0004) in XS mode TeXs 6761/s Y Text::Xslate (0.2015) =item uncached_disk This test simulate standard CGI which read template from HDD, compile and render it on each run - no caches used at all (except HDD files caching by OS). Rate XS? TeXs 1.4/s Y Text::Xslate (0.2015) TeClev 1.5/s Y Text::Clevery (0.0004) in XS mode HM 12.6/s - HTML::Mason (1.45) MoTe 21.0/s - Mojo::Template () TeMT 32.1/s - Text::MicroTemplate (0.18) TeMMHM 36.2/s - Text::MicroMason (2.12) using Text::MicroMason::HTMLMason * TMTU 54.1/s - Text::MiniTmpl (1.1.0) with enabled Unicode * TMT 67.9/s - Text::MiniTmpl (1.1.0) TeTmpl 448/s Y Text::Tmpl (0.33) TeCS 725/s Y Text::ClearSilver (0.10.5.4) HTP 1422/s Y HTML::Template::Pro (0.9504) =back =head1 BUGS AND LIMITATIONS No bugs have been reported. =head1 SUPPORT Please report any bugs or feature requests through the web interface at L. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. You can also look for information at: =over =item * RT: CPAN's request tracker L =item * AnnoCPAN: Annotated CPAN documentation L =item * CPAN Ratings L =item * Search CPAN L =back =head1 AUTHOR Alex Efros C<< >> =head1 LICENSE AND COPYRIGHT Copyright 2007-2010 Alex Efros . This program is distributed under the MIT (X11) License: L Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.