<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">SYNOPSIS

     use Data::Transmute qw(transmute_array transmute_hash);
    
     my %hash = (
         foo =&gt; 1,
    
         one =&gt; 2,
         two =&gt; 3,
    
         x_apple =&gt; 4,
         x_mango =&gt; 5,
     );
    
     transmute_hash(
         data =&gt; \%hash,
         rules =&gt; [
    
             # create a new key, error if key already exists
             [create_key =&gt; {name=&gt;'foo', value=&gt;1}],
    
             # create another key, but this time ignore/noop if key already exists
             # (ignore=1). this is like INSERT IGNORE in SQL.
             [create_key =&gt; {name=&gt;'bar', value=&gt;2, ignore=&gt;1}],
    
             # create yet another key, this time replace existing keys (replace=1).
             # this is like REPLACE INTO in SQL.
             [create_key =&gt; {name=&gt;'baz', value=&gt;3, replace=&gt;1}],
    
             # rename a single key, error if old name doesn't exist or new name
             # exists
             [rename_key =&gt; {from=&gt;'qux', to=&gt;'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 =&gt; {from=&gt;'corge', to=&gt;'grault', ignore_missing_from=&gt;1, replace=&gt;1}],
    
             # delete a key, will noop if key already doesn't exist
             [delete_key =&gt; {name=&gt;'garply'}],
    
         ],
     );
    
     # %hash will become:
     # (
     #     baz =&gt; 1,
     #
     #     1 =&gt; 2,
     #     2 =&gt; 3,
     #
     #     apple =&gt; 4,
     #     mango =&gt; 5,
     # )

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.

</pre></body></html>