.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Data::Serializer 3pm"
.TH Data::Serializer 3pm "2022-10-22" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Serializer:: \- Modules that serialize data structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Data::Serializer;
\&  
\&  $obj = Data::Serializer\->new();
\&
\&  $obj = Data::Serializer\->new(
\&                          serializer => \*(AqStorable\*(Aq,
\&                          digester   => \*(AqMD5\*(Aq,
\&                          cipher     => \*(AqDES\*(Aq,
\&                          secret     => \*(Aqmy secret\*(Aq,
\&                          compress   => 1,
\&                        );
\&
\&  $serialized = $obj\->serialize({a => [1,2,3],b => 5});
\&  $deserialized = $obj\->deserialize($serialized);
\&  print "$deserialized\->{b}\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides a unified interface to the various serializing modules
currently available.  Adds the functionality of both compression
and encryption.
.PP
By default \fBData::Serializer\fR\|(3) adds minor metadata and encodes serialized data
structures in it's own format.  If you are looking for a simple unified
pass through interface to the underlying serializers then look into \fBData::Serializer::Raw\fR\|(3) 
that comes bundled with \fBData::Serializer\fR\|(3).
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.IP "Please see \fBData::Serializer::Cookbook\fR\|(3)" 4
.IX Item "Please see Data::Serializer::Cookbook"
.SH "METHODS"
.IX Header "METHODS"
.PD 0
.IP "\fBnew\fR \- constructor" 4
.IX Item "new - constructor"
.PD
.Vb 1
\&  $obj = Data::Serializer\->new();
\&
\&
\&  $obj = Data::Serializer\->new(
\&                         serializer => \*(AqData::Dumper\*(Aq,
\&                         digester   => \*(AqSHA\-256\*(Aq,
\&                         cipher     => \*(AqBlowfish\*(Aq,
\&                         secret     => undef,
\&                         portable   => \*(Aq1\*(Aq,
\&                         compress   => \*(Aq0\*(Aq,
\&                   serializer_token => \*(Aq1\*(Aq,
\&                           options  => {},
\&                        );
.Ve
.Sp
\&\fBnew\fR is the constructor object for \fBData::Serializer\fR\|(3) objects.
.RS 4
.IP "\(bu" 4
The default \fIserializer\fR is \f(CW\*(C`Data::Dumper\*(C'\fR
.IP "\(bu" 4
The default \fIdigester\fR is \f(CW\*(C`SHA\-256\*(C'\fR
.IP "\(bu" 4
The default \fIcipher\fR is \f(CW\*(C`Blowfish\*(C'\fR
.IP "\(bu" 4
The default \fIsecret\fR is \f(CW\*(C`undef\*(C'\fR
.IP "\(bu" 4
The default \fIportable\fR is \f(CW1\fR
.IP "\(bu" 4
The default \fIencoding\fR is \f(CW\*(C`hex\*(C'\fR
.IP "\(bu" 4
The default \fIcompress\fR is \f(CW0\fR
.IP "\(bu" 4
The default \fIcompressor\fR is \f(CW\*(C`Compress::Zlib\*(C'\fR
.IP "\(bu" 4
The default \fIserializer_token\fR is \f(CW1\fR
.IP "\(bu" 4
The default \fIoptions\fR is \f(CW\*(C`{}\*(C'\fR (pass nothing on to serializer)
.RE
.RS 4
.RE
.IP "\fBserialize\fR \- serialize reference" 4
.IX Item "serialize - serialize reference"
.Vb 1
\&  $serialized = $obj\->serialize({a => [1,2,3],b => 5});
.Ve
.Sp
Serializes the reference specified.
.Sp
Will compress if compress is a true value.
.Sp
Will encrypt if secret is defined.
.IP "\fBdeserialize\fR \- deserialize reference" 4
.IX Item "deserialize - deserialize reference"
.Vb 1
\&  $deserialized = $obj\->deserialize($serialized);
.Ve
.Sp
Reverses the process of serialization and returns a copy 
of the original serialized reference.
.IP "\fBfreeze\fR \- synonym for serialize" 4
.IX Item "freeze - synonym for serialize"
.Vb 1
\&  $serialized = $obj\->freeze({a => [1,2,3],b => 5});
.Ve
.IP "\fBthaw\fR \- synonym for deserialize" 4
.IX Item "thaw - synonym for deserialize"
.Vb 1
\&  $deserialized = $obj\->thaw($serialized);
.Ve
.IP "\fBraw_serialize\fR \- serialize reference in raw form" 4
.IX Item "raw_serialize - serialize reference in raw form"
.Vb 1
\&  $serialized = $obj\->raw_serialize({a => [1,2,3],b => 5});
.Ve
.Sp
This is a straight pass through to the underlying serializer,
nothing else is done. (no encoding, encryption, compression, etc)
.Sp
If you desire this functionality you should look at \fBData::Serializer::Raw\fR\|(3) instead, it is 
faster and leaner.
.IP "\fBraw_deserialize\fR \- deserialize reference in raw form" 4
.IX Item "raw_deserialize - deserialize reference in raw form"
.Vb 1
\&  $deserialized = $obj\->raw_deserialize($serialized);
.Ve
.Sp
This is a straight pass through to the underlying serializer,
nothing else is done. (no encoding, encryption, compression, etc)
.Sp
If you desire this functionality you should look at \fBData::Serializer::Raw\fR\|(3) instead, it is 
faster and leaner.
.IP "\fBsecret\fR \- specify secret for use with encryption" 4
.IX Item "secret - specify secret for use with encryption"
.Vb 1
\&  $obj\->secret(\*(Aqmysecret\*(Aq);
.Ve
.Sp
Changes setting of secret for the \fBData::Serializer\fR\|(3) object.  Can also be set
in the constructor.  If specified than the object will utilize encryption.
.IP "\fBportable\fR \- encodes/decodes serialized data" 4
.IX Item "portable - encodes/decodes serialized data"
Uses \fBencoding\fR method to ascii armor serialized data
.Sp
Aids in the portability of serialized data.
.IP "\fBcompress\fR \- compression of data" 4
.IX Item "compress - compression of data"
Compresses serialized data.  Default is not to use it.  Will compress if set to a true value
  \f(CW$obj\fR\->\fBcompress\fR\|(1);
.IP "\fBraw\fR \- all calls to serializer and deserializer will automatically use raw mode" 4
.IX Item "raw - all calls to serializer and deserializer will automatically use raw mode"
Setting this to a true value will force serializer and deserializer to work in raw mode 
(see raw_serializer and raw_deserializer).  The default is for this to be off.
.Sp
If you desire this functionality you should look at \fBData::Serializer::Raw\fR\|(3) instead, it is 
faster and leaner.
.IP "\fBserializer\fR \- change the serializer" 4
.IX Item "serializer - change the serializer"
Currently supports the following serializers:
.RS 4
.IP "\fBBencode\fR\|(3)" 4
.IX Item "Bencode"
.PD 0
.IP "\fBConvert::Bencode\fR\|(3)" 4
.IX Item "Convert::Bencode"
.IP "\fBConvert::Bencode_XS\fR\|(3)" 4
.IX Item "Convert::Bencode_XS"
.IP "\fBConfig::General\fR\|(3)" 4
.IX Item "Config::General"
.IP "\fBData::Denter\fR\|(3)" 4
.IX Item "Data::Denter"
.IP "\fBData::Dumper\fR\|(3)" 4
.IX Item "Data::Dumper"
.IP "\fBData::Taxi\fR\|(3)" 4
.IX Item "Data::Taxi"
.IP "\fBFreezeThaw\fR\|(3)" 4
.IX Item "FreezeThaw"
.IP "\s-1\fBJSON\s0\fR\|(3)" 4
.IX Item "JSON"
.IP "\fBJSON::Syck\fR\|(3)" 4
.IX Item "JSON::Syck"
.IP "\fBPHP::Serialization\fR\|(3)" 4
.IX Item "PHP::Serialization"
.IP "\fBStorable\fR\|(3)" 4
.IX Item "Storable"
.IP "\fBXML::Dumper\fR\|(3)" 4
.IX Item "XML::Dumper"
.IP "\fBXML::Simple\fR\|(3)" 4
.IX Item "XML::Simple"
.IP "\s-1\fBYAML\s0\fR\|(3)" 4
.IX Item "YAML"
.IP "\fBYAML::Syck\fR\|(3)" 4
.IX Item "YAML::Syck"
.RE
.RS 4
.PD
.Sp
Default is to use Data::Dumper.
.Sp
Each serializer has its own caveat's about usage especially when dealing with
cyclical data structures or \s-1CODE\s0 references.  Please see the appropriate
documentation in those modules for further information.
.RE
.IP "\fBcipher\fR \- change the cipher method" 4
.IX Item "cipher - change the cipher method"
Utilizes \fBCrypt::CBC\fR\|(3) and can support any cipher method that it supports.
.IP "\fBdigester\fR \- change digesting method" 4
.IX Item "digester - change digesting method"
Uses \fBDigest\fR\|(3) so can support any digesting method that it supports.  Digesting
function is used internally by the encryption routine as part of data verification.
.IP "\fBcompressor\fR \- changes compresing module" 4
.IX Item "compressor - changes compresing module"
Currently \fBCompress::Zlib\fR\|(3) and \fBCompress::PPMd\fR\|(3) are the only options
.IP "\fBencoding\fR \- change encoding method" 4
.IX Item "encoding - change encoding method"
Encodes data structure in ascii friendly manner.  Currently the only valid options
are hex, or b64.
.Sp
The b64 option uses Base64 encoding provided by \fBMIME::Base64\fR\|(3), but strips out newlines.
.IP "\fBserializer_token\fR \- add usage hint to data" 4
.IX Item "serializer_token - add usage hint to data"
\&\fBData::Serializer\fR\|(3) prepends a token that identifies what was used to process its data.
This is used internally to allow runtime determination of how to extract serialized
data.  Disabling this feature is not recommended.   (Use \fBData::Serializer::Raw\fR\|(3) instead).
.IP "\fBoptions\fR \- pass options through to underlying serializer" 4
.IX Item "options - pass options through to underlying serializer"
Currently is only supported by \fBConfig::General\fR\|(3), and \fBXML::Dumper\fR\|(3).
.Sp
.Vb 9
\&  my $obj = Data::Serializer\->new(serializer => \*(AqConfig::General\*(Aq,
\&                                  options    => {
\&                                             \-LowerCaseNames       => 1,
\&                                             \-UseApacheInclude     => 1,
\&                                             \-MergeDuplicateBlocks => 1,
\&                                             \-AutoTrue             => 1,
\&                                             \-InterPolateVars      => 1
\&                                                },
\&                                              ) or die "$!\en";
\&
\&  or
\&
\&  my $obj = Data::Serializer\->new(serializer => \*(AqXML::Dumper\*(Aq,
\&                                  options    => { dtd => 1, }
\&                                  ) or die "$!\en";
.Ve
.IP "\fBstore\fR \- serialize data and write it to a file (or file handle)" 4
.IX Item "store - serialize data and write it to a file (or file handle)"
.Vb 1
\&  $obj\->store({a => [1,2,3],b => 5},$file, [$mode, $perm]);
\&
\&  or 
\&
\&  $obj\->store({a => [1,2,3],b => 5},$fh);
.Ve
.Sp
Serializes the reference specified using the \fBserialize\fR method
and writes it out to the specified file or filehandle.
.Sp
If a file path is specified you may specify an optional mode and permission as the
next two arguments.  See IO::File for examples.
.Sp
Trips an exception if it is unable to write to the specified file.
.IP "\fBretrieve\fR \- read data from file (or file handle) and return it after deserialization" 4
.IX Item "retrieve - read data from file (or file handle) and return it after deserialization"
.Vb 1
\&  my $ref = $obj\->retrieve($file);
\&
\&  or 
\&
\&  my $ref = $obj\->retrieve($fh);
.Ve
.Sp
Reads first line of supplied file or filehandle and returns it deserialized.
.SH "AUTHOR"
.IX Header "AUTHOR"
Neil Neely <\fIneil@neely.cx\fR>.
.PP
Feature requests are certainly welcome.
.PP
http://neil\-neely.blogspot.com/
.SH "BUGS"
.IX Header "BUGS"
Please report all bugs here:
.PP
http://rt.cpan.org/Public/Dist/Display.html?Name=Data\-Serializer
.SH "TODO"
.IX Header "TODO"
Extend the persistent framework.  Perhaps  \fBPersistent::Base\fR\|(3) framework
would be useful to explore further.  Volunteers for putting this together
would be welcome.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2001\-2020 Neil Neely.  All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.2 or,
at your option, any later version of Perl 5 you may have available.
.PP
See http://www.perl.com/language/misc/Artistic.html
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Gurusamy Sarathy and Raphael Manfredi for writing \s-1\fBMLDBM\s0\fR\|(3),
the module which inspired the creation of \fBData::Serializer\fR\|(3).
.PP
And thanks to all of you who have provided the feedback 
that has improved this module over the years.
.PP
In particular I'd like to thank Florian Helmberger, for the 
numerous suggestions and bug fixes.
.SH "DEDICATION"
.IX Header "DEDICATION"
This module is dedicated to my beautiful wife Erica.
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<http://github.com/neilneely/Data\-Serializer/>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\fBBencode\fR\|(3)" 4
.IX Item "Bencode"
.PD 0
.IP "\fBConvert::Bencode\fR\|(3)" 4
.IX Item "Convert::Bencode"
.IP "\fBConvert::Bencode_XS\fR\|(3)" 4
.IX Item "Convert::Bencode_XS"
.IP "\fBConfig::General\fR\|(3)" 4
.IX Item "Config::General"
.IP "\fBData::Denter\fR\|(3)" 4
.IX Item "Data::Denter"
.IP "\fBData::Dumper\fR\|(3)" 4
.IX Item "Data::Dumper"
.IP "\fBData::Taxi\fR\|(3)" 4
.IX Item "Data::Taxi"
.IP "\fBFreezeThaw\fR\|(3)" 4
.IX Item "FreezeThaw"
.IP "\s-1\fBJSON\s0\fR\|(3)" 4
.IX Item "JSON"
.IP "\fBJSON::Syck\fR\|(3)" 4
.IX Item "JSON::Syck"
.IP "\fBPHP::Serialization\fR\|(3)" 4
.IX Item "PHP::Serialization"
.IP "\fBStorable\fR\|(3)" 4
.IX Item "Storable"
.IP "\fBXML::Dumper\fR\|(3)" 4
.IX Item "XML::Dumper"
.IP "\fBXML::Simple\fR\|(3)" 4
.IX Item "XML::Simple"
.IP "\s-1\fBYAML\s0\fR\|(3)" 4
.IX Item "YAML"
.IP "\fBYAML::Syck\fR\|(3)" 4
.IX Item "YAML::Syck"
.IP "\fBCompress::Zlib\fR\|(3)" 4
.IX Item "Compress::Zlib"
.IP "\fBCompress::PPMd\fR\|(3)" 4
.IX Item "Compress::PPMd"
.IP "\fBDigest\fR\|(3)" 4
.IX Item "Digest"
.IP "\fBDigest::SHA\fR\|(3)" 4
.IX Item "Digest::SHA"
.IP "\fBCrypt::CBC\fR\|(3)" 4
.IX Item "Crypt::CBC"
.IP "\fBMIME::Base64\fR\|(3)" 4
.IX Item "MIME::Base64"
.IP "\fBIO::File\fR\|(3)" 4
.IX Item "IO::File"
.IP "\fBData::Serializer::Config::Wrest\fR\|(3) \- adds supports for \fBConfig::Wrest\fR\|(3)" 4
.IX Item "Data::Serializer::Config::Wrest - adds supports for Config::Wrest"