NAME

Parse::FieldPath

ABSTRACT

Parses an XPath inspired field list and extracts those fields from an object hierarchy.

Based on the "fields" parameter for the Google+ API: http://developers.google.com/+/api/

SYNOPSIS

Say you have an object, with some sub-objects, that's initialized like this:

  my $cow = Cow->new();
  $cow->color("black and white");
  $cow->tail(Cow::Tail->new(floppy => 1));
  $cow->mouth(Cow::Tounge->new(
    tounge => Cow::Tounge->new,
    teeth  => Cow::Teeth->new,
  );

And you want a hash containing some of those fields (perhaps to pass to JSON::XS, or something). Then you can do this:

  use Parse::FieldPath qw/extract_fields/;

  my $cow_hash = extract_fields($cow, "color,tail/floppy");
  # $cow_hash is now:
  # {
  #   color => 'black and white',
  #   tail  => {
  #     floppy => 1,
  #   }
  # }

FUNCTIONS

extract_fields ($object_or_hashref, $field_path)

Parses the field_path and returns a hashref with the fields requested from $object_or_hashref.

$object_or_hashref, and any sub-objects, will need to define a method called all_fields(). See CALLBACKS for details.

field_path is a string describing the fields to return. Each field is separated by a comma, e.g. "a,b" will return fields "a" and "b".

To request a field from a sub-objects, use the form "subobject/field". If more than one field from a sub-object is required, put the field names in parenthesis, "subobject(field1,field2)".

field_path can go as deep as necessary, for example, this works fine: "a/b/c(d/e,f)"

CALLBACKS

all_fields()

A method called all_fields() should be defined for any object (including sub-objects), that will be used with this module. It needs to return an arrayref containing all the valid fields. Any field requested that's not in the list returned by all_fields() will be skipped.

A simple implementation would be:

  sub all_fields {
      my ($self) = @_;
      return [qw/field1 field2/];
  }

If the list doesn't change, a constant will work too:

  use constant all_fields => [qw/field1 field2/];

This method is required because simply allowing any method to be called would be dangerous (e.g. if your object had a "delete_everything()" method, or something). It's also necessary to know which fields constitute "everything" for the object.

requested_fields($field_list)

Called on an object right before the accessor methods are called. It's passed a list of fields that are about to be requested. This method is completely optional. It's intended to allow the object to fetch anything it needs to, in order to make the requested data available.

GitHub

https://github.com/pboyd/Parse-FieldPath

AUTHOR

Paul Boyd <pboyd@dev3l.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Paul Boyd.

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