Data::Annotated - Data structure Annotation module

Data-Annotated documentation Contained in the Data-Annotated distribution.

Index

Code Index:

NAME

Top

Data::Annotated - Data structure Annotation module

VERSION

Top

Version 0.01

SYNOPSIS

Top

    use Data::Annotated;

    my $da = Data::Annotated->new();

    $da->annotate('/foo/bar[2]/baz', {desc => 'this is an interesting field'});
    $da->annotate('/some/other/path', {test => 1, runthis => sub { print 'I was one'; } });

    my $struct = {some => {other => {path => 1}}}; 
    my @annotations = $da->cat_annotation();

    # this will print out "I was one';
    $annotations[0]{runthis}->() if $struct->{some}{other}{path} == $annotations[0]{test};

METHODS

Top

new()

instantiate a new Data::Annotated object;

annotate($path, \%annotation);

Annotate a piece of a data structure. The path is an XPath like path like Data::Path uses. The annotation can be any scalar value. Possible uses are String for descriptive text. Or a reference to a more complex data structure.

cat_annotation($data)

spit out the annotations for a data structure. Returns the annotations that apply for the passed in data structures. Does not return an annotation if the data doesn't contain the data location it is matched to.

get_annotation($path);

retrieves an annotation keyed by the path in the data structure.

INTERNAL METHODS

Top

_validate_path($path)

validates a Data::Path path for validity.

TODO

Top

Should Data::Annotate wrap data? or stay a collection of annotations?

Make Data::Annotate return the data from a requested path. my $info = $da->get($path, $data) basically just a wrapper around Data::Path get()

COPYRIGHT & LICENSE

Top

Copyright 2007 Jeremy Wall, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Top

Jeremy Wall, <jeremy at marzhillstudios.com>

Data-Annotated documentation Contained in the Data-Annotated distribution. 
package Data::Annotated;
use Data::Path;

use warnings;
use strict;


our $VERSION = '0.2';

my $callbacks = {
                key_does_not_exist => sub {},
                index_does_not_exist => sub {},
                retrieve_index_from_non_array => sub {},
                retrieve_key_from_non_hash => sub {},
                };


sub new {
    return bless {}, shift;
}


sub annotate {
    my ($self, $path, $anno) = @_;
    croak('Not a valid path: '.$path) unless $self->_validate_path($path); 
    $self->{$path} = $anno;
}


sub cat_annotation {
    my ($self, $data) = @_;
    my $dp = Data::Path->new($data, $callbacks);
    my @paths = grep { $dp->get($_) } keys(%$self);
    return map { $self->get_annotation($_) } @paths;
}


sub get_annotation {
    my ($self, $path) = @_;
    return {path => $_, %{$self->{$path}}} if $self->_validate_path($path);
    carp('Invalid Path requested: '. $path);
}


sub _validate_path {
    my ($self, $path) = @_;
    return 1 if $path =~ qr/^\/.*[^\/]$/;
    return;
}




1;