NAME

recs-join

recs-join --help-all

Help from: --help-basic:

Usage: recs-join <args> <inputkey> <dbkey> <dbfile> [<files>]
   Records of input (or records from <files>) are joined against records in
   <dbfile>, using field <inputkey> from input and field <dbkey> from <dbfile>.
   Each record from input may match 0, 1, or more records from <dbfile>. Each
   pair of matches will be combined to form a larger record, with fields from
   the dbfile overwriting fields from the input stream. If the join is a left
   join or inner join, any inputs that do not match a dbfile record are
   discarded. If the join is a right join or inner join, any db records that do
   not match an input record are discarded.

   dbkey and inputkey may be key specs, see '--help-keyspecs' for more
   information

Arguments:
   --left                       Do a left join
   --right                      Do a right join
   --inner                      Do an inner join (This is the default)
   --outer                      Do an outer join
   --operation                  An perl expression to evaluate for merging two
                                records together, in place of the default
                                behavior of db fields overwriting input fields.
                                See "Operation" below.
   --accumulate-right           Accumulate all input records with the same key
                                onto each db record matching that key. See
                                "Accumulate Right" below.
   --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-full      Help on join types and accumulate-right
      --help-keyspecs  Help on keyspecs, a way to index deeply and with regexes
      --help-snippet   Help on code snippets

Operation:
   The expression provided is evaluated for every pair of db record and input
   record that have matching keys, in place of the default operation to
   overwrite input fields with db fields. The variable $d is set to a
   App::RecordStream::Record object for the db record, and $i is set to a
   App::RecordStream::Record object for the input record. The $d record is used
   for the result. Thus, if you provide an empty operation, the result will
   contain only fields from the db record.

Examples:
   Join type from STDIN and typeName from dbfile
      cat recs | recs-join type typeName dbfile

   Join host name from a mapping file to machines to get IPs
      recs-join host host hostIpMapping machines

Help from: --help-full:
Join Types
   For instance, if you did:
   recs-join type typeName dbfile fromfile

   with a db file like:
   { 'typeName': 'foo', 'hasSetting': 1 }
   { 'typeName': 'bar', 'hasSetting': 0 }

   and joined that with
   { 'name': 'something', 'type': 'foo'}
   { 'name': 'blarg', 'type': 'hip'}

   for an inner (default) join, you would get
   { 'name': 'something', 'type': 'foo', 'typeName': 'foo', 'hasSetting': 1}

   for an outer join, you would get
   { 'name': 'something', 'type': 'foo', 'typeName': 'foo', 'hasSetting': 1}
   { 'name': 'blarg', 'type': 'hip'}
   { 'typeName': 'bar', 'hasSetting': 0 }

   for a left join, you would get
   { 'name': 'something', 'type': 'foo', 'typeName': 'foo', 'hasSetting': 1}
   { 'typeName': 'bar', 'hasSetting': 0 }

   for a right join, you would get
   { 'name': 'something', 'type': 'foo', 'typeName': 'foo', 'hasSetting': 1}
   { 'name': 'blarg', 'type': 'hip'}

Accumulate Right:
   Accumulate all input records with the same key onto each db record matching
   that key. This means that a db record can have multiple input records merged
   into it. If no operation is provided, any fields in second or later records
   will be lost due to them being discarded. This option is most useful with a
   user defined operation to handle collisions. For example, one could provide
   an operation to add fields together:

   recs-join --left --operation '
     foreach $k (keys %$i) {
       if (exists($d->{$k})) {
         if ($k =~ /^value/) {$d->{$k} = $d->{$k} + $i->{$k};}
       } else {
         $d->{$k} = $i->{$k};
       }
     }' --accumulate-right name name dbfile inputfile

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