A Catmandu::Fix is a Perl package that can transform data. These packages are used for easy data manipulation by non programmers. The main intention is to use fixes on the command line or in Fix scripts. A small DSL language is available to execute many Fix command on a stream of data.

Binds are used to manipulate the context in which Fixes are executed. E.g. execute a fix on every item in a list:

# 'demo' is an array of hashes
bind list(path:demo)
add_field(foo,bar)
end
# do is an alias for bind
do list(path:demo)
add_field(foo,bar)
end

To delete records from a stream of data the reject Fix can be used:

reject() # Reject all in the stream
if exists(foo)
reject() # Reject records that contain a 'foo' field
end
reject exists(foo) # Reject records that contain a 'foo' field

The opposite of reject is select:

select() # Keep all records in the stream
select exists(foo) # Keep only the records that contain a 'foo' field

Comments in Fix scripts are all lines (or parts of a line) that start with a hash (#):

# This is ignored
add_field(test,123) # This is also a comment

You can load fixes from another namespace with the use statement:

# this will look for fixes in the Foo::Bar namespace and make them
# available prefixed by fb
use(foo.bar, as: fb)
fb.baz()
# this will look for Foo::Bar::Condition::is_baz
if fb.is_baz()
end
# the import option makes them available without prefix
use(foo.bar, import: 1)
baz()

Most of the Fix commandsuse paths to point to values in a data record. 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)

An array of fixes. Catmandu::Fix which will execute every fix in 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. Required.

A Fix function is a Perl class in the Catmandu::Fix namespace that implements a fix method. The fix methods accepts a Perl hash as input and returns a (fixed) Perl hash as output. As an example, the code belows implements the meow Fix which inserts a 'meow' field with value 'purrrrr'.

Given this Perl class, the following fix statement can be used in your application:

# Will add 'meow' = 'purrrrr' to the data
meow()

Use the quick and easy method when your fixes are not dependent on reading or writing data from/to a JSON path. Your Perl classes need to implement their own logic to read or write data into the given Perl hash.

Fix arguments are passed as arguments to the new function of the Perl class. As in

The advanced method is required when one needs to read or write values from/to deeply nested JSON paths. One could parse JSON paths using the quick and easy Perl class above, but this would require a lot of inefficient for-while loops. The advanced method emits Perl code that gets compiled. This compiled code is evaled against all Perl hashes in the unput.The best way to learn this method is by inspecting some example Fix commands.

To ease the implementation of Fixed that emit Perl code some helper methods are created. Many Fix functions require a transformation of one or more values on a JSON Path. The Catmandu::Fix::SimpleGetValue provides an easy way to create such as script. In the example below we'll set the value at a JSON Path to 'purrrrr':

# Set the value(s) of an existing path to 'purrr'
purrrrr(my.deep.nested.path)
purrrrr(all.my.values.*)

Notice how the emit_value of the Catmandu::Fix::purrrrr package returns Perl code and doesn't operate directy on the Perl data. The parameter $var contains only the name of a temporary variable that will hold the value of the JSON path after compiling the code into Perl.