4.1 Extension Options

The remaining extensibility options are called at various points in the program: when it starts, when a file is started, when a match is found, when a record is read, when a record is written, when a file is closed, and at the very end of the program. The options are listed below along with the way to get access to the relevant data.

The various non-field=specific options are as follows. They all occur as arguments to the option ‘--extension’ (or ‘-x’).

‘lscheme-command’

Filter records from the current file using the scheme command provided. The scheme command must return ‘#t’ (to keep processing the record) or ‘#f’ (to ignore this record and move on to the next). The variables ‘reference-field-n’ or ‘data-field-n’ will be available to the scheme command, depending on whether the record to be filtered is from the data file or a reference file. In the variable names ‘n’ represents the number of the specified output field, numbered from 1.

‘mscheme-command’

Validate a proposed match using the scheme command provided. The scheme command must return ‘#t’ (to confirm that this is a good match) or ‘#f’ (to tell combine that this is not a match). The variables ‘reference-field-n’ and ‘data-field-n’ will be available to the scheme command from the reference and data records involved in a particular match. In the variable names ‘n’ represents the number of the specified output field, numbered from 1. The extension specification affects the match between the data file and the last named reference file.

‘hscheme-command’

Validate a proposed match between two records in the same hierarchy using the scheme command provided. The scheme command must return ‘#t’ (to confirm that this is a good match) or ‘#f’ (to tell combine that this is not a match). The variables ‘reference-field-n’ and ‘prior-reference-field-n’ will be available to the scheme command from the prior and current reference records involved in a particular match. In the variable names ‘n’ represents the number of the specified output field, numbered from 1. The extension specification affects the match while traversing the hierarchs in the last named reference file.

‘rscheme-command’

Modify a record that has just been read using the scheme command provided. The scheme command must return a string, which will become the new value of the input record to be processed. The input record iteself can be referred to in the scheme command by using the variable ‘input-record’ in the scheme command at the right place. The records affected by this option are the records from the most recently named reference file, or from the data file if no reference file has yet been named.

As an example, consider that you may have received a file from someone who strips all the trailing spaces from the end of a record, but you need to treat it with a fixed-width record layout. Assuming that you have defined a scheme function rpad in the initialization file ‘util.scm’, you can use the following command to get at the field in positions 200-219, with spaces in place of the missing rest of the record.

combine -X util.scm -x 'r(rpad input-record 219 #\space)' \
            -o 200-219 trimmed_file.txt

The same syntax works with the other ‘--extension’ options.

This document was generated by Daniel P. Valentine on July 28, 2013 using texi2html 1.82.