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_create_path

emit_declare_vars

emit_delete_key

emit_fix

emit_fixes

emit_get_key

emit_reject

emit_retain_key

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.

cpanm Catmandu

perl -MCPAN -e shell
install Catmandu