Hash::Transform - a simple data-driven class for doing data transformation.
Version 0.01
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', ## );
This class transforms data according to rules setup at instantiation or via the rules mutator.
rules
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.
new
apply
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); }
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.
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.
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.
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).
init
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.
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}).
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.
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.
join
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.
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.
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.
Dave Trischuk, <trischuk at gmail.com>
<trischuk at gmail.com>
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.
bug-hash-transform at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Hash::Transform
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Hash-Transform
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Hash-Transform
CPAN Ratings
http://cpanratings.perl.org/d/Hash-Transform
Search CPAN
http://search.cpan.org/dist/Hash-Transform
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.
To install Hash::Transform, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Hash::Transform
CPAN shell
perl -MCPAN -e shell install Hash::Transform
For more information on module installation, please visit the detailed CPAN module installation guide.