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.

*   Fields may be renamed upon output.

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

*   Field values may be transformed prior to output.

  Types

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

*   "N" - Number (any number)

*   "I" - Integer

*   "S" - String

*   "B" - Boolean

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:

*   "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" - Data::Record::Serialize::Sink::null

    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

    write to a stream

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

    send the encoded data to the bit bucket.

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

    append the encoded data to an array.

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.

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