1Encode::Encoding(3pm) Perl Programmers Reference Guide Encode::Encoding(3pm)
2
6 Encode::Encoding - Encode Implementation Base Class
7
9 package Encode::MyEncoding;
10 use base qw(Encode::Encoding);
11 __PACKAGE__->Define(qw(myCanonical myAlias));
13
15 As mentioned in Encode, encodings are (in the current implementation at
16 least) defined as objects. The mapping of encoding name to object is
17 via the %Encode::Encoding hash. Though you can directly manipulate
18 this hash, it is strongly encouraged to use this base class module and
19 add encode() and decode() methods.
20 Methods you should implement
22 You are strongly encouraged to implement methods below, at least either
23 encode() or decode().
24 ->encode($string [,$check])
26 MUST return the octet sequence representing $string.
27 · If $check is true, it SHOULD modify $string in place to remove
29 the converted part (i.e. the whole string unless there is an
30 error). If perlio_ok() is true, SHOULD becomes MUST.
31 · If an error occurs, it SHOULD return the octet sequence for the
33 fragment of string that has been converted and modify $string in-
34 place to remove the converted part leaving it starting with the
35 problem fragment. If perlio_ok() is true, SHOULD becomes MUST.
36 · If $check is is false then "encode" MUST make a "best effort" to
38 convert the string - for example, by using a replacement
39 character.
40 ->decode($octets [,$check])
42 MUST return the string that $octets represents.
43 · If $check is true, it SHOULD modify $octets in place to remove
45 the converted part (i.e. the whole sequence unless there is an
46 error). If perlio_ok() is true, SHOULD becomes MUST.
47 · If an error occurs, it SHOULD return the fragment of string that
49 has been converted and modify $octets in-place to remove the
50 converted part leaving it starting with the problem fragment. If
51 perlio_ok() is true, SHOULD becomes MUST.
52 · If $check is false then "decode" should make a "best effort" to
54 convert the string - for example by using Unicode's "\x{FFFD}" as
55 a replacement character.
56 If you want your encoding to work with encoding pragma, you should also
58 implement the method below.
59 ->cat_decode($destination, $octets, $offset, $terminator [,$check])
61 MUST decode $octets with $offset and concatenate it to
62 $destination. Decoding will terminate when $terminator (a string)
63 appears in output. $offset will be modified to the last $octets
64 position at end of decode. Returns true if $terminator appears
65 output, else returns false.
66 Other methods defined in Encode::Encodings
68 You do not have to override methods shown below unless you have to.
69 ->name
71 Predefined As:
72 sub name { return shift->{'Name'} }
74 MUST return the string representing the canonical name of the
76 encoding.
77 ->mime_name
79 Predefined As:
80 sub mime_name{
82 require Encode::MIME::Name;
83 return Encode::MIME::Name::get_mime_name(shift->name);
84 }
85 MUST return the string representing the IANA charset name of the
87 encoding.
88 ->renew
90 Predefined As:
91 sub renew {
93 my $self = shift;
94 my $clone = bless { %$self } => ref($self);
95 $clone->{renewed}++;
96 return $clone;
97 }
98 This method reconstructs the encoding object if necessary. If you
100 need to store the state during encoding, this is where you clone
101 your object.
102 PerlIO ALWAYS calls this method to make sure it has its own private
104 encoding object.
105 ->renewed
107 Predefined As:
108 sub renewed { $_[0]->{renewed} || 0 }
110 Tells whether the object is renewed (and how many times). Some
112 modules emit "Use of uninitialized value in null operation" warning
113 unless the value is numeric so return 0 for false.
114 ->perlio_ok()
116 Predefined As:
117 sub perlio_ok {
119 eval{ require PerlIO::encoding };
120 return $@ ? 0 : 1;
121 }
122 If your encoding does not support PerlIO for some reasons, just;
124 sub perlio_ok { 0 }
126 ->needs_lines()
128 Predefined As:
129 sub needs_lines { 0 };
131 If your encoding can work with PerlIO but needs line buffering, you
133 MUST define this method so it returns true. 7bit ISO-2022
134 encodings are one example that needs this. When this method is
135 missing, false is assumed.
136 Example: Encode::ROT13
138 package Encode::ROT13;
139 use strict;
140 use base qw(Encode::Encoding);
141 __PACKAGE__->Define('rot13');
143 sub encode($$;$){
145 my ($obj, $str, $chk) = @_;
146 $str =~ tr/A-Za-z/N-ZA-Mn-za-m/;
147 $_[1] = '' if $chk; # this is what in-place edit means
148 return $str;
149 }
150 # Jr pna or ynml yvxr guvf;
152 *decode = \&encode;
153 1;
155
157 It should be noted that the $check behaviour is different from the
158 outer public API. The logic is that the "unchecked" case is useful when
159 the encoding is part of a stream which may be reporting errors (e.g.
160 STDERR). In such cases, it is desirable to get everything through
161 somehow without causing additional errors which obscure the original
162 one. Also, the encoding is best placed to know what the correct
163 replacement character is, so if that is the desired behaviour then
164 letting low level code do it is the most efficient.
165 By contrast, if $check is true, the scheme above allows the encoding to
167 do as much as it can and tell the layer above how much that was. What
168 is lacking at present is a mechanism to report what went wrong. The
169 most likely interface will be an additional method call to the object,
170 or perhaps (to avoid forcing per-stream objects on otherwise stateless
171 encodings) an additional parameter.
172 It is also highly desirable that encoding classes inherit from
174 "Encode::Encoding" as a base class. This allows that class to define
175 additional behaviour for all encoding objects.
176 package Encode::MyEncoding;
178 use base qw(Encode::Encoding);
179 __PACKAGE__->Define(qw(myCanonical myAlias));
181 to create an object with "bless {Name => ...}, $class", and call
183 define_encoding. They inherit their "name" method from
184 "Encode::Encoding".
185 Compiled Encodings
187 For the sake of speed and efficiency, most of the encodings are now
188 supported via a compiled form: XS modules generated from UCM files.
189 Encode provides the enc2xs tool to achieve that. Please see enc2xs for
190 more details.
191
193 perlmod, enc2xs
194perl v5.10.1 2009-02-12 Encode::Encoding(3pm)