NAME
Data::Annotation::Overlay
SYNOPSIS
use Data::Annotation::Overlay;
my %data = (...);
my $overlay = Data::Annotation::Overlay->new(under => \%data);DESCRIPTION
Wrapper around a data structure, useful to record "changes" to the data structure without making actual modifications to it. Loosely inspired by the overalay file systems.
INTERFACE
Constructor
my $rule = Data::Annotation::Overlay->(%opts);Make a new instance for an overlay. Accepted options are all "Accessors".
Input parameter under is the only required key, representing the data structure that the overlay wraps around.
All paths used in this module must be compatible with "Data::Annotation::Traverse::crumble" and will be normalized with "Data::Annotation::Traverse::kpath".
Accessors
cache_existing
All values retrieved with "get" will be cached for quicker access later on. Set by default. Disable if there are intermediate function calls that need to be executed at every access.
method_over_key
Prefer the method call over key access when there is an intermediate blessed object while traversing.
over
Reference to the overlay data structure (a hash reference).
strict_blessed
Only consider method calls on blessed objects while traversing. False by default.
traverse_methods
Consider using methods when traversing an object. True by default.
under
Reference to the underlay data structure. Required.
value_if_missing
Value to return if the path of a traversal in "get" or "get_external" leads to nothing. By default, an empty list (in list context) or undef will be returned.
value_if_undef
Value to return if the path of a traversal in "get" or "get_external" leads to an undefined value. By default undef is returned.
Methods
delete
$ov->delete($path);Mark $path as deleted.
get
my $value = $ov->get($path);Look for the value associated to $path. This first looks into "over", then into "under".
get_external
my $value = $ov->get_external($path, $data);Shorthand to apply the same traversing algorithm (with the same options) in traversing $data with $path. In particular, it also uses "return_value_for" to cope with missing/undefined elements.
merged
my $thin_ov = $stacked_ov->merged;Generate a new overlay from a stack of multiple wrapped overlays. The "under" of this new overlay is the same as the one for the bottom overlay of the whole stack, as well as traversal options; "over" is generated anew and independent of what's in the stacked overlay; "value_if_missing" and "value_if_undef" are taken from the top overlay, and cache_existing is taken from any layer.
All in all, it aims at being a close representation of the behaviour as seen from the top layer of the $stacked_ov.
return_value_for
my $value = $ov->return_value_for($retval);Adapt the return value according to the configuration.
A $retval meaning "missing" (according to "Data::Annotation::Traverse::means_missing") is turned into what is set for "value_if_missing", if the accessor is set, or to just return nothing (which will be turned into undef in scalar context).
An undefined $retval will be turned into whatever is set for value_if_undef or simply undef if that is not set.
set
$ov->set($path, $value);Set the $value for the specific $path.
traversal_options
my %opts = $ov->traversal_options;Get all options for traversing the data structure (i.e. "traverse_methods", "strict_blessed", and "method_over_key") as a hash reference suitable to pass to "Data::Annotation::Traverse::traverse_plain".