CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
  • Methods you should implement
  • Other methods defined in Encode::Encodings
  • Example: Encode::ROT13
• Why the heck Encode API is different?
  • Compiled Encodings
• SEE ALSO

#NAME

Encode::Encoding - Encode Implementation Base Class

#SYNOPSIS

package Encode::MyEncoding;
use parent qw(Encode::Encoding);

__PACKAGE__->Define(qw(myCanonical myAlias));

#DESCRIPTION

As mentioned in Encode, encodings are (in the current implementation at least) defined as objects. The mapping of encoding name to object is via the %Encode::Encoding hash. Though you can directly manipulate this hash, it is strongly encouraged to use this base class module and add encode() and decode() methods.

#Methods you should implement

You are strongly encouraged to implement methods below, at least either encode() or decode().

#->encode($string [,$check])

MUST return the octet sequence representing $string.

• If $check is true, it SHOULD modify $string in place to remove the converted part (i.e. the whole string unless there is an error). If perlio_ok() is true, SHOULD becomes MUST.

• If an error occurs, it SHOULD return the octet sequence for the fragment of string that has been converted and modify $string in-place to remove the converted part leaving it starting with the problem fragment. If perlio_ok() is true, SHOULD becomes MUST.

• If $check is false then encode MUST make a "best effort" to convert the string - for example, by using a replacement character.

#->decode($octets [,$check])

MUST return the string that $octets represents.

• If $check is true, it SHOULD modify $octets in place to remove the converted part (i.e. the whole sequence unless there is an error). If perlio_ok() is true, SHOULD becomes MUST.

• If an error occurs, it SHOULD return the fragment of string that has been converted and modify $octets in-place to remove the converted part leaving it starting with the problem fragment. If perlio_ok() is true, SHOULD becomes MUST.

• If $check is false then decode should make a "best effort" to convert the string - for example by using Unicode's "\x{FFFD}" as a replacement character.

If you want your encoding to work with encoding pragma, you should also implement the method below.

#->cat_decode($destination, $octets, $offset, $terminator [,$check])

MUST decode $octets with $offset and concatenate it to $destination. Decoding will terminate when $terminator (a string) appears in output. $offset will be modified to the last $octets position at end of decode. Returns true if $terminator appears output, else returns false.

#Other methods defined in Encode::Encodings

You do not have to override methods shown below unless you have to.

#->name

Predefined As:

sub name  { return shift->{'Name'} }

MUST return the string representing the canonical name of the encoding.

#->mime_name

Predefined As:

sub mime_name{
  return Encode::MIME::Name::get_mime_name(shift->name);
}

MUST return the string representing the IANA charset name of the encoding.

#->renew

Predefined As:

sub renew {
  my $self = shift;
  my $clone = bless { %$self } => ref($self);
  $clone->{renewed}++;
  return $clone;
}

This method reconstructs the encoding object if necessary. If you need to store the state during encoding, this is where you clone your object.

PerlIO ALWAYS calls this method to make sure it has its own private encoding object.

#