= NAME =
parse_log

= SYNOPSIS =
 * parse_log(regex_string)

= DESCRIPTION =
This function parses the test log for the just-exected test, using the regex
string to match lines from the log.

It returns a list of tuples with group elements for each of the matches found.

The regular expression string is compiled using re.MULTILINE, so it should usually include anchors for the start and end of the a line ("^" and "$").
(That is, if the test log is line-oriented).
The pattern should have enough detail to make the parsing results unique.
The regular expression string should also include groups, to pull out the
values desired from the test log.

After this call, it is customary to build a list of results to provide
to the [[parser_func_process|process]] function.  See that page for
details about it's input parameter format.

= EXAMPLES =
Here is a sample invocation:

== Dhrystone ==
{{{#!YellowBox
  regex_string = "^(Dhrystones.per.Second:)(\ *)([\d]{1,8}.?[\d]{1,3})(.*)$"
  matches = plib.parse_log(regex_string)
}}}

This regex_string has 4 groups, to match:
 * 1. the marker "Dhrystones per Second"
 * 2. middle whitespace
 * 3. a number, consisting of 1 to 8 digits, a period and 1 to 3 digits
 * 4. the rest of the line

In this example, the 2nd and 4th parts of the pattern did not need to be
in groups (surrounded by parentheses).

After a normal run of Benchmark.Dhrystone, this will return something like the following:
{{{#!YellowBox
[('Dhrystones per Second:', '                      ', '11111111.0', ' ')]
}}}

In this case, the group that is desired is the 3rd tuple element, of the first match. That is, matches[0][2] has the value '11111111.0' (as a string).

A Dhrystone test log is shown below.  Note that the
indicated regex_string only matches one line in the file.

{{{#!YellowBox
Dhrystone Benchmark, Version 2.1 (Language: C)

Program compiled without 'register' attribute

Please give the number of runs through the benchmark: 
Execution starts, 100000000 runs through Dhrystone
Execution ends

Final values of the variables used in the benchmark:

Int_Glob:            5
        should be:   5
Bool_Glob:           1
        should be:   1
Ch_1_Glob:           A
        should be:   A
Ch_2_Glob:           B
        should be:   B
Arr_1_Glob[8]:       7
        should be:   7
Arr_2_Glob[8][7]:    100000010
        should be:   Number_Of_Runs + 10
Ptr_Glob->
  Ptr_Comp:          29564944
        should be:   (implementation-dependent)
  Discr:             0
        should be:   0
  Enum_Comp:         2
        should be:   2
  Int_Comp:          17
        should be:   17
  Str_Comp:          DHRYSTONE PROGRAM, SOME STRING
        should be:   DHRYSTONE PROGRAM, SOME STRING
Next_Ptr_Glob->
  Ptr_Comp:          29564944
        should be:   (implementation-dependent), same as above
  Discr:             0
        should be:   0
  Enum_Comp:         1
        should be:   1
  Int_Comp:          18
        should be:   18
  Str_Comp:          DHRYSTONE PROGRAM, SOME STRING
        should be:   DHRYSTONE PROGRAM, SOME STRING
Int_1_Loc:           5
        should be:   5
Int_2_Loc:           13
        should be:   13
Int_3_Loc:           7
        should be:   7
Enum_Loc:            1
        should be:   1
Str_1_Loc:           DHRYSTONE PROGRAM, 1'ST STRING
        should be:   DHRYSTONE PROGRAM, 1'ST STRING
Str_2_Loc:           DHRYSTONE PROGRAM, 2'ND STRING
        should be:   DHRYSTONE PROGRAM, 2'ND STRING

Microseconds for one run through Dhrystone:    0.1 
Dhrystones per Second:                      11111111.0 
}}}






= ENVIRONMENT and ARGUMENTS =
The "common.py" module uses the following environment variables, to find the test log:
 * FUEGO_RW
 * TESTDIR
 * NODE_NAME
 * TESTSPEC
 * BUILD_NUMBER
 * BUILD_ID

= RETURN =
Returns a list of tuples, with each tuple holding the matched text from the log for the groups in the regex_string.

Returns an empty list ([]) if there were no matches found.

Returns None if there was a error reading the test log.

Raises an exception if there was a problem compiling the regular expression string.

= SOURCE =
Located in ''scripts/parser/common.py''

= SEE ALSO =
 * [[parser.py]], [[parser_func_process|process]]