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. Note that an empty operation is
    different from no --operation at all.
 
 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