package Hash::Transform; use warnings; use strict; our $VERSION = '0.01'; use Carp (); sub new { my $class = shift; my $self = bless {}, $class; $self->init(@_); return $self; } sub init { my $self = shift; $self->{rules} = {}; $self->rules(@_) if @_; return $self; } sub rules { my $self = shift; Carp::croak "Missing rules" unless @_; my $hash_ref = _hash_arg(@_); Carp::croak "Invalid rules" unless $hash_ref; $self->{rules} = $hash_ref; return $self; } sub _apply_rule { my ($self, $code, $data) = @_; return unless defined $code && ref $data eq 'HASH'; '' eq ref $code and return $data->{$code}; 'SCALAR' eq ref $code and return $$code; 'CODE' eq ref $code and return $code->($data); 'ARRAY' eq ref $code and return join( $code->[0], map { my $entry = $self->_apply_rule($_, $data); defined $entry ? $entry : ''; } @$code[1..$#$code] ); ## default return; } sub apply { my $self = shift; my $source = _hash_arg (@_) or Carp::croak "Invalid data set"; my $rules = $self->{rules} or Carp::croak "Missing rules table"; my %target = map { my $key = $_; my $value = $self->_apply_rule ($rules->{$key}, $source); ($key => $value); } keys %$rules; return wantarray ? %target : \%target; } sub _hash_arg { my $hash_ref = (@_ == 1 and ref $_[0] eq 'HASH') ? $_[0] : (@_ % 2 == 0) ? { @_ } : return ; return wantarray ? %$hash_ref : $hash_ref; } 1; __END__ =head1 NAME Hash::Transform - a simple data-driven class for doing data transformation. =head1 VERSION Version 0.01 =head1 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', ## ); =head1 DESCRIPTION This class transforms data according to rules setup at instantiation or via the C mutator. The basic interface is C, C and C. The C and C 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 C 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); } =head1 CONSTRUCTOR =head2 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 C accessor. They are required prior to applying a transformation. =head1 METHODS =head2 $transform->rules(%transform_rules) The mutator for transformation rules. New rules passed to C completely overwrite the old rules. Note, this is only a mutator; there is no accessor for rules. =head2 $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. =head2 $transform->init(%transform_rules) This method is called by C. It resets an object to a "like new" state, with only the transform rules passed to C (if any). =head1 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 C method will perform to create the value of the new key. =head2 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}). =head2 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. =head2 Array reference An array reference acts very similar to the C function. It causes the C 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. =head2 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. =head1 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. Calls to sub refs are not wrapped in evals, so if they do something illegal the error will propegate back to the caller. =head1 AUTHOR Dave Trischuk, C<< >> =head1 BUGS Please report any bugs or feature requests to C, or through the web interface at L. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. =head1 SUPPORT You can find documentation for this module with the perldoc command. perldoc Hash::Transform You can also look for information at: =over 4 =item * RT: CPAN's request tracker L =item * AnnoCPAN: Annotated CPAN documentation L =item * CPAN Ratings L =item * Search CPAN L =back =head1 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.