2 # $Id: Encoder.pm,v 0.2 2002/04/08 18:08:07 dankogai Exp $
4 package Encode::Encoder;
7 our $VERSION = do { my @r = (q$Revision: 0.2 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
10 our @ISA = qw(Exporter);
11 our @EXPORT = qw ( encoder );
15 use Encode qw(encode decode find_encoding from_to);
19 my ($class, $data, $encname) = @_;
21 $encname = Encode::is_utf8($data) ? 'utf8' : '';
23 my $obj = find_encoding($encname)
24 or croak __PACKAGE__, ": unknown encoding: $encname";
25 $encname = $obj->name;
31 bless $self => $class;
34 sub encoder{ __PACKAGE__->new(@_) }
37 my ($self, $data) = shift;
39 $self->{data} = $data;
47 my ($self, $encname) = @_;
49 my $obj = find_encoding($encname)
50 or confess __PACKAGE__, ": unknown encoding: $encname";
51 $self->{encoding} = $obj->name;
54 return $self->{encoding}
59 my ($self, $encname) = @_;
60 $encname ||= $self->{encoding};
61 my $obj = find_encoding($encname)
62 or confess __PACKAGE__, ": unknown encoding: $encname";
63 $self->{data} = $obj->decode($self->{data}, 1);
64 $self->{encoding} = '' ;
68 sub DESTROY{ # defined so it won't autoload.
69 $DEBUG and warn shift;
75 or confess "$self is not an object";
76 my $myname = $AUTOLOAD;
77 $myname =~ s/.*://; # strip fully-qualified portion
78 my $obj = find_encoding($myname)
79 or confess __PACKAGE__, ": unknown encoding: $myname";
80 $DEBUG and warn $self->{encoding}, " => ", $obj->name;
81 if ($self->{encoding}){
82 from_to($self->{data}, $self->{encoding}, $obj->name, 1);
84 $self->{data} = $obj->encode($self->{data}, 1);
86 $self->{encoding} = $obj->name;
91 q("") => sub { $_[0]->{data} },
92 q(0+) => sub { use bytes (); bytes::length($_[0]->{data}) },
101 Encode::Encoder -- Object Oriented Encoder
106 # Encode::encode("ISO-8859-1", $data);
107 Encoder->new($data)->iso_8859_1; # OOP way
109 encoder($data)->iso_8859_1;
110 # you can stack them!
111 encoder($data)->iso_8859_1->base64; # provided base64() is defined
112 # you can use it as a decoder as well
113 encoder($base64)->bytes('base64')->latin1;
115 print encoder($data)->utf8->latin1; # prints the string in latin1
117 encoder("\x{abcd}\x{ef}g")->utf8 == 6; # true. bytes::length($data)
121 B<Encode::Encoder> allows you to use Encode via OOP style. This is
122 not only more intuitive than functional approach, but also handier
123 when you want to stack encodings. Suppose you want your UTF-8 string
124 converted to Latin1 then Base64, you can simply say
126 my $base64 = encoder($utf8)->latin1->base64;
130 my $latin1 = encode("latin1", $utf8);
131 my $base64 = encode_base64($utf8);
133 or lazier and convolted
135 my $base64 = encode_base64(encode("latin1", $utf8));
139 Here is how to use this module.
145 There are at least two instance variable stored in hash reference,
146 {data} and {encoding}.
150 When there is no method, it takes the method name as the name of
151 encoding and encode instance I<data> with I<encoding>. If successful,
152 instance I<encoding> is set accordingly.
156 You can retrieve the result via -E<gt>data but usually you don't have to
157 because the stringify operator ("") is overridden to do exactly that.
161 =head2 Predefined Methods
163 This module predefines the methods below;
167 =item $e = Encode::Encoder-E<gt>new([$data, $encoding]);
169 returns the encoder object. Its data is initialized with $data if
170 there, and its encoding is set to $encoding if there.
172 When $encoding is omitted, it defaults to utf8 if $data is already in
173 utf8 or "" (empty string) otherwise.
177 is an alias of Encode::Encoder-E<gt>new(). This one is exported for
180 =item $e-E<gt>data([$data])
182 when $data is present, sets instance data to $data and returns the
183 object itself. otherwise the current instance data is returned.
185 =item $e-E<gt>encoding([$encoding])
187 when $encoding is present, sets instance encoding to $encoding and
188 returns the object itself. otherwise the current instance encoding is
191 =item $e-E<gt>bytes([$encoding])
193 decodes instance data from $encoding, or instance encoding if omitted.
194 when the conversion is successful, the enstance encoding will be set
197 The name I<bytes> was deliberately picked to avoid namespace tainting
198 -- this module may be used as a base class so method names that appear
199 in Encode::Encoding are avoided.
203 =head2 Example: base64 transcoder
205 This module is desined to work with L<Encode::Encoding>.
206 To make the Base64 transcorder example above really work, you should
207 write a module like this.
209 package Encode::Base64;
210 use base 'Encode::Encoding';
211 __PACKAGE__->Define('base64');
214 my ($obj, $data) = @_;
215 return encode_base64($data);
218 my ($obj, $data) = @_;
219 return decode_base64($data);
224 And your caller module should be like this;
229 # now you can really do the following
231 encoder($data)->iso_8859_1->base64;
232 encoder($base64)->bytes('base64')->latin1;
234 =head2 operator overloading
236 This module overloads two operators, stringify ("") and numify (0+).
238 Stringify dumps the data therein.
240 Numify returns the number of bytes therein.
242 They come in handy when you want to print or find the size of data.