8.3 Adding Parsers to Graphit

Graphit parsers work much like the Getstats parsers described in Getstats Parsers.

Graphit itself does not include any parsers, instead it searches the Perl @INC array which contains possible include paths for files of the pattern gi_parser_*, and includes them. Graphit two parsers by default, one for Getstats output and Auto-pilot results files, and another for CSV files. 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 one argument, which is the input specification. 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 four arguments. The first is the Graphit mode (i.e., bar or line). The second is a reference to the @seriesdata array. The third is the name of the series, and the fourth is the input specification. The parsing function can assume that the input specification is correct, because the detection function has already returned true.

The series data array contains references to hashes that define a series. To see the value of the @seriesdata array after parsing, pass the -d option to Graphit. Each hash contains a "name" key that is the name of the series. The rest of the keys in the top-level hash are a position along the x-axis for line graphs. For bar graphs, the only other key is "0". Each of these keys contains a sub-hash, that is indexed by each component. These sub-hashes, in turn contain a sub-sub-hash that has three keys: high, low, and mean. These keys map to integers for the top and bottom value of the error bar and the y-value for that x position (or bar).

The @seriesdata array for Figure 8.1, is as follows:

     
     @seriesdata = [
               {
                 '0' => {
                          'System' => {
                                        'high' => '2.807',
                                        'low' => '2.709',
                                        'mean' => '2.758'
                                      },
                          'User' => {
                                      'high' => '1.735',
                                      'low' => '1.615',
                                      'mean' => '1.675'
                                    },
                          'Elapsed' => {
                                         'high' => '6.120',
                                         'low' => '5.991',
                                         'mean' => '6.055'
                                       }
                        },
                 'name' => 'Ext2'
               },
               {
                 '0' => {
                          'System' => {
                                        'high' => '4.327',
                                        'low' => '4.217',
                                        'mean' => '4.272'
                                      },
                          'User' => {
                                      'high' => '1.877',
                                      'low' => '1.773',
                                      'mean' => '1.825'
                                    },
                          'Elapsed' => {
                                         'high' => '81.567',
                                         'low' => '74.156',
                                         'mean' => '77.861'
                                       }
                        },
                 'name' => 'Ext3'
               },
               {
                 '0' => {
                          'System' => {
                                        'high' => '12.944',
                                        'low' => '12.632',
                                        'mean' => '12.788'
                                      },
                          'User' => {
                                      'high' => '2.087',
                                      'low' => '1.907',
                                      'mean' => '1.997'
                                    },
                          'Elapsed' => {
                                         'high' => '69.842',
                                         'low' => '65.597',
                                         'mean' => '67.719'
                                       }
                        },
                 'name' => 'Reiserfs'
               }
     ];

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.

Priority

The priority controls what order detection and parsing is performed. Lower-numbered priorities are tried first. Getstats output and Auto-pilot results files have a priority of 64, 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 Getstats output parser should have a crack at reading the file first.

Parsers may need to process command line arguments, which are specified with the --Xparser command line option. To access the arguments, a parser can access @PARSERARGV, but should not modify it. Also, if an argument is unknown the parser should not fail or exit the program, because the argument could be for another parser.