7.7 Adding Parsers to Getstats
Getstats itself does not include any parsers, instead it searches the
Perl @INC
array which contains possible include paths for files
of the pattern gs_parser_*, and includes them. Getstats includes
three parsers by default, one for Auto-pilot results files, one for CSV
files, and one for a sequence of GNU time outputs. To add your own
parser, you should simply copy one of these parsers and modify it to
suit your needs.
Each parser defines two functions, and three parameters:
- Detection Function
- The detection function takes a list argument. The first item is the filename.
The next items are the file's lines. The filename should not be used
exclusively (because Getstats can read from stdin, which has a filename of
"-"). For example, the CSV detection makes sure each line is a valid CSV line.
If the file is of the correct type the detection function returns true,
otherwise it returns false. If the file name does not exist, the detection
function is called with the name, but not lines. This is so that parsers
expecting filename globs will still be executed. If no detection function
returns true, then an error is reported. If a detection function does return
true, the corresponding parsing function is called.
- Parsing Function
- The parsing function takes the same arguments as the detection function, but
now the file is assumed to be of that correct type (because the corresponding
detection function has already returned true). The parsing function returns a
two dimensional array containing the relation represented by the input file.
The first element of the array is a "label" row that has a short description of
each column (e.g., "elapsed" for Elapsed time). Each additional row of the
array is a test result.
- Description
- A short description of the file type this parser supports (e.g., "Comma
separated values.").
- Extension
- The default file extension (e.g., ".csv" is used for the CSV parser).
This is not used by Auto-pilot internally, except to derive the basename
of an input file.
- Priority
- The priority controls what order detection and parsing is performed.
Lower-numbered priorities are tried first. Auto-pilot results files
have a priority of 64, GNU time files have a priority of 96, and CSV
files have a priority of 128. If there is a chance that a parser
detects an invalid file as input, it should have a high-numbered
priority. For example, the CSV parser accepts more input than it
probably should , because a single column CSV file without any columns
is valid. This means that the Auto-pilot results and GNU time should
have a crack at reading the file first.