docs(parser): add CST Structure section to README

Add a new 'CST Structure' subsection under 'Usage' with a concrete
JSON example showing the Chevrotain CST output for a self-closing
element (<xs:element name="api" />). The example accurately reflects
the grammar rules in parser.js and the type definitions in api.d.ts.

Closes #470

Author: harshanacz

packages/parser/README.md

@@ -43,6 +43,102 @@ const { cst, lexErrors, parseErrors } = parse(xmlText);
 console.log(cst.children["element"][0].children["Name"][0].image); // -> note
 ```
 
+### CST Structure
+
+The parser outputs a Concrete Syntax Tree (CST) using **Chevrotain**.
+
+For example, given the following XML input:
+
+```xml
+<root>
+  <child attr="value">Hello World</child>
+  <empty/>
+</root>
+```
+
+The resulting `cst` object for the document has the following structure (whitespace `chardata` nodes omitted for brevity):
+
+```jsonc
+{
+  "name": "document",
+  "children": {
+    "element": [
+      // top-level element(s)
+      {
+        "name": "element",
+        "children": {
+          "OPEN": [{ "image": "<" }],
+          "Name": [{ "image": "root" }],
+          "START_CLOSE": [{ "image": ">" }],
+
+          "content": [
+            // child content lives here
+            {
+              "name": "content",
+              "children": {
+                "element": [
+                  // nested child elements
+                  {
+                    "name": "element",
+                    "children": {
+                      "OPEN": [{ "image": "<" }],
+                      "Name": [{ "image": "child" }],
+                      "attribute": [
+                        {
+                          "name": "attribute",
+                          "children": {
+                            "Name": [{ "image": "attr" }],
+                            "EQUALS": [{ "image": "=" }],
+                            "STRING": [{ "image": "\"value\"" }],
+                          },
+                        },
+                      ],
+                      "START_CLOSE": [{ "image": ">" }],
+                      "content": [
+                        {
+                          "name": "content",
+                          "children": {
+                            "chardata": [
+                              {
+                                "name": "chardata",
+                                "children": {
+                                  "TEXT": [{ "image": "Hello World" }],
+                                },
+                              },
+                            ],
+                          },
+                        },
+                      ],
+                      "SLASH_OPEN": [{ "image": "</" }],
+                      "END_NAME": [{ "image": "child" }],
+                      "END": [{ "image": ">" }],
+                    },
+                  },
+                  {
+                    "name": "element", // self-closing: <empty/>
+                    "children": {
+                      "OPEN": [{ "image": "<" }],
+                      "Name": [{ "image": "empty" }],
+                      "SLASH_CLOSE": [{ "image": "/>" }],
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+
+          "SLASH_OPEN": [{ "image": "</" }],
+          "END_NAME": [{ "image": "root" }],
+          "END": [{ "image": ">" }],
+        },
+      },
+    ],
+  },
+}
+```
+
+Every property in `children` is an array of matched tokens (`IToken`) or nested rule nodes (`CstNode`). For full details on all node types (such as `prolog`, `docTypeDecl`, `content`, and `chardata`), see the [TypeScript Definitions](./api.d.ts).
+
 ## Support
 
 Please open [issues](https://github.com/SAP/xml-tols/issues) on github.