Add a sort option

Add a --sort command line option to Parser.py, to allow sorting the tests
data in a configurable manner before producing the outputs.

Also, document usage in the README.md and fix parser.py case.

Signed-off-by: Vincent Stehlé <vincent.stehle@arm.com>

README.md

 # SCT_Parser
 
-This is an external Parser script for UEFI SCT. (WIP)
+This is an external parser script for UEFI SCT. (WIP)
 
 It's designed to read a `.ekl` results log from an UEFI SCT run, and a generated `.seq` from UEFI SCT configurator.
 
@@ -15,15 +15,22 @@ The output filename can be specified with `--md <filename>`.
 An online help is available with the `-h` option.
 
 ### Custom search
-For a custom Key:value search, the next two arguments *MUST be included together.* The program will search and display files that met that constraint, without the crosscheck, and display the names, guid, and key:value to the command line. `python3 Parser.py <file.ekl> <file.seq> <search key> <search value>`
+For a custom Key:value search, the next two arguments *MUST be included together.* The program will search and display files that met that constraint, without the crosscheck, and display the names, guid, and key:value to the command line. `python3 parser.py <file.ekl> <file.seq> <search key> <search value>`
 
 you can use the `test_dict` below to see available keys.
 
+### Sorting data
 
+It is possible to sort the tests data before output using
+the `--sort <key1,key2,...>` option.
+Sorting the test data helps when comparing results with diff.
 
+Example command:
 
-
-
+``` {.sh}
+$ ./parser.py --sort \
+      'group,descr,set guid,test set,sub set,guid,name,log' ...
+```
 
 ## Notes
 ### Known Issues:

parser.py

@@ -165,6 +165,16 @@ def dict_2_md(input_list,file):
     file.write("\n\n")
 
 
+# Sort tests data in-place
+# sort_keys is a comma-separated list
+# The first key has precedence, then the second, etc.
+# To use python list in-place sorting, we use the keys in reverse order.
+def sort_data(cross_check, sort_keys):
+    logging.debug(f"Sorting on `{sort_keys}'")
+    for k in reversed(sort_keys.split(',')):
+        cross_check.sort(key=lambda x: x[k])
+
+
 # Generate csv
 def gen_csv(cross_check, filename):
     # Find keys
@@ -196,6 +206,11 @@ def main():
         description='Process SCT results.'
                     ' This program takes the SCT summary and sequence files,'
                     ' and generates a nice report in mardown format.',
+        epilog='When sorting is requested, tests data are sorted'
+               ' according to the first sort key, then the second, etc.'
+               ' Sorting happens after update by the configuration rules.'
+               ' Useful example: --sort'
+               ' "group,descr,set guid,test set,sub set,guid,name,log"',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
     parser.add_argument('--csv', help='Output .csv filename')
     parser.add_argument('--json', help='Output .json filename')
@@ -203,6 +218,8 @@ def main():
         '--md', help='Output .md filename', default='result.md')
     parser.add_argument(
         '--debug', action='store_true', help='Turn on debug messages')
+    parser.add_argument(
+        '--sort', help='Comma-separated list of keys to sort output on')
     parser.add_argument(
         'log_file', nargs='?', default='sample.ekl',
         help='Input .ekl filename')
@@ -247,7 +264,11 @@ def main():
             would_not_run.append(x)
 
 
-    #search for failures and warnings & passes,
+    # Sort tests data in-place, if requested
+    if args.sort is not None:
+        sort_data(cross_check, args.sort)
+
+    # search for failures and warnings & passes,
 
     failures = key_value_find(cross_check,"result","FAILURE")
     warnings = key_value_find(cross_check,"result","WARNING")