view release on metacpan or  search on metacpan

lib/Data/Overlay.pm  view on Meta::CPAN

Some made up use-cases.

=head2 Configuration Data Merging

 overlay_all($defaults, $host_conf, $app_conf, $user_conf, $cmd_line_conf);

=head2 List of Undoable Edits

Use the memory sharing to keep a sequence of persistent data structures.
"Persistent" in the functional programming sense, you can
access (read-only) old and new versions.

=head2 Circular References in Overlays

There is no protection against reference cycles in overlays.

L<Devel::Cycle> or L<Data::Structure::Util> may help.

=head2 Unsharing Data with Clone

If you don't want any sharing of data between the result and
source or overlay, then use a clone.
Either L<Storable>'s dclone or L<Clone>

    $new_clone = dclone(overlay($old, $overlay));

=head2 Escaping "=" Keys

Rmap

=head2 Writing Your Own Callbacks

Note that while most of the names of core actions are based
on mutating perl functions, their implementation is careful
to do shallow copies.

=head2 Readonly for Testing

The Readonly module is useful for testing that nothing is
changing data that is supposed to be Readonly.

=head2 Sharing State in Callbacks

Shared lexical variables.

=head2 Where Are The Objects?

This is a bit of an experiment in using data immutability, persistence
and sharing instead of using OO conventions to manage changing state.
(This approach doesn't hit all of the OO targets, but Data::Overlay's
subset may be useful).

Blessed references are treated as opaque object by default (not overlaid).
(Encapsulation was ignored in developer release 0.53 and earlier).

=head1 DEPENDENCIES

L<List::MoreUtils>, L<Sub::Name>

=head1 BUGS AND LIMITATIONS

I'm happy to hear suggestions, please email them or use RT
in addition to using cpan ratings or annocpan (I'll notice them faster).

No bugs have been reported.

Please report any bugs or feature requests to
C<bug-data-edit@rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org>.

=head1 SEE ALSO

Merging of nested data structures:

=over

=item * L<Hash::Merge> merge with global options

=item * L<Data::Utilities> (L<Data::Merger>) merge with call-time options

=item * L<Data::Nested> merging (per application options), paths and schemas

=item * L<Data::ModeMerge>

"Mode" (overwrite/add/default) is in the data merged, like Data::Overlay.
Uses special characters to indicate the action performed.  Also permits
local config overrides and extensions.

=back

Potential overlay builders, modules that could be used to build
overlays for data:

=over

=item * L<CGI::Expand>

Build nested hashes from a flat path hash:

    use CGI::Expand qw(expand_hash);

    my $overlay = expand_hash({"a.b.c"=>1,"a.b.d"=>[2,3]})
    # = {'a' => {'b' => {'c' => 1,'d' => [1,2,3]}}};

L<Hash::Flatten> also has an unflatten function.

=back

Lazy deep copying nested data:

=over

=item * L<Data::COW> - Copy on write

=back

Data structure differences:

=over