NAME

Data::DPath::DataParser - data parser for Data::DPath

SYNOPSIS

use Data::DPath::DataParser;

my $data = new Data::DPath::DataParser
               apache => $r,
               separator => '/',
           ;

my $data = new Data::DPath::DataParser
               cgi => $cgi,
           ;
my $cgi = $data -> get_cgi;

DESCRIPTION

Data::DPath::DataParser manages data extraction from various sources into a common hash tree that is then used by Data::DPath.

The following data sources are supported.

apache

This is an Apache::Request object. Data::DPath::DataParser will extract all parameters and file upload objects. Parameter names will be split on the separator. Names with multiple parts are placed in nested hashes. For example, data associated with the name foo.bar will be placed in $data -> {foo} -> {bar} if . is the separator.

cgi

This is a CGI object.

context

filename

hash

This should be a regular Perl hash reference. The contents will not be modified by Data::DPath.

ioref

This is a IO::File object from which a string may be read. The string should be an XML string or the result of freezing a hash by Storable.

storable

This is a string that has been frozen by Storable.

xml

This is an XML string. If the root element is <data/>, then it is parsed with the Data::DumpXML module. Otherwise, it is parsed with the XML::Dumper module.

In addition to the data sources, the following parameters may be specified.

separator

This is the separator used to break parameter names into shorter sequences to create nested hashes. The default value is the period (.). It may be changed at any time with the set_separator method. It may be retrieved with the get_separator method.

xml_dumper_preference

This should be one of the module names listed below. The default depends on which modules are already loaded when the Data::DPath::DataParser object is created. Preference is given to Data::DumpXML if both are loaded.

Data::DumpXML

XML::Dumper

ADDING SOURCES

To add a data source, use the following template.

package My::DataParser;

use base Data::DPath::DataParser;
use Params::Validate qw(:types);

# Some_Type should be whatever type is expected by data_from_foo
__PACKAGE__->valid_params (
    foo    => { type => Some_Type, optional => 1, },
); 

sub data_from_foo {
    my $self = shift;
   
    return { } unless defined $self -> {foo};
   
    # return a hash representing the data in $self -> {foo}
}

sub get_foo {
    my $self = shift;

    if(@_) {   
        my $data = shift || $self -> {_data};

        # return whatever can be fed back in to get $data
        # using the `foo' parameter in the data_from_foo
        # method above.
        return Foo -> new( $self -> flatten_hash($data) );
    }
    else {
        return $self -> {foo};
    }
}

1;

__END__