Stateful PerlIO implemented [Was: [perl #22261] Was: Unrecognised BOM...]

Message-Id: <1C123D88-8D10-11D7-B277-000393AE4244@dan.co.jp>

p4raw-id: //depot/perl@19593

1 files changed, 24 insertions, 8 deletions

diff --git a/ext/Encode/lib/Encode/Encoding.pm b/ext/Encode/lib/Encode/Encoding.pm
index 0bb4350a63..3978e9df89 100644
--- a/ext/Encode/lib/Encode/Encoding.pm
+++ b/ext/Encode/lib/Encode/Encoding.pm
@@ -14,8 +14,10 @@ sub Define
     Encode::define_encoding($obj, $canonical, @_);
 }
 
-sub name         { return shift->{'Name'} }
-sub new_sequence { return $_[0] }
+sub name  { return shift->{'Name'} }
+
+sub renew { return $_[0] }
+*new_sequence = \&renew;
 
 sub needs_lines { 0 };
 
@@ -24,7 +26,8 @@ sub perlio_ok {
     return $@ ? 0 : 1;
 }
 
-# Temporary legacy methods
+# (Temporary|legacy) methods
+
 sub toUnicode    { shift->decode(@_) }
 sub fromUnicode  { shift->encode(@_) }
 
@@ -160,15 +163,28 @@ Predefined As:
 
 MUST return the string representing the canonical name of the encoding.
 
-=item -E<gt>new_sequence
+=item -E<gt>renew
 
 Predefined As:
 
-  sub new_sequence { return $_[0] }
+  sub renew { return $_[0] }
+
+This method reconstructs the encoding object if necessary.  If you need
+to store the state during encoding, this is where you clone your object.
+Here is an example:
+
+  sub renew { 
+      my $self = shift;
+      my $clone = bless { %$self } => ref($self);
+      $clone->{clone} = 1; # so the caller can see it
+      return $clone;
+  }
+
+Since most encodings are stateless the default behavior is just return
+itself as shown above.
 
-This is a placeholder for encodings with state. It should return an
-object which implements this interface.  All current implementations
-return the original object.
+PerlIO ALWAYS calls this method to make sure it has its own private
+encoding object.
 
 =item -E<gt>perlio_ok()