++ed by:
JONASS VOJ

2 PAUSE user(s)
3 non-PAUSE user(s).

Nicolas Steenlant
and 13 contributors

NAME

Catmandu::Fix - a Catmandu class used for data crunching

SYNOPSIS

    use Catmandu::Fix;

    my $fixer = Catmandu::Fix->new(fixes => ['upcase("job")','remove_field("test")']);

    or

    my $fixer = Catmandu::Fix->new(fixes => ['fix_file.txt']);

    my $arr  = $fixer->fix([ ... ]);
    my $hash = $fixer->fix({ ... });

    my $it = Catmandu::Importer::YAML(file => '...');
    $fixer->fix($it)->each(sub {
        ...
    });

    or

    use Catmandu::Fix::upcase as => 'my_upcase';
    use Catmandu::Fix::remove_field as => 'my_remove';

    my $hash = { 'job' => 'librarian' , deep => { nested => '1'} };

    my_upcase($hash,'job');
    my_remove($hash,'deep.nested');

DESCRIPTION

Catmandu::Fixes can be used for easy data manipulation by non programmers. Using a small Perl DSL language end-users can use Fix routines to manipulate data objects. A plain text file of fixes can be created to specify all the routines needed to tranform the data into the desired format.

PATHS

All the Fix routines in Catmandu::Fix use a TT2 type reference to point to values in a Perl Hash. E.g. 'foo.2.bar' is a key 'bar' which is the 3-rd value of the key 'foo'.

A special case is when you want to point to all items in an array. In this case the wildcard '*' can be used. E.g. 'foo.*' points to all the items in the 'foo' array.

For array values there are special wildcards available:

 * $append   - Add a new item at the end of an array
 * $prepend  - Add a new item at the start of an array
 * $first    - Syntactic sugar for index '0' (the head of the array)
 * $last     - Syntactic sugar for index '-1' (the tail of the array)

E.g.

 # Create { mods => { titleInfo => [ { 'title' => 'a title' }] } };
 add_field('mods.titleInfo.$append.title', 'a title');

 # Create { mods => { titleInfo => [ { 'title' => 'a title' } , { 'title' => 'another title' }] } };
 add_field('mods.titleInfo.$append.title', 'another title');

 # Create { mods => { titleInfo => [ { 'title' => 'foo' } , { 'title' => 'another title' }] } };
 add_field('mods.titleInfo.$first.title', 'foo');

 # Create { mods => { titleInfo => [ { 'title' => 'foo' } , { 'title' => 'bar' }] } };
 add_field('mods.titleInfo.$last.title', 'bar');

Read more about the Fix language at our Wiki: https://github.com/LibreCat/Catmandu/wiki/Fixes

PUBLIC METHODS

new(fixes => [ FIX , ...])

Create a new Catmandu::Fix which will execute every FIX into a consecutive order. A FIX can be the name of a Catmandu::Fix::* routine, or the path to a plain text file containing all the fixes to be executed or a path to any executable if Catmandu::Fix::cmd is installed.

fix(HASH)

Execute all the fixes on a HASH. Returns the fixed HASH.

fix(ARRAY)

Execute all the fixes on every element in the ARRAY. Returns an ARRAY of fixes.

fix(Catmandu::Iterator)

Execute all the fixes on every item in an Catmandu::Iterator. Returns a (lazy) iterator on all the fixes.

fix(sub {})

Executes all the fixes on a generator function. Returns a new generator with fixed data.

log

Return the current logger. Can be used when creating your own Fix commands, e.g.

    package Catmandu::Fix::meow;

    use Moo;

    sub fix {
        my ($self,$data) = @_;

        $self->log->debug("Setting meow");
        $data->{meow} = 'purrrrr';

        $data;
    }

See Catmandu for activating the logger in your main code.

INTERNAL METHODS

This module provides several methods for writing fix packages. Usage can best be understood by reading the code of existing fix packages.

capture
emit_block
emit_clone
emit_clear_hash_ref
emit_create_path
emit_declare_vars
emit_delete_key
emit_fix
emit_fixes
emit_foreach
emit_foreach_key
emit_get_key
emit_reject
emit_retain_key

this method is DEPRECATED.

emit_set_key
emit_string
emit_value
emit_walk_path
generate_var
split_path

SEE ALSO

Fixes are used by instances of Catmandu::Fixable to manipulate items Catmandu::Importer, Catmandu::Exporter, and Catmandu::Bag.