[libcatmandu-perl] 62/101: More pod

[Jonas Smedegaard]

This is an automated email from the git hooks/post-receive script.

js pushed a commit to branch master
in repository libcatmandu-perl.

commit 0ee6479cbafb4b874c4d834b5931ea63c8039f9e
Author: Patrick Hochstenbach <patrick.hochstenbach at ugent.be>
Date:   Thu Feb 4 10:39:24 2016 +0100

    More pod
---
 lib/Catmandu/Fix.pm | 70 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 58 insertions(+), 12 deletions(-)

diff --git a/lib/Catmandu/Fix.pm b/lib/Catmandu/Fix.pm
index 1f8b7d5..d7f6a69 100644
--- a/lib/Catmandu/Fix.pm
+++ b/lib/Catmandu/Fix.pm
@@ -705,16 +705,37 @@ for easy data manipulation by non programmers. The main intention is to use fixe
 on the command line or in Fix scripts. A small DSL language is available to execute
 many Fix command on a stream of data.
 
-When a C<fix> argument is given to a L<Catmandu::Importer>, L<Catmandu::Store> or
+When a C<fix> argument is given to a L<Catmandu::Importer>, L<Catmandu::Exporter> or
 L<Catmandu::Store> then the transformations are executed on every item in the stream.
 
-Many fixes can use Fix paths (see below) to point to fields in a data record. A
-Fix script is a collection of one or more Fix commands:
+=head1 FIX LANGUAGE
+
+A Fix script is a collection of one or more Fix commands. The fixes are executed 
+on every record in the dataset. If this command is executed on the command line:
+
+    $ catmandu convert JSON --fix 'upcase(title); add_field(deep.nested.field,1)' < data.json
+
+then all the title fields will be upcased and a new deeply nested field will be added:
+
+    { "title":"foo" }
+    { "title":"bar" }
+
+becomes:
+
+    { "title":"FOO" , "deep":{"nested":{"field":1}} }
+    { "title":"BAR" , "deep":{"nested":{"field":1}} }
+
+Using the command line, Fix commands need a semicolon (;) as separator. All these commands can 
+also be written into a Fix script where semicolons are not required:
+
+    $ catmandu convert JSON --fix script.fix < data.json
+
+where C<script.fix> contains:
 
     upcase(title)
     add_field(deep.nested.field,1)
 
-Conditionals can be used to provide the logic when to execute some fixes:
+Conditionals can be used to provide the logic when to execute fixes:
 
     if exists(deep.nested.field)
         add_field(nested,"ok!")
@@ -725,17 +746,38 @@ Conditionals can be used to provide the logic when to execute some fixes:
     end
 
 Binds are used to manipulate the context in which Fixes are executed. E.g.
-execute a fix on every item in a list
+execute a fix on every item in a list:
 
      # 'demo' is an array of hashes
      do list(path:demo)
         add_field(foo,bar)
-     end   
+     end
+
+To delete records from a stream of data the C<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 C<reject> is C<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
 
 =head1 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
+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
@@ -763,9 +805,10 @@ E.g.
  # Create { mods => { titleInfo => [ { 'title' => 'foo' } , { 'title' => 'bar' }] } };
  add_field('mods.titleInfo.$last.title', 'bar');
 
-Read more about the Fix language in our Wiki: L<https://github.com/LibreCat/Catmandu/wiki/Fixes>
+=head1 PERL API
 
-=head1 PUBLIC METHODS
+The following is a list of methods available when including Catmandu::Fix as part of
+a Perl program.
 
 =head2 new(fixes => [ FIX , ...])
 
@@ -985,7 +1028,10 @@ this method is DEPRECATED.
 
 =head1 SEE ALSO
 
-Fixes are used by instances of L<Catmandu::Fixable> to manipulate items
-L<Catmandu::Importer>, L<Catmandu::Exporter>, and L<Catmandu::Bag>.
+L<Catmandu::Fixable>,
+L<Catmandu::Importer>, 
+L<Catmandu::Exporter>,
+L<Catmandu::Store>,  
+L<Catmandu::Bag>
 
 =cut

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libcatmandu-perl.git