Data::Record::Serialize

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.

*   A record is a collection of fields, i.e. keys and *scalar* values.

*   All records are assumed to have the same structure.

*   Fields may have simple types which may be determined automatically.
    Some encoders use this information during encoding.

*   Fields may be renamed upon output

*   A subset of the fields may be selected for output.

*   Fields may be formatted via "sprintf" prior to output

  Encoders

The available encoders and their respective documentation are:

*   "dbi" - Data::Record::Serialize::Encode::dbi

    Write to a database via DBI. This is a combined encoder and sink.

*   "ddump" - Data::Record::Serialize::Encode::ddump

    encode via Data::Dumper

*   "json" - Data::Record::Serialize::Encode::json

*   "null" - send the data to the bit bucket. This is a combined encoder
    and sink.

*   "rdb" - Data::Record::Serialize::Encode::rdb

*   "yaml" - Data::Record::Serialize::Encode::yaml

  Sinks

Sinks are where encoded data are sent.

The available sinks and their documentation are:

*   "stream" - Data::Record::Serialize::Sink::stream

*   "null" - send the encoded data to the bit bucket.

  Types

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

*   "N" - Numeric

*   "I" - Integral

*   "S" - String

Not all encoders support a separate integral type; in those cases
integer fields are treated as general numeric fields.

  Fields and their types

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

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 send
to the output stream.

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

  N/all   N        N         All fields are output.
                             Types are automatically determined.

  N/all   N        Y         All fields are output.
                             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         All fields are output.
                             Fields in <types> get the specified type.
                             Types for other fields are automatically determined.

   all    Y        Y         All fields are output.
                             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.

INSTALLATION

This is a Perl module distribution. It should be installed with whichever
tool you use to manage your installation of Perl, e.g. any of

  cpanm .
  cpan  .
  cpanp -i .

Consult http://www.cpan.org/modules/INSTALL.html for further instruction.
Should you wish to install this module manually, the procedure is

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

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