update parse_cli documentation with more examples (#28258)

* update parse_cli documentation with more examples

docs/docsite/rst/playbooks_filters.rst

@@ -339,13 +339,14 @@ output and return JSON data.  Below is an example of a valid spec file that
 will parse the output from the ``show vlan`` command.::
 
     ---
-    vlan:
-      vlan_id: "{{ item.vlan_id }}"
-      name: "{{ item.name }}"
-      enabled: "{{ item.state != 'act/lshut' }}"
-      state: "{{ item.state }}"
+    vars:
+      vlan:
+        vlan_id: "{{ item.vlan_id }}"
+        name: "{{ item.name }}"
+        enabled: "{{ item.state != 'act/lshut' }}"
+        state: "{{ item.state }}"
 
-    attributes:
+    keys:
       vlans:
         type: list
         value: "{{ vlan }}"
@@ -353,9 +354,56 @@ will parse the output from the ``show vlan`` command.::
       state_static:
         value: present
 
-The spec file above will return a JSON data structure that is a list of hashs
+The spec file above will return a JSON data structure that is a list of hashes
 with the parsed VLAN information.
 
+The same command could be parsed into a hash by using the key and values 
+directives.  Here is an example of how to parse the output into a hash 
+value using the same ``show vlan`` command.::
+
+    ---
+    vars:
+      vlan:
+        key: "{{ item.vlan_id }}"
+        values:
+          vlan_id: "{{ item.vlan_id }}"
+          name: "{{ item.name }}"
+          enabled: "{{ item.state != 'act/lshut' }}"
+          state: "{{ item.state }}"
+
+    keys:
+      vlans:
+        type: list
+        value: "{{ vlan }}"
+        items: "^(?P<vlan_id>\\d+)\\s+(?P<name>\\w+)\\s+(?P<state>active|act/lshut|suspended)"
+      state_static:
+        value: present
+
+Another common use case for parsing CLI commands is to break a large command 
+into blocks that can parsed.  This can be done using the ``start_block`` and
+``end_block`` directives to break the command into blocks that can be parsed.::
+
+    ---
+    vars:
+      interface:
+        name: "{{ item[0].match[0] }}"
+        state: "{{ item[1].state }}"
+        mode: "{{ item[2].match[0] }}"
+
+    keys:
+      interfaces:
+        value: "{{ interface }}"
+        start_block: "^Ethernet.*$"
+        end_block: "^$"
+        items:
+          - "^(?P<name>Ethernet\\d\\/\\d*)"
+          - "admin state is (?P<state>.+),"
+          - "Port mode is (.+)"
+
+
+The example above will parse the output of ``show interface`` into a list of
+hashes.
+
 The network filters also support parsing the output of a CLI command using the
 TextFSM library.  To parse the CLI output with TextFSM use the following
 filter::