Data::Serializer(3pm)

1Data::Serializer(3)   User Contributed Perl Documentation  Data::Serializer(3)
2
3
4

NAME

6       Data::Serializer:: - Modules that serialize data structures
7

SYNOPSIS

9         use Data::Serializer;
10
11         $obj = Data::Serializer->new();
12
13         $obj = Data::Serializer->new(
14                                 serializer => 'Storable',
15                                 digester   => 'MD5',
16                                 cipher     => 'DES',
17                                 secret     => 'my secret',
18                                 compress   => 1,
19                               );
20
21         $serialized = $obj->serialize({a => [1,2,3],b => 5});
22         $deserialized = $obj->deserialize($serialized);
23         print "$deserialized->{b}\n";
24

DESCRIPTION

26       Provides a unified interface to the various serializing modules
27       currently available.  Adds the functionality of both compression and
28       encryption.
29
30       By default Data::Serializer(3) adds minor metadata and encodes
31       serialized data structures in it's own format.  If you are looking for
32       a simple unified pass through interface to the underlying serializers
33       then look into Data::Serializer::Raw(3) that comes bundled with
34       Data::Serializer(3).
35

EXAMPLES

37       Please see Data::Serializer::Cookbook(3)
38

METHODS

40       new - constructor
41             $obj = Data::Serializer->new();
42
43
44             $obj = Data::Serializer->new(
45                                    serializer => 'Data::Dumper',
46                                    digester   => 'SHA-256',
47                                    cipher     => 'Blowfish',
48                                    secret     => undef,
49                                    portable   => '1',
50                                    compress   => '0',
51                              serializer_token => '1',
52                                      options  => {},
53                                   );
54
55           new is the constructor object for Data::Serializer(3) objects.
56
57           •   The default serializer is "Data::Dumper"
58
59           •   The default digester is "SHA-256"
60
61           •   The default cipher is "Blowfish"
62
63           •   The default secret is "undef"
64
65           •   The default portable is 1
66
67           •   The default encoding is "hex"
68
69           •   The default compress is 0
70
71           •   The default compressor is "Compress::Zlib"
72
73           •   The default serializer_token is 1
74
75           •   The default options is "{}" (pass nothing on to serializer)
76
77       serialize - serialize reference
78             $serialized = $obj->serialize({a => [1,2,3],b => 5});
79
80           Serializes the reference specified.
81
82           Will compress if compress is a true value.
83
84           Will encrypt if secret is defined.
85
86       deserialize - deserialize reference
87             $deserialized = $obj->deserialize($serialized);
88
89           Reverses the process of serialization and returns a copy of the
90           original serialized reference.
91
92       freeze - synonym for serialize
93             $serialized = $obj->freeze({a => [1,2,3],b => 5});
94
95       thaw - synonym for deserialize
96             $deserialized = $obj->thaw($serialized);
97
98       raw_serialize - serialize reference in raw form
99             $serialized = $obj->raw_serialize({a => [1,2,3],b => 5});
100
101           This is a straight pass through to the underlying serializer,
102           nothing else is done. (no encoding, encryption, compression, etc)
103
104           If you desire this functionality you should look at
105           Data::Serializer::Raw(3) instead, it is faster and leaner.
106
107       raw_deserialize - deserialize reference in raw form
108             $deserialized = $obj->raw_deserialize($serialized);
109
110           This is a straight pass through to the underlying serializer,
111           nothing else is done. (no encoding, encryption, compression, etc)
112
113           If you desire this functionality you should look at
114           Data::Serializer::Raw(3) instead, it is faster and leaner.
115
116       secret - specify secret for use with encryption
117             $obj->secret('mysecret');
118
119           Changes setting of secret for the Data::Serializer(3) object.  Can
120           also be set in the constructor.  If specified than the object will
121           utilize encryption.
122
123       portable - encodes/decodes serialized data
124           Uses encoding method to ascii armor serialized data
125
126           Aids in the portability of serialized data.
127
128       compress - compression of data
129           Compresses serialized data.  Default is not to use it.  Will
130           compress if set to a true value
131             $obj->compress(1);
132
133       raw - all calls to serializer and deserializer will automatically use
134       raw mode
135           Setting this to a true value will force serializer and deserializer
136           to work in raw mode (see raw_serializer and raw_deserializer).  The
137           default is for this to be off.
138
139           If you desire this functionality you should look at
140           Data::Serializer::Raw(3) instead, it is faster and leaner.
141
142       serializer - change the serializer
143           Currently supports the following serializers:
144
145           Bencode(3)
146           Convert::Bencode(3)
147           Convert::Bencode_XS(3)
148           Config::General(3)
149           Data::Denter(3)
150           Data::Dumper(3)
151           Data::Taxi(3)
152           FreezeThaw(3)
153           JSON(3)
154           JSON::Syck(3)
155           PHP::Serialization(3)
156           Storable(3)
157           XML::Dumper(3)
158           XML::Simple(3)
159           YAML(3)
160           YAML::Syck(3)
161
162           Default is to use Data::Dumper.
163
164           Each serializer has its own caveat's about usage especially when
165           dealing with cyclical data structures or CODE references.  Please
166           see the appropriate documentation in those modules for further
167           information.
168
169       cipher - change the cipher method
170           Utilizes Crypt::CBC(3) and can support any cipher method that it
171           supports.
172
173       digester - change digesting method
174           Uses Digest(3) so can support any digesting method that it
175           supports.  Digesting function is used internally by the encryption
176           routine as part of data verification.
177
178       compressor - changes compresing module
179           Currently Compress::Zlib(3) and Compress::PPMd(3) are the only
180           options
181
182       encoding - change encoding method
183           Encodes data structure in ascii friendly manner.  Currently the
184           only valid options are hex, or b64.
185
186           The b64 option uses Base64 encoding provided by MIME::Base64(3),
187           but strips out newlines.
188
189       serializer_token - add usage hint to data
190           Data::Serializer(3) prepends a token that identifies what was used
191           to process its data.  This is used internally to allow runtime
192           determination of how to extract serialized data.  Disabling this
193           feature is not recommended.   (Use Data::Serializer::Raw(3)
194           instead).
195
196       options - pass options through to underlying serializer
197           Currently is only supported by Config::General(3), and
198           XML::Dumper(3).
199
200             my $obj = Data::Serializer->new(serializer => 'Config::General',
201                                             options    => {
202                                                        -LowerCaseNames       => 1,
203                                                        -UseApacheInclude     => 1,
204                                                        -MergeDuplicateBlocks => 1,
205                                                        -AutoTrue             => 1,
206                                                        -InterPolateVars      => 1
207                                                           },
208                                                         ) or die "$!\n";
209
210             or
211
212             my $obj = Data::Serializer->new(serializer => 'XML::Dumper',
213                                             options    => { dtd => 1, }
214                                             ) or die "$!\n";
215
216       store - serialize data and write it to a file (or file handle)
217             $obj->store({a => [1,2,3],b => 5},$file, [$mode, $perm]);
218
219             or
220
221             $obj->store({a => [1,2,3],b => 5},$fh);
222
223           Serializes the reference specified using the serialize method and
224           writes it out to the specified file or filehandle.
225
226           If a file path is specified you may specify an optional mode and
227           permission as the next two arguments.  See IO::File for examples.
228
229           Trips an exception if it is unable to write to the specified file.
230
231       retrieve - read data from file (or file handle) and return it after
232       deserialization
233             my $ref = $obj->retrieve($file);
234
235             or
236
237             my $ref = $obj->retrieve($fh);
238
239           Reads first line of supplied file or filehandle and returns it
240           deserialized.
241

AUTHOR

243       Neil Neely <neil@neely.cx>.
244
245       Feature requests are certainly welcome.
246
247       http://neil-neely.blogspot.com/
248

BUGS

250       Please report all bugs here:
251
252       http://rt.cpan.org/Public/Dist/Display.html?Name=Data-Serializer
253

TODO

255       Extend the persistent framework.  Perhaps  Persistent::Base(3)
256       framework would be useful to explore further.  Volunteers for putting
257       this together would be welcome.
258

COPYRIGHT AND LICENSE

260       Copyright (c) 2001-2020 Neil Neely.  All rights reserved.
261
262       This library is free software; you can redistribute it and/or modify it
263       under the same terms as Perl itself, either Perl version 5.8.2 or, at
264       your option, any later version of Perl 5 you may have available.
265
266       See http://www.perl.com/language/misc/Artistic.html
267

ACKNOWLEDGEMENTS

269       Gurusamy Sarathy and Raphael Manfredi for writing MLDBM(3), the module
270       which inspired the creation of Data::Serializer(3).
271
272       And thanks to all of you who have provided the feedback that has
273       improved this module over the years.
274
275       In particular I'd like to thank Florian Helmberger, for the numerous
276       suggestions and bug fixes.
277

DEDICATION

279       This module is dedicated to my beautiful wife Erica.
280

REPOSITORY

282       <http://github.com/neilneely/Data-Serializer/>
283