Data::Serializer(3pm)

📦
version 0.65 · 6 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ Data::Serializer(3pm) ✨

okay so bestie, welcome to Data::Serializer — the perl module that serializes data structures and is, genuinely, that girl 💅

💖 NAME 💖

Data::Serializer:: — modules that serialize data structures. That's it, that's the whole vibe. She takes your data structures and she makes them strings. Iconic behaviour honestly 🎀

🌸 SYNOPSIS 🌸

like, here's the whole plot in five seconds:

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";

and then it prints 5. slay. ✨

🦋 DESCRIPTION 🦋

So the whole point of this module is giving you one unified interface to all the various serializing modules out there that are currently available. No more learning fifteen different APIs, bestie, we're not doing that anymore. On top of that it adds both compression and encryption. Like, the full glow-up. 💖

Here's the tea though: by default Data::Serializer(3) adds minor metadata and encodes serialized data structures in its own format. Which is fine! It's fine! But if what you actually want is just a simple unified pass-through interface to the underlying serializers, then go look at Data::Serializer::Raw(3) which comes bundled with Data::Serializer(3). iykyk 🫶

⭐ EXAMPLES ⭐

Please see Data::Serializer::Cookbook(3) — she's got all the recipes, go get fed. 🍓

💅 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(3) objects. Main character energy fr fr 👑

And here's the defaults, no surprises, no cap:

  • 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 {} (like, pass nothing on to serializer)

serialize — serialize reference

$serialized = $obj->serialize({a => [1,2,3],b => 5});

Serializes the reference you specified. Simple as that.

  • Will compress if compress is a true value.
  • Will encrypt if secret is defined.

deserialize — deserialize reference

$deserialized = $obj->deserialize($serialized);

Reverses the whole process of serialization and hands you back a copy of the original serialized reference. It's giving time travel honestly 🦋

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, no encryption, no compression, none of it. Just vibes and data.

ngl if this is the functionality you're after, you should look at Data::Serializer::Raw(3) instead — it's faster and leaner. fr fr.

raw_deserialize — deserialize reference in raw form

$deserialized = $obj->raw_deserialize($serialized);

Again, a straight pass through to the underlying serializer, nothing else is done. No encoding, no encryption, no compression, etc.

Same deal bestie, if you want this, use Data::Serializer::Raw(3) — faster and leaner. 🫶

secret — specify secret for use with encryption

$obj->secret('mysecret');

Changes the setting of the secret for the Data::Serializer(3) object. Can also be set in the constructor, obviously. And if it's specified, then the object will utilize encryption. 🔥

portable — encodes/decodes serialized data

Uses the encoding method to ascii armor your serialized data. It aids in the portability of serialized data. Basically she puts on a cute lil travel outfit so she can go anywhere. ✈️

compress — compression of data

Compresses serialized data. Default is not to use it — will compress if set to a true value.

$obj->compress(1);

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.

And yes, same note again: if you desire this functionality, please look at Data::Serializer::Raw(3) instead, it is faster and leaner. 💖

serializer — change the serializer

Currently supports the following serializers, bestie — take a lil scroll:

Default is to use Data::Dumper.

Heads up though: each serializer has its own caveats about usage, especially when dealing with cyclical data structures or CODE references. Please see the appropriate documentation in those modules for further information. Like, actually go read them, don't just wing it. 💀

cipher — change the cipher method

Utilizes Crypt::CBC(3) and can support any cipher method that it supports. She's flexible like that. 💅

digester — change digesting method

Uses Digest(3) so it can support any digesting method that it supports. The digesting function is used internally by the encryption routine as part of data verification. Lowkey the bouncer at the club checking IDs. 🎀

compressor — changes compressing module

Currently Compress::Zlib(3) and Compress::PPMd(3) are the only options. That's the whole list, bestie.

encoding — change encoding method

Encodes data structure in an ascii friendly manner. Currently the only valid options are hex or b64.

The b64 option uses Base64 encoding provided by MIME::Base64(3), but strips out newlines. Neat. ✨

serializer_token — add usage hint to data

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.) Like, I'm not gonna stop you but I'm gonna look at you weird. 🙈

options — pass options through to underlying serializer

Currently this is only supported by Config::General(3), and XML::Dumper(3).

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 you 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. She will let you know. Loudly.

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 the first line of the supplied file or filehandle and returns it deserialized. 🦋

💜 AUTHOR 💜

Neil Neely <neil@neely.cx>.

Feature requests are certainly welcome. Like genuinely, slide into the inbox. 🫶

http://neil-neely.blogspot.com/

💀 BUGS 💀

Please report all bugs here, bestie:

http://rt.cpan.org/Public/Dist/Display.html?Name=Data-Serializer

🌈 TODO 🌈

Extend the persistent framework. Perhaps Persistent::Base(3) framework would be useful to explore further. Volunteers for putting this together would be welcome — like, someone come be the main character here, please. 👑

Copyright (c) 2001-2020 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.

See http://www.perl.com/language/misc/Artistic.html

🫶 ACKNOWLEDGEMENTS 🫶

Gurusamy Sarathy and Raphael Manfredi for writing MLDBM(3), the module which inspired the creation of Data::Serializer(3). Legends, honestly. 🌟

And thanks to all of you who have provided the feedback that has improved this module over the years. That's so sweet actually. 😭

In particular I'd like to thank Florian Helmberger, for the numerous suggestions and bug fixes. The real MVP. 💖

🌸 DEDICATION 🌸

This module is dedicated to my beautiful wife Erica. Okay that's actually the cutest thing I've read all day, I'm not crying you're crying. 😭💖

🧚 REPOSITORY 🧚

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

✨ SEE ALSO ✨

and that's the whole page, bestie!! 🎉 this one's from perl v5.36.0 and it's dated 2022-10-22 — you can find her filed under Data::Serializer(3pm). go serialize something cute, ily, bye!! 💖✨🦋

📦 where this page comes from