Upgrade to Encode 0.96, from Dan Kogai.
[p5sagit/p5-mst-13.2.git] / ext / Encode / lib / Encode / Encoding.pm
1 package Encode::Encoding;
2 # Base class for classes which implement encodings
3 use strict;
4 our $VERSION = do { my @r = (q$Revision: 0.96 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
5
6 sub Define
7 {
8     my $obj = shift;
9     my $canonical = shift;
10     $obj = bless { Name => $canonical },$obj unless ref $obj;
11     # warn "$canonical => $obj\n";
12   Encode::define_encoding($obj, $canonical, @_);
13 }
14
15 sub name { shift->{'Name'} }
16
17 # Temporary legacy methods
18 sub toUnicode    { shift->decode(@_) }
19 sub fromUnicode  { shift->encode(@_) }
20
21 sub new_sequence { return $_[0] }
22
23 sub DESTROY {}
24
25 1;
26 __END__
27
28 =head1 NAME
29
30 Encode::Encoding - Encode Implementation Base Class
31
32 =head1 SYNOPSIS
33
34   package Encode::MyEncoding;
35   use base qw(Encode::Encoding);
36
37   __PACKAGE__->Define(qw(myCanonical myAlias));
38
39 =head1 DESCRIPTION
40
41 As mentioned in L<Encode>, encodings are (in the current
42 implementation at least) defined by objects. The mapping of encoding
43 name to object is via the C<%encodings> hash.
44
45 The values of the hash can currently be either strings or objects.
46 The string form may go away in the future. The string form occurs
47 when C<encodings()> has scanned C<@INC> for loadable encodings but has
48 not actually loaded the encoding in question. This is because the
49 current "loading" process is all Perl and a bit slow.
50
51 Once an encoding is loaded then value of the hash is object which
52 implements the encoding. The object should provide the following
53 interface:
54
55 =over 4
56
57 =item -E<gt>name
58
59 Should return the string representing the canonical name of the encoding.
60
61 =item -E<gt>new_sequence
62
63 This is a placeholder for encodings with state. It should return an
64 object which implements this interface, all current implementations
65 return the original object.
66
67 =item -E<gt>encode($string,$check)
68
69 Should return the octet sequence representing I<$string>. If I<$check>
70 is true it should modify I<$string> in place to remove the converted
71 part (i.e.  the whole string unless there is an error).  If an error
72 occurs it should return the octet sequence for the fragment of string
73 that has been converted, and modify $string in-place to remove the
74 converted part leaving it starting with the problem fragment.
75
76 If check is is false then C<encode> should make a "best effort" to
77 convert the string - for example by using a replacement character.
78
79 =item -E<gt>decode($octets,$check)
80
81 Should return the string that I<$octets> represents. If I<$check> is
82 true it should modify I<$octets> in place to remove the converted part
83 (i.e.  the whole sequence unless there is an error).  If an error
84 occurs it should return the fragment of string that has been
85 converted, and modify $octets in-place to remove the converted part
86 leaving it starting with the problem fragment.
87
88 If check is is false then C<decode> should make a "best effort" to
89 convert the string - for example by using Unicode's "\x{FFFD}" as a
90 replacement character.
91
92 =back
93
94 It should be noted that the check behaviour is different from the
95 outer public API. The logic is that the "unchecked" case is useful
96 when encoding is part of a stream which may be reporting errors
97 (e.g. STDERR).  In such cases it is desirable to get everything
98 through somehow without causing additional errors which obscure the
99 original one. Also the encoding is best placed to know what the
100 correct replacement character is, so if that is the desired behaviour
101 then letting low level code do it is the most efficient.
102
103 In contrast if check is true, the scheme above allows the encoding to
104 do as much as it can and tell layer above how much that was. What is
105 lacking at present is a mechanism to report what went wrong. The most
106 likely interface will be an additional method call to the object, or
107 perhaps (to avoid forcing per-stream objects on otherwise stateless
108 encodings) and additional parameter.
109
110 It is also highly desirable that encoding classes inherit from
111 C<Encode::Encoding> as a base class. This allows that class to define
112 additional behaviour for all encoding objects. For example built in
113 Unicode, UCS-2 and UTF-8 classes use :
114
115   package Encode::MyEncoding;
116   use base qw(Encode::Encoding);
117
118   __PACKAGE__->Define(qw(myCanonical myAlias));
119
120 To create an object with bless {Name => ...},$class, and call
121 define_encoding.  They inherit their C<name> method from
122 C<Encode::Encoding>.
123
124 =head2 Compiled Encodings
125
126 F<Encode.xs> provides a class C<Encode::XS> which provides the
127 interface described above. It calls a generic octet-sequence to
128 octet-sequence "engine" that is driven by tables (defined in
129 F<encengine.c>). The same engine is used for both encode and
130 decode. C<Encode:XS>'s C<encode> forces Perl's characters to their
131 UTF-8 form and then treats them as just another multibyte
132 encoding. C<Encode:XS>'s C<decode> transforms the sequence and then
133 turns the UTF-8-ness flag as that is the form that the tables are
134 defined to produce. For details of the engine see the comments in
135 F<encengine.c>.
136
137 The tables are produced by the Perl script F<compile> (the name needs
138 to change so we can eventually install it somewhere). F<compile> can
139 currently read two formats:
140
141 =over 4
142
143 =item *.enc
144
145 This is a coined format used by Tcl. It is documented in
146 Encode/EncodeFormat.pod.
147
148 =item *.ucm
149
150 This is the semi-standard format used by IBM's ICU package.
151
152 =back
153
154 F<compile> can write the following forms:
155
156 =over 4
157
158 =item *.ucm
159
160 See above - the F<Encode/*.ucm> files provided with the distribution have
161 been created from the original Tcl .enc files using this approach.
162
163 =item *.c
164
165 Produces tables as C data structures - this is used to build in encodings
166 into F<Encode.so>/F<Encode.dll>.
167
168 =item *.xs
169
170 In theory this allows encodings to be stand-alone loadable Perl
171 extensions.  The process has not yet been tested. The plan is to use
172 this approach for large East Asian encodings.
173
174 =back
175
176 The set of encodings built-in to F<Encode.so>/F<Encode.dll> is
177 determined by F<Makefile.PL>.  The current set is as follows:
178
179 =over 4
180
181 =item ascii and iso-8859-*
182
183 That is all the common 8-bit "western" encodings.
184
185 =item IBM-1047 and two other variants of EBCDIC.
186
187 These are the same variants that are supported by EBCDIC Perl as
188 "native" encodings.  They are included to prove "reversibility" of
189 some constructs in EBCDIC Perl.
190
191 =item symbol and dingbats as used by Tk on X11.
192
193 (The reason Encode got started was to support Perl/Tk.)
194
195 =back
196
197 That set is rather ad hoc and has been driven by the needs of the
198 tests rather than the needs of typical applications. It is likely
199 to be rationalized.
200
201 =cut