ext/Encode/lib/Encode/MIME/Header.pm

   1 package Encode::MIME::Header;
   2 use strict;
   3 # use warnings;
   4 our $VERSION = do { my @r = (q$Revision: 1.3 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
   5
   6 use Encode qw(find_encoding encode_utf8);
   7 use MIME::Base64;
   8 use Carp;
   9
  10 my %seed =
  11     (
  12      decode_b     => '1', # decodes 'B' encoding ?
  13      decode_q     => '1', # decodes 'Q' encoding ?
  14      encode       => 'B', # encode with 'B' or 'Q' ?
  15      bpl          => 75,  # bytes per line
  16      );
  17
  18 $Encode::Encoding{'MIME-Header'} =
  19     bless {
  20         %seed,
  21         Name => 'MIME-Header',
  22     } => __PACKAGE__;
  23
  24 $Encode::Encoding{'MIME-B'} =
  25     bless {
  26         %seed,
  27         decode_q  => 0,
  28         Name      => 'MIME-B',
  29     } => __PACKAGE__;
  30
  31 $Encode::Encoding{'MIME-Q'} =
  32     bless {
  33         %seed,
  34         decode_q    => 1,
  35         encode      => 'Q',
  36         Name        => 'MIME-Q',
  37     } => __PACKAGE__;
  38
  39 use base qw(Encode::Encoding);
  40
  41 sub needs_lines { 1 }
  42 sub perlio_ok{ 0 };
  43
  44 sub decode($$;$){
  45     use utf8;
  46     my ($obj, $str, $chk) = @_;
  47     # zap spaces between encoded words
  48     $str =~ s/\?=\s+=\?/\?==\?/gos;
  49     # multi-line header to single line
  50     $str =~ s/(:?\r|\n|\r\n)[ \t]//gos;
  51     $str =~
  52         s{
  53             =\?                  # begin encoded word
  54                 ([0-9A-Za-z\-]+) # charset (encoding)
  55                 \?([QqBb])\?     # delimiter
  56                 (.*?)            # Base64-encodede contents
  57                 \?=              # end encoded word
  58             }{
  59                 if    (uc($2) eq 'B'){
  60                     $obj->{decode_b} or croak qq(MIME "B" unsupported);
  61                     decode_b($1, $3);
  62                 }elsif(uc($2) eq 'Q'){
  63                     $obj->{decode_q} or croak qq(MIME "Q" unsupported);
  64                     decode_q($1, $3);
  65                 }else{
  66                     croak qq(MIME "$2" encoding is nonexistent!);
  67                 }
  68             }egox;
  69     $_[1] = '' if $chk;
  70     return $str;
  71 }
  72
  73 sub decode_b{
  74     my $enc = shift;
  75     my $d = find_encoding($enc) or croak(Unknown encoding "$enc");
  76     my $db64 = decode_base64(shift);
  77     return $d->decode($db64, Encode::FB_PERLQQ);
  78 }
  79
  80 sub decode_q{
  81     my ($enc, $q) = @_;
  82     my $d = find_encoding($enc) or croak(Unknown encoding "$enc");
  83     $q =~ s/_/ /go;
  84     $q =~ s/=([0-9A-Fa-f]{2})/pack("C", hex($1))/ego;
  85     return $d->decode($q, Encode::FB_PERLQQ);
  86 }
  87
  88 my $especials =
  89     join('|' =>
  90          map {quotemeta(chr($_))}
  91          unpack("C*", qq{()<>@,;:\"\'/[]?.=}));
  92
  93 my $re_especials = qr/$especials/o;
  94
  95 sub encode($$;$){
  96     my ($obj, $str, $chk) = @_;
  97     my @line = ();
  98     for my $line (split /\r|\n|\r\n/o, $str){
  99         my (@word, @subline);
 100         for my $word (split /($re_especials)/o, $line){
 101             if ($word =~ /[^\x00-\x7f]/o){
 102                 push @word, $obj->_encode($word);
 103             }else{
 104                 push @word, $word;
 105             }
 106         }
 107         my $subline = '';
 108         for my $word (@word){
 109             use bytes ();
 110             if (bytes::length($subline) + bytes::length($word) > $obj->{bpl}){
 111                 push @subline, $subline;
 112                 $subline = '';
 113             }
 114             $subline .= $word;
 115         }
 116         $subline and push @subline, $subline;
 117         push @line, join("\n " => @subline);
 118     }
 119     $_[1] = '' if $chk;
 120     return join("\n", @line);
 121 }
 122
 123 use constant HEAD  => '=?UTF-8?';
 124 use constant TAIL    => '?=';
 125 use constant SINGLE => { B => \&_encode_b, Q => \&_encode_q, };
 126
 127 sub _encode{
 128     my ($o, $str) = @_;
 129     my $enc = $o->{encode};
 130     my $llen = ($o->{bpl} - length(HEAD) - 2 - length(TAIL));
 131     $llen *= $enc eq 'B' ? 3/4 : 1/3;
 132     my @result = ();
 133     my $chunk = '';
 134     while(my $chr = substr($str, 0, 1, '')){
 135         use bytes ();
 136         if (bytes::length($chunk) + bytes::length($chr) > $llen){
 137             push @result, SINGLE->{$enc}($chunk);
 138             $chunk = '';
 139         }
 140         $chunk .= $chr;
 141     }
 142     $chunk and push @result, SINGLE->{$enc}($chunk);
 143     return @result;
 144 }
 145
 146 sub _encode_b{
 147     HEAD . 'B?' . encode_base64(encode_utf8(shift), '') . TAIL;
 148 }
 149
 150 sub _encode_q{
 151     my $chunk = shift;
 152     $chunk =~ s{
 153                 ([^0-9A-Za-z])
 154                }{
 155                    join("" => map {sprintf "=%02X", $_} unpack("C*", $1))
 156                }egox;
 157     return HEAD . 'Q?' . $chunk . TAIL;
 158 }
 159
 160 1;
 161 __END__
 162
 163 =head1 NAME
 164
 165 Encode::MIME::Header -- MIME 'B' and 'Q' header encoding
 166
 167 =head1 SYNOPSIS
 168
 169     use Encode qw/encode decode/;
 170     $utf8   = decode('MIME-Header', $header);
 171     $header = encode('MIME-Header', $utf8);
 172
 173 =head1 ABSTRACT
 174
 175 This module implements RFC 2047 Mime Header Encoding.  There are 3
 176 variant encoding names; C<MIME-Header>, C<MIME-B> and C<MIME-Q>.  The
 177 difference is described below
 178
 179               decode()          encode()
 180   ----------------------------------------------
 181   MIME-Header Both B and Q      =?UTF-8?B?....?=
 182   MIME-B      B only; Q croaks  =?UTF-8?B?....?=
 183   MIME-Q      Q only; B croaks  =?UTF-8?Q?....?=
 184
 185 =head1 DESCRIPTION
 186
 187 When you decode(=?I<encoding>?I<X>?I<ENCODED WORD>?=), I<ENCODED WORD>
 188 is extracted and decoded for I<X> encoding (B for Base64, Q for
 189 Quoted-Printable). Then the decoded chunk is fed to
 190 decode(I<encoding>).  So long as I<encoding> is supported by Encode,
 191 any source encoding is fine.
 192
 193 When you encode, it just encodes UTF-8 string with I<X> encoding then
 194 quoted with =?UTF-8?I<X>?....?= .  The parts that RFC 2047 forbids to
 195 encode are left as is and long lines are folded within 76 bytes per
 196 line.
 197
 198 =head1 BUGS
 199
 200 It would be nice to support encoding to non-UTF8, such as =?ISO-2022-JP?
 201 and =?ISO-8859-1?= but that makes the implementation too complicated.
 202 These days major mail agents all support =?UTF-8? so I think it is
 203 just good enough.
 204
 205 =head1 SEE ALSO
 206
 207 L<Encode>
 208
 209 RFC 2047, L<http://www.faqs.org/rfcs/rfc2047.html> and many other
 210 locations.
 211
 212 =cut