SYNOPSIS

     use Data::Transmute qw(transmute_array transmute_hash);
    
     transmute_hash(
         data => \%hash,
         rules => [
    
             # create a new key, error if key already exists
             [create_key => {name=>'foo', value=>1}],
    
             # create another key, but this time ignore/noop if key already exists
             # (ignore=1). this is like INSERT IGNORE in SQL.
             [create_key => {name=>'bar', value=>2, ignore=>1}],
    
             # create yet another key, this time replace existing keys (replace=1).
             # this is like REPLACE INTO in SQL.
             [create_key => {name=>'baz', value=>3, replace=>1}],
    
             # rename a single key, error if old name doesn't exist or new name
             # exists
             [rename_key => {from=>'qux', to=>'quux'}],
    
             # rename another key, but this time ignore if old name doesn't exist
             # (ignore=1) or if new name already exists (replace=1)
             [rename_key => {from=>'corge', to=>'grault', ignore_missing_from=>1, replace=>1}],
    
             # delete a key, will noop if key already doesn't exist
             [delete_key => {name=>'garply'}],
    
         ],
     );

DESCRIPTION

    STATUS: EARLY DEVELOPMENT, SOME FEATURES MIGHT BE MISSING

    This module provides routines to transmute (transform) a data structure
    in-place using rules which is another data structure (an arrayref of
    rule specifications). It is similar to Hash::Transform except the
    recipe offers ability for more complex transformations.

    One use-case for this module is to convert/upgrade configuration files.

RULES

    Rules is an array of rule specifications.

    Each rule specification: [$funcname, \%args]

    $funcname is the name of an actual function in Data::Transmute
    namespace, with transmute_array_ or transmute_hash_ prefix removed.

    \%args: a special arg will be inserted: data.

FUNCTIONS

 transmute_array(%args)

    Transmute an array, die on failure. Input data is specified in the data
    argument, which will be modified in-place (so you'll need to clone it
    first if you don't want to modify the original data). Rules is
    specified in rules argument.

 transmute_hash(%args)

    Transmute a hash, die on failure. Input data is specified in the data
    argument, which will be modified in-place (so you'll need to clone it
    first if you don't want to modify the original data). Rules is
    specified in rules argument.

TODOS

    Check arguments (DZP:Rinci::Wrap?).

    Undo?

    Function to mass rename keys (by regex substitution, prefix, custom
    Perl code, ...).

    Function to mass delete keys (by regex, prefix, ...).

    Specify subrules.

SEE ALSO

    Hash::Transform is similar in concept. It allows transforming a hash
    using rules encoded in a hash. However, the rules only allow for
    simpler transformations: rename a key, create a key with a specified
    value, create a key that from a string-based join of other
    keys/strings. For more complex needs, you'll have to supply a coderef
    to do the transformation yourself manually. Another thing I find
    limiting is that the rules is a hash, which means there is no way to
    specify order of processing.

    Config::Model, which you can also use to convert/upgrade configuration
    files. But I find this module slightly too heavyweight for the simpler
    needs that I have, hence I created Data::Transmute.