=head1 NAME

recs-generate

=head1 recs-generate --help-all

 Help from: --help-basic:
 Usage: recs-generate <args> <command> [<files>]
    Executes <command> for each record to generate a record stream, which is then
    output with a chain link back to the original record.
 
    <command> is executed opened as a command for each record of input (or
    records from <files>) with $r set to a App::RecordStream::Record object. The
    output lines of each command execution are interpreted as a serialized Recs
    records, one per line. Each such line is reconstituted as a
    App::RecordStream::Record, and the '_chain' key is added to the record before
    it is printed. The value of the '_chain' key is the record that was
    originally passed to the eval expression.
 
    For instance.  If you did:
    recs-generate "recs-fromatomfeed http://...?key=$r->{title}..."
 
    with input that looked like:
    { 'title' : 'foo' }
    { 'title' : 'bar' }
 
    then recs-generate would end up executing:
    recs-fromatomfeed http://...?key=foo...
 
    and interpreting the result as a series of new line separated records.
 
    If the result from recs-fromatomfeed was something like:
    { 'title' : 'zip' }
    { 'title' : 'zap' }
 
    then recs-generate would add the chain link so the output would look like:
    { 'title' : 'zip', 'chain' : { 'title' : 'foo' } }
    { 'title' : 'zap', 'chain' : { 'title' : 'foo' } }
 
 Arguments:
    --e                          a perl snippet to execute, optional
    --E                          the name of a file to read as a perl snippet
    --M module[=...]             execute "use module..." before executing
                                 snippet; same behaviour as perl -M
    --m module[=...]             same as -M, but by default import nothing
    --passthrough                Emit input record in addition to generated
                                 records
    --keychain <name>            Use 'name' as the chain key (default is
                                 '_chain') may be a key spec, see '--help-
                                 keyspecs' for more info
    --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
 
 Examples:
    Chain recs from a feed to recs from a second feed and the print the titles.
       recs-fromatomfeed "http://..." | recs-generate "recs-fromatomfeed http://...?key=$r->{title}" | recs-eval 'join("	", $r->{title}, $r->{chain}->{title})'
 
 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
 

=head1 SEE ALSO

=over

=item * See L<App::RecordStream> for an overview of the scripts and the system

=item * Run C<recs examples> or see L<App::RecordStream::Manual::Examples> for a set of simple recs examples

=item * Run C<recs story> or see L<App::RecordStream::Manual::Story> for a humorous introduction to RecordStream

=item * Every command has a C<--help> mode available to print out usage and
examples for the particular command, just like the output above.

=back

