NAME

Data::Abridge

VERSION

version 0.03.01

Simplify data structures for naive serialization.

SYNOPSIS

    use Data::Abridge qw( abridge_recursive );
    use JSON;

    my $foo = bless { handle => \*STDIN }, 'SomeObj';

    print encode_json abridge_recursive( $foo );

    local $DATA::Abridge::HONOR_STRINGIFY = undef;

    print encode_json abridge_recursive( $foo );

DESCRIPTION

Webster's 1913 edition defines abridge as follows:

  A*bridge" (#), v. t.
  1. To make shorter; to shorten in duration; to lessen; to diminish; to
  curtail; as, to abridge labor; to abridge power or rights. The bridegroom

This module exists to simplify the process of serializing data to formats, such as JSON, which do not support the full richness of perl datatypes.

An abridged data structure will feature only scalars, hashes and arrays.

This module does NOT guarantee round-trip capability. Abridgement is a lossy process and some information may be lost.

EXPORTED SYMBOLS

Nothing is exported by default.

The three subroutines in the public API are available for export by request.

SUBROUTINES

abridge_item

Abridges the top level of an item. Deep structures are not modified below the top structure. For complete conversion, use abridge_recursive.

Scalars that aren't references, array references and hash references are unchanged:

    Input         Output
    ------------------------------------------
    'A string'    'A string'
    57            57
    {a=>1, b=>2}  {a=>1, b=>2}
    [1,2,3]       [1,2,3]

Code references are converted to a hash ref that indicates the fully qualified name of the subroutine pointed to. Anonymous subroutines are marked as __ANON__.

    Input         Output
    ------------------------------------------
    \&foo         {CODE => '\&main::foo'}
    sub {0}       {CODE => '\&main::__ANON__'}

Typeglob references are converted to a hash ref that contains the name of the glob.

    Input         Output
    ------------------------------------------
    \*main::foo   {GLOB => '\*main::foo'}

Scalar references are converted to a hash ref that contains the scalar.

    Input         Output
    ------------------------------------------
    \$foo         {SCALAR => $foo}

Objects are converted to a hash ref that contains the name of the class and an unblessed copy of the object's underlying data type.

    Input                 Output
    ------------------------------------------
    bless {a=>'b'}, 'Foo' { Foo => {a=>'b'} }
    bless [1,2,3], 'Foo'  { Foo => [1,2,3]  }

Objects that override stringification will be treated as strings, by default.

    Given:
      package Foo;
      use overload '""' => sub { join ' ', keys %$_[0] };

    Input                 Output              Condition
    ----------------------------------------------------
    bless {a=>'b'}, 'Foo' 'a'                 Default
    bless {a=>'b'}, 'Foo' { Foo => {a=>'b'} } $HONOR_STRINGIFY = undef
    bless {a=>'b'}, 'Foo' 'a'                 $HONOR_STRINGIFY = 1

abridge_items

Operates as abridge item, but applied to a list.

Takes a list of arguments, applies abridge_item to each, and then returns an array ref containing the results.

abridge_recursive

Operates on a single data structure as per abridge_item, but in a top-down recursive mode.

The data structure returned will consist of only abridged data.

Recursive processing adds one more transformation type to the set described above:

    Input              Output
    ------------------------------------------
    Any repeated item  {SEEN => [ 0, 'Path' ]}

This means that any item that appears more than once in a data structure will be replaced with a pointer to the other location. A hash ref with a single key "SEEN" and a value consisting of an array reference to indicate the path of keys and indexes that must be traversed to find the fully dumped instance.

A reference to the top level data structure will yeild an empty [] path.

A reference to an element in an object or other special item will include the Data::Abridge generated keys in the path [ 2, 'SCALAR', 'SomeClass', 'that_attrib', 5 ].

abridge_items_recursive

Operates as abridge_recursive, but applied to a list.

Takes a list of arguments, applies abridge_recursive to each, and then returns an array ref of the results.

The top level item, in this case, is taken to be the array of items.

SUPPORT

Please file any bugs through the standard CPAN ticketing system. At the time of writing this is http://rt.cpan.org.

LICENSE

This module is licensed under the same terms as Perl.

To be specific, you may choose to use it under any of the licensing terms available for Perl 5.6.0 or newer.

AUTHOR

Mark Swayne

Copyright 2012

ACKNOWLEDGEMENTS

Thank you to Marchex http://marchex.com for supporting the development and release of this module.

Special thanks to Tye McQueen for the original idea and his readiness to kibbitz during the development process.

cpanm Data::Abridge

perl -MCPAN -e shell
install Data::Abridge