File Coverage

blib/lib/Template/Provider/Encoding.pm
Criterion Covered Total %
statement 24 24 100.0
branch 5 6 83.3
condition 2 5 40.0
subroutine 6 6 100.0
pod 0 1 0.0
total 37 42 88.1


line stmt bran cond sub pod time code
1             package Template::Provider::Encoding;
2              
3 2     2   79248 use strict;
  2         5  
  2         108  
4             our $VERSION = '0.10';
5              
6 2     2   11 use base qw( Template::Provider );
  2         3  
  2         2310  
7 2     2   35184 use Encode;
  2         11560  
  2         767  
8              
9             sub _init {
10 8     8   25606 my ($self, $params) = @_;
11              
12 8         46 $self = $self->SUPER::_init($params);
13 8   50     481 $self->{DEFAULT_ENCODING} = $params->{DEFAULT_ENCODING} || 'utf8';
14 8   33     61 $self->{ENCODE_CHECK} = $params->{ENCODE_CHECK} || Encode::FB_DEFAULT;
15 8         21 return $self;
16             }
17              
18             sub _load {
19 8     8   12519 my $self = shift;
20 8         37 my($data, $error) = $self->SUPER::_load(@_);
21              
22 8 50       1980 return ($data, $error) unless defined $data;
23              
24 8 100       37 unless (Encode::is_utf8($data->{text})) {
25 6         23 my $decoder = $self->detect_encoding($data);
26 6         12723 $data->{text} = $decoder->decode($data->{text}, $self->{ENCODE_CHECK});
27             }
28              
29 8         74 return ($data, $error);
30             }
31              
32             sub detect_encoding {
33 6     6 0 8 my ($self, $data) = @_;
34              
35 6 100       51 my $encoding = $data->{text} =~ /^\[% USE encoding '([\w\-]+)'/
36             ? $1 : $self->{DEFAULT_ENCODING};
37 6         33 return Encode::find_encoding($encoding);
38             }
39              
40             1;
41             __END__
42              
43             =head1 NAME
44              
45             Template::Provider::Encoding - Explicitly declare encodings of your templates
46              
47             =head1 SYNOPSIS
48              
49             use Template::Provider::Encoding;
50             use Template::Stash::ForceUTF8;
51             use Template;
52              
53             my $tt = Template->new(
54             LOAD_TEMPLATES => [ Template::Provider::Encoding->new ],
55             STASH => Template::Stash::ForceUTF8->new,
56             );
57              
58             # Everything should be Unicode
59             # (but you can pass UTF-8 bytes as well, thanks to Template::Stash::ForceUTF8)
60             my $author = "\x{5bae}\x{5ddd}";
61              
62             # this will emit Unicode flagged string to STDOUT. You might
63             # probably want to binmode(STDOUT, ":encoding($enccoding)")
64             # before process() call
65             $tt->process($template, { author => $author });
66              
67             # in your templates
68             [% USE encoding 'utf-8' -%]
69             My name is [% author %]. { ... whatever UTF-8 bytes }
70              
71             =head1 DESCRIPTION
72              
73             Template::Provider::Encoding is a Template Provider subclass to decode
74             template using its declaration. You have to declare encoding of the
75             template in the head (1st line) of template using (fake) encoding TT
76             plugin. Otherwise the template is handled as utf-8.
77              
78             [% USE encoding 'utf-8' %]
79             Here comes utf-8 strings with [% variable %].
80              
81             =head1 DIFFERNCE WITH OTHER WAYS
82              
83             =head2 UNICODE option and BOM
84              
85             Recent TT allows C<UNICODE> option to Template::Provider and by adding
86             it Provider scans BOM (byte-order mark) to detect UTF-8/UTF-16 encoded
87             template files. This module does basically the same thing in a
88             different way, but IMHO adding BOM to template files is a little
89             painful especially for non-programmers.
90              
91             =head2 Template::Provider::Encode
92              
93             L<Template::Provider::Encode> provides a very similar way to detect
94             Template file encodings and output the template into various
95             encodings.
96              
97             This module doesn't touch output encoding of the template and instead
98             it emits valid Unicode flagged string. I think the output encoding
99             conversion should be done by other piece of code, especially in the
100             framework.
101              
102             This module doesn't require you to specify encoding in the code, nor
103             doesn't I<guess> encodings. Instead it forces you to put C<< [% USE
104             encoding 'foo-bar' %] >> in the top of template files, which is
105             explicit and, I think, is a good convention.
106              
107             =head1 AUTHOR
108              
109             Tatsuhiko Miyagawa E<lt>miyagawa@bulknews.netE<gt>
110              
111             This library is free software; you can redistribute it and/or modify
112             it under the same terms as Perl itself.
113              
114             =head1 SEE ALSO
115              
116             L<Template::Stash::ForceUTF8>, L<Template::Provider::Encode>
117              
118             =cut