The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Hash-Sanitize-0.04
River stage zero No dependents
++
/ Hash::Sanitize

NAME

Hash::Sanitize - Remove undesired keys from a hash (recursive)

VERSION

Version 0.04

DESCRIPTION

This module implements two methods that allows you to clean up a hash of undesired keys.

When called the method will iterate trough the hash keys and delete any keys that are non in the desired set.

This module is like Hash::Util's "legal_keys" method with the difference that while legal_keys doens't let you create keys that are not allowed, this module alows you to modify an existing hash and get a sanitized copy of it.

SYNOPSIS

Quick summary of what the module does.

Perhaps a little code snippet.

    use Hash::Sanitize qw(sanitize_hash sanitize_hash_deep);

    sanitize_hash(\%hash,\@allowed_keys);
    
    sanitize_hash_deep(\%hash,\@allowed_keys);

EXPORT

This module exports two methods:

    sanitize_hash
    
    and
    
    sanitize_hash_deep

SUBROUTINES/METHODS

sanitize_hash

Given a hash, it iterates trough the list of keys in the hash and deletes the keys that are not in the allowed keys list

When called in a void context, it modifies the hash sent as a parameter. When called in a array context (hash to be more exact) it will clone the original hash and sanitize & return the copy, leaving the original hash intact.

Example :

    my %new_hash = sanitize_hash(\%hash,[qw/foo bar/]);

Called this way the method leaves %hash intact and returns a hash containing only "foo" and "bar" keys (if they exist)

Example 2:

    sanitize_hash(\%hash,[qw/foo bar/]);

Called this way the method remove all the heys from %hash that are not "foo" or "bar". Called this way the method *will* modifiy the setucture of the original hash that was passed as an argument

In scalar context will return a hash referece, to a copy of the original hash.

sanitize_hash_deep

Same as sanitize_hash but this method will also sanitize the HASH structures that are found as values for allowed keys

Example :

    my %hash = (
                a => 1,
                b => 2,
                c => { d => 3, e => 4, f => 5},
                g => 6,
    );
    
    my %hash_copy = sanitize_hash_deep(\%hash,[qw/a c d/]);

The content of %hash_copy will be :

    ( a => 1, c => { d => 3 } )

It can also be called in a void context. In this case it will apply all changes to the original hash that was passed as an argument

In scalar context will return a hash referece, to a copy of the original hash.

AUTHOR

Horea Gligan, <gliganh at gmail.com>

BUGS

Please report any bugs or feature requests to bug-hash-sanitize at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HASH-Sanitize. 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::Sanitize

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2012 Evozon Systems

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.