/ 
Hash-Transform-0.01
River stage zero No dependents
/ Hash::Transform

NAME

Hash::Transform - a simple data-driven class for doing data transformation.

VERSION

Version 0.01

SYNOPSIS

my %rules = (
             foo_field => 'foo',
             bar_field => 'bar',
             name      => [' ', \'Name:', 'first', 'last'],
             constant  => \'42',
             friend    => sub {
               my $data = shift;
               my $fullname = join (' ', @$data{'first','last'});
               return 'Ford' if $fullname eq 'Arthur Dent';
               return 'Arthur' if $fullname eq 'Ford Prefect';
               return 'No friends';
             },
            );
my $transform = Hash::Transform->new(%rules);
my %old_data = (
                foo   => 'hello',
                bar   => 'goodbye',
                first => 'Arthur',
                last  => 'Dent',
               );
my %new_data = $transform->apply(%old_data);

## current contents of %new_data = (
##                                  foo_field => 'hello',
##                                  bar_field => 'goodbye',
##                                  name      => 'Name: Arthur Dent',
##                                  constant  => '42',
##                                  friend    => 'Ford',
##                                 );

DESCRIPTION

This class transforms data according to rules setup at instantiation or via the rules mutator.

The basic interface is new, rules and apply. The new and rules methods take the same argument, which is either a hash or a reference to a hash which will be used to setup the transformation rules.

The apply method takes a hash or reference to a hash and returns either a hash or reference to a hash which is the result of applying the current rule set to the passed hash or hash ref.

The usual pattern of use would probably be:

my %rules = (
             # ... transform rules
            );
my $transform = Hash::Transform->new(%rules);

while (my $source_hash_ref = get_data_from_some_source()) {
  my $target_hash_ref = $transform->apply($source_hash);
  store_data_somewhere($target_hash_ref);
}

CONSTRUCTOR

new()

Creates a new transformation object, which implements a single transformation.

my $transform = Hash::Transform->new(%transform_rules);

The transformation rules are optional at instantiation, and may be set later via the rules accessor. They are required prior to applying a transformation.

METHODS

$transform->rules(%transform_rules)

The mutator for transformation rules. New rules passed to rules completely overwrite the old rules. Note, this is only a mutator; there is no accessor for rules.

$transform->apply(%original_data)

Applies the current transformation rules to the supplied hash or hash ref, and returns the result as either a hash ref in scalar context, or a hash list in array context.

$transform->init(%transform_rules)

This method is called by new. It resets an object to a "like new" state, with only the transform rules passed to init (if any).

HOW THE RULES WORK

The rules are passed in the form of a hash in which each key represents a key in the transformed hash which will be returned. Each value may be a scalar value, a reference to a scalar, a reference to an array, or a reference to code. The ref type of the value will determine the type of processing the apply method will perform to create the value of the new key.

Scalar value

A scalar value will copy the value of the old key equal to the scalar value to the value of the new key. No changes of any kind are made.

In the example in the synopsis, the value of $new_data{foo_field} will be 'hello' (the value of $old_data{foo}).

Scalar reference

A scalar reference will set the value of the new key to that value. The old data is not checked at all and no changes to the data are made.

In the example in the synopsis, the value of $new_data{constant} will be the string '42' (%old_data does not affect this). A reference to a variable containing the value '42' would have the same effect.

Array reference

An array reference acts very similar to the join function. It causes the apply method to take the first element of the array as a separator field, then recursively process the rest of the elements according to the same rules, and concatenate those values with the separator field between each value. The final result is the value of the new key.

In the example in the synopsis, the value of $new_data{name} will be 'Name: Arthur Dent', which is the 'Name:' (from a scalar reference), $old_data{first} (from a scalar), and $old_data{last} (also from a scalar) all concatenated together with a space separating them.

Code reference

A code reference is for complex data processing not manageable by the above rules. The code will be called passing a reference to the old data set (which may or may not be a reference to the original hash). The value of the new key will be set to whatever is returned by that call. Code references are the most powerful but most obscure way of transforming data.

In the example in the synopsis, the value of $new_data{friend} will be 'Ford', which is what the anonymous subroutine will return for this particular %old_data.

ERROR HANDLING

This module deliberately does very little error handling. If a key referenced in the rules doesn't exist, then that key in the new hash will be silently set to c<undef>. Calls to sub refs are not wrapped in evals, so if they do something illegal the error will propegate back to the caller.

AUTHOR

Dave Trischuk, <trischuk at gmail.com>

BUGS

Please report any bugs or feature requests to bug-hash-transform at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Hash-Transform. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Hash::Transform

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Dave Trischuk, all rights reserved.

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