ext/Encode/lib/Encode/Encoder.pm

   1 #
   2 # $Id: Encoder.pm,v 0.1 2002/04/08 02:35:10 dankogai Exp $
   3 #
   4 package Encoder;
   5 use strict;
   6 our $VERSION = do { my @r = (q$Revision: 0.1 $ =~ /\d+/g); sprintf "%d."."%02d"  x $#r, @r };
   7
   8 require Exporter;
   9 our @ISA = qw(Exporter);
  10 # Public, encouraged API is exported by default
  11 our @EXPORT = qw (
  12   encoder
  13 );
  14
  15 our $AUTOLOAD;
  16 our $DEBUG = 0;
  17 use Encode qw(encode decode find_encoding from_to);
  18 use Carp;
  19
  20 sub new{
  21     my ($class, $data, $encname) = @_;
  22     $encname ||= 'utf8';
  23     my $obj = find_encoding($encname)
  24         or croak __PACKAGE__, ": unknown encoding: $encname";
  25     my $self = {
  26                 data     => $data,
  27                 encoding => $obj->name,
  28                };
  29     bless $self => $class;
  30 }
  31
  32 sub encoder{ shift->new(@_) }
  33
  34 sub data{
  35     my ($self, $data) = shift;
  36     defined $data and $self->{data} = $data;
  37     return $self;
  38 }
  39
  40 sub encoding{
  41     my ($self, $encname) = @_;
  42     if ($encname){
  43         my $obj = find_encoding($encname)
  44             or confess __PACKAGE__, ": unknown encoding: $encname";
  45         $self->{encoding} = $obj->name;
  46     }
  47     $self;
  48 }
  49
  50 sub AUTOLOAD {
  51     my $self = shift;
  52     my $type = ref($self)
  53         or confess "$self is not an object";
  54     my $myname = $AUTOLOAD;
  55     $myname =~ s/.*://;   # strip fully-qualified portion
  56     my $obj = find_encoding($myname)
  57             or confess __PACKAGE__, ": unknown encoding: $myname";
  58     $DEBUG and warn $self->{encoding}, " => ", $obj->name;
  59     from_to($self->{data}, $self->{encoding}, $obj->name, 1);
  60     $self->{encoding} = $obj->name;
  61     return $self;
  62 }
  63
  64 use overload
  65     q("") => sub { $_[0]->{data} },
  66     q(0+) => sub { use bytes (); bytes::length($_[0]->{data}) },
  67     fallback => 1,
  68     ;
  69
  70 1;
  71 __END__
  72
  73 =head1 NAME
  74
  75 Encode::Encoder -- Object Oriented Encoder
  76
  77 =head1 SYNOPSIS
  78
  79   use Encode::Encoder;
  80   # Encode::encode("ISO-8859-1", $data);
  81   Encoder->new($data)->iso_8859_1; # OOP way
  82   # shortcut
  83   encoder($data)->iso_8859_1;
  84   # you can stack them!
  85   encoder($data)->iso_8859_1->base64; # provided base64() is defined
  86   # stringified
  87   print encoder($utf8)->latin1     # prints the string in latin1
  88   # numified
  89   encoder("\x{abcd}\x{ef}g") == 6; # true. bytes::length($data)
  90
  91 =head1 ABSTRACT
  92
  93 B<Encode::Encoder> allows you to use Encode via OOP style.  This is
  94 not only more intuitive than functional approach, but also handier
  95 when you want to stack encodings.  Suppose you want your UTF-8 string
  96 converted to Latin1 then Base64, you can simply say
  97
  98   my $base64 = encoder($utf8)->latin1->base64;
  99
 100 instead of
 101
 102   my $latin1 = encode("latin1", $utf8);
 103
 104 or lazier and convolted
 105
 106   my $base64 = encode_base64(encode("latin1", $utf8));
 107
 108 =head1 Description
 109
 110 Here is how to use this module.
 111
 112 =over 4
 113
 114 =item *
 115
 116 There are at least two instance variable stored in hash reference,
 117 {data} and {encoding}.
 118
 119 =item *
 120
 121 When there is no method, it takes the method name as the name of
 122 encoding and encode instance I<data> with I<encoding>.  If successful,
 123 instance I<encoding> is set accordingly.
 124
 125 =item *
 126
 127 This module is desined to work with L<Encode::Encoding>.
 128 To make the Base64 transcorder example above really work, you should
 129 write a module like this.
 130
 131   package Encode::Base64;
 132   use base 'Encode::Encoding';
 133   __PACKAGE->Define('base64');
 134   use MIME::Base64;
 135   sub encode{
 136     my ($obj, $data) = @_;
 137     return encode_base64($data);
 138   }
 139   sub decode{
 140     my ($obj, $data) = @_;
 141     return decode_base64($data);
 142   }
 143   1;
 144   __END__
 145
 146 And your caller module should be like this;
 147
 148   use Encode::Encoder;
 149   use Encode::Base64;
 150   # and be creative.
 151
 152 =head2 operator overloading
 153
 154 This module overloads two operators, stringify ("") and numify (0+).
 155
 156 Stringify dumps the data therein.
 157
 158 Numify returns the number of bytes therein.
 159
 160 They come in handy when you want to print or find the size of data.
 161
 162 =back
 163
 164 =head2 Predefined Methods
 165
 166 This module predefines the methods below;
 167
 168 =over 4
 169
 170 =item $e = Encode::Encoder-E<gt>new([$data, $encoding]);
 171
 172 returns the encoder object.  Its data is initialized with $data if
 173 there, and its encoding is set to $encoding if there.
 174
 175 =item encoder()
 176
 177 is an alias of Encode::Encoder-E<gt>new().  This one is exported for
 178 convenience.
 179
 180 =item $e-E<gt>data($data)
 181
 182 sets instance data to $data.
 183
 184 =item $e-E<gt>encoding($encoding)
 185
 186 sets instance encoding to $encoding
 187
 188 =back
 189
 190 =head1 SEE ALSO
 191
 192 L<Encode>
 193 L<Encode::Encoding>
 194
 195 =cut