Changeset 26781 for lang/perl/Text-MicroTemplate

Timestamp:

12/15/08 18:01:10 (4 years ago)

Author:

kazuho

Message:

adjust function names, more doc

Location:

lang/perl/Text-MicroTemplate/trunk

Files:

• lib/Text/MicroTemplate.pm (modified) (9 diffs)
• t/02-as_html.t (modified) (2 diffs)
• t/03-modes.t (modified) (2 diffs)
• t/04-multiline.t (modified) (5 diffs)

lang/perl/Text-MicroTemplate/trunk/lib/Text/MicroTemplate.pm

@@ -14 +14 @@
 our $VERSION = '0.01';
 our @ISA = qw(Exporter);
-our @EXPORT_OK = qw(as_html encoded_string);
+our @EXPORT_OK = qw(encoded_string build_mt render_mt);
 our %EXPORT_TAGS = (
     all => [ @EXPORT_OK ],
@@ -32 +32 @@
         tag_end             => '?>',
         escape_func         => 'Text::MicroTemplate::escape_html',
-        ref($_[0]) ? %{$_[0]} : @_,
+        @_ == 1 ? ref($_[0]) ? %{$_[0]} : (template => $_[0]) : @_,
     }, $class;
     if (defined $self->{template}) {
@@ -337 +337 @@
 }
 
-sub mt_build {
-    my $_mt = Text::MicroTemplate->new(
-        ref($_[0]) ? $_[0] : { template => shift },
-    );
+sub build_mt {
+    my $_mt = Text::MicroTemplate->new(@_);
     my $_code = $_mt->code;
     my $expr = << "...";
@@ -361 +359 @@
 }
 
-sub as_html {
-    my $builder = mt_build(shift);
+sub render_mt {
+    my $builder = build_mt(shift);
     $builder->(@_);
 }
@@ -390 +388 @@
 =head1 SYNOPSIS
 
-    use Text::MicroTemplate qw(as_html);
+    use Text::MicroTemplate qw(:all);
 
     # simple form
-    $user = 'John';
-    $html = eval as_html('hello, <?= $user ?>')
-        or die $@;
+    $html = render_mt(
+         'hello, <?= $args->{user} ?>',
+         { user => 'John' },
+    )->as_string;
+
+    # cache compiled template as subref
+    $renderer = build_mt('hello, <?= $args->{user} ?>');
+    $html = $renderer->({ user => 'John' })->as_string;
 
     # complex form
@@ -402 +405 @@
     );
     $code = $mt->code;
-    $builder = eval << "..." or die $@;
+    $renderer = eval << "..." or die $@;
     sub {
         my \$query = shift;
@@ -408 +411 @@
     }
     ...
-    $html = $builder->(CGI->new);
+    $html = $renderer->(CGI->new)->as_string;
 
 =head1 DESCRIPTION
@@ -457 +460 @@
 =head1 EXPORTABLE FUNCTIONS
 
-=head2 as_html($template)
-
-Utility funtion that returns an expression that renders given template when evaluated.
-
-    # outputs: hello, John!
-    $user = 'John';
-    $html = eval as_html('hello, <?= $user ?>!') or die $@;
+=head2 render_mt($template, $args)
+
+Utility function that renders given template and returns an EncodedString.
+
+    # render
+    $hello = render_mt(
+        'hello, <?= $args->{user} ?>!',
+        { user => 'John' },
+    );
+
+    # print as HTML
+    print $hello->as_string;
+
+    # use the result in another template (no double-escapes)
+    $enc = render_mt(
+        '<h1><?= $args->{hello} ?></h1>',
+        { hello => $hello },
+    );
+
+Intertally, the function is equivalent to:
+
+    build_mt($template)->($args);
+
+=head2 build_mt($template)
+
+Returns a subref that renders given template.  Parameters are equivalent to Text::MicroTemplate->new.
+
+    # build template renderer at startup time and use it multiple times
+    my $renderer = build_mt('hello, <?= $args->{user} ?>!');
+
+    sub run {
+        ...
+        my $hello = $renderer->({ user => $query->param('user') });
+        ...
+    }
 
 =head2 encoded_string($str)
@@ -471 +502 @@
 =head1 OO-STYLE INTERFACE
 
-Text::MicroTemplate provides OO-style interface to handle more complex cases.  The constructor accepts a hash (or a hasref) with following arguments.
-
-=head2 template
-
-template
-
-=head2 escape_func
-
-name of function used to escape variables.  If set to undef, no escape occurs. (default: html escape)
-
-=head1 OO-STYLE ACCESSORS
+Text::MicroTemplate provides OO-style interface to handle more complex cases.
+
+=head2 new($template)
+
+=head2 new({ template => $template, escape_func => 'escape_funcname' })
+
+In the first form, constructs a HTML template renderer.  In the second form, constructs a renderer that would escape non-encoded strings using given escape function.  If escape function is set to undef, no escape will occur.  The default escape function is C<Text::MicroTemplate::escape_html>.
 
 =head2 code()

lang/perl/Text-MicroTemplate/trunk/t/02-as_html.t

@@ -5 +5 @@
 
 is(
-    as_html('hello <?= $args->{user} ?>', { user => 'fo<o' })->as_string,
+    render_mt('hello <?= $args->{user} ?>', { user => 'fo<o' })->as_string,
     'hello fo&lt;o',
 );
 is(
-    as_html('hello <?= $args->{user} ?>', user => 'fo<o')->as_string,
+    render_mt('hello <?= $args->{user} ?>', user => 'fo<o')->as_string,
     'hello fo&lt;o',
 );
@@ -17 +17 @@
     my $s = 0;
     eval {
-        as_html('hello <?= $nonexistent ?>');
+        render_mt('hello <?= $nonexistent ?>');
         $s = 1;
     };

lang/perl/Text-MicroTemplate/trunk/t/03-modes.t

@@ -5 +5 @@
 
 # comment
-is as_html(<<'...')->as_string, "aaa\nbbb\n";
+is render_mt(<<'...')->as_string, "aaa\nbbb\n";
 aaa
 ?# 
@@ -11 +11 @@
 ?# 
 ...
-is as_html('aaa<?# a ?>bbb')->as_string, "aaabbb";
+is render_mt('aaa<?# a ?>bbb')->as_string, "aaabbb";
 
 # expression and raw expression
 do {
-    is as_html('<?= $args ?>', 'foo<a')->as_string, 'foo&lt;a';
-    is as_html('<?=r $args ?>', 'foo<a')->as_string, 'foo<a';
+    is render_mt('<?= $args ?>', 'foo<a')->as_string, 'foo&lt;a';
+    is render_mt('<?=r $args ?>', 'foo<a')->as_string, 'foo<a';
     my $rs = encoded_string('foo<a');
-    is as_html('<?= $args ?>', $rs)->as_string, 'foo<a';
-    is as_html('<?=r $args ?>', $rs)->as_string, 'foo<a';
+    is render_mt('<?= $args ?>', $rs)->as_string, 'foo<a';
+    is render_mt('<?=r $args ?>', $rs)->as_string, 'foo<a';
 };
 do {
     use utf8;
-    is as_html('あ<?= $args ?>う', 'い<')->as_string, 'あい&lt;う';
+    is render_mt('あ<?= $args ?>う', 'い<')->as_string, 'あい&lt;う';
     my $rs = encoded_string('い<');
-    is as_html('あ<?= $args ?>う', $rs)->as_string, 'あい<う';
+    is render_mt('あ<?= $args ?>う', $rs)->as_string, 'あい<う';
 }

lang/perl/Text-MicroTemplate/trunk/t/04-multiline.t

@@ -7 +7 @@
 do {
     my $y;
-    is(as_html(<<'...', sub { $y = 1 })->as_string, "abc 1 def\n", 'multiline expr');
+    is(render_mt(<<'...', sub { $y = 1 })->as_string, "abc 1 def\n", 'multiline expr');
 abc <?= 1
  $args->() ?> def
@@ -17 +17 @@
 do {
     my $y;
-    is as_html(<<'...', sub { $y = 1 })->as_string, "abc 1 def\n", 'multiline rawexpr';
+    is render_mt(<<'...', sub { $y = 1 })->as_string, "abc 1 def\n", 'multiline rawexpr';
 abc <?=r 1
  $args->() ?> def
@@ -25 +25 @@
 
 # automatic semicolon insertion
-is as_html(<<'...')->as_string, "abc\n1\n-1\ndef\n", 'expr auto-sci';
+is render_mt(<<'...')->as_string, "abc\n1\n-1\ndef\n", 'expr auto-sci';
 abc
 ?= 1
@@ -31 +31 @@
 def
 ...
-is as_html(<<'...')->as_string, "abc\n1\n-1\ndef\n", 'expr auto-sci';
+is render_mt(<<'...')->as_string, "abc\n1\n-1\ndef\n", 'expr auto-sci';
 abc
 ?=r 1
@@ -39 +39 @@
 
 # no automatic semicolon insertion for code
-is as_html(<<'...')->as_string, "abc\n0\ndef\n", 'no auto-sci for code';
+is render_mt(<<'...')->as_string, "abc\n0\ndef\n", 'no auto-sci for code';
 abc
 ? my $a = 1