Commit 900f5d18 authored by Krzysztof Krzyzaniak's avatar Krzysztof Krzyzaniak

[svn-inject] Installing original source of libdata-serializer-perl

parents
This diff is collapsed.
INSTALLATION
============
First unpack the kit, if you have not already done so:
tar -xzvf Data-Serializer-x.xx.tar.gz
cd Data-Serializer-x.xx
Data::Serializer can be installed with:
perl Makefile.PL
make
make test
make install
Changes
MANIFEST
README
INSTALL
Makefile.PL
lib/Data/Serializer.pm
lib/Data/Serializer/Storable.pm
lib/Data/Serializer/FreezeThaw.pm
lib/Data/Serializer/Data/Dumper.pm
lib/Data/Serializer/Data/Denter.pm
lib/Data/Serializer/Data/Taxi.pm
lib/Data/Serializer/Config/General.pm
lib/Data/Serializer/YAML.pm
lib/Data/Serializer/YAML/Syck.pm
lib/Data/Serializer/PHP/Serialization.pm
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/JSON/Syck.pm
t/ExtUtils/TBone.pm
t/01-01-Data-Dumper.t
t/01-02-Data-Denter.t
t/01-03-Storable.t
t/01-04-FreezeThaw.t
t/01-05-Config-General.t
t/01-06-YAML.t
t/01-07-XML-Dumper.t
t/01-08-PHP-Serialization.t
t/01-09-XML-Simple.t
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/03-Non-Portable.t
t/04-Compression.t
t/05-Encryption.t
t/06-B64-Encoding.t
t/07-01-MD5-Digest.t
t/07-02-SHA1-Digest.t
t/07-03-SHA-256-Digest.t
t/08-Store-Retrieve.t
t/09-Feature-Combos.t
t/serializer-testlib
META.yml Module meta-data (added by MakeMaker)
# http://module-build.sourceforge.net/META-spec.html
#XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
name: Data-Serializer
version: 0.39
version_from: lib/Data/Serializer.pm
installdirs: site
requires:
Data::Dumper: 2.08
Digest::SHA: 0
IO::File: 0
distribution_type: module
generated_by: ExtUtils::MakeMaker version 6.23
use ExtUtils::MakeMaker;
# See lib/ExtUtils/MakeMaker.pm for details of how to influence
# the contents of the Makefile that is written.
#
WriteMakefile(
'NAME' => 'Data::Serializer',
'DISTNAME' => 'Data-Serializer',
'VERSION_FROM' => 'lib/Data/Serializer.pm', # finds $VERSION
'AUTHOR' => 'Neil Neely (neil@frii.net)',
'PREREQ_PM' => {
'IO::File' => 0,
'Digest::SHA' => 0,
'Data::Dumper' => 2.08,
},
'dist' => {'COMPRESS'=>'gzip -9f', 'SUFFIX' => 'gz',
'ZIP'=>'/usr/bin/zip','ZIPFLAGS'=>'-rl'}
);
NAME
Data::Serializer:: - Modules that serialize data structures
SYNOPSIS
use Data::Serializer;
$obj = Data::Serializer->new();
$obj = Data::Serializer->new(
serializer => 'Storable',
digester => 'MD5',
cipher => 'DES',
secret => 'my secret',
compress => 1,
);
$serialized = $obj->serialize({a => [1,2,3],b => 5});
$deserialized = $obj->deserialize($serialized);
print "$deserialized->{b}\n";
DESCRIPTION
Provides a unified interface to the various serializing modules
currently available. Adds the functionality of both compression and
encryption.
EXAMPLES
Please see Data::Serializer::Cookbook(3)
METHODS
new - constructor
$obj = Data::Serializer->new();
$obj = Data::Serializer->new(
serializer => 'Data::Dumper',
digester => 'SHA-256',
cipher => 'Blowfish',
secret => undef,
portable => '1',
compress => '0',
serializer_token => '1',
options => {},
);
new is the constructor object for Data::Serializer objects.
* The default *serializer* is "Data::Dumper"
* The default *digester* is "SHA-256"
* The default *cipher* is "Blowfish"
* The default *secret* is "undef"
* The default *portable* is 1
* The default *encoding* is "hex"
* The default *compress* is 0
* The default *compressor* is "Compress::Zlib"
* The default *serializer_token* is 1
* The default *options* is "{}" (pass nothing on to serializer)
serialize - serialize reference
$serialized = $obj->serialize({a => [1,2,3],b => 5});
Serializes the reference specified.
Will compress if compress is a true value.
Will encrypt if secret is defined.
deserialize - deserialize reference
$deserialized = $obj->deserialize($serialized);
Reverses the process of serialization and returns a copy of the
original serialized reference.
freeze - synonym for serialize
$serialized = $obj->freeze({a => [1,2,3],b => 5});
thaw - synonym for deserialize
$deserialized = $obj->thaw($serialized);
raw_serialize - serialize reference in raw form
$serialized = $obj->raw_serialize({a => [1,2,3],b => 5});
This is a straight pass through to the underlying serializer,
nothing else is done. (no encoding, encryption, compression, etc)
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)
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.
portable - encodes/decodes serialized data
Uses encoding method to ascii armor serialized data
Aids in the portability of serialized data.
compress - compression of data
Compresses serialized data. Default is not to use it. Will compress
if set to a true value $obj->compress(1);
serializer - change the serializer
Currently have 8 supported serializers: Storable, FreezeThaw,
Data::Denter, Config::General, YAML, PHP::Serialization,
XML::Dumper, and Data::Dumper.
Default is to use Data::Dumper.
Each serializer has its own caveat's about usage especially when
dealing with cyclical data structures or CODE references. Please see
the appropriate documentation in those modules for further
information.
cipher - change the cipher method
Utilizes Crypt::CBC and can support any cipher method that it
supports.
digester - change digesting method
Uses Digest 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
This method is included for possible future inclusion of alternate
compression method Currently Compress::Zlib is the only supported
compressor.
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
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.
options - pass options through to underlying serializer
Currently is only supported by Config::General, and XML::Dumper.
my $obj = Data::Serializer->new(serializer => 'Config::General',
options => {
-LowerCaseNames => 1,
-UseApacheInclude => 1,
-MergeDuplicateBlocks => 1,
-AutoTrue => 1,
-InterPolateVars => 1
},
) or die "$!\n";
or
my $obj = Data::Serializer->new(serializer => 'XML::Dumper',
options => { dtd => 1, }
) or die "$!\n";
store - serialize data and write it to a file (or file handle)
$obj->store({a => [1,2,3],b => 5},$file, [$mode, $perm]);
or
$obj->store({a => [1,2,3],b => 5},$fh);
Serializes the reference specified using the serialize method and
writes it out to the specified file or filehandle.
If a file path is specified you may specify an optional mode and
permission as the next two arguments. See IO::File for examples.
Trips an exception if it is unable to write to the specified file.
retrieve - read data from file (or file handle) and return it after
deserialization
my $ref = $obj->retrieve($file);
or
my $ref = $obj->retrieve($fh);
Reads first line of supplied file or filehandle and returns it
deserialized.
TRANSIENCE
Data::Serializer is aware of Tie::Transient. What this means is that you
use Tie::Transient as normal, and when your object is serialized, the
transient components will be automatically removed for you.
Tie::Transient is not on CPAN, and doesn't look like it ever will be.
With the advent of attributes from 5.8 this feature should probably be
deprecated anyway.
If you would like to use Tie::Transient you can download it directly
from Brian's site here:
http://www.maz.org/perl/Tie-Transient-0.05.tar.gz
With perl attributes in 5.8, this should probably be deprecated.
AUTHOR
Neil Neely <neil@frii.net>.
Feature requests are certainly welcome.
BUGS
Please report all bugs here:
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Serializer
TODO
Phase out support for Tie::Transient
Extend the persistent framework. Perhaps Persistent::Base(3) framework
would be useful to explore further. Volunteers for putting this together
would be welcome.
COPYRIGHT
Copyright (c) 2001-2006 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 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.
And thanks to all of you who have provided the feedback that has
improved this module over the years.
In particular I'd like to thank Florian Helmberger, for the numerous
suggestions and bug fixes.
DEDICATION
This module is dedicated to my beautiful wife Erica.
SEE ALSO
Data::Dumper(3)
Data::Denter(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)
Compress::Zlib(3)
Digest(3)
Digest::SHA(3)
Crypt(3)
MIME::Base64(3)
IO::File(3)
Tie::Transient(3)
This diff is collapsed.
package Data::Serializer::Config::General;
BEGIN { @Data::Serializer::Config::General::ISA = qw(Data::Serializer) }
use strict;
use Config::General;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
require Exporter;
require AutoLoader;
@ISA = qw(Exporter AutoLoader);
@EXPORT = qw();
$VERSION = '0.01';
sub options {
return (shift)->{options};
}
sub serialize {
my $self = (shift);
my $ref = (shift);
return (new Config::General(%{$self->options()}, -ConfigHash => $ref))->save_string();
}
sub deserialize {
my $self = (shift);
my $ref = (shift);
my %hash = (new Config::General(%{$self->options()}, -String => $ref))->getall();
return \%hash;
}
1;
__END__
=head1 NAME
Data::Serializer::Config::General - Creates bridge between Data::Serializer and Config::General
=head1 SYNOPSIS
use Data::Serializer::Config::General;
=head1 DESCRIPTION
Module is used internally to Data::Serializer
=head1 METHODS
=over 4
=item B<serialize> - Wrapper to normalize serializer method name
=item B<deserialize> - Wrapper to normalize deserializer method name
=item B<options> - Pass options through to underlying serializer
=back
=head1 CAVEAT
Base data structure to serialize must be a hash reference
=head1 AUTHOR
Thomas Linden <tom@daemon.de>
=head1 COPYRIGHT
Copyright 2002 by Thomas Linden. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
=head1 SEE ALSO
perl(1), Data::Serializer(3), Config::General(3)
=cut
package Data::Serializer::Cookbook;
use warnings;
use strict;
use vars ('$VERSION');
$VERSION = '0.02';
1;
__END__;
#Documentation follows
=pod
=head1 NAME
Cookbook - Examples of how to use Data::Serializer
=head1 DESCRIPTION
B<Data::Serializer::Cookbook> is a collection of solutions
for using B<Data::Serializer>.
=head1 CONVENTIONS
Unless otherwise specified, all examples can be assumed to
begin with:
use Data::Serializer;
my $serializer = Data::Serializer->new();
Some examples will show different arguments to the B<new> method,
where specified simply use that line instead of the simple form above.
=head1 Encrypting your data
You wish to encrypt your data structure, so that it can only be decoded
by someone who shares the same key.
=head2 Solution
$serializer->secret('mysecret');
my $encrypted_hashref = $serializer->serializer($hash);
... (in other program) ...
$serializer->secret('mysecret');
my $clear_hash = $serializer->deserializer($encrypted_hash);
Note: You will have to have the Crypt::CBC module installed for
this to work.
=head1 Compressing your data
You wish to compress your data structure to cut down on how much
disk space it will take up.
=head2 Solution
$serializer->compress(1);
my $compressed_hashref = $serializer->serializer($hash);
... (in other program) ...
my $clear_hash = $serializer->deserializer($compressed_hash);
Note: You will have to have the Compress::Zlib module installed for
this to work. Your mileage will vary dramatically depending on what
serializer you use. Some serializers are already fairly compact.
=head1 You want to read in data serialized outside of Data::Serializer
You need to write a program that can read in data serialized in a
format other than Data::Serializer. For example you need to be able
to be able to process data serialized by XML::Dumper.
=head2 Solution
$serializer->serializer('XML::Dumper');
my $hash_ref = $serializer->raw_deserialize($xml_data);
=head1 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 than Data::Serializer. Or said more generically you need
to write out data in the format native to the underlying serializer.
For our example we will be exporting data using XML::Dumper format.
=head2 Solution
$serializer->serializer('XML::Dumper');
my $xml_data = $serializer->raw_serialize($hash_ref);
=head1 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.
=head2 Solution
my $xml_serializer = Data::Serializer->(serializer => 'XML::Dumper');
my $php_serializer = Data::Serializer->(serializer => 'PHP::Serialization');
my $hash_ref = $php_serializer->raw_deserialize($php_data);
my $xml_data = $xml_serializer->raw_serialize($hash_ref);
=head1 Keeping data persistent between executions of a program.
You have a program that you run every 10 minutes, it uses SNMP to pull
some counters from one of your routers. You want your program to keep
the counters from the last run so that it can see how much traffic has
passed over a link since it last ran.
=head2 Solution
# path to store our serialized data
# be paranoid, use full paths
my $last_run_datafile = '/full/path/to/file/lastrun.data';
#We keep our data as a hash reference
my $last_data = $serializer->retrieve($last_run_datafile);
#Pull in our new data through 'pull_data()';
my $new_data = query_router($router);
#run comparison code
run_comparison($last_data,$new_data);
$serializer->store($new_data);
=head1 AUTHOR
Neil Neely <F<neil@frii.net>>.
=head1 COPYRIGHT
Copyright (c) 2001-2004 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.
=head1 DEDICATION
This module is dedicated to my beautiful wife Erica,
because a woman of such quality deserves a dedication.
=head1 SEE ALSO
=over 4
=item L<Data::Dumper(3)>
=item L<Data::Denter(3)>
=item L<Storable(3)>
=item L<FreezeThaw(3)>
=item L<Config::General(3)>
=item L<YAML(3)>
=item L<PHP::Serialization(3)>
=item L<XML::Dumper(3)>
=item L<Compress::Zlib(3)>
=item L<Digest(3)>
=item L<Crypt(3)>
=item L<MIME::Base64(3)>
=item L<Tie::Transient(3)>
=back
=cut
package Data::Serializer::Data::Denter;
BEGIN { @Data::Serializer::Data::Denter::ISA = qw(Data::Serializer) }
use strict;
use Carp;
use Data::Denter;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
require Exporter;
require AutoLoader;
@ISA = qw(Exporter AutoLoader);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
);
$VERSION = '0.01';
# Preloaded methods go here.
# Autoload methods go after =cut, and are processed by the autosplit program.
1;
__END__
# Below is the stub of documentation for your module. You better edit it!
=head1 NAME
Data::Serializer::Data::Denter - Creates bridge between Data::Serializer and Data::Denter
=head1 SYNOPSIS
use Data::Serializer::Data::Denter;
=head1 DESCRIPTION
Module is used internally to Data::Serializer
=head1 AUTHOR
Neil Neely <neil@frii.net>
=head1 COPYRIGHT
Copyright 2002 by 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.
=head1 SEE ALSO
perl(1), Data::Serializer(3), Data::Denter(3).
=cut
#
# Create a Data::Denter serializer object.
#
sub serialize {
my $self = shift;
my ($val) = @_;
return undef unless defined $val;
return $val unless ref($val);
return Data::Denter::Indent($val);
}
sub deserialize {
my $self = shift;
my ($val) = @_;
return undef unless defined $val;
return Data::Denter::Undent($val);
}
package Data::Serializer::Data::Dumper;
BEGIN { @Data::Serializer::Data::Dumper::ISA = qw(Data::Serializer) }
use strict;
use Carp;
use Data::Dumper;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
require Exporter;
require AutoLoader;
@ISA = qw(Exporter AutoLoader);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
);
$VERSION = '0.04';
# Preloaded methods go here.
# Autoload methods go after =cut, and are processed by the autosplit program.
1;
__END__
# Below is the stub of documentation for your module. You better edit it!
=head1 NAME
Data::Serializer::Data::Dumper - Creates bridge between Data::Serializer and Data::Dumper
=head1 SYNOPSIS
use Data::Serializer::Data::Dumper;
=head1 DESCRIPTION
Module is used internally to Data::Serializer