Merge pull request #209 from kellyjonbrazil/dev

Dev v1.18.4

CHANGELOG

@@ -1,5 +1,19 @@
 jc changelog
 
+20220304 v1.18.4
+- Add nmcli command parser tested on linux
+- Enhance parse error messages at the cli
+- Add standard and streaming parser list functions to the public API
+- Enhance python developer documentation formatting
+
+20220214 v1.18.3
+- Add rsync command and log file parser tested on linux and macOS
+- Add rsync command and log file streaming parser tested on linux and macOS
+- Add xrandr command parser tested on linux
+- Enhance timestamp performance with caching and format hints
+- Refactor ignore_exceptions functionality in streaming parsers
+- Fix man page in packages
+
 20220127 v1.18.2
 - Fix for plugin parsers with underscores in the name
 - Add type hints to public API functions

EXAMPLES.md

@@ -2387,6 +2387,47 @@ netstat -i | jc --netstat -p          # or:  jc -p netstat -i
   }
 ]
 ```
+### nmcli
+```bash
+nmcli connection show ens33 | jc --nmcli -p          # or jc -p nmcli connection show ens33
+```
+```json
+[
+      {
+        "connection_id": "ens33",
+        "connection_uuid": "d92ece08-9e02-47d5-b2d2-92c80e155744",
+        "connection_stable_id": null,
+        "connection_type": "802-3-ethernet",
+        "connection_interface_name": "ens33",
+        "connection_autoconnect": "yes",
+        "ip4_address_1": "192.168.71.180/24",
+        "ip4_gateway": "192.168.71.2",
+        "ip4_route_1": {
+          "dst": "0.0.0.0/0",
+          "nh": "192.168.71.2",
+          "mt": 100
+        },
+        "ip4_route_2": {
+          "dst": "192.168.71.0/24",
+          "nh": "0.0.0.0",
+          "mt": 100
+        },
+        "ip4_dns_1": "192.168.71.2",
+        "ip4_domain_1": "localdomain",
+        "dhcp4_option_1": {
+          "name": "broadcast_address",
+          "value": "192.168.71.255"
+        },
+        "ip6_address_1": "fe80::c1cb:715d:bc3e:b8a0/64",
+        "ip6_gateway": null,
+        "ip6_route_1": {
+          "dst": "fe80::/64",
+          "nh": "::",
+          "mt": 100
+        }
+      }
+    ]
+```
 ### ntpq
 ```bash
 ntpq -p | jc --ntpq -p          # or:  jc -p ntpq -p
@@ -2743,6 +2784,39 @@ rpm_qia | jc --rpm_qi -p          # or:  jc -p rpm -qia
   }
 ]
 ```
+### rsync
+```bash
+rsync -i -a source/ dest | jc --rsync -p          # or jc -p rsync -i -a source/ dest
+```
+```json
+[
+  {
+    "summary": {
+      "sent": 1708,
+      "received": 8209,
+      "bytes_sec": 19834.0,
+      "total_size": 235,
+      "speedup": 0.02
+    },
+    "files": [
+      {
+        "filename": "./",
+        "metadata": ".d..t......",
+        "update_type": "not updated",
+        "file_type": "directory",
+        "checksum_or_value_different": false,
+        "size_different": false,
+        "modification_time_different": true,
+        "permissions_different": false,
+        "owner_different": false,
+        "group_different": false,
+        "acl_different": false,
+        "extended_attribute_different": false
+      }
+    ]
+  }
+]
+```
 ### sfdisk
 ```bash
 sfdisk -l | jc --sfdisk -p          # or jc -p sfdisk -l
@@ -3751,6 +3825,68 @@ cat cd_catalog.xml | jc --xml -p
   }
 }
 ```
+### xrandr
+```bash
+$ xrandr | jc --xrandr -p          # or  jc -p xrandr
+```
+```json
+{
+  "screens": [
+    {
+      "screen_number": 0,
+      "minimum_width": 8,
+      "minimum_height": 8,
+      "current_width": 1920,
+      "current_height": 1080,
+      "maximum_width": 32767,
+      "maximum_height": 32767,
+      "associated_device": {
+        "associated_modes": [
+          {
+            "resolution_width": 1920,
+            "resolution_height": 1080,
+            "is_high_resolution": false,
+            "frequencies": [
+              {
+                "frequency": 60.03,
+                "is_current": true,
+                "is_preferred": true
+              },
+              {
+                "frequency": 59.93,
+                "is_current": false,
+                "is_preferred": false
+              }
+            ]
+          },
+          {
+            "resolution_width": 1680,
+            "resolution_height": 1050,
+            "is_high_resolution": false,
+            "frequencies": [
+              {
+                "frequency": 59.88,
+                "is_current": false,
+                "is_preferred": false
+              }
+            ]
+          }
+        ],
+        "is_connected": true,
+        "is_primary": true,
+        "device_name": "eDP1",
+        "resolution_width": 1920,
+        "resolution_height": 1080,
+        "offset_width": 0,
+        "offset_height": 0,
+        "dimension_width": 310,
+        "dimension_height": 170
+      }
+    }
+  ],
+  "unassociated_devices": []
+}
+```
 ### YAML files
 ```bash
 cat istio.yaml 

README.md

@@ -1,8 +1,6 @@
 ![Tests](https://github.com/kellyjonbrazil/jc/workflows/Tests/badge.svg?branch=master)
 ![Pypi](https://img.shields.io/pypi/v/jc.svg)
 
-> `jc` was recently featured in the [Console Open Source Newsletter](https://console.substack.com/p/console-89)
-
 > Check out the `jc` Python [package documentation](https://github.com/kellyjonbrazil/jc/tree/master/docs) for developers
 
 > Try the `jc` [web demo](https://jc-web-demo.herokuapp.com/)
@@ -13,7 +11,7 @@ Ansible filter plugin in the `community.general` collection. See this
 for an example.
 
 # JC
-JSON CLI output utility
+JSON Convert
 
 `jc` JSONifies the output of many CLI tools and file-types for easier parsing in
 scripts. See the [**Parsers**](#parsers) section for supported commands and
@@ -55,16 +53,9 @@ will be a python dictionary, or list of dictionaries, instead of JSON:
 >>> cmd_output = subprocess.check_output(['dig', 'example.com'], text=True)
 >>> data = jc.parse('dig', cmd_output)
 >>>
->>> data
-[{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', 'flags': ['qr', 'rd',
-'ra'], 'query_num': 1, 'answer_num': 1, 'authority_num': 0, 'additional_num':
-1, 'opt_pseudosection': {'edns': {'version': 0, 'flags': [], 'udp': 4096}},
-'question': {'name': 'example.com.', 'class': 'IN', 'type': 'A'}, 'answer':
+>>> data[0]['answer']
 [{'name': 'example.com.', 'class': 'IN', 'type': 'A', 'ttl': 29658, 'data':
-'93.184.216.34'}], 'query_time': 52, 'server':
-'2600:1700:bab0:d40::1#53(2600:1700:bab0:d40::1)', 'when':
-'Fri Apr 16 16:13:00 PDT 2021', 'rcvd': 56, 'when_epoch': 1618614780,
-'when_epoch_utc': None}]
+'93.184.216.34'}]
 ```
 
 > For `jc` Python package documentation, use `help('jc')`, `help('jc.lib')`, or
@@ -128,7 +119,7 @@ pip3 install jc
 
 > For more OS Packages, see https://repology.org/project/jc/versions.
 
-### Binaries and Packages
+### Binaries
 For precompiled binaries, see [Releases](https://github.com/kellyjonbrazil/jc/releases)
 on Github.
 
@@ -199,6 +190,7 @@ option.
 - `--lsusb` enables the `lsusb` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/lsusb))
 - `--mount` enables the `mount` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/mount))
 - `--netstat` enables the `netstat` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/netstat))
+- `--nmcli` enables the `nmcli` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/nmcli))
 - `--ntpq` enables the `ntpq -p` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ntpq))
 - `--passwd` enables the `/etc/passwd` file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/passwd))
 - `--ping` enables the `ping` and `ping6` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ping))
@@ -208,6 +200,8 @@ option.
 - `--ps` enables the `ps` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ps))
 - `--route` enables the `route` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/route))
 - `--rpm-qi` enables the `rpm -qi` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/rpm_qi))
+- `--rsync` enables the `rsync` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/rsync))
+- `--rsync-s` enables the `rsync` command streaming parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/rsync_s))
 - `--sfdisk` enables the `sfdisk` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/sfdisk))
 - `--shadow` enables the `/etc/shadow` file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/shadow))
 - `--ss` enables the `ss` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ss))
@@ -234,6 +228,7 @@ option.
 - `--wc` enables the `wc` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/wc))
 - `--who` enables the `who` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/who))
 - `--xml` enables the XML file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/xml))
+- `--xrandr` enables the `xrandr` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/xrandr))
 - `--yaml` enables the YAML file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/yaml))
 - `--zipinfo` enables the `zipinfo` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/zipinfo))
 

docgen.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Generate docs.md
-# requires pydoc-markdown 4.5.0
+# requires pydoc-markdown 4.6.1
 readme_config=$(cat <<'EOF'
 {
     "processors": [
@@ -18,7 +18,7 @@ readme_config=$(cat <<'EOF'
             "Class": 3,
             "Method": 3,
             "Function": 3,
-            "Data": 3
+            "Variable": 3
         }
     }
 }
@@ -43,7 +43,7 @@ toc_config=$(cat <<'EOF'
             "Class": 3,
             "Method": 3,
             "Function": 3,
-            "Data": 3
+            "Variable": 3
         }
     }
 }
@@ -68,7 +68,7 @@ parser_config=$(cat <<'EOF'
             "Class": 3,
             "Method": 3,
             "Function": 3,
-            "Data": 3
+            "Variable": 3
         }
     }
 }
@@ -85,6 +85,9 @@ pydoc-markdown -m jc.lib "${toc_config}" > ../docs/lib.md
 echo Building docs for: utils
 pydoc-markdown -m jc.utils "${toc_config}" > ../docs/utils.md
 
+echo Building docs for: streaming
+pydoc-markdown -m jc.streaming "${toc_config}" > ../docs/streaming.md
+
 echo Building docs for: universal parser
 pydoc-markdown -m jc.parsers.universal "${toc_config}" > ../docs/parsers/universal.md
 

docs/lib.md

@@ -4,6 +4,8 @@
   * [parse](#jc.lib.parse)
   * [parser\_mod\_list](#jc.lib.parser_mod_list)
   * [plugin\_parser\_mod\_list](#jc.lib.plugin_parser_mod_list)
+  * [standard\_parser\_mod\_list](#jc.lib.standard_parser_mod_list)
+  * [streaming\_parser\_mod\_list](#jc.lib.streaming_parser_mod_list)
   * [parser\_info](#jc.lib.parser_info)
   * [all\_parser\_info](#jc.lib.all_parser_info)
   * [get\_help](#jc.lib.get_help)
@@ -12,7 +14,7 @@
 
 # jc.lib
 
-jc - JSON CLI output utility
+jc - JSON Convert
 JC lib module
 
 <a id="jc.lib.parse"></a>
@@ -20,7 +22,12 @@ JC lib module
 ### parse
 
 ```python
-def parse(parser_mod_name: str, data: Union[str, Iterable[str]], quiet: bool = False, raw: bool = False, ignore_exceptions: bool = None, **kwargs) -> Union[Dict, List[Dict], Iterator[Dict]]
+def parse(parser_mod_name: str,
+          data: Union[str, Iterable[str]],
+          quiet: bool = False,
+          raw: bool = False,
+          ignore_exceptions: bool = None,
+          **kwargs) -> Union[Dict, List[Dict], Iterator[Dict]]
 ```
 
 Parse the string data using the supplied parser module.
@@ -34,9 +41,7 @@ Example:
     >>> jc.parse('date', 'Tue Jan 18 10:23:07 PST 2022')
     {'year': 2022, 'month': 'Jan', 'month_num': 1, 'day'...}
 
-To get a list of available parser module names, use `parser_mod_list()`
-or `plugin_parser_mod_list()`. `plugin_parser_mod_list()` is a subset
-of `parser_mod_list()`.
+To get a list of available parser module names, use `parser_mod_list()`.
 
 You can also use the lower-level parser modules directly:
 
@@ -100,12 +105,35 @@ def plugin_parser_mod_list() -> List[str]
 Returns a list of plugin parser module names. This function is a
 subset of `parser_mod_list()`.
 
+<a id="jc.lib.standard_parser_mod_list"></a>
+
+### standard\_parser\_mod\_list
+
+```python
+def standard_parser_mod_list() -> List[str]
+```
+
+Returns a list of standard parser module names. This function is a
+subset of `parser_mod_list()` and does not contain any streaming
+parsers.
+
+<a id="jc.lib.streaming_parser_mod_list"></a>
+
+### streaming\_parser\_mod\_list
+
+```python
+def streaming_parser_mod_list() -> List[str]
+```
+
+Returns a list of streaming parser module names. This function is a
+subset of `parser_mod_list()`.
+
 <a id="jc.lib.parser_info"></a>
 
 ### parser\_info
 
 ```python
-def parser_info(parser_mod_name: str) -> Union[Dict, None]
+def parser_info(parser_mod_name: str) -> Dict
 ```
 
 Returns a dictionary that includes the module metadata.
@@ -118,10 +146,10 @@ This function will accept **module_name**, **cli-name**, and
 ### all\_parser\_info
 
 ```python
-def all_parser_info() -> List[Optional[Dict]]
+def all_parser_info() -> List[Dict]
 ```
 
-Returns a list of dictionaris that includes metadata for all modules.
+Returns a list of dictionaries that includes metadata for all modules.
 
 <a id="jc.lib.get_help"></a>
 

docs/parsers/acpi.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.acpi
 
-jc - JSON CLI output utility `acpi` command output parser
+jc - JSON Convert `acpi` command output parser
 
 Usage (cli):
 

docs/parsers/airport.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.airport
 
-jc - JSON CLI output utility `airport -I` command output parser
+jc - JSON Convert `airport -I` command output parser
 
 The `airport` program can be found at `/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport`.
 

docs/parsers/airport_s.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.airport\_s
 
-jc - JSON CLI output utility `airport -s` command output parser
+jc - JSON Convert `airport -s` command output parser
 
 The `airport` program can be found at `/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport`.
 

docs/parsers/arp.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.arp
 
-jc - JSON CLI output utility `arp` command output parser
+jc - JSON Convert `arp` command output parser
 
 Supports `arp` and `arp -a` output.
 

docs/parsers/blkid.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.blkid
 
-jc - JSON CLI output utility `blkid` command output parser
+jc - JSON Convert `blkid` command output parser
 
 Usage (cli):
 

docs/parsers/cksum.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.cksum
 
-jc - JSON CLI output utility `cksum` command output parser
+jc - JSON Convert `cksum` command output parser
 
 This parser works with the following checksum calculation utilities:
 - `sum`

docs/parsers/crontab.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.crontab
 
-jc - JSON CLI output utility `crontab -l` command output and crontab
+jc - JSON Convert `crontab -l` command output and crontab
 file parser
 
 Supports `crontab -l` command output and crontab files.

docs/parsers/crontab_u.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.crontab\_u
 
-jc - JSON CLI output utility `crontab -l` command output and crontab
+jc - JSON Convert `crontab -l` command output and crontab
 file parser
 
 This version of the `crontab -l` parser supports output that contains user

docs/parsers/csv.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.csv
 
-jc - JSON CLI output utility `csv` file parser
+jc - JSON Convert `csv` file parser
 
 The `csv` parser will attempt to automatically detect the delimiter
 character. If the delimiter cannot be detected it will default to comma.

docs/parsers/csv_s.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.csv\_s
 
-jc - JSON CLI output utility `csv` file streaming parser
+jc - JSON Convert `csv` file streaming parser
 
 > This streaming parser outputs JSON Lines
 
@@ -73,6 +73,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -93,9 +94,9 @@ Yields:
 
 Returns:
 
-    Iterator object
+    Iterator object (generator)
 
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
 
-Version 1.2 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/date.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.date
 
-jc - JSON CLI output utility `date` command output parser
+jc - JSON Convert `date` command output parser
 
 The `epoch` calculated timestamp field is naive. (i.e. based on the local
 time of the system the parser is run on)
@@ -105,4 +105,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 2.2 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 2.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/df.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.df
 
-jc - JSON CLI output utility `df` command output parser
+jc - JSON Convert `df` command output parser
 
 Usage (cli):
 

docs/parsers/dig.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.dig
 
-jc - JSON CLI output utility `dig` command output parser
+jc - JSON Convert `dig` command output parser
 
 Options supported:
 - `+noall +answer` options are supported in cases where only the answer
@@ -350,4 +350,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, aix, freebsd, darwin, win32, cygwin
 
-Version 2.2 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 2.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/dir.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.dir
 
-jc - JSON CLI output utility `dir` command output parser
+jc - JSON Convert `dir` command output parser
 
 Options supported:
 - `/T timefield`
@@ -148,4 +148,4 @@ Returns:
 ### Parser Information
 Compatibility:  win32
 
-Version 1.4 by Rasheed Elsaleh (rasheed@rebelliondefense.com)
+Version 1.5 by Rasheed Elsaleh (rasheed@rebelliondefense.com)

docs/parsers/dmidecode.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.dmidecode
 
-jc - JSON CLI output utility `dmidecode` command output parser
+jc - JSON Convert `dmidecode` command output parser
 
 Usage (cli):
 

docs/parsers/dpkg_l.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.dpkg\_l
 
-jc - JSON CLI output utility `dpkg -l` command output parser
+jc - JSON Convert `dpkg -l` command output parser
 
 Set the `COLUMNS` environment variable to a large value to avoid field
 truncation. For example:

docs/parsers/du.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.du
 
-jc - JSON CLI output utility `du` command output parser
+jc - JSON Convert `du` command output parser
 
 Usage (cli):
 

docs/parsers/env.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.env
 
-jc - JSON CLI output utility `env` and `printenv` command output parser
+jc - JSON Convert `env` and `printenv` command output parser
 
 This parser will output a list of dictionaries each containing `name` and
 `value` keys. If you would like a simple dictionary output, then use the

docs/parsers/file.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.file
 
-jc - JSON CLI output utility `file` command output parser
+jc - JSON Convert `file` command output parser
 
 Usage (cli):
 

docs/parsers/finger.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.finger
 
-jc - JSON CLI output utility `finger` command output parser
+jc - JSON Convert `finger` command output parser
 
 Supports `-s` output option. Does not support the `-l` detail option.
 

docs/parsers/free.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.free
 
-jc - JSON CLI output utility `free` command output parser
+jc - JSON Convert `free` command output parser
 
 Usage (cli):
 

docs/parsers/fstab.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.fstab
 
-jc - JSON CLI output utility `fstab` file parser
+jc - JSON Convert `fstab` file parser
 
 Usage (cli):
 

docs/parsers/group.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.group
 
-jc - JSON CLI output utility `/etc/group` file parser
+jc - JSON Convert `/etc/group` file parser
 
 Usage (cli):
 

docs/parsers/gshadow.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.gshadow
 
-jc - JSON CLI output utility `/etc/gshadow` file parser
+jc - JSON Convert `/etc/gshadow` file parser
 
 Usage (cli):
 

docs/parsers/hash.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.hash
 
-jc - JSON CLI output utility `hash` command output parser
+jc - JSON Convert `hash` command output parser
 
 Usage (cli):
 

docs/parsers/hashsum.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.hashsum
 
-jc - JSON CLI output utility `hash sum` command output parser
+jc - JSON Convert `hash sum` command output parser
 
 This parser works with the following hash calculation utilities:
 - `md5`

docs/parsers/hciconfig.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.hciconfig
 
-jc - JSON CLI output utility `hciconfig` command output parser
+jc - JSON Convert `hciconfig` command output parser
 
 Usage (cli):
 

docs/parsers/history.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.history
 
-jc - JSON CLI output utility `history` command output parser
+jc - JSON Convert `history` command output parser
 
 This parser will output a list of dictionaries each containing `line` and
 `command` keys. If you would like a simple dictionary output, then use the

docs/parsers/hosts.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.hosts
 
-jc - JSON CLI output utility `/etc/hosts` file parser
+jc - JSON Convert `/etc/hosts` file parser
 
 Usage (cli):
 

docs/parsers/id.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.id
 
-jc - JSON CLI output utility `id` command output parser
+jc - JSON Convert `id` command output parser
 
 Usage (cli):
 

docs/parsers/ifconfig.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ifconfig
 
-jc - JSON CLI output utility `ifconfig` command output parser
+jc - JSON Convert `ifconfig` command output parser
 
 Note: No `ifconfig` options are supported.
 

docs/parsers/ini.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ini
 
-jc - JSON CLI output utility `INI` file parser
+jc - JSON Convert `INI` file parser
 
 Parses standard `INI` files and files containing simple key/value pairs.
 Delimiter can be `=` or `:`. Missing values are supported. Comment prefix

docs/parsers/iostat.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.iostat
 
-jc - JSON CLI output utility `iostat` command output parser
+jc - JSON Convert `iostat` command output parser
 
 Note: `iostat` version 11 and higher include a JSON output option
 

docs/parsers/iostat_s.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.iostat\_s
 
-jc - JSON CLI output utility `iostat` command output streaming parser
+jc - JSON Convert `iostat` command output streaming parser
 
 > This streaming parser outputs JSON Lines
 
@@ -110,6 +110,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -130,9 +131,9 @@ Yields:
 
 Returns:
 
-    Iterator object
+    Iterator object (generator)
 
 ### Parser Information
 Compatibility:  linux
 
-Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/iptables.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.iptables
 
-jc - JSON CLI output utility `iptables` command output parser
+jc - JSON Convert `iptables` command output parser
 
 Supports `-vLn` and `--line-numbers` for all tables.
 

docs/parsers/iw_scan.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.iw\_scan
 
-jc - JSON CLI output utility `iw dev <device> scan` command output parser
+jc - JSON Convert `iw dev <device> scan` command output parser
 
 This parser is considered beta quality. Not all fields are parsed and there
 are not enough samples to test.

docs/parsers/jar_manifest.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.jar\_manifest
 
-jc - JSON CLI output utility `MANIFEST.MF` file parser
+jc - JSON Convert `MANIFEST.MF` file parser
 
 Usage (cli):
 

docs/parsers/jobs.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.jobs
 
-jc - JSON CLI output utility `jobs` command output parser
+jc - JSON Convert `jobs` command output parser
 
 Also supports the `-l` option.
 

docs/parsers/kv.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.kv
 
-jc - JSON CLI output utility `Key/Value` file parser
+jc - JSON Convert `Key/Value` file parser
 
 Supports files containing simple key/value pairs. Delimiter can be `=` or
 `:`. Missing values are supported. Comment prefix can be `#` or `;`.

docs/parsers/last.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.last
 
-jc - JSON CLI output utility `last` and `lastb` command output parser
+jc - JSON Convert `last` and `lastb` command output parser
 
 Supports `-w` and `-F` options.
 

docs/parsers/ls.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ls
 
-jc - JSON CLI output utility `ls` and `vdir` command output parser
+jc - JSON Convert `ls` and `vdir` command output parser
 
 Options supported:
 - `lbaR1`
@@ -144,4 +144,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, aix, freebsd
 
-Version 1.10 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.11 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ls_s.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ls\_s
 
-jc - JSON CLI output utility `ls` and `vdir` command output streaming
+jc - JSON Convert `ls` and `vdir` command output streaming
 parser
 
 > This streaming parser outputs JSON Lines
@@ -87,6 +87,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -107,9 +108,9 @@ Yields:
 
 Returns:
 
-    Iterator object
+    Iterator object (generator)
 
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, aix, freebsd
 
-Version 0.6 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/lsblk.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.lsblk
 
-jc - JSON CLI output utility `lsblk` command output parser
+jc - JSON Convert `lsblk` command output parser
 
 Usage (cli):
 

docs/parsers/lsmod.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.lsmod
 
-jc - JSON CLI output utility `lsmod` command output parser
+jc - JSON Convert `lsmod` command output parser
 
 Usage (cli):
 

docs/parsers/lsof.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.lsof
 
-jc - JSON CLI output utility `lsof` command output parser
+jc - JSON Convert `lsof` command output parser
 
 Usage (cli):
 

docs/parsers/lsusb.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.lsusb
 
-jc - JSON CLI output utility `lsusb` command output parser
+jc - JSON Convert `lsusb` command output parser
 
 Supports the `-v` option or no options.
 

docs/parsers/mount.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.mount
 
-jc - JSON CLI output utility `mount` command output parser
+jc - JSON Convert `mount` command output parser
 
 Usage (cli):
 

docs/parsers/netstat.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.netstat
 
-jc - JSON CLI output utility `netstat` command output parser
+jc - JSON Convert `netstat` command output parser
 
 Caveats:
 - Use of multiple `l` options is not supported on OSX (e.g. `netstat -rlll`)

docs/parsers/nmcli.md

@@ -0,0 +1,176 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.nmcli"></a>
+
+# jc.parsers.nmcli
+
+jc - JSON Convert `nmcli` command output parser
+
+Supports the following `nmcli` subcommands:
+- `nmcli general`
+- `nmcli general permissions`
+- `nmcli connection`
+- `nmcli connection show <device_name>`
+- `nmcli device`
+- `nmcli device show`
+- `nmcli device show <device_name>`
+
+Usage (cli):
+
+    $ nmcli device show lo | jc --nmcli
+
+    or
+
+    $ jc nmcli device show lo
+
+Usage (module):
+
+    import jc
+    result = jc.parse('nmcli', nmcli_command_output)
+
+    or
+
+    import jc.parsers.nmcli
+    result = jc.parsers.nmcli.parse(nmcli_command_output)
+
+Schema:
+
+    Because there are so many options, the schema is not strictly defined.
+    Integer and Float value conversions are attempted and the original
+    values are kept if they fail. If you don't want automatic conversion,
+    then use the -r or raw=True option to disable it.
+
+    The structure is flat, for the most part, but there are a couple of
+    "well-known" keys that are further parsed into objects for convenience.
+    These are documented below.
+
+    [
+      {
+        "<key>":                  string/integer/float,  [0]
+        "dhcp4_option_x": {
+          "name":                 string,
+          "value":                string/integer/float,
+        },
+        "dhcp6_option_x": {
+          "name":                 string,
+          "value":                string/integer/float,
+        },
+        "ip4_route_x": {
+          "dst":                  string,
+          "nh":                   string,
+          "mt":                   integer
+        },
+        "ip6_route_x": {
+          "dst":                  string,
+          "nh":                   string,
+          "mt":                   integer,
+          "table":                integer
+        }
+      }
+    ]
+
+    [0] all values of `---` are converted to null
+
+Examples:
+
+    $ nmcli connection show ens33 | jc --nmcli -p
+    [
+      {
+        "connection_id": "ens33",
+        "connection_uuid": "d92ece08-9e02-47d5-b2d2-92c80e155744",
+        "connection_stable_id": null,
+        "connection_type": "802-3-ethernet",
+        "connection_interface_name": "ens33",
+        "connection_autoconnect": "yes",
+        ...
+        "ip4_address_1": "192.168.71.180/24",
+        "ip4_gateway": "192.168.71.2",
+        "ip4_route_1": {
+          "dst": "0.0.0.0/0",
+          "nh": "192.168.71.2",
+          "mt": 100
+        },
+        "ip4_route_2": {
+          "dst": "192.168.71.0/24",
+          "nh": "0.0.0.0",
+          "mt": 100
+        },
+        "ip4_dns_1": "192.168.71.2",
+        "ip4_domain_1": "localdomain",
+        "dhcp4_option_1": {
+          "name": "broadcast_address",
+          "value": "192.168.71.255"
+        },
+        ...
+        "ip6_address_1": "fe80::c1cb:715d:bc3e:b8a0/64",
+        "ip6_gateway": null,
+        "ip6_route_1": {
+          "dst": "fe80::/64",
+          "nh": "::",
+          "mt": 100
+        }
+      }
+    ]
+
+    $ nmcli connection show ens33 | jc --nmcli -p -r
+    [
+      {
+        "connection_id": "ens33",
+        "connection_uuid": "d92ece08-9e02-47d5-b2d2-92c80e155744",
+        "connection_stable_id": null,
+        "connection_type": "802-3-ethernet",
+        "connection_interface_name": "ens33",
+        "connection_autoconnect": "yes",
+        ...
+        "ip4_address_1": "192.168.71.180/24",
+        "ip4_gateway": "192.168.71.2",
+        "ip4_route_1": {
+          "dst": "0.0.0.0/0",
+          "nh": "192.168.71.2",
+          "mt": "100"
+        },
+        "ip4_route_2": {
+          "dst": "192.168.71.0/24",
+          "nh": "0.0.0.0",
+          "mt": "100"
+        },
+        "ip4_dns_1": "192.168.71.2",
+        "ip4_domain_1": "localdomain",
+        "dhcp4_option_1": {
+          "name": "broadcast_address",
+          "value": "192.168.71.255"
+        },
+        ...
+        "ip6_address_1": "fe80::c1cb:715d:bc3e:b8a0/64",
+        "ip6_gateway": null,
+        "ip6_route_1": {
+          "dst": "fe80::/64",
+          "nh": "::",
+          "mt": "100"
+        }
+      }
+    ]
+
+<a id="jc.parsers.nmcli.parse"></a>
+
+### parse
+
+```python
+def parse(data: str, raw: bool = False, quiet: bool = False) -> List[Dict]
+```
+
+Main text parsing function
+
+Parameters:
+
+    data:        (string)  text data to parse
+    raw:         (boolean) unprocessed output if True
+    quiet:       (boolean) suppress warning messages if True
+
+Returns:
+
+    List of Dictionaries. Raw or processed structured data.
+
+### Parser Information
+Compatibility:  linux
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ntpq.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ntpq
 
-jc - JSON CLI output utility `ntpq -p` command output parser
+jc - JSON Convert `ntpq -p` command output parser
 
 Usage (cli):
 

docs/parsers/passwd.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.passwd
 
-jc - JSON CLI output utility `/etc/passwd` file Parser
+jc - JSON Convert `/etc/passwd` file Parser
 
 Usage (cli):
 

docs/parsers/ping.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ping
 
-jc - JSON CLI output utility `ping` command output parser
+jc - JSON Convert `ping` command output parser
 
 Supports `ping` and `ping6` output.
 

docs/parsers/ping_s.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ping\_s
 
-jc - JSON CLI output utility `ping` command output streaming parser
+jc - JSON Convert `ping` command output streaming parser
 
 > This streaming parser outputs JSON Lines
 
@@ -93,6 +93,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -113,9 +114,9 @@ Yields:
 
 Returns:
 
-    Iterator object
+    Iterator object (generator)
 
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 0.6 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/pip_list.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.pip\_list
 
-jc - JSON CLI output utility `pip-list` command output parser
+jc - JSON Convert `pip-list` command output parser
 
 Usage (cli):
 

docs/parsers/pip_show.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.pip\_show
 
-jc - JSON CLI output utility `pip-show` command output parser
+jc - JSON Convert `pip-show` command output parser
 
 Usage (cli):
 

docs/parsers/ps.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ps
 
-jc - JSON CLI output utility `ps` command output parser
+jc - JSON Convert `ps` command output parser
 
 `ps` options supported:
 - `ef`

docs/parsers/route.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.route
 
-jc - JSON CLI output utility `route` command output parser
+jc - JSON Convert `route` command output parser
 
 Usage (cli):
 

docs/parsers/rpm_qi.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.rpm\_qi
 
-jc - JSON CLI output utility `rpm -qi` command output parser
+jc - JSON Convert `rpm -qi` command output parser
 
 Works with `rpm -qi [package]` or `rpm -qia`.
 
@@ -189,4 +189,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux
 
-Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/rsync.md

@@ -0,0 +1,165 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.rsync"></a>
+
+# jc.parsers.rsync
+
+jc - JSON Convert `rsync` command output parser
+
+Supports the `-i` or `--itemize-changes` options with all levels of
+verbosity. This parser will process the STDOUT output or a log file
+generated with the `--log-file` option.
+
+Usage (cli):
+
+    $ rsync -i -a source/ dest | jc --rsync
+
+    or
+
+    $ jc rsync -i -a source/ dest
+
+    or
+
+    $ cat rsync-backup.log | jc --rsync
+
+Usage (module):
+
+    import jc
+    result = jc.parse('rsync', rsync_command_output)
+
+    or
+
+    import jc.parsers.rsync
+    result = jc.parsers.rsync.parse(rsync_command_output)
+
+Schema:
+
+    [
+      {
+        "summary": {
+          "date":                             string,
+          "time":                             string,
+          "process":                          integer,
+          "sent":                             integer,
+          "received":                         integer,
+          "total_size":                       integer,
+          "matches":                          integer,
+          "hash_hits":                        integer,
+          "false_alarms":                     integer,
+          "data":                             integer,
+          "bytes_sec":                        float,
+          "speedup":                          float
+        },
+        "files": [
+          {
+            "filename":                       string,
+            "date":                           string,
+            "time":                           string,
+            "process":                        integer,
+            "metadata":                       string,
+            "update_type":                    string/null,  [0]
+            "file_type":                      string/null,  [1]
+            "checksum_or_value_different":    bool/null,
+            "size_different":                 bool/null,
+            "modification_time_different":    bool/null,
+            "permissions_different":          bool/null,
+            "owner_different":                bool/null,
+            "group_different":                bool/null,
+            "acl_different":                  bool/null,
+            "extended_attribute_different":   bool/null,
+            "epoch":                          integer,      [2]
+          }
+        ]
+      }
+    ]
+
+    [0] 'file sent', 'file received', 'local change or creation',
+        'hard link', 'not updated', 'message'
+    [1] 'file', 'directory', 'symlink', 'device', 'special file'
+    [2] naive timestamp if time and date fields exist and can be converted.
+
+Examples:
+
+    $ rsync -i -a source/ dest | jc --rsync -p
+    [
+      {
+        "summary": {
+          "sent": 1708,
+          "received": 8209,
+          "bytes_sec": 19834.0,
+          "total_size": 235,
+          "speedup": 0.02
+        },
+        "files": [
+          {
+            "filename": "./",
+            "metadata": ".d..t......",
+            "update_type": "not updated",
+            "file_type": "directory",
+            "checksum_or_value_different": false,
+            "size_different": false,
+            "modification_time_different": true,
+            "permissions_different": false,
+            "owner_different": false,
+            "group_different": false,
+            "acl_different": false,
+            "extended_attribute_different": false
+          },
+          ...
+        ]
+      }
+    ]
+
+    $ rsync | jc --rsync -p -r
+    [
+      {
+        "summary": {
+          "sent": "1,708",
+          "received": "8,209",
+          "bytes_sec": "19,834.00",
+          "total_size": "235",
+          "speedup": "0.02"
+        },
+        "files": [
+          {
+            "filename": "./",
+            "metadata": ".d..t......",
+            "update_type": "not updated",
+            "file_type": "directory",
+            "checksum_or_value_different": false,
+            "size_different": false,
+            "modification_time_different": true,
+            "permissions_different": false,
+            "owner_different": false,
+            "group_different": false,
+            "acl_different": false,
+            "extended_attribute_different": false
+          },
+          ...
+        ]
+      }
+    ]
+
+<a id="jc.parsers.rsync.parse"></a>
+
+### parse
+
+```python
+def parse(data: str, raw: bool = False, quiet: bool = False) -> List[Dict]
+```
+
+Main text parsing function
+
+Parameters:
+
+    data:        (string)  text data to parse
+    raw:         (boolean) unprocessed output if True
+    quiet:       (boolean) suppress warning messages if True
+
+Returns:
+
+    List of Dictionaries. Raw or processed structured data.
+
+### Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/rsync_s.md

@@ -0,0 +1,130 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.rsync_s"></a>
+
+# jc.parsers.rsync\_s
+
+jc - JSON Convert `rsync` command output streaming parser
+
+> This streaming parser outputs JSON Lines
+
+Supports the `-i` or `--itemize-changes` options with all levels of
+verbosity. This parser will process the STDOUT output or a log file
+generated with the `--log-file` option.
+
+Usage (cli):
+
+    $ rsync -i -a source/ dest | jc --rsync-s
+
+    or
+
+    $ cat rsync-backup.log | jc --rsync-s
+
+Usage (module):
+
+    import jc
+    # result is an iterable object (generator)
+    result = jc.parse('rsync_s', rsync_command_output.splitlines())
+    for item in result:
+        # do something
+
+    or
+
+    import jc.parsers.rsync_s
+    # result is an iterable object (generator)
+    result = jc.parsers.rsync_s.parse(rsync_command_output.splitlines())
+    for item in result:
+        # do something
+
+Schema:
+
+    {
+      "type":                           string,       # 'file' or 'summary'
+      "date":                           string,
+      "time":                           string,
+      "process":                        integer,
+      "sent":                           integer,
+      "received":                       integer,
+      "total_size":                     integer,
+      "matches":                        integer,
+      "hash_hits":                      integer,
+      "false_alarms":                   integer,
+      "data":                           integer,
+      "bytes_sec":                      float,
+      "speedup":                        float,
+      "filename":                       string,
+      "date":                           string,
+      "time":                           string,
+      "process":                        integer,
+      "metadata":                       string,
+      "update_type":                    string/null,  [0]
+      "file_type":                      string/null,  [1]
+      "checksum_or_value_different":    bool/null,
+      "size_different":                 bool/null,
+      "modification_time_different":    bool/null,
+      "permissions_different":          bool/null,
+      "owner_different":                bool/null,
+      "group_different":                bool/null,
+      "acl_different":                  bool/null,
+      "extended_attribute_different":   bool/null,
+      "epoch":                          integer,      [2]
+
+      # Below object only exists if using -qq or ignore_exceptions=True
+
+      "_jc_meta":
+        {
+          "success":    boolean,     # false if error parsing
+          "error":      string,      # exists if "success" is false
+          "line":       string       # exists if "success" is false
+        }
+    }
+
+    [0] 'file sent', 'file received', 'local change or creation',
+        'hard link', 'not updated', 'message'
+    [1] 'file', 'directory', 'symlink', 'device', 'special file'
+    [2] naive timestamp if time and date fields exist and can be converted.
+
+Examples:
+
+    $ rsync -i -a source/ dest | jc --rsync-s
+    {"type":"file","filename":"./","metadata":".d..t......","update_...}
+    ...
+
+    $ cat rsync_backup.log | jc --rsync-s
+    {"type":"file","filename":"./","date":"2022/01/28","time":"03:53...}
+    ...
+
+<a id="jc.parsers.rsync_s.parse"></a>
+
+### parse
+
+```python
+@add_jc_meta
+def parse(data: Iterable[str],
+          raw: bool = False,
+          quiet: bool = False,
+          ignore_exceptions: bool = False) -> Union[Iterable[Dict], tuple]
+```
+
+Main text parsing generator function. Returns an iterator object.
+
+Parameters:
+
+    data:              (iterable)  line-based text data to parse
+                                   (e.g. sys.stdin or str.splitlines())
+
+    raw:               (boolean)   unprocessed output if True
+    quiet:             (boolean)   suppress warning messages if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+
+Yields:
+
+    Dictionary. Raw or processed structured data.
+
+Returns:
+
+    Iterator object (generator)
+
+### Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/sfdisk.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.sfdisk
 
-jc - JSON CLI output utility `sfdisk` command output parser
+jc - JSON Convert `sfdisk` command output parser
 
 Supports the following `sfdisk` options:
 - `-l`

docs/parsers/shadow.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.shadow
 
-jc - JSON CLI output utility `/etc/shadow` file parser
+jc - JSON Convert `/etc/shadow` file parser
 
 Usage (cli):
 

docs/parsers/ss.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ss
 
-jc - JSON CLI output utility `ss` command output parser
+jc - JSON Convert `ss` command output parser
 
 Extended information options like -e and -p are not supported and may cause
 parsing irregularities.

docs/parsers/stat.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.stat
 
-jc - JSON CLI output utility `stat` command output parser
+jc - JSON Convert `stat` command output parser
 
 The `xxx_epoch` calculated timestamp fields are naive. (i.e. based on the
 local time of the system the parser is run on)
@@ -198,4 +198,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 1.10 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.11 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/stat_s.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.stat\_s
 
-jc - JSON CLI output utility `stat` command output streaming parser
+jc - JSON Convert `stat` command output streaming parser
 
 > This streaming parser outputs JSON Lines
 
@@ -91,6 +91,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -111,9 +112,9 @@ Yields:
 
 Returns:
 
-    Iterator object
+    Iterator object (generator)
 
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 0.5 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/sysctl.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.sysctl
 
-jc - JSON CLI output utility `sysctl -a` command output parser
+jc - JSON Convert `sysctl -a` command output parser
 
 Note: Since `sysctl` output is not easily parsable only a very simple
       key/value object will be output. An attempt is made to convert obvious

docs/parsers/systemctl.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.systemctl
 
-jc - JSON CLI output utility `systemctl` command output parser
+jc - JSON Convert `systemctl` command output parser
 
 Usage (cli):
 

docs/parsers/systemctl_lj.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.systemctl\_lj
 
-jc - JSON CLI output utility `systemctl list-jobs` command output parser
+jc - JSON Convert `systemctl list-jobs` command output parser
 
 Usage (cli):
 

docs/parsers/systemctl_ls.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.systemctl\_ls
 
-jc - JSON CLI output utility `systemctl list-sockets` command output
+jc - JSON Convert `systemctl list-sockets` command output
 parser
 
 Usage (cli):

docs/parsers/systemctl_luf.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.systemctl\_luf
 
-jc - JSON CLI output utility `systemctl list-unit-files` command output
+jc - JSON Convert `systemctl list-unit-files` command output
 parser
 
 Usage (cli):

docs/parsers/systeminfo.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.systeminfo
 
-jc - JSON CLI output utility `systeminfo` command output parser
+jc - JSON Convert `systeminfo` command output parser
 
 Blank or missing elements are set to `null`.
 
@@ -239,4 +239,4 @@ Returns:
 ### Parser Information
 Compatibility:  win32
 
-Version 1.1 by Jon Smith (jon@rebelliondefense.com)
+Version 1.2 by Jon Smith (jon@rebelliondefense.com)

docs/parsers/time.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.time
 
-jc - JSON CLI output utility `/usr/bin/time` command output parser
+jc - JSON Convert `/usr/bin/time` command output parser
 
 Output from `/usr/bin/time` is sent to `STDERR`, so the `-o` option can be
 used to redirect the output to a file that can be read by `jc`.

docs/parsers/timedatectl.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.timedatectl
 
-jc - JSON CLI output utility `timedatectl` command output parser
+jc - JSON Convert `timedatectl` command output parser
 
 The `epoch_utc` calculated timestamp field is timezone-aware and is only
 available if the `universal_time` field is available.
@@ -92,4 +92,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux
 
-Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/tracepath.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.tracepath
 
-jc - JSON CLI output utility `tracepath` command output parser
+jc - JSON Convert `tracepath` command output parser
 
 Supports `tracepath` and `tracepath6` output.
 

docs/parsers/traceroute.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.traceroute
 
-jc - JSON CLI output utility `traceroute` command output parser
+jc - JSON Convert `traceroute` command output parser
 
 Supports `traceroute` and `traceroute6` output.
 

docs/parsers/ufw.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ufw
 
-jc - JSON CLI output utility `ufw status` command output parser
+jc - JSON Convert `ufw status` command output parser
 
 Usage (cli):
 

docs/parsers/ufw_appinfo.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.ufw\_appinfo
 
-jc - JSON CLI output utility `ufw app info [application]` command
+jc - JSON Convert `ufw app info [application]` command
 output parser
 
 Supports individual apps via `ufw app info [application]` and all apps list

docs/parsers/uname.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.uname
 
-jc - JSON CLI output utility `uname -a` command output parser
+jc - JSON Convert `uname -a` command output parser
 
 Note: Must use `uname -a`
 

docs/parsers/universal.md

@@ -8,7 +8,7 @@
 
 # jc.parsers.universal
 
-jc - JSON CLI output utility universal Parsers
+jc - JSON Convert universal parsers
 
 <a id="jc.parsers.universal.simple_table_parse"></a>
 
@@ -40,7 +40,7 @@ Returns:
 ### sparse\_table\_parse
 
 ```python
-def sparse_table_parse(data: List[str], delim: Optional[str] = '\u2063') -> List[Dict]
+def sparse_table_parse(data: List[str], delim: str = '\u2063') -> List[Dict]
 ```
 
 Parse tables with missing column data or with spaces in column data.

docs/parsers/upower.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.upower
 
-jc - JSON CLI output utility `upower` command output parser
+jc - JSON Convert `upower` command output parser
 
 The `updated_epoch` calculated timestamp field is naive. (i.e. based on the
 local time of the system the parser is run on)
@@ -226,4 +226,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux
 
-Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/uptime.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.uptime
 
-jc - JSON CLI output utility `uptime` command output parser
+jc - JSON Convert `uptime` command output parser
 
 Usage (cli):
 

docs/parsers/vmstat.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.vmstat
 
-jc - JSON CLI output utility `vmstat` command output parser
+jc - JSON Convert `vmstat` command output parser
 
 Options supported: `-a`, `-w`, `-d`, `-t`
 
@@ -154,4 +154,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux
 
-Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/vmstat_s.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.vmstat\_s
 
-jc - JSON CLI output utility `vmstat` command output streaming parser
+jc - JSON Convert `vmstat` command output streaming parser
 
 > This streaming parser outputs JSON Lines
 
@@ -110,6 +110,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -130,9 +131,9 @@ Yields:
 
 Returns:
 
-    Iterator object
+    Iterator object (generator)
 
 ### Parser Information
 Compatibility:  linux
 
-Version 0.6 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/w.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.w
 
-jc - JSON CLI output utility `w` command output parser
+jc - JSON Convert `w` command output parser
 
 Usage (cli):
 

docs/parsers/wc.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.wc
 
-jc - JSON CLI output utility `wc` command output parser
+jc - JSON Convert `wc` command output parser
 
 Usage (cli):
 

docs/parsers/who.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.who
 
-jc - JSON CLI output utility `who` command output parser
+jc - JSON Convert `who` command output parser
 
 Accepts any of the following who options (or no options): `-aTH`
 
@@ -163,4 +163,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, aix, freebsd
 
-Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/xml.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.xml
 
-jc - JSON CLI output utility `XML` file parser
+jc - JSON Convert `XML` file parser
 
 Usage (cli):
 

docs/parsers/xrandr.md

@@ -0,0 +1,168 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.xrandr"></a>
+
+# jc.parsers.xrandr
+
+jc - JSON Convert `xrandr` command output parser
+
+Usage (cli):
+
+    $ xrandr | jc --xrandr
+
+    or
+
+    $ jc xrandr
+
+Usage (module):
+
+    import jc
+    result = jc.parse('xrandr', xrandr_command_output)
+
+    or
+
+    import jc.parsers.xrandr
+    result = jc.parsers.xrandr.parse(xrandr_command_output)
+
+Schema:
+
+    {
+      "screens": [
+        {
+          "screen_number":                     integer,
+          "minimum_width":                     integer,
+          "minimum_height":                    integer,
+          "current_width":                     integer,
+          "current_height":                    integer,
+          "maximum_width":                     integer,
+          "maximum_height":                    integer,
+          "associated_device": {
+            "associated_modes": [
+              {
+                "resolution_width":            integer,
+                "resolution_height":           integer,
+                "is_high_resolution":          boolean,
+                "frequencies": [
+                  {
+                    "frequency":               float,
+                    "is_current":              boolean,
+                    "is_preferred":            boolean
+                  }
+                ]
+              }
+            ]
+          },
+          "is_connected":                      boolean,
+          "is_primary":                        boolean,
+          "device_name":                       string,
+          "resolution_width":                  integer,
+          "resolution_height":                 integer,
+          "offset_width":                      integer,
+          "offset_height":                     integer,
+          "dimension_width":                   integer,
+          "dimension_height":                  integer
+        }
+      ],
+      "unassociated_devices": [
+        {
+          "associated_modes": [
+            {
+              "resolution_width":              integer,
+              "resolution_height":             integer,
+              "is_high_resolution":            boolean,
+              "frequencies": [
+                {
+                  "frequency":                 float,
+                  "is_current":                boolean,
+                  "is_preferred":              boolean
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+
+Examples:
+
+    $ xrandr | jc --xrandr -p
+    {
+      "screens": [
+        {
+          "screen_number": 0,
+          "minimum_width": 8,
+          "minimum_height": 8,
+          "current_width": 1920,
+          "current_height": 1080,
+          "maximum_width": 32767,
+          "maximum_height": 32767,
+          "associated_device": {
+            "associated_modes": [
+              {
+                "resolution_width": 1920,
+                "resolution_height": 1080,
+                "is_high_resolution": false,
+                "frequencies": [
+                  {
+                    "frequency": 60.03,
+                    "is_current": true,
+                    "is_preferred": true
+                  },
+                  {
+                    "frequency": 59.93,
+                    "is_current": false,
+                    "is_preferred": false
+                  }
+                ]
+              },
+              {
+                "resolution_width": 1680,
+                "resolution_height": 1050,
+                "is_high_resolution": false,
+                "frequencies": [
+                  {
+                    "frequency": 59.88,
+                    "is_current": false,
+                    "is_preferred": false
+                  }
+                ]
+              }
+            ],
+            "is_connected": true,
+            "is_primary": true,
+            "device_name": "eDP1",
+            "resolution_width": 1920,
+            "resolution_height": 1080,
+            "offset_width": 0,
+            "offset_height": 0,
+            "dimension_width": 310,
+            "dimension_height": 170
+          }
+        }
+      ],
+      "unassociated_devices": []
+    }
+
+<a id="jc.parsers.xrandr.parse"></a>
+
+### parse
+
+```python
+def parse(data: str, raw: bool = False, quiet: bool = False) -> Dict
+```
+
+Main text parsing function
+
+Parameters:
+
+    data:        (string)  text data to parse
+    raw:         (boolean) unprocessed output if True
+    quiet:       (boolean) suppress warning messages if True
+
+Returns:
+
+    Dictionary. Raw or processed structured data.
+
+### Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.0 by Kevin Lyter (lyter_git at sent.com)

docs/parsers/yaml.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.yaml
 
-jc - JSON CLI output utility `YAML` file parser
+jc - JSON Convert `YAML` file parser
 
 Usage (cli):
 

docs/parsers/zipinfo.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.zipinfo
 
-jc - JSON CLI output utility `zipinfo` command output parser
+jc - JSON Convert `zipinfo` command output parser
 
 Options supported:
 - none
@@ -44,7 +44,7 @@ Schema:
           {
             "flags":            string,
             "zipversion":       string,
-            "zipunder":         string
+            "zipunder":         string,
             "filesize":         integer,
             "type":             string,
             "method":           string,
@@ -107,4 +107,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin
 
-Version 0.01 by Matt J (https://github.com/listuser)
+Version 1.0 by Matt J (https://github.com/listuser)

docs/readme.md

@@ -2,7 +2,7 @@
 
 # jc
 
-JC - JSON CLI output utility
+JC - JSON Convert
 
 * kellyjonbrazil@gmail.com
 
@@ -14,6 +14,8 @@ and file-types to dictionaries and lists of dictionaries.
     >>> help('jc')
     >>> help('jc.lib')
     >>> help('jc.utils')
+    >>> help('jc.streaming')
+    >>> help('jc.parsers.universal')
     >>> jc.get_help('parser_module_name')
 
 ## Online Documentation
@@ -24,9 +26,9 @@ https://github.com/kellyjonbrazil/jc/tree/master/docs
 
 ### Specific Version
 
-Replace `{{full_version_number}}` - e.g. `1.17.7`:
+Replace `<full_version_number>` - e.g. `1.17.7`:
 
-`https://github.com/kellyjonbrazil/jc/tree/v{{full_version_number}}/docs`
+`https://github.com/kellyjonbrazil/jc/tree/v<full_version_number>/docs`
 
 Specific versions can also be selected by tag in the branch dropdown menu.
 
@@ -55,29 +57,65 @@ modules directly:
 
 ## Available Functions
 
-Use `help(jc.lib)` for details:
+Use `help(jc.lib)` for details.
 
-    parse(parser_module_name: str, data: str | Iterable)
-      -> dict | list[dict] | Iterable[dict]
-        High-level API to easily access the parser. This API will find both
-        built-in parsers and local plugin parsers.
+### parse
+
+    parse(
+        parser_module_name: str,
+        data: str | Iterable
+    ) -> dict | list[dict] | Iterable[dict]
+
+High-level API to easily access the parser. This API will find both
+built-in parsers and local plugin parsers.
+
+### parser_info
 
     parser_info(parser_module_name: str) -> dict
-        Get the metadata for a particular parser.
+
+Get the metadata for a particular parser.
+
+### all_parser_info
 
     all_parser_info() -> list[dict]
-        Get the metadata for all parsers.
+
+Get the metadata for all parsers.
+
+### get_help
 
     get_help(parser_module_name: str) -> None
-        Convenience function to display the help screen for a parser using
-        its module name.
+
+Convenience function to display the help screen for a parser using
+its module name.
+
+### parser_mod_list
 
     parser_mod_list() -> list
-        Get a list of all available parser module names to be used in
-        parse(), parser_info(), and get_help().
+
+Get a list of all available parser module names to be used in
+`parse()`, `parser_info()`, and `get_help()`.
+
+### plugin_parser_mod_list
 
     plugin_parser_mod_list() -> list
-        Get a list of plugin parser module names to be used in
-        parse(), parser_info(), and get_help(). This list is a subset of
-        parser_mod_list().
+
+Get a list of plugin parser module names to be used in
+`parse()`, `parser_info()`, and `get_help()`. This list is a subset of
+`parser_mod_list()`.
+
+### standard_parser_mod_list
+
+    standard_parser_mod_list() -> list
+
+Get a list of standard parser module names to be used in
+`parse()`, `parser_info()`, and `get_help()`. This list is a subset of
+`parser_mod_list()` and does not contain any streaming parsers.
+
+### streaming_parser_mod_list
+
+    streaming_parser_mod_list() -> list
+
+Get a list of streaming parser module names to be used in
+`parse()`, `parser_info()`, and `get_help()`. This list is a subset of
+`parser_mod_list()`.
 

docs/streaming.md

@@ -0,0 +1,115 @@
+# Table of Contents
+
+* [jc.streaming](#jc.streaming)
+  * [streaming\_input\_type\_check](#jc.streaming.streaming_input_type_check)
+  * [streaming\_line\_input\_type\_check](#jc.streaming.streaming_line_input_type_check)
+  * [stream\_success](#jc.streaming.stream_success)
+  * [stream\_error](#jc.streaming.stream_error)
+  * [add\_jc\_meta](#jc.streaming.add_jc_meta)
+  * [raise\_or\_yield](#jc.streaming.raise_or_yield)
+
+<a id="jc.streaming"></a>
+
+# jc.streaming
+
+jc - JSON Convert streaming utils
+
+<a id="jc.streaming.streaming_input_type_check"></a>
+
+### streaming\_input\_type\_check
+
+```python
+def streaming_input_type_check(data: Iterable) -> None
+```
+
+Ensure input data is an iterable, but not a string or bytes. Raises
+`TypeError` if not.
+
+<a id="jc.streaming.streaming_line_input_type_check"></a>
+
+### streaming\_line\_input\_type\_check
+
+```python
+def streaming_line_input_type_check(line: str) -> None
+```
+
+Ensure each line is a string. Raises `TypeError` if not.
+
+<a id="jc.streaming.stream_success"></a>
+
+### stream\_success
+
+```python
+def stream_success(output_line: Dict, ignore_exceptions: bool) -> Dict
+```
+
+Add `_jc_meta` object to output line if `ignore_exceptions=True`
+
+<a id="jc.streaming.stream_error"></a>
+
+### stream\_error
+
+```python
+def stream_error(e: BaseException, line: str) -> Dict
+```
+
+Return an error `_jc_meta` field.
+
+<a id="jc.streaming.add_jc_meta"></a>
+
+### add\_jc\_meta
+
+```python
+def add_jc_meta(func)
+```
+
+Decorator for streaming parsers to add stream_success and stream_error
+objects. This simplifies the yield lines in the streaming parsers.
+
+With the decorator on parse():
+
+    # successfully parsed line:
+    yield output_line if raw else _process(output_line)
+
+    # unsuccessfully parsed line:
+    except Exception as e:
+        yield raise_or_yield(ignore_exceptions, e, line)
+
+Without the decorator on parse():
+
+    # successfully parsed line:
+    if raw:
+        yield stream_success(output_line, ignore_exceptions)
+    else:
+        stream_success(_process(output_line), ignore_exceptions)
+
+    # unsuccessfully parsed line:
+    except Exception as e:
+        yield stream_error(raise_or_yield(ignore_exceptions, e, line))
+
+In all cases above:
+
+    output_line:  (Dict)  successfully parsed line yielded as a dict
+
+    e:            (BaseException)  exception object as the first value
+                  of the tuple if the line was not successfully parsed.
+
+    line:         (str)  string of the original line that did not
+                  successfully parse.
+
+    ignore_exceptions:  (bool)  continue processing lines and ignore
+                        exceptions if True.
+
+<a id="jc.streaming.raise_or_yield"></a>
+
+### raise\_or\_yield
+
+```python
+def raise_or_yield(ignore_exceptions: bool, e: BaseException,
+                   line: str) -> tuple
+```
+
+Return the exception object and line string if ignore_exceptions is
+True. Otherwise, re-raise the exception from the exception object with
+an annotation.
+

docs/utils.md

@@ -8,11 +8,7 @@
   * [convert\_to\_int](#jc.utils.convert_to_int)
   * [convert\_to\_float](#jc.utils.convert_to_float)
   * [convert\_to\_bool](#jc.utils.convert_to_bool)
-  * [stream\_success](#jc.utils.stream_success)
-  * [stream\_error](#jc.utils.stream_error)
   * [input\_type\_check](#jc.utils.input_type_check)
-  * [streaming\_input\_type\_check](#jc.utils.streaming_input_type_check)
-  * [streaming\_line\_input\_type\_check](#jc.utils.streaming_line_input_type_check)
   * [timestamp](#jc.utils.timestamp)
     * [\_\_init\_\_](#jc.utils.timestamp.__init__)
 
@@ -20,7 +16,7 @@
 
 # jc.utils
 
-jc - JSON CLI output utility utils
+jc - JSON Convert utils
 
 <a id="jc.utils.warning_message"></a>
 
@@ -67,7 +63,9 @@ Returns:
 ### compatibility
 
 ```python
-def compatibility(mod_name: str, compatible: List, quiet: Optional[bool] = False) -> None
+def compatibility(mod_name: str,
+                  compatible: List,
+                  quiet: bool = False) -> None
 ```
 
 Checks for the parser's compatibility with the running OS
@@ -112,7 +110,7 @@ Returns:
 ### convert\_to\_int
 
 ```python
-def convert_to_int(value: Union[str, float]) -> Union[int, None]
+def convert_to_int(value: Union[str, float]) -> Optional[int]
 ```
 
 Converts string and float input to int. Strips all non-numeric
@@ -131,7 +129,7 @@ Returns:
 ### convert\_to\_float
 
 ```python
-def convert_to_float(value: Union[str, int]) -> Union[float, None]
+def convert_to_float(value: Union[str, int]) -> Optional[float]
 ```
 
 Converts string and int input to float. Strips all non-numeric
@@ -165,27 +163,6 @@ Returns:
     True/False      False unless a 'truthy' number or string is found
                     ('y', 'yes', 'true', '1', 1, -1, etc.)
 
-<a id="jc.utils.stream_success"></a>
-
-### stream\_success
-
-```python
-def stream_success(output_line: Dict, ignore_exceptions: bool) -> Dict
-```
-
-Add `_jc_meta` object to output line if `ignore_exceptions=True`
-
-<a id="jc.utils.stream_error"></a>
-
-### stream\_error
-
-```python
-def stream_error(e: BaseException, ignore_exceptions: bool, line: str) -> Dict
-```
-
-Reraise the stream exception with annotation or print an error
-`_jc_meta` field if `ignore_exceptions=True`.
-
 <a id="jc.utils.input_type_check"></a>
 
 ### input\_type\_check
@@ -196,27 +173,6 @@ def input_type_check(data: str) -> None
 
 Ensure input data is a string. Raises `TypeError` if not.
 
-<a id="jc.utils.streaming_input_type_check"></a>
-
-### streaming\_input\_type\_check
-
-```python
-def streaming_input_type_check(data: Iterable) -> None
-```
-
-Ensure input data is an iterable, but not a string or bytes. Raises
-`TypeError` if not.
-
-<a id="jc.utils.streaming_line_input_type_check"></a>
-
-### streaming\_line\_input\_type\_check
-
-```python
-def streaming_line_input_type_check(line: str) -> None
-```
-
-Ensure each line is a string. Raises `TypeError` if not.
-
 <a id="jc.utils.timestamp"></a>
 
 ### timestamp Objects
@@ -230,29 +186,35 @@ class timestamp()
 ### \_\_init\_\_
 
 ```python
-def __init__(datetime_string: str) -> None
+def __init__(datetime_string: str,
+             format_hint: Union[List, Tuple, None] = None) -> None
 ```
 
-Input a date-time text string of several formats and convert to a
+Input a datetime text string of several formats and convert to a
 naive or timezone-aware epoch timestamp in UTC.
 
 Parameters:
 
-    datetime_string:  (str)  a string representation of a
-                             date-time in several supported formats
+    datetime_string  (str):  a string representation of a
+        datetime in several supported formats
 
-Attributes:
+    format_hint  (list | tuple):  an optional list of format ID
+        integers to instruct the timestamp object to try those
+        formats first in the order given. Other formats will be
+        tried after the format hint list is exhausted. This can
+        speed up timestamp conversion so several different formats
+        don't have to be tried in brute-force fashion.
 
-    string            (str)  the input datetime string
+Returns a timestamp object with the following attributes:
 
-    format            (int)  the format rule that was used to
-                             decode the datetime string. None if
-                             conversion fails
+    string  (str):  the input datetime string
 
-    naive             (int)  timestamp based on locally configured
-                             timezone. None if conversion fails
+    format  (int | None):  the format rule that was used to decode
+        the datetime string. None if conversion fails.
 
-    utc               (int)  aware timestamp only if UTC timezone
-                             detected in datetime string. None if
-                             conversion fails
+    naive  (int | None):  timestamp based on locally configured
+        timezone. None if conversion fails.
+
+    utc  (int | None):  aware timestamp only if UTC timezone
+        detected in datetime string. None if conversion fails.
 

jc/__init__.py

@@ -1,4 +1,4 @@
-"""JC - JSON CLI output utility
+"""JC - JSON Convert
 
 * kellyjonbrazil@gmail.com
 
@@ -10,6 +10,8 @@ and file-types to dictionaries and lists of dictionaries.
     >>> help('jc')
     >>> help('jc.lib')
     >>> help('jc.utils')
+    >>> help('jc.streaming')
+    >>> help('jc.parsers.universal')
     >>> jc.get_help('parser_module_name')
 
 ## Online Documentation
@@ -20,9 +22,9 @@ https://github.com/kellyjonbrazil/jc/tree/master/docs
 
 ### Specific Version
 
-Replace `{{full_version_number}}` - e.g. `1.17.7`:
+Replace `<full_version_number>` - e.g. `1.17.7`:
 
-`https://github.com/kellyjonbrazil/jc/tree/v{{full_version_number}}/docs`
+`https://github.com/kellyjonbrazil/jc/tree/v<full_version_number>/docs`
 
 Specific versions can also be selected by tag in the branch dropdown menu.
 
@@ -51,31 +53,68 @@ modules directly:
 
 ## Available Functions
 
-Use `help(jc.lib)` for details:
+Use `help(jc.lib)` for details.
 
-    parse(parser_module_name: str, data: str | Iterable)
-      -> dict | list[dict] | Iterable[dict]
-        High-level API to easily access the parser. This API will find both
-        built-in parsers and local plugin parsers.
+### parse
+
+    parse(
+        parser_module_name: str,
+        data: str | Iterable
+    ) -> dict | list[dict] | Iterable[dict]
+
+High-level API to easily access the parser. This API will find both
+built-in parsers and local plugin parsers.
+
+### parser_info
 
     parser_info(parser_module_name: str) -> dict
-        Get the metadata for a particular parser.
+
+Get the metadata for a particular parser.
+
+### all_parser_info
 
     all_parser_info() -> list[dict]
-        Get the metadata for all parsers.
+
+Get the metadata for all parsers.
+
+### get_help
 
     get_help(parser_module_name: str) -> None
-        Convenience function to display the help screen for a parser using
-        its module name.
+
+Convenience function to display the help screen for a parser using
+its module name.
+
+### parser_mod_list
 
     parser_mod_list() -> list
-        Get a list of all available parser module names to be used in
-        parse(), parser_info(), and get_help().
+
+Get a list of all available parser module names to be used in
+`parse()`, `parser_info()`, and `get_help()`.
+
+### plugin_parser_mod_list
 
     plugin_parser_mod_list() -> list
-        Get a list of plugin parser module names to be used in
-        parse(), parser_info(), and get_help(). This list is a subset of
-        parser_mod_list().
+
+Get a list of plugin parser module names to be used in
+`parse()`, `parser_info()`, and `get_help()`. This list is a subset of
+`parser_mod_list()`.
+
+### standard_parser_mod_list
+
+    standard_parser_mod_list() -> list
+
+Get a list of standard parser module names to be used in
+`parse()`, `parser_info()`, and `get_help()`. This list is a subset of
+`parser_mod_list()` and does not contain any streaming parsers.
+
+### streaming_parser_mod_list
+
+    streaming_parser_mod_list() -> list
+
+Get a list of streaming parser module names to be used in
+`parse()`, `parser_info()`, and `get_help()`. This list is a subset of
+`parser_mod_list()`.
 """
 from .lib import (__version__, parse, parser_mod_list, plugin_parser_mod_list,
+                  standard_parser_mod_list, streaming_parser_mod_list,
                   parser_info, all_parser_info, get_help)

jc/cli.py

@@ -1,4 +1,4 @@
-"""jc - JSON CLI output utility
+"""jc - JSON Convert
 JC cli module
 """
 
@@ -11,7 +11,7 @@ import shlex
 import subprocess
 import json
 from .lib import (__version__, all_parser_info, parsers,
-                  _parser_argument, _get_parser)
+                  _parser_argument, _get_parser, _parser_is_streaming)
 from . import utils
 from . import tracebackplus
 from .exceptions import LibraryNotInstalled, ParseError
@@ -34,7 +34,7 @@ JC_ERROR_EXIT = 100
 
 class info():
     version = __version__
-    description = 'JSON CLI output utility'
+    description = 'JSON Convert'
     author = 'Kelly Brazil'
     author_email = 'kellyjonbrazil@gmail.com'
     website = 'https://github.com/kellyjonbrazil/jc'
@@ -89,13 +89,15 @@ def set_env_colors(env_colors=None):
     """
     Return a dictionary to be used in Pygments custom style class.
 
-    Grab custom colors from JC_COLORS environment variable. JC_COLORS env variable takes 4 comma
-    separated string values and should be in the format of:
+    Grab custom colors from JC_COLORS environment variable. JC_COLORS env
+    variable takes 4 comma separated string values and should be in the
+    format of:
 
     JC_COLORS=<keyname_color>,<keyword_color>,<number_color>,<string_color>
 
-    Where colors are: black, red, green, yellow, blue, magenta, cyan, gray, brightblack, brightred,
-                      brightgreen, brightyellow, brightblue, brightmagenta, brightcyan, white, default
+    Where colors are: black, red, green, yellow, blue, magenta, cyan, gray,
+                      brightblack, brightred, brightgreen, brightyellow,
+                      brightblue, brightmagenta, brightcyan, white, default
 
     Default colors:
 
@@ -132,8 +134,10 @@ def set_env_colors(env_colors=None):
 
 
 def piped_output(force_color):
-    """Return False if stdout is a TTY. True if output is being piped to another program
-       and foce_color is True. This allows forcing of ANSI color codes even when using pipes.
+    """
+    Return False if stdout is a TTY. True if output is being piped to
+    another program and foce_color is True. This allows forcing of ANSI
+    color codes even when using pipes.
     """
     return not sys.stdout.isatty() and not force_color
 
@@ -224,8 +228,8 @@ def helptext():
 
 def help_doc(options):
     """
-    Returns the parser documentation if a parser is found in the arguments, otherwise
-    the general help text is returned.
+    Returns the parser documentation if a parser is found in the arguments,
+    otherwise the general help text is returned.
     """
     for arg in options:
         parser_name = parser_shortname(arg)
@@ -253,7 +257,10 @@ def versiontext():
 
 
 def json_out(data, pretty=False, env_colors=None, mono=False, piped_out=False):
-    """Return a JSON formatted string. String may include color codes or be pretty printed."""
+    """
+    Return a JSON formatted string. String may include color codes or be
+    pretty printed.
+    """
     separators = (',', ':')
     indent = None
 
@@ -277,10 +284,10 @@ def magic_parser(args):
     Parse command arguments for magic syntax: jc -p ls -al
 
     Return a tuple:
-        valid_command   (bool)  is this a valid command? (exists in magic dict)
-        run_command     (list)  list of the user's command to run. None if no command.
-        jc_parser       (str)   parser to use for this user's command.
-        jc_options      (list)  list of jc options
+        valid_command (bool)  is this a valid cmd? (exists in magic dict)
+        run_command   (list)  list of the user's cmd to run. None if no cmd.
+        jc_parser     (str)   parser to use for this user's cmd.
+        jc_options    (list)  list of jc options
     """
     # bail immediately if there are no args or a parser is defined
     if len(args) <= 1 or args[1].startswith('--'):
@@ -335,12 +342,15 @@ def magic_parser(args):
 
 
 def run_user_command(command):
-    """Use subprocess to run the user's command. Returns the STDOUT, STDERR, and the Exit Code as a tuple."""
+    """
+    Use subprocess to run the user's command. Returns the STDOUT, STDERR,
+    and the Exit Code as a tuple.
+    """
     proc = subprocess.Popen(command,
                             stdout=subprocess.PIPE,
                             stderr=subprocess.PIPE,
-                            close_fds=False,            # Allows inheriting file descriptors. Useful for process substitution
-                            universal_newlines=True)
+                            close_fds=False,            # Allows inheriting file descriptors;
+                            universal_newlines=True)    # useful for process substitution
     stdout, stderr = proc.communicate()
 
     return (
@@ -441,14 +451,18 @@ def main():
                 raise
 
             error_msg = os.strerror(e.errno)
-            utils.error_message([f'"{run_command_str}" command could not be run: {error_msg}. For details use the -d or -dd option.'])
+            utils.error_message([
+                f'"{run_command_str}" command could not be run: {error_msg}. For details use the -d or -dd option.'
+            ])
             sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
 
         except Exception:
             if debug:
                 raise
 
-            utils.error_message([f'"{run_command_str}" command could not be run. For details use the -d or -dd option.'])
+            utils.error_message([
+                f'"{run_command_str}" command could not be run. For details use the -d or -dd option.'
+            ])
             sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
 
     elif run_command is not None:
@@ -488,8 +502,11 @@ def main():
         # differentiate between regular and streaming parsers
 
         # streaming
-        if getattr(parser.info, 'streaming', None):
-            result = parser.parse(sys.stdin, raw=raw, quiet=quiet, ignore_exceptions=ignore_exceptions)
+        if _parser_is_streaming(parser):
+            result = parser.parse(sys.stdin,
+                                  raw=raw,
+                                  quiet=quiet,
+                                  ignore_exceptions=ignore_exceptions)
             for line in result:
                 print(json_out(line,
                                pretty=pretty,
@@ -503,7 +520,9 @@ def main():
         # regular
         else:
             data = magic_stdout or sys.stdin.read()
-            result = parser.parse(data, raw=raw, quiet=quiet)
+            result = parser.parse(data,
+                                  raw=raw,
+                                  quiet=quiet)
             print(json_out(result,
                            pretty=pretty,
                            env_colors=jc_colors,
@@ -517,10 +536,11 @@ def main():
         if debug:
             raise
 
-        utils.error_message([f'Parser issue with {parser_name}:',
-                             f'{e.__class__.__name__}: {e}',
-                             'If this is the correct parser, try setting the locale to C (LANG=C).',
-                             'For details use the -d or -dd option. Use "jc -h" for help.'])
+        utils.error_message([
+            f'Parser issue with {parser_name}:', f'{e.__class__.__name__}: {e}',
+            'If this is the correct parser, try setting the locale to C (LANG=C).',
+            f'For details use the -d or -dd option. Use "jc -h --{parser_name}" for help.'
+        ])
         sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
 
     except json.JSONDecodeError:
@@ -543,7 +563,7 @@ def main():
             f'{parser_name} parser could not parse the input data.',
             f'{streaming_msg}',
             'If this is the correct parser, try setting the locale to C (LANG=C).',
-            'For details use the -d or -dd option. Use "jc -h" for help.'
+            f'For details use the -d or -dd option. Use "jc -h --{parser_name}" for help.'
         ])
         sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))