Commit b4b9a160 authored by Nicholas Bamber's avatar Nicholas Bamber

[svn-upgrade] new version libdata-serializer-perl (0.56)

parent eea38331
......@@ -36,6 +36,9 @@ my $build = Module::Build->new
'JSON::Syck' => 0,
'XML::Simple' => 0,
'XML::Dumper' => 0,
'Bencode' => 0,
'Convert::Bencode' => 0,
'Convert::Bencode_XS' => 0,
'Compress::Zlib' => 0,
'Compress::PPMd' => 0,
'MIME::Base64' => 0,
......
Revision history for Perl extension Data::Serializer
0.56 Fri Jan 14 2011
- Moved store/retrieve internals to Data::Serializer::Persistent (internals only)
This defers the inclusion of IO::File to happen only if store or retrieve is called
- Added store/retireve to Data::Serializer::Raw
0.55 Fri Jan 14 2011
- Added support for Bencode, Convert::Bencode, and Convert::Bencode_XS
- Documentation updates
0.54 Thu Jan 13 2011
- Added Data::Serializer::Raw as a lightweight means of providing a unified raw access to the underlying serializers
also improved caching of serializer object inside of Data::Serializer
Thanks to Peter Makholm <peter@makholm.net> for the profiling done by Benchmark::Serialize
0.53 Mon Jan 10 2011
- Modified tests for XML::Simple - it has sub-dependencies on either XML::Parser or XML::SAX
the test harness was posting a failure if neither of these were present. Now it will treat XML::Simple
......
......@@ -7,6 +7,8 @@ INSTALL
Build.PL
Makefile.PL
lib/Data/Serializer.pm
lib/Data/Serializer/Raw.pm
lib/Data/Serializer/Persistent.pm
lib/Data/Serializer/Storable.pm
lib/Data/Serializer/FreezeThaw.pm
lib/Data/Serializer/Data/Dumper.pm
......@@ -20,6 +22,9 @@ lib/Data/Serializer/XML/Dumper.pm
lib/Data/Serializer/XML/Simple.pm
lib/Data/Serializer/Cookbook.pm
lib/Data/Serializer/JSON.pm
lib/Data/Serializer/Bencode.pm
lib/Data/Serializer/Convert/Bencode.pm
lib/Data/Serializer/Convert/Bencode_XS.pm
lib/Data/Serializer/JSON/Syck.pm
t/ExtUtils/TBone.pm
t/00-01-Signature.t
......@@ -37,7 +42,11 @@ t/01-10-Data-Taxi.t
t/01-11-YAML-Syck.t
t/01-12-JSON.t
t/01-13-JSON-Syck.t
t/02-Raw.t
t/01-14-Bencode.t
t/01-15-Convert-Bencode.t
t/01-16-Convert-Bencode_XS.t
t/02-01-Orig-Raw.t
t/02-02-Fast-Raw.t
t/03-Non-Portable.t
t/04-01-Compress-Zlib.t
t/04-02-Compress-PPMd.t
......
......@@ -17,13 +17,22 @@ name: Data-Serializer
provides:
Data::Serializer:
file: lib/Data/Serializer.pm
version: 0.53
version: 0.56
Data::Serializer::Bencode:
file: lib/Data/Serializer/Bencode.pm
version: 0.03
Data::Serializer::Config::General:
file: lib/Data/Serializer/Config/General.pm
version: 0.02
Data::Serializer::Convert::Bencode:
file: lib/Data/Serializer/Convert/Bencode.pm
version: 0.03
Data::Serializer::Convert::Bencode_XS:
file: lib/Data/Serializer/Convert/Bencode_XS.pm
version: 0.03
Data::Serializer::Cookbook:
file: lib/Data/Serializer/Cookbook.pm
version: 0.04
version: 0.05
Data::Serializer::Data::Denter:
file: lib/Data/Serializer/Data/Denter.pm
version: 0.02
......@@ -45,6 +54,12 @@ provides:
Data::Serializer::PHP::Serialization:
file: lib/Data/Serializer/PHP/Serialization.pm
version: 0.02
Data::Serializer::Persistent:
file: lib/Data/Serializer/Persistent.pm
version: 0.01
Data::Serializer::Raw:
file: lib/Data/Serializer/Raw.pm
version: 0.02
Data::Serializer::Storable:
file: lib/Data/Serializer/Storable.pm
version: 0.03
......@@ -61,9 +76,12 @@ provides:
file: lib/Data/Serializer/YAML/Syck.pm
version: 0.02
recommends:
Bencode: 0
Compress::PPMd: 0
Compress::Zlib: 0
Config::General: 0
Convert::Bencode: 0
Convert::Bencode_XS: 0
Crypt::Blowfish: 0
Crypt::CBC: 0
Data::Denter: 0
......@@ -87,4 +105,4 @@ requires:
IO::File: 0
resources:
license: http://dev.perl.org/licenses/
version: 0.53
version: 0.56
......@@ -23,6 +23,12 @@ DESCRIPTION
currently available. Adds the functionality of both compression and
encryption.
By default Data::Serializer(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 Data::Serializer::Raw(3) that comes bundled with
Data::Serializer(3).
EXAMPLES
Please see Data::Serializer::Cookbook(3)
......@@ -41,7 +47,7 @@ METHODS
options => {},
);
new is the constructor object for Data::Serializer objects.
new is the constructor object for Data::Serializer(3) objects.
* The default *serializer* is "Data::Dumper"
......@@ -90,18 +96,24 @@ METHODS
This is a straight pass through to the underlying serializer,
nothing else is done. (no encoding, encryption, compression, etc)
If you desire this functionality you should look at
Data::Serializer::Raw(3) instead, it is faster and leaner.
raw_deserialize - deserialize reference in raw form
$deserialized = $obj->raw_deserialize($serialized);
This is a straight pass through to the underlying serializer,
nothing else is done. (no encoding, encryption, compression, etc)
If you desire this functionality you should look at
Data::Serializer::Raw(3) instead, it is faster and leaner.
secret - specify secret for use with encryption
$obj->secret('mysecret');
Changes setting of secret for the Data::Serializer object. Can also
be set in the constructor. If specified than the object will utilize
encryption.
Changes setting of secret for the Data::Serializer(3) object. Can
also be set in the constructor. If specified than the object will
utilize encryption.
portable - encodes/decodes serialized data
Uses encoding method to ascii armor serialized data
......@@ -118,10 +130,28 @@ METHODS
to work in raw mode (see raw_serializer and raw_deserializer). The
default is for this to be off.
If you desire this functionality you should look at
Data::Serializer::Raw(3) instead, it is faster and leaner.
serializer - change the serializer
Currently have 8 supported serializers: Storable, FreezeThaw,
Data::Denter, Config::General, YAML, PHP::Serialization,
XML::Dumper, and Data::Dumper.
Currently supports the following serializers:
Bencode(3)
Convert::Bencode(3)
Convert::Bencode_XS(3)
Config::General(3)
Data::Denter(3)
Data::Dumper(3)
Data::Taxi(3)
FreezeThaw(3)
JSON(3)
JSON::Syck(3)
PHP::Serialization(3)
Storable(3)
XML::Dumper(3)
XML::Simple(3)
YAML(3)
YAML::Syck(3)
Default is to use Data::Dumper.
......@@ -131,32 +161,34 @@ METHODS
information.
cipher - change the cipher method
Utilizes Crypt::CBC and can support any cipher method that it
Utilizes Crypt::CBC(3) and can support any cipher method that it
supports.
digester - change digesting method
Uses Digest so can support any digesting method that it supports.
Uses Digest(3) so can support any digesting method that it supports.
Digesting function is used internally by the encryption routine as
part of data verification.
compressor - changes compresing module
Currently Compress::Zlib and Compress::PPMd are the only options
Currently Compress::Zlib(3) and Compress::PPMd(3) are the only
options
encoding - change encoding method
Encodes data structure in ascii friendly manner. Currently the only
valid options are hex, or b64.
The b64 option uses Base64 encoding provided by MIME::Base64, but
The b64 option uses Base64 encoding provided by MIME::Base64(3), but
strips out newlines.
serializer_token - add usage hint to data
Data::Serializer 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.
Data::Serializer(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 Data::Serializer::Raw(3) instead).
options - pass options through to underlying serializer
Currently is only supported by Config::General, and XML::Dumper.
Currently is only supported by Config::General(3), and
XML::Dumper(3).
my $obj = Data::Serializer->new(serializer => 'Config::General',
options => {
......@@ -210,7 +242,7 @@ AUTHOR
BUGS
Please report all bugs here:
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Serializer
http://rt.cpan.org/Public/Dist/Display.html?Name=Data-Serializer
TODO
Extend the persistent framework. Perhaps Persistent::Base(3) framework
......@@ -218,7 +250,7 @@ TODO
would be welcome.
COPYRIGHT AND LICENSE
Copyright (c) 2001-2008 Neil Neely. All rights reserved.
Copyright (c) 2001-2011 Neil Neely. All rights reserved.
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
......@@ -227,8 +259,8 @@ COPYRIGHT AND LICENSE
See http://www.perl.com/language/misc/Artistic.html
ACKNOWLEDGEMENTS
Gurusamy Sarathy and Raphael Manfredi for writing MLDBM, the module
which inspired the creation of Data::Serializer.
Gurusamy Sarathy and Raphael Manfredi for writing MLDBM(3), the module
which inspired the creation of Data::Serializer(3).
And thanks to all of you who have provided the feedback that has
improved this module over the years.
......@@ -240,23 +272,28 @@ DEDICATION
This module is dedicated to my beautiful wife Erica.
SEE ALSO
Data::Dumper(3)
Bencode(3)
Convert::Bencode(3)
Convert::Bencode_XS(3)
Config::General(3)
Data::Denter(3)
Data::Dumper(3)
Data::Taxi(3)
Storable(3)
FreezeThaw(3)
Config::General(3)
YAML(3)
YAML::Syck(3)
PHP::Serialization(3)
XML::Dumper(3)
JSON(3)
JSON::Syck(3)
PHP::Serialization(3)
Storable(3)
XML::Dumper(3)
XML::Simple(3)
YAML(3)
YAML::Syck(3)
Compress::Zlib(3)
Compress::PPMd(3)
Digest(3)
Digest::SHA(3)
Crypt(3)
Crypt::CBC(3)
MIME::Base64(3)
IO::File(3)
Data::Serializer::Config::Wrest(3) - adds supports for Config::Wrest(3)
......@@ -15,6 +15,17 @@ CONVENTIONS
Some examples will show different arguments to the new method, where
specified simply use that line instead of the simple form above.
CONVENTIONS for Raw Access
Fort hose who want a straight pass through to the underlying serializer,
where nothing else is done (no encoding, encryption, compression, etc)
there is Data::Serializer::Raw(3).
These begin like this:
use Data::Serializer::Raw;
my $raw_serializer = Data::Serializer::Raw->new();
Encrypting your data
You wish to encrypt your data structure, so that it can only be decoded
by someone who shares the same key.
......@@ -56,12 +67,11 @@ You want to read in data serialized outside of Data::Serializer
to process data serialized by XML::Dumper.
Solution
my $xml_serializer = Data::Serializer->(serializer => 'XML::Dumper', raw => 1);
use Data::Serializer::Raw;
my $hash_ref = $serializer->deserialize($xml_data);
my $xml_raw_serializer = Data::Serializer::Raw->(serializer => 'XML::Dumper');
Note: the raw_deserialize method can be used as well, but the above
approach is preferred.
my $hash_ref = $xml_raw_serializer->deserialize($xml_data);
You want to write serialized data in a form understood outside of Data::Serializer
You need to write a program that can write out data in a format other
......@@ -70,25 +80,26 @@ You want to write serialized data in a form understood outside of Data::Serializ
we will be exporting data using XML::Dumper format.
Solution
my $xml_serializer = Data::Serializer->(serializer => 'XML::Dumper', raw => 1);
ues Data::Serializer::Raw;
my $xml_data = $serializer->serialize($hash_ref);
my $xml_raw_serializer = Data::Serializer::Raw->(serializer => 'XML::Dumper');
Note: the raw_serialize method can be used as well, but the above
approach is preferred.
my $xml_data = $xml_raw_serializer->serialize($hash_ref);
You want to convert data between two different serializers native formats
You have data serialized by php that you want to convert to xml for use
by other programs.
Solution
my $xml_serializer = Data::Serializer->(serializer => 'XML::Dumper', raw => 1);
use Data::Serializer::Raw;
my $xml_raw_serializer = Data::Serializer::Raw->(serializer => 'XML::Dumper');
my $php_serializer = Data::Serializer->(serializer => 'PHP::Serialization', raw => 1);
my $php_raw_serializer = Data::Serializer::Raw->(serializer => 'PHP::Serialization');
my $hash_ref = $php_serializer->deserialize($php_data);
my $hash_ref = $php_raw_serializer->deserialize($php_data);
my $xml_data = $xml_serializer->serialize($hash_ref);
my $xml_data = $xml_raw_serializer->serialize($hash_ref);
Keeping data persistent between executions of a program.
You have a program that you run every 10 minutes, it uses SNMP to pull
......@@ -116,11 +127,12 @@ AUTHOR
Neil Neely <neil@neely.cx>.
COPYRIGHT
Copyright (c) 2001-2008 Neil Neely. All rights reserved.
Copyright (c) 2001-2011 Neil Neely. All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
Data::Serializer(3)
Data::Serializer::Raw(3)
This diff is collapsed.
package Data::Serializer::Bencode;
BEGIN { @Data::Serializer::Bencode::ISA = qw(Data::Serializer) }
use warnings;
use strict;
use Bencode;
use vars qw($VERSION @ISA);
$VERSION = '0.03';
sub serialize {
return Bencode::bencode($_[1]);
}
sub deserialize {
return Bencode::bdecode($_[1]);
}
1;
__END__
=head1 NAME
Data::Serializer::Bencode - Creates bridge between Data::Serializer and Bencode
=head1 SYNOPSIS
use Data::Serializer::Bencode;
=head1 DESCRIPTION
Module is used internally to Data::Serializer
=over 4
=item B<serialize> - Wrapper to normalize serializer method name
=item B<deserialize> - Wrapper to normalize deserializer method name
=back
=head1 AUTHOR
Neil Neely <F<neil@neely.cx>>.
http://neil-neely.blogspot.com/
=head1 BUGS
Please report all bugs here:
http://rt.cpan.org/Public/Dist/Display.html?Name=Data-Serializer
=head1 COPYRIGHT AND LICENSE
Copyright (c) 2011 Neil Neely. All rights reserved.
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.
=head1 SEE ALSO
perl(1), Data::Serializer(3), Bencode(3).
=cut
package Data::Serializer::Convert::Bencode;
BEGIN { @Data::Serializer::Convert::Bencode::ISA = qw(Data::Serializer) }
use warnings;
use strict;
use Convert::Bencode;
use vars qw($VERSION @ISA);
$VERSION = '0.03';
sub serialize {
return Convert::Bencode::bencode($_[1]);
}
sub deserialize {
return Convert::Bencode::bdecode($_[1]);
}
1;
__END__
=head1 NAME
Data::Serializer::Convert::Bencode - Creates bridge between Data::Serializer and Convert::Bencode
=head1 SYNOPSIS
use Data::Serializer::Convert::Bencode;
=head1 DESCRIPTION
Module is used internally to Data::Serializer
=over 4
=item B<serialize> - Wrapper to normalize serializer method name
=item B<deserialize> - Wrapper to normalize deserializer method name
=back
=head1 AUTHOR
Neil Neely <F<neil@neely.cx>>.
http://neil-neely.blogspot.com/
=head1 BUGS
Please report all bugs here:
http://rt.cpan.org/Public/Dist/Display.html?Name=Data-Serializer
=head1 COPYRIGHT AND LICENSE
Copyright (c) 2011 Neil Neely. All rights reserved.
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.
=head1 SEE ALSO
perl(1), Data::Serializer(3), Convert::Bencode(3).
=cut
package Data::Serializer::Convert::Bencode_XS;
BEGIN { @Data::Serializer::Convert::Bencode_XS::ISA = qw(Data::Serializer) }
use warnings;
use strict;
use Convert::Bencode_XS;
use vars qw($VERSION @ISA);
$VERSION = '0.03';
sub serialize {
return Convert::Bencode_XS::bencode($_[1]);
}
sub deserialize {
return Convert::Bencode_XS::bdecode($_[1]);
}
1;
__END__
=head1 NAME
Data::Serializer::Convert::Bencode_XS - Creates bridge between Data::Serializer and Convert::Bencode_XS
=head1 SYNOPSIS
use Data::Serializer::Convert::Bencode_XS;
=head1 DESCRIPTION
Module is used internally to Data::Serializer
=over 4
=item B<serialize> - Wrapper to normalize serializer method name
=item B<deserialize> - Wrapper to normalize deserializer method name
=back
=head1 AUTHOR
Neil Neely <F<neil@neely.cx>>.
http://neil-neely.blogspot.com/
=head1 BUGS
Please report all bugs here:
http://rt.cpan.org/Public/Dist/Display.html?Name=Data-Serializer
=head1 COPYRIGHT AND LICENSE
Copyright (c) 2011 Neil Neely. All rights reserved.
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.
=head1 SEE ALSO
perl(1), Data::Serializer(3), Convert::Bencode_XS(3).
=cut
......@@ -5,7 +5,7 @@ use warnings;
use strict;
use vars ('$VERSION');
$VERSION = '0.04';
$VERSION = '0.05';
1;
......@@ -35,6 +35,18 @@ begin with:
Some examples will show different arguments to the B<new> method,
where specified simply use that line instead of the simple form above.
=head1 CONVENTIONS for Raw Access
Fort hose who want a straight pass through to the underlying serializer, where
nothing else is done (no encoding, encryption, compression, etc) there is L<Data::Serializer::Raw(3)>.
These begin like this:
use Data::Serializer::Raw;
my $raw_serializer = Data::Serializer::Raw->new();
=head1 Encrypting your data
You wish to encrypt your data structure, so that it can only be decoded
......@@ -82,11 +94,11 @@ to be able to process data serialized by XML::Dumper.
=head2 Solution
my $xml_serializer = Data::Serializer->(serializer => 'XML::Dumper', raw => 1);
use Data::Serializer::Raw;
my $hash_ref = $serializer->deserialize($xml_data);
my $xml_raw_serializer = Data::Serializer::Raw->(serializer => 'XML::Dumper');
Note: the raw_deserialize method can be used as well, but the above approach is preferred.
my $hash_ref = $xml_raw_serializer->deserialize($xml_data);
=head1 You want to write serialized data in a form understood outside of Data::Serializer
......@@ -97,11 +109,12 @@ For our example we will be exporting data using XML::Dumper format.
=head2 Solution
my $xml_serializer = Data::Serializer->(serializer => 'XML::Dumper', raw => 1);
ues Data::Serializer::Raw;
my $xml_raw_serializer = Data::Serializer::Raw->(serializer => 'XML::Dumper');
my $xml_data = $serializer->serialize($hash_ref);
my $xml_data = $xml_raw_serializer->serialize($hash_ref);
Note: the raw_serialize method can be used as well, but the above approach is preferred.
=head1 You want to convert data between two different serializers native formats
......@@ -110,13 +123,15 @@ programs.
=head2 Solution
my $xml_serializer = Data::Serializer->(serializer => 'XML::Dumper', raw => 1);
use Data::Serializer::Raw;
my $php_serializer = Data::Serializer->(serializer => 'PHP::Serialization', raw => 1);
my $xml_raw_serializer = Data::Serializer::Raw->(serializer => 'XML::Dumper');
my $hash_ref = $php_serializer->deserialize($php_data);
my $php_raw_serializer = Data::Serializer::Raw->(serializer => 'PHP::Serialization');
my $xml_data = $xml_serializer->serialize($hash_ref);
my $hash_ref = $php_raw_serializer->deserialize($php_data);
my $xml_data = $xml_raw_serializer->serialize($hash_ref);
=head1 Keeping data persistent between executions of a program.
......@@ -148,7 +163,7 @@ Neil Neely <F<neil@neely.cx>>.
=head1 COPYRIGHT
Copyright (c) 2001-2008 Neil Neely. All rights reserved.
Copyright (c) 2001-2011 Neil Neely. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
......@@ -160,6 +175,8 @@ and/or modify it under the same terms as Perl itself.
=item L<Data::Serializer(3)>
=item L<Data::Serializer::Raw(3)>
=back
=cut
package Data::Serializer::Persistent;
use warnings;
use strict;
use vars qw($VERSION @ISA);
use IO::File;
use Carp;
$VERSION = '0.01';
sub _store {
my $self = (shift);
my $data = (shift);
my $file_or_fh = (shift);
if (ref($file_or_fh)) {
#it is a file handle so print straight to it
print $file_or_fh $self->{parent}->serialize($data), "\n";
#We didn't open the filehandle, so we shouldn't close it.
} else {
#it is a file, so open it
my ($mode,$perm) = @_;
unless (defined $mode) {
$mode = O_CREAT|O_WRONLY;
}
unless (defined $perm) {
$perm = 0600;
}
my $fh = new IO::File;
$fh->open($file_or_fh, $mode,$perm) || croak "Cannot write to $file_or_fh: $!";
print $fh $self->{parent}->serialize($data), "\n";
$fh->close();
}
}
sub _retrieve {
my $self = (shift);
my $file_or_fh = (shift);
if (ref($file_or_fh)) {
#it is a file handle so read straight from it
my $input = join('', <$file_or_fh>);
chomp($input);
return $self->{parent}->deserialize($input);
#We didn't open the filehandle, so we shouldn't close it.
} else {
my $fh = new IO::File;
$fh->open($file_or_fh, O_RDONLY) || croak "Cannot read from $file_or_fh: $!";
my $input = join('', <$fh>);
chomp($input);
$fh->close;
return $self->{parent}->deserialize($input);
}
}
1;
__END__
=pod
=head1 NAME
Data::Serializer::Persistent - Provide means of persistently storing serialized data in a file
=head1 SYNOPSIS
use Data::Serializer::Persistent
=head1 DESCRIPTION
Used internally to L<Data::Serializer(3)>, does not currently have any public methods
=head1 EXAMPLES
=over 4