NAME

recs-xform

recs-xform --help-all

Help from: --help-basic:
Usage: recs-xform <args> <expr> [<files>]
   <expr> is evaluated as perl on each record of input (or records from <files>) with $r set to a App::RecordStream::Record object and $line set to the current line number (starting at 1). All records are printed back out (changed as
   they may be).

   If $r is set to an ARRAY ref in the expr, then the values of the array will be treated as records and outputed one to a line. The values of the array may either be a hash ref or a App::RecordStream::Record object. The original record
   will not be outputted in this case.

   --e                          a perl snippet to execute, optional
   --E                          the name of a file to read as a perl snippet
   --filename-key|fk <keyspec>  Add a key with the source filename (if no filename is applicable will put NONE)

  Help Options:
      --help-all       Output all help for this script
      --help           This help screen
      --help-keyspecs  Help on keyspecs, a way to index deeply and with regexes
      --help-snippet   Help on code snippets

Examples:
   Add line number to records
      recs-xform '$r->{line} = $line'
   Rename field old to new
      recs-xform '$r->rename("old", "new")'
   Delete fields a and b
      recs-xform '$r->remove("a", "b")'
   Remove fields which are not "a", "b", or "c"
      recs-xform '$r->prune_to("a", "b", "c")'
   Double records
      recs-xform --ret '$r = [{%$r}, {%$r}]'
   Split the records on field a
      recs-xform --ret '[map { {%$r, "a" => $_} } split(/,/, delete($r->{"a"}))]'

Help from: --help-keyspecs:
KEY SPECS   
   A key spec is short way of specifying a field with prefixes or regular expressions, it may also be nested into hashes and arrays. Use a '/' to nest into a hash and a '#NUM' to index into an array (i.e. #2)

   An example is in order, take a record like this:
   
     {"biz":["a","b","c"],"foo":{"bar 1":1},"zap":"blah1"}
     {"biz":["a","b","c"],"foo":{"bar 1":2},"zap":"blah2"}
     {"biz":["a","b","c"],"foo":{"bar 1":3},"zap":"blah3"}
   
   In this case a key spec of 'foo/bar 1' would have the values 1,2, and 3 in the respective records.

   Similarly, 'biz/#0' would have the value of 'a' for all 3 records

   You can also prefix key specs with '@' to engage the fuzzy matching logic
   
   Fuzzy matching works like this in order, first key to match wins
     1. Exact match ( eq )
     2. Prefix match ( m/^/ )
     3. Match anywehre in the key (m//)
   
   So, in the above example '@b/#2', the 'b' portion would expand to 'biz' and 2 would be the index into the array, so all records would have the value of 'c'

   Simiarly, @f/b would have values 1, 2, and 3

   You can escape / with a \. For example, if you have a record:
   {"foo/bar":2}

   You can address that key with foo\/bar

Help from: --help-snippet:
CODE SNIPPETS:
    Recs code snippets are perl code, with one exception. There a couple of variables predefined for you, and one piece of special syntax to assist in modifying hashes.

Special Variables:
    $r - the current record object. This may be used exactly like a hash, or you can use some of the special record functions, see App::RecordStream::Record for more information

    $line - This is the number of records run through the code snippet, starting at 1. For most scripts this corresponds to the line number of the input to the script.

    $filename - The filename of the originating record. Note: This is only useful if you're passing filenames directly to the recs script, piping from other recs scripts or from cat, for instance, will not have a useful filename.

Special Syntax
    Use {{search_string}} to look for a string in the keys of a record, use / to nest keys. You can nest into arrays by using an index. If you are vivifying arrays (if the array doesn't exist, prefix your key with # so that an array
    rather than a hash will be created to put a / in your key, escape it twice, i.e. \/

    This is exactly the same as a key spec that is always prefaced with a @, see 'man recs' for more info on key specs

    For example: A record that looks like:
    { "foo" : { "bar 1" : 1 }, "zoo" : 2}
    Could be accessed like this:

    # value of zoo  # value of $r->{foo}->{bar 1}: (comma separate nested keys)
    {{zoo}}         {{foo/ar 1}}

    # Even assign to values (set the foo key to the value 1)
    {{foo}} = 1

   # And auto, vivify
    {{new_key/array_key/#0}} = 3 # creates an array within a hash within a hash

    # Index into an array
    {{array_key/#3}} # The value of index 3 of the array ref under the
                       'array_key' hash key.

    This matching is a fuzzy keyspec matching, see --help-keyspecs for more details.

See Also

RecordStream(3) - Overview of the scripts and the system

recs-examples(3) - A set of simple recs examples

recs-story(3) - A humorous introduction to RecordStream

SCRIPT --help - every script has a --help option, like the output above