# NAME

Object::Serializer - General Purpose Object Serializer

# VERSION

version 0.000007

# SYNOPSIS

    package Point;

    use Moo;
    use parent 'Object::Serializer';

    has 'x' => (is => 'rw');
    has 'y' => (is => 'rw');

    package main;

    my $p = Point->new(x => 10, y => 10);

    # serialize the class into a hash
    my $p1 = $p->serialize; # returns { __CLASS__ => 'Point', x => 10, y => 10 }

    # deserialize the hash into a class
    my $p2 = $p->deserialize($p1);

# DESCRIPTION

Getting objects into an ideal format for passing representations in and out of
applications can be a real pain. Object::Serializer is a fast and simple
pure-perl framework-agnostic type-less none-opinionated light-weight primitive
general purpose object serializer which tries to help make object serialization
easier. Note, this module should be considered experimental though I don't
anticipate the interface will change much.

# METHODS

## serialize

The serialize method expects an object and returns a serialized (hashified)
version of that object.

    my $hash = $self->serialize;
    my $hash = $self->serialize($object);
    my $hash = $self->serialize($object, marker => 0); # without any marker
    my $hash = $self->serialize($object, marker => '@'); # with @ as the marker

## deserialize

The deserialize method expects an object and returns a deserialized
(objectified) version of that object.

    my $object = $self->deserialize($object);
    my $hash = $self->serialize($object, marker => '@'); # with @ as the marker

## serialization\_strategy\_for

The serialization\_strategy\_for method expects a reftype and a list of key/value
pairs having the keys expand and/or collapse. This method registers a custom
serialization strategy to be used during the expanding and/or collapsing of
specific reference types.

    CLASS->serialization_strategy_for(
        REFTYPE => (
            expand   => sub { ... },
            collapse => sub { ... }
        )
    );

# EXTENSION

Object::Serializer can be used as a serializer independently, however, it is
primarily designed to be used as a base class for your classes or roles. By
default, Object::Serializer doesn't do anything special for you in the way of
serialization, however, you can easily hook into the serialization process by
defining your serialization strategy using your own custom serialization
routines which will be executed whenever a specific reference type is
encountered. The following syntax is what you might use to register your
own custom serialization strategy. This example registers a custom serializer
that is executed globally whenever a DateTime object is found. The expand and
collapse coderefs suggest what will happen on deserialization and serialization
respectively.

    Object::Serializer->serialization_strategy_for(
        DateTime => ( collapse => sub { pop->iso8601 } )
    );

Additionally, you can register a serialization strategy to be used only when
invoked by a specific class. The following syntax is what you might use to
register a serialization strategy to be executed only for a specific class:

    Point->serialization_strategy_for(
        DateTime => ( collapse => sub { pop->iso8601 } )
    );

# CAVEATS

Circular references are problematic and should be avoided, you can weaken or
otherwise handle them yourself then re-assemble them later as a means toward
getting around this. Blessed objects are made into hashes and tagged for
deserialization. Tagging blessed references other than hashrefs has not yet
been implemented. Custom serializers must match the object's reftype exactly to
be enacted. Extending the serialization process with a custom serialization
strategy usually means losing the ability to recreate (deserialize) the
serialized objects, i.e. custom serializers will usually be designed to either
expand or collapse but probably not both.

# AUTHOR

Al Newkirk <anewkirk@ana.io>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Al Newkirk.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
