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.
There are two helper methods: push_input and push_output. Invoking push_input
on a Record object or hash will cause the next record to be processed to be
the indicated record. You may pass multiple records with one call. Similarly
push_output causes the next record to be output to be the passed record(s).
If push_output is called, the original record will not be output in this
case. (call push_output($r) if you want that record also outputted). You may
call these methods from a --pre-snippet or a --post-snippet. You may also
call push_output() without any argument to suppress the outputting of the
current record
--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
--A NUM Make NUM records after this one available in $A
(closest record to current in first position)
--B NUM Make NUM records before this one available in $B
(closest record to current in first position)
--C NUM Make NUM records after this one available in $A
and $B, as per -A NUM and -B NUM
--post-snippet SNIP A snippet to run once the stream has completed
--pre-snippet SNIP A snippet to run before the stream starts
--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, remove field a
recs-xform '$r->rename("old", "new"); $r->remove("a");'
Remove fields which are not "a", "b", or "c"
recs-xform '$r->prune_to("a", "b", "c")'
Double records
recs-xform '$r = [{%$r}, {%$r}]'
Double records with function interface
recs-xform 'push_output($r, $r);'
Move a value from the previous record to the next record
recs-xform -B 1 '{{before_val}} = $B->[0]'
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