Add * Examples to README

README.org

@@ -34,6 +34,88 @@
   pip install -e .
   #+END_SRC
 
+* Examples
+  To use git parlance, the porcelain tool is =sarif-results-summary=, while the
+  plumbing tools are =sarif-digest=, =sarif-labeled= and =sarif-list-files=.
+
+  Following are short summaries of each.
+
+** =sarif-results-summary=
+   Display the SARIF results in human-readable plain text form. Taking the warning around
+   #+BEGIN_SRC text
+     src/stc/scintilla/lexers/LexMySQL.cxx:153:24:153:30:
+   #+END_SRC
+   as example, there are two options using only the SARIF file, and one more when
+   source code is available.
+
+   1. Display only main result.  Using
+      #+BEGIN_SRC sh
+        sarif-results-summary -s data/wxWidgets-small  -r data/wxWidgets_wxWidgets__2021-11-21_16_06_30__export.sarif 2>&1 |less -p LexMySQL.cxx
+      #+END_SRC
+      only displays
+      #+BEGIN_SRC text
+        RESULT: src/stc/scintilla/lexers/LexMySQL.cxx:153:24:153:30: Local variable 'length' hides a [parameter of the same name](1).
+      #+END_SRC
+   2. Display the related information.  Using
+      #+BEGIN_SRC sh
+        sarif-results-summary -r data/wxWidgets_wxWidgets__2021-11-21_16_06_30__export.sarif 2>&1 | less -p LexMySQL.cxx
+      #+END_SRC
+      displays
+      #+BEGIN_SRC text
+        RESULT: src/stc/scintilla/lexers/LexMySQL.cxx:153:24:153:30: Local variable 'length' hides a [parameter of the same name](1).
+
+        REFERENCE: src/stc/scintilla/lexers/LexMySQL.cxx:108:68:108:74: parameter of the same name
+      #+END_SRC
+   3. Either display can be supplemented by source code snippets if the source is
+      available.  Using
+
+      #+BEGIN_SRC sh
+        sarif-results-summary -s data/wxWidgets-small  -r data/wxWidgets_wxWidgets__2021-11-21_16_06_30__export.sarif 2>&1 |less
+      #+END_SRC
+      displays the source code with underlines
+      #+BEGIN_SRC text
+        RESULT: src/stc/scintilla/lexers/LexMySQL.cxx:153:24:153:30: Local variable 'length' hides a [parameter of the same name](1).
+
+                  Sci_Position length = sc.LengthCurrent() + 1;
+                               ^^^^^^
+        REFERENCE: src/stc/scintilla/lexers/LexMySQL.cxx:108:68:108:74: parameter of the same name
+
+        static void ColouriseMySQLDoc(Sci_PositionU startPos, Sci_Position length, int initStyle, WordList *keywordlists[],
+                                                                           ^^^^^^
+      #+END_SRC
+
+** =sarif-digest=
+   Get an idea of the SARIF file structure by showing only first / last entries in arrays.
+   #+BEGIN_SRC sh
+     sarif-digest  data/torvalds_linux__2021-10-21_10_07_00__export.sarif |less
+   #+END_SRC
+
+** =sarif-labeled=
+   Display the SARIF file with explicit paths inserted before json objects and
+   selected array entries.  Handy when reverse-engineering the format by searching
+   for results.
+   #+BEGIN_SRC sh
+     sarif-labeled  data/torvalds_linux__2021-10-21_10_07_00__export.sarif |less
+   #+END_SRC
+   For example, the
+   #+BEGIN_SRC text
+     "uri": "drivers/gpu/drm/i915/gt/uc/intel_guc.c",
+   #+END_SRC
+   is nested; the labeled display shows where:
+   #+BEGIN_SRC text
+     "sarif_struct['runs'][1]['results'][4]['locations'][0]['physicalLocation']['artifactLocation']": "----path----",
+     "artifactLocation": {
+     "uri": "drivers/gpu/drm/i915/gt/uc/intel_guc.c",
+   #+END_SRC
+
+** =sarif-list-files=
+   Display the list of files referenced by a SARIF file.  This is the tools used to
+   get file names that ultimately went into =data/linux-small/= and
+   =data/wxWidgets-small/=.
+   #+BEGIN_SRC sh
+     sarif-list-files data/wxWidgets_wxWidgets__2021-11-21_16_06_30__export.sarif
+   #+END_SRC
+
 * Sample Data
   The query results in =data/= are taken from lgtm.com, which ran the
   : ql/$LANG/ql/src/codeql-suites/$LANG-lgtm.qls
@@ -54,6 +136,18 @@
     ]
   #+end_src
 
+  The wxWidgets library has both single-location results (="kind": "problem"=) and path
+  results (="kind": "path-problem"=). 
+
+  The subset of files referenced by the sarif results is in =data/wxWidgets-small/=
+  and is taken from 
+
+  #+BEGIN_SRC js
+    "repositoryUri": "https://github.com/wxWidgets/wxWidgets.git",
+    "revisionId": "7a03d5fe9bca2d2a2cd81fc0620bcbd2cbc4c7b0"
+  #+END_SRC
+
+
 # * Commands