patt [-m] -f templatefile [-s regexp] [-t output_tag] [inputfile ...]
The pattern sought must be defined as a separate "template" file. The template file is identified using the -f command option.
Pattern templates consist of one or more records. Each record specifies a regular expression pattern. The input is scanned from beginning to end, in order to find passages that match the defined template. In order for a match to take place, successive records in the input stream must match the regular expressions given in each of the corresponding records of the template. For example, if the template is 9 lines in length, then the input stream must contain 9 successive lines of matching data in order for a pattern match to be successful.
The patt command implements a full UNIX regular expression syntax. Each line in the template file represents an independent regular expression. For example, the template:
1 2 3
will match inputs such as the following:
1 112 43.9
A more circumspect regular expression template might look like this:
0x.=%&1* Figure 32 abc(...32...)
^1$ ^2$ ^3$
(The caret (^) and dollar sign ($) are regular expression anchors that indicate the beginning of the record and end of the record respectively.) Refer to regexp (6) for further information regarding regular expressions. Note that the related pattern command implements a more powerful regular expression syntax for defining multi-record patterns.
Options are specified in the command line.
-c makes pattern-matching sensitive to comments -e echoes matched patterns in the output -f templatefile use pattern specified in templatefile -h displays a help screen summarizing the command syntax -m invokes collapsed multiple-record matching mode -s regexp skip (ignore) data records containing the defined regular expression -t output_tag generate
**pattoutput spine; tag each occurrence of the pattern
with the string output_tag
By default, the patt command is insensitive to the presence or absence of Humdrum comments. Pattern searches may be made sensitive to occurrences of comments by specifying the -c option.
In the default operation, patt outputs a Humdrum global comment for each pattern matched in the input. Each comment identifies the line number in the input where the found pattern begins.
With the -e option, each instance of the found pattern is echoed in the output. Each output pattern is preceded by the appropriate exclusive interpretation(s) and followed by appropriate spine-path terminator(s).
Certain types of data records may be ignored in the pattern-search by invoking the -s (skip) option. This option must be accompanied by a user-define regular expression. All input data records matching the regular expression are ignored. This option is useful, for example, in skipping null data tokens, barlines, marked embellishment tones, or other types of data.
The -m option invokes a multiple record matching mode. In this mode, patt attempts to match as many successive regular expressions in the template file as possible for a given input record, before continuing with the next input and template records. In this way, a template file consisting of several records, may possibly match a single input record. (See EXAMPLES below.)
to output a single spine of
The user specifies an output tag (character string) on the command line.
Each instance of the found pattern causes the tag to be
output in the
**patt spine at the position corresponding to
the onset of each found pattern.
(See EXAMPLES below.)
Note that the
options are mutually exclusive.
Whatever options are invoked, patt always produces output that conforms to the Humdrum syntax.
1 2 3
A simple search for the pattern template might use the command:
**foo 1 2 =1 1 3 2 1 3 2 3 =2 1 2 3 4 2 3 1 *-
patt -f template target
Pattern matches are announced by outputting Humdrum global comments.
Given the above command, the following output would result:
!! Pattern found at line 5 of file input !! Pattern found at line 6 of file input
Note however, that the first instance of the pattern (beginning at line 2) was not identified due to the interruption of the common system barline in the fourth line. The barlines can be ignored by invoking the -s option, followed by a regular expression that uniquely identifies the records to be skipped -- in this case the equals sign. The command:
patt -s = -f template target
would produce the following output:
!! Pattern found at line 2 of file input !! Pattern found at line 5 of file input !! Pattern found at line 6 of file input
patt -e -s = -f template target
The following output would result:
!! Pattern found at line 2 of file input **foo 1 2 =1 1 3 *- !! Pattern found at line 5 of file input **foo 1 3 2 1 3 2 *- !! Pattern found at line 6 of file input **foo 2 1 3 2 3 *-
Instead of outputting the individual patterns, the
option may be used to output a spine that marks each instance
of the found pattern.
In the following command, the beginning of each occurrence of the pattern
is labelled in the
**patt spine by the tag "one-two-three."
patt -t one-two-three -s = -f template target
The follow output would result:
**foo **patt 1 one-two-three 2 . =1 . 1 3 one-two-three 2 1 one-two-three 3 2 . 3 . =2 . 1 . 2 3 . 4 . 2 3 1 . *- *-
patt -m -t theme123 -s = -f template target
will produce the following output:
**foo **patt 1 theme123 2 . =1 . 1 3 theme123 2 1 theme123 3 2 . 3 . =2 . 1 theme123 2 3 . 4 . 2 3 1 theme123 *- *-
Note that in the above examples, the extensive capabilities provided by patt for defining complex regular expressions have not been illustrated. Refer to regexp (6) for further pertinent information.