local-lib5/lib/perl5/Template/Provider/Encoding.pm

   1 package Template::Provider::Encoding;
   2
   3 use strict;
   4 our $VERSION = '0.10';
   5
   6 use base qw( Template::Provider );
   7 use Encode;
   8
   9 sub _init {
  10     my ($self, $params) = @_;
  11
  12     $self = $self->SUPER::_init($params);
  13     $self->{DEFAULT_ENCODING} = $params->{DEFAULT_ENCODING} || 'utf8';
  14     $self->{ENCODE_CHECK}     = $params->{ENCODE_CHECK} || Encode::FB_DEFAULT;
  15     return $self;
  16 }
  17
  18 sub _load {
  19     my $self = shift;
  20     my($data, $error) = $self->SUPER::_load(@_);
  21
  22     return ($data, $error) unless defined $data;
  23
  24     unless (Encode::is_utf8($data->{text})) {
  25         my $decoder = $self->detect_encoding($data);
  26         $data->{text} = $decoder->decode($data->{text}, $self->{ENCODE_CHECK});
  27     }
  28
  29     return ($data, $error);
  30 }
  31
  32 sub detect_encoding {
  33     my ($self, $data) = @_;
  34
  35     my $encoding = $data->{text} =~ /^\[% USE encoding '([\w\-]+)'/
  36         ? $1 : $self->{DEFAULT_ENCODING};
  37     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