README.md

   1 # NAME
   2
   3 MooseX::Storage - A serialization framework for Moose classes
   4
   5 # SYNOPSIS
   6
   7     package Point;
   8     use Moose;
   9     use MooseX::Storage;
  10
  11     with Storage('format' => 'JSON', 'io' => 'File');
  12
  13     has 'x' => (is => 'rw', isa => 'Int');
  14     has 'y' => (is => 'rw', isa => 'Int');
  15
  16     1;
  17
  18     my $p = Point->new(x => 10, y => 10);
  19
  20     ## methods to pack/unpack an
  21     ## object in perl data structures
  22
  23     # pack the class into a hash
  24     $p->pack(); # { __CLASS__ => 'Point-0.01', x => 10, y => 10 }
  25
  26     # unpack the hash into a class
  27     my $p2 = Point->unpack({ __CLASS__ => 'Point-0.01', x => 10, y => 10 });
  28
  29     ## methods to freeze/thaw into
  30     ## a specified serialization format
  31     ## (in this case JSON)
  32
  33     # pack the class into a JSON string
  34     $p->freeze(); # { "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }
  35
  36     # unpack the JSON string into a class
  37     my $p2 = Point->thaw('{ "__CLASS__" : "Point-0.01", "x" : 10, "y" : 10 }');
  38
  39     ## methods to load/store a class
  40     ## on the file system
  41
  42     $p->store('my_point.json');
  43
  44     my $p2 = Point->load('my_point.json');
  45
  46 # DESCRIPTION
  47
  48 MooseX::Storage is a serialization framework for Moose, it provides
  49 a very flexible and highly pluggable way to serialize Moose classes
  50 to a number of different formats and styles.
  51
  52 ## Important Note
  53
  54 This is still an early release of this module, so use with caution.
  55 It's outward facing serialization API should be considered stable,
  56 but I still reserve the right to make tweaks if I need too. Anything
  57 beyond the basic pack/unpack, freeze/thaw and load/store should not
  58 be relied on.
  59
  60 ## Levels of Serialization
  61
  62 There are 3 levels to the serialization, each of which builds upon
  63 the other and each of which can be customized to the specific needs
  64 of your class.
  65
  66 - __base__
  67
  68     The first (base) level is `pack` and `unpack`. In this level the
  69     class is serialized into a Perl HASH reference, it is tagged with the
  70     class name and each instance attribute is stored. Very simple.
  71
  72     This level is not optional, it is the bare minimum that
  73     MooseX::Storage provides and all other levels build on top of this.
  74
  75     See [MooseX::Storage::Basic](http://search.cpan.org/perldoc?MooseX::Storage::Basic) for the fundamental implementation and
  76     options to `pack` and `unpack`
  77
  78 - __format__
  79
  80     The second (format) level is `freeze` and `thaw`. In this level the
  81     output of `pack` is sent to `freeze` or the output of `thaw` is sent
  82     to `unpack`. This levels primary role is to convert to and from the
  83     specific serialization format and Perl land.
  84
  85     This level is optional, if you don't want/need it, you don't have to
  86     have it. You can just use `pack`/`unpack` instead.
  87
  88 - __io__
  89
  90     The third (io) level is `load` and `store`. In this level we are reading
  91     and writing data to file/network/database/etc.
  92
  93     This level is also optional, in most cases it does require a `format` role
  94     to also be used, the exception being the `StorableFile` role.
  95
  96 ## Behaviour modifiers
  97
  98 The serialization behaviour can be changed by supplying `traits`.
  99 This can be done as follows:
 100
 101     use MooseX::Storage;
 102     with Storage( traits => [Trait1, Trait2,...] );
 103
 104 The following traits are currently bundled with `MooseX::Storage`:
 105
 106 - OnlyWhenBuilt
 107
 108     Only attributes that have been built (i.e., where the predicate returns
 109     'true') will be serialized. This avoids any potentially expensive computations.
 110
 111     See [MooseX::Storage::Traits::OnlyWhenBuilt](http://search.cpan.org/perldoc?MooseX::Storage::Traits::OnlyWhenBuilt) for details.
 112
 113 ## How we serialize
 114
 115 There are always limits to any serialization framework, there are just
 116 some things which are really difficult to serialize properly and some
 117 things which cannot be serialized at all.
 118
 119 ## What can be serialized?
 120
 121 Currently only numbers, string, ARRAY refs, HASH refs and other
 122 MooseX::Storage enabled objects are supported.
 123
 124 With Array and Hash references the first level down is inspected and
 125 any objects found are serialized/deserialized for you. We do not do
 126 this recursively by default, however this feature may become an
 127 option eventually.
 128
 129 The specific serialize/deserialize routine is determined by the
 130 Moose type constraint a specific attribute has. In most cases subtypes
 131 of the supported types are handled correctly, and there is a facility
 132 for adding handlers for custom types as well. This will get documented
 133 eventually, but it is currently still in development.
 134
 135 ## What can not be serialized?
 136
 137 We do not support CODE references yet, but this support might be added
 138 in using B::Deparse or some other deep magic.
 139
 140 Scalar refs are not supported, mostly because there is no way to know
 141 if the value being referenced will be there when the object is inflated.
 142 I highly doubt will be ever support this in a general sense, but it
 143 would be possible to add this yourself for a small specific case.
 144
 145 Circular references are specifically disallowed, however if you break
 146 the cycles yourself then re-assemble them later you can get around this.
 147 The reason we disallow circular refs is because they are not always supported
 148 in all formats we use, and they tend to be very tricky to do for all
 149 possible cases. It is almost always something you want to have tight control
 150 over anyway.
 151
 152 # CAVEAT
 153
 154 This is __not__ a persistence framework; changes to your object after
 155 you load or store it will not be reflected in the stored class.
 156
 157 # EXPORTS
 158
 159 - __Storage (%options)__
 160
 161     This module will export the `Storage` method and can be used to
 162     load a specific set of MooseX::Storage roles to implement a specific
 163     combination of features. It is meant to make things easier, but it
 164     is by no means the only way. You can still compose your roles by
 165     hand if you like.
 166
 167     By default, options are assumed to be short forms.  For example, this:
 168
 169         Storage(format => 'JSON');
 170
 171     ...will result in looking for MooseX::Storage::Format::JSON.  To use a role
 172     that is not under the default namespace prefix, start with an equal sign:
 173
 174         Storage(format => '=My::Private::JSONFormat');
 175
 176     To use a parameterized role (for which, see [MooseX::Role::Parameterized](http://search.cpan.org/perldoc?MooseX::Role::Parameterized)) you
 177     can pass an arrayref of the role name (in short or long form, as above) and its
 178     parameters:
 179
 180         Storage(format => [ JSONpm => { json_opts => { pretty => 1 } } ]);
 181
 182 # METHODS
 183
 184 - __import__
 185
 186 ## Introspection
 187
 188 - __meta__
 189
 190 # TODO
 191
 192 This module needs docs and probably a Cookbook of some kind as well.
 193 This is an early release, so that is my excuse for now :)
 194
 195 For the time being, please read the tests and feel free to email me
 196 if you have any questions. This module can also be discussed on IRC
 197 in the \#moose channel on irc.perl.org.
 198
 199 # BUGS
 200
 201 All complex software has bugs lurking in it, and this module is no
 202 exception. If you find a bug please either email me, or add the bug
 203 to cpan-RT.
 204
 205 # AUTHOR
 206
 207 Chris Prather <chris.prather@iinteractive.com>
 208
 209 Stevan Little <stevan.little@iinteractive.com>
 210
 211 Yuval Kogman <yuval.kogman@iinteractive.com>
 212
 213 # COPYRIGHT AND LICENSE
 214
 215 Copyright 2007-2008 by Infinity Interactive, Inc.
 216
 217 [http://www.iinteractive.com](http://www.iinteractive.com)
 218
 219 This library is free software; you can redistribute it and/or modify
 220 it under the same terms as Perl itself.