view release on metacpan or  search on metacpan

README  view on Meta::CPAN

            my $h = HTTP::XSHeaders->new(
                Content_Type => 'text/html; charset=utf8',
            );
            say "Content-Type: ", $h->header( 'Content-Type' );
            say "Serialising.";
            my $serial = Storable::freeze( $h );
            my $h2 = Storable::thaw( $serial );
            say "Is $h2 an object of HTTP::XSHeaders? ", ( $h2->isa( 'HTTP::XSHeaders' ) ? 'yes' : 'no' );
            say "Can $h2 do header? ", ( $h2->can( 'header' ) ? 'yes' : 'no' );
            say "Content-Type: ", $h2->header( 'Content-Type' );
            # Exception occurs here: "hl is not an instance of HTTP::XSHeaders"

        would produce:

            Content-Type: text/html; charset=utf8
            Serialising.
            Is My::Headers=HASH(0x555a5c06f198) an object of HTTP::XSHeaders? yes
            Can My::Headers=HASH(0x555a5c06f198) do header? yes
            hl is not an instance of HTTP::XSHeaders

        This is because, although the "HTTP::XSHeaders" object in this
        example created by Storable itself, is a blessed reference of
        HTTP::XSHeaders, that object cannot successfully call its own
        methods! This is because that object is not a native XS module
        object. Storable created that replica, but it is not working, and
        Storable could have taken from the best practices as implemented in
        the API of CBOR::XS or Sereal by taking and using the return value
        from STORABLE_thaw like CBOR::XS and Sereal do with the "THAW" hook,
        but nope.

        It would have made sense, since each module knows better than
        Storable what needs to be done ultimately to make their object work.

  STORABLE_freeze_pre_processing
    New

    If the data passed to "freeze" is a blessed reference and that
    "STORABLE_freeze_pre_processing" is implemented in the object's module,
    this is called by "freeze" before the object is serialised by Storable,
    giving it a chance to make it in a way that is acceptable to Storable
    without dying.

    Consider the following:

        use IO::File;
        my $io = IO::File->new( __FILE__, 'r' );
        my $serial = Storable::freeze( $io );

    would throw a fatal error that Storable does not accept glob, but if you
    did:

        use IO::File;
        local $Storable::forgive_me = 1;
        sub IO::File::STORABLE_freeze_pre_processing
        {
            my $self = shift( @_ );
            my $class = ref( $self ) || $self;
            my $args = [ __FILE__, 'r' ];
            # We change the glob object into a regular hash-based one to be Storable-friendly
            my $this = bless( { args => $args, class => $class } => $class );
            return( $this );
        }

        sub IO::File::STORABLE_thaw_post_processing
        {
            my $self = shift( @_ );
            my $args = $self->{args};
            my $class = $self->{class};
            # We restore our glob object. Geez that was hard. Not.
            my $obj = $class->new( @$args );
            return( $obj );
        }
        my $io = IO::File->new( __FILE__, 'r' );
        my $serial = Storable::Improved::freeze( $io );
        my $io2 = Storable::Improved::thaw( $serial );

    And here you go, $io2 would be equivalent to your initial glob, opened
    with the same arguments as the first one.

  STORABLE_thaw_post_processing
    New

    If the data passed to "freeze" is a blessed reference and that
    "STORABLE_thaw_post_processing" is implemented in the object's module,
    this is called by "thaw" after Storable has deserialised the data,
    giving you an opportunity to make final adjustments to make the module
    object a working one.

    Consider the following:

        use HTTP::XSHeaders;
        use Storable::Improved;
    
        sub HTTP::XSHeaders::STORABLE_freeze
        {
            my( $self, $cloning ) = @_;
            return if( $cloning );
            my $class = ref( $self ) || $self;
            my $h = {};
            my $headers = [];
            my $order = [];
            # Get all headers field and values in their original order
            $self->scan(sub
            {
                my( $f, $val ) = @_;
                if( exists( $h->{ $f } ) )
                {
                    $h->{ $f } = [ $h->{ $f } ] unless( ref( $h->{ $f } ) eq 'ARRAY' );
                    push( @{$h->{ $f }}, $val );
                }
                else
                {
                    $h->{ $f } = $val;
                    push( @$order, $f );
                }
            });
            foreach my $f ( @$order )
            {
                push( @$headers, $f, $h->{ $f } );
            }