/ 
Bot-Cobalt-0.021003
River stage two • 15 direct dependents • 15 total dependents
/ Bot::Cobalt::Serializer

NAME

Bot::Cobalt::Serializer - Bot::Cobalt serialization wrapper

SYNOPSIS

use Bot::Cobalt::Serializer;

## Spawn a YAML (1.1) handler:
my $serializer = Bot::Cobalt::Serializer->new;

## Spawn a JSON handler:
my $serializer = Bot::Cobalt::Serializer->new('JSON');
## ...same as:
my $serializer = Bot::Cobalt::Serializer->new( Format => 'JSON' );

## Serialize some data to our Format:
my $ref = { Stuff => { Things => [ 'a', 'b'] } };
my $frozen = $serializer->freeze( $ref );

## Turn it back into a Perl data structure:
my $thawed = $serializer->thaw( $frozen );

## Serialize some $ref to a file at $path
## The file will be overwritten
## Returns false on failure
$serializer->writefile( $path, $ref );

## Do the same thing, but without locking
$serializer->writefile( $path, $ref, { Locking => 0 } );

## Turn a serialized file back into a $ref
## Boolean false on failure
my $ref = $serializer->readfile( $path );

## Do the same thing, but without locking
my $ref = $serializer->readfile( $path, { Locking => 0 } );

DESCRIPTION

Various pieces of Bot::Cobalt need to read and write serialized perl data from/to disk. This simple OO frontend makes it trivially easy to work with a selection of serialization formats, automatically enabling Unicode encode/decode and optionally providing the ability to read/write files directly.

Errors will typically throw fatal exceptions (usually with a stack trace) via "confess" in Carp -- you may want to look into Try::Tiny for handling them cleanly.

METHODS

new

my $serializer = Bot::Cobalt::Serializer->new;
my $serializer = Bot::Cobalt::Serializer->new( $format );
my $serializer = Bot::Cobalt::Serializer->new( %opts );

Spawn a serializer instance. Will croak with a stack trace if you are missing the relevant serializer module; see "Format", below.

The default is to spawn a YAML::XS (YAML1.1) serializer with error logging to carp.

You can spawn an instance using a different Format by passing the name of the format as an argument:

$handle_syck = Bot::Cobalt::Serializer->new('YAML');
$handle_yaml = Bot::Cobalt::Serializer->new('YAMLXS');
$handle_json = Bot::Cobalt::Serializer->new('JSON');

Format

Specify an input and output serialization format; this determines the serialization method used by "writefile", "readfile", "thaw", and "freeze" methods. (You can change formats on the fly by calling Format as a method.)

Currently available formats are:

The default is YAML (YAML Ain't Markup Language) 1.1 (YAMLXS)

YAML is very powerful, and the appearance of the output makes it easy for humans to read and edit.

JSON is a more simplistic format, often more suited for network transmission and talking to other networked apps. JSON is noticably faster than YAML.

freeze

Turn the specified reference $ref into the configured Format.

my $frozen = $serializer->freeze($ref);

Upon success returns a scalar containing the serialized format, suitable for saving to disk, transmission, etc.

thaw

Turn the specified serialized data (stored in a scalar) back into a Perl data structure.

my $ref = $serializer->thaw($data);

(Try Data::Dumper if you're not sure what your data actually looks like.)

writefile

"freeze" the specified $ref and write the serialized data to $path

$serializer->writefile($path, $ref);

Will croak with a stack trace if the specified path/data could not be written to disk due to an error.

Locks the file by default; blocks for up to 2 seconds attempting to gain a lock. You can turn this behavior off entirely:

$serializer->writefile($path, $ref, { Locking => 0 });

... or change the lock timeout (defaults to 2 seconds):

$serializer->writefile($path, $ref,
  { Locking => 1, Timeout => 5 }
);

readfile

Read the serialized file at the specified $path (if possible) and "thaw" the data structures back into a reference.

my $ref = $serializer->readfile($path);

By default, attempts to gain a shared (LOCK_SH) lock on the file in a blocking manner. You can turn this behavior off:

$serializer->readfile($path, { Locking => 0 });

Will croak with a stack trace if $path cannot be read or deserialized.

version

Obtains the backend serializer and its VERSION for the current instance.

my ($module, $modvers) = $serializer->version;

Returns a list of two values: the module name and its version.

## via Devel::REPL:
$ Bot::Cobalt::Serializer->new->version
$VAR1 = 'YAML::Syck';
$VAR2 = 1.19;

SEE ALSO

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>