/ 
Data-Record-Serialize-2.03
River stage one • 3 direct dependents • 3 total dependents
/ README.md

NAME

Data::Record::Serialize - Flexible serialization of a record

VERSION

version 2.03

SYNOPSIS

use Data::Record::Serialize;

# simple output to json
$s = Data::Record::Serialize->new( encode => 'json', \%attr );
$s->send( \%record );

# cleanup record before sending
$s = Data::Record::Serialize->new( encode => 'json',
    fields => [ qw( obsid chip_id phi theta ) ],
    format => 1,
    format_types => { N => '%0.4f' },
    format_fields => { obsid => '%05d' },
    rename_fields => { chip_id => 'CHIP' },
    types => { obsid => 'I', chip_id => 'S',
               phi => 'N', theta => 'N' },
);
$s->send( \%record );


# send to an SQLite database
$s = Data::Record::Serialize->new(
    encode => 'dbi',
    dsn => [ 'SQLite', [ dbname => $dbname ] ],
    table => 'stuff',
    format => 1,
    fields => [ qw( obsid chip_id phi theta ) ],
    format_types => { N => '%0.4f' },
    format_fields => { obsid => '%05d' },
    rename_fields => { chip_id => 'CHIP' },
    types => { obsid => 'I', chip_id => 'S',
               phi => 'N', theta => 'N' },
);
$s->send( \%record );

DESCRIPTION

Data::Record::Serialize encodes data records and sends them somewhere. This module is primarily useful for output of sets of uniformly structured data records. It provides a uniform, thin, interface to various serializers and output sinks. Its raison d'etre is its ability to manipulate the records prior to encoding and output.

Types

Some output encoders care about the type of a field. Data::Record::Serialize recognizes these types:

Not all encoders support separate integer or Boolean types. Where not supported, integers are encoded as numbers and Booleans as integers.

Types may be specified for fields, or may be automatically determined from the first record which is output. It is not possible to deterministically determine if a field is Boolean, so such fields must be explicitly specified. Boolean fields should be "truthy", e.g., when used in a conditional, they evaluate to true or false.

Field transformation

Transformations can be applied to fields prior to output, and may be specified globally for data types as well as for specifically for fields. The latter take precedence.

Transformations are specified via the "format_fields" and "format_types" parameters. They can either be a sprintf compatible format string,

   format_types => { N => '%0.4f' },
   format_fields => { obsid => '%05d' },

or a code reference:

   format_types => { B => sub { Lingua::Boolean::Tiny::boolean( $_[0] ) } }

Encoders

The available encoders and their respective documentation are:

Sinks

Sinks are where encoded data are sent.

The available sinks and their documentation are:

Refer to the documentation for additional constructor options, and object and class methods and attributes;

Fields and their types

Which fields are output and how their types are determined depends upon the "fields", "types", and "default_type" attributes.

This seems a bit complicated, but the idea is to provide a DWIM interface requiring minimal specification.

In the following table:

N   => not specified
Y   => specified
X   => doesn't matter
all => the string 'all'

Automatic type determination is done by examining the first record sent to the output stream.

Automatic output field determination is done by examining the first record sent to the output stream. Only those fields will be output for subsequent records.

fields types default_type  Result
------ ----- ------------  ------

N/all   N        N         Output fields are automatically determined.
                           Types are automatically determined.

N/all   N        Y         Output fields are automatically determined.
                           Types are set to <default_type>.

  Y     N        N         Fields in <fields> are output.
                           Types are automatically determined.

  Y     Y        N         Fields in <fields> are output.
                           Fields in <types> get the specified type.
                           Types for other fields are automatically determined.

  Y     Y        Y         Fields in <fields> are output.
                           Fields in <types> get the specified type.
                           Types for other fields are set to <default_type>.

 all    Y        N         Output fields are automatically determined.
                           Fields in <types> get the specified type.
                           Types for other fields are automatically determined.

 all    Y        Y         Output fields are automatically determined.
                           Fields in <types> get the specified type.
                           Types for other fields are set to <default_type>.

  N     Y        X         Fields in <types> are output.
                           Types are specified by <types>.

Errors

Most errors result in exception objects being thrown, typically in the Data::Record::Serialize::Error hierarchy.

CLASS METHODS

new

$s = Data::Record::Serialize->new( %args );
$s = Data::Record::Serialize->new( \%args );

Construct a new object. In addition to any arguments required or provided by the specified encoders and sinks, the following arguments are recognized:

METHODS

For additional methods, see the following modules

send

$s->send( \%record );

Encode and send the record to the associated sink.

WARNING: the passed hash is modified. If you need the original contents, pass in a copy.

ATTRIBUTES

Object attributes are provided by the following modules

EXAMPLES

Generate a JSON stream to the standard output stream

$s = Data::Record::Serialize->new( encode => 'json' );

Only output select fields

$s = Data::Record::Serialize->new(
  encode => 'json',
  fields => [ qw( obsid chip_id phi theta ) ],
 );

Format numeric fields

$s = Data::Record::Serialize->new(
  encode => 'json',
  fields => [ qw( obsid chip_id phi theta ) ],
  format => 1,
  format_types => { N => '%0.4f' },
 );

Override formats for specific fields

$s = Data::Record::Serialize->new(
  encode => 'json',
  fields => [ qw( obsid chip_id phi theta ) ],
  format_types => { N => '%0.4f' },
  format_fields => { obsid => '%05d' },
 );

Rename fields

$s = Data::Record::Serialize->new(
  encode => 'json',
  fields => [ qw( obsid chip_id phi theta ) ],
  format_types => { N => '%0.4f' },
  format_fields => { obsid => '%05d' },
  rename_fields => { chip_id => 'CHIP' },
 );

Specify field types

$s = Data::Record::Serialize->new(
  encode => 'json',
  fields => [ qw( obsid chip_id phi theta ) ],
  format_types => { N => '%0.4f' },
  format_fields => { obsid => '%05d' },
  rename_fields => { chip_id => 'CHIP' },
  types => { obsid => 'N', chip_id => 'S', phi => 'N', theta => 'N' }'
 );

Switch to an SQLite database in $dbname

$s = Data::Record::Serialize->new(
  encode => 'dbi',
  dsn => [ 'SQLite', [ dbname => $dbname ] ],
  table => 'stuff',
  fields => [ qw( obsid chip_id phi theta ) ],
  format_types => { N => '%0.4f' },
  format_fields => { obsid => '%05d' },
  rename_fields => { chip_id => 'CHIP' },
  types => { obsid => 'N', chip_id => 'S', phi => 'N', theta => 'N' }'
 );

SUPPORT

Bugs

Please report any bugs or feature requests to bug-data-record-serialize@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Data-Record-Serialize

Source

Source is available at

https://gitlab.com/djerius/data-record-serialize

and may be cloned from

https://gitlab.com/djerius/data-record-serialize.git

SEE ALSO

Please see those modules/websites for more information related to this module.

AUTHOR

Diab Jerius djerius@cpan.org

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007