Merge pull request #249 from kellyjonbrazil/dev

Dev v1.20.0

CHANGELOG

@@ -1,5 +1,54 @@
 jc changelog
 
+20220531 v1.20.0
+- Add YAML output option with `-y`
+- Add `top -b` standard and streaming parsers tested on linux
+- Add `plugin_parser_count`, `standard_parser_count`, and `streaming_parser_count`
+  keys to `jc -a` output
+- Add `is_compatible` function to the `utils` module
+- Fix `pip-show` parser for packages with a multi-line license field
+- Fix ASCII Table parser for cases where centered headers cause mis-aligned fields
+
+20220513 v1.19.0
+- Add `chage --list` command parser tested on linux
+- Add `git log` command streaming parser
+- Fix `git log` standard parser for corner-cases where hash values are in messages
+- Fix `df` command parser for rare instances when a newline is found at the end
+- Allow jc to pip install on unsupported python version 3.6
+- Fix `asciitable-m` parser to skip some rows that contain column separator
+  characters in cell data. A warning message will be printed to STDERR
+  unless `-q` or `quiet=True` is used.
+
+20220427 v1.18.8
+- Fix `update-alternatives --query` parser for cases where `slaves` are not present
+- Fix UnicodeEncodeError on some systems where LANG=C is set and unicode
+  characters are in the output
+- Update `history` parser: do not drop non-ASCII characters if the system
+  is configured for UTF-8 encoding
+- Enhance "magic syntax" to always use UTF-8 encoding
+
+20220425 v1.18.7
+- Add `git log` command parser
+- Add `update-alternatives --query` parser
+- Add `update-alternatives --get-selections` parser
+- Fix key/value and ini parsers to allow duplicate keys
+- Fix yaml file parser for files including timestamp objects
+- Update `xrandr` parser: add a 'rotation' field
+- Fix failing tests by moving template files
+- Add python interpreter version and path to -v and -a output
+
+20220325 v1.18.6
+- Add `pidstat` command parser tested on linux
+- Add `pidstat` command streaming parser tested on linux
+- Add `mpstat` command parser tested on linux
+- Add `mpstat` command streaming parser tested on linux
+- Add single-line ASCII and Unicode table parser
+- Add multi-line ASCII and Unicode table parser
+- Add documentation option to `parser_info()` and `all_parser_info()`
+
+20220305 v1.18.5
+- Fix date parser to ensure AM/PM period string is always uppercase
+
 20220304 v1.18.4
 - Add nmcli command parser tested on linux
 - Enhance parse error messages at the cli
@@ -349,16 +398,16 @@ jc changelog
 - Add axfr support for dig command parser
 
 20200312 v1.9.2
-- Updated arp parser to fix OSX detection for some edge cases
+- Update arp parser to fix OSX detection for some edge cases
 
 20200312 v1.9.1
-- Updated file command parser to make filename splitting more robust
+- Update file command parser to make filename splitting more robust
 
 20200311 v1.9.0
-- Added ntpq command parser
-- Added timedatectl status command parser
-- Added airport -I and airport -s command parser
-- Added file command parser
+- Add ntpq command parser
+- Add timedatectl status command parser
+- Add airport -I and airport -s command parser
+- Add file command parser
 - Optimized history command parser by https://github.com/philippeitis
 - Magic syntax fix for certain edge cases
 
@@ -366,23 +415,23 @@ jc changelog
 - CLI optimizations by https://github.com/philippeitis
 - Refactored magic syntax function and added tests (https://github.com/philippeitis)
 - Github actions for CI testing on multiple platforms by https://github.com/philippeitis
-- Updated ls parser to fix parsing error in OSX with -lR when there are empty folders
+- Update ls parser to fix parsing error in OSX with -lR when there are empty folders
 
 20200303 v1.8.0
-- Added blkid command parser
-- Added last and lastb command parser
-- Added who command parser
-- Added CSV file parser
-- Added /etc/passwd file parser
-- Added /etc/shadow file parser
-- Added /etc/group file parser
-- Added /etc/gshadow file parser
+- Add blkid command parser
+- Add last and lastb command parser
+- Add who command parser
+- Add CSV file parser
+- Add /etc/passwd file parser
+- Add /etc/shadow file parser
+- Add /etc/group file parser
+- Add /etc/gshadow file parser
 
 20200227 v1.7.5
-- Updated ls parser to support filenames with newline characters
+- Update ls parser to support filenames with newline characters
 
 20200219 v1.7.4
-- Updated ls parser to support multiple directories, globbing, and -R (recursive)
+- Update ls parser to support multiple directories, globbing, and -R (recursive)
 
 20200211 v1.7.3
 - Add alternative 'magic' syntax: e.g. `jc ls -al`
@@ -399,8 +448,8 @@ jc changelog
 - Add crontab file parser with user support (tested on linux)
 - Add __version__ variable to parser modules
 - Add exit code on error
-- Updated history parser to output "line" as an integer
-- Updated compatibility list for some parsers
+- Update history parser to output "line" as an integer
+- Update compatibility list for some parsers
 - Bugfix in crontab file parser: header insertion was clobbering first row
 - Just-in-time loading of parser modules instead of loading all at start
 
@@ -413,7 +462,7 @@ jc changelog
 - Add tests for ls, dig, ps, w, uptime on OSX
 - Add about option
 - Add universal parsers to refactor repetitive code
-- Updated ifconfig parser to output 'state' as an array
+- Update ifconfig parser to output 'state' as an array
 
 20191117 v1.5.1
 - Add ss parser
@@ -426,11 +475,11 @@ jc changelog
 - Add -d option to debug parsing issues
 - Add compatibility warnings to stderr
 - Add documentation
-- Updated iptables parser to allow --line-numbers option
-- Updated lsblk parser to allow parsing of added columns
-- Updated mount parser: changed 'access' field name to 'options'
-- Updated netstat parser to allow parsing of unix sockets and raw network connections
-- Updated w parser to fix unaligned data where blanks are possible
+- Update iptables parser to allow --line-numbers option
+- Update lsblk parser to allow parsing of added columns
+- Update mount parser: changed 'access' field name to 'options'
+- Update netstat parser to allow parsing of unix sockets and raw network connections
+- Update w parser to fix unaligned data where blanks are possible
 - Clean up code and reorganize package
 
 20191031 v1.1.1

EXAMPLES.md

@@ -265,6 +265,21 @@ blkid -o udev -ip /dev/sda2 | jc --blkid -p          # or:  jc -p blkid -o udev
   }
 ]
 ```
+### chage --list
+```bash
+chage --list joeuser | jc --chage -p          # or:  jc -p chage --list joeuser
+```
+```json
+{
+  "password_last_changed": "never",
+  "password_expires": "never",
+  "password_inactive": "never",
+  "account_expires": "never",
+  "min_days_between_password_change": 0,
+  "max_days_between_password_change": 99999,
+  "warning_days_before_password_expires": 7
+}
+```
 ### cksum
 ```bash
 cksum * | jc --cksum -p          # or:  jc -p cksum *
@@ -1059,6 +1074,53 @@ cat /etc/fstab | jc --fstab -p
   }
 ]
 ```
+### git log
+```bash
+git log --stat | jc --git-log -p          or:  jc -p git log --stat
+```
+```json
+[
+  {
+    "commit": "728d882ed007b3c8b785018874a0eb06e1143b66",
+    "author": "Kelly Brazil",
+    "author_email": "kellyjonbrazil@gmail.com",
+    "date": "Wed Apr 20 09:50:19 2022 -0400",
+    "stats": {
+      "files_changed": 2,
+      "insertions": 90,
+      "deletions": 12,
+      "files": [
+        "docs/parsers/git_log.md",
+        "jc/parsers/git_log.py"
+      ]
+    },
+    "message": "add timestamp docs and examples",
+    "epoch": 1650462619,
+    "epoch_utc": null
+  },
+  {
+    "commit": "b53e42aca623181aa9bc72194e6eeef1e9a3a237",
+    "author": "Kelly Brazil",
+    "author_email": "kellyjonbrazil@gmail.com",
+    "date": "Wed Apr 20 09:44:42 2022 -0400",
+    "stats": {
+      "files_changed": 5,
+      "insertions": 29,
+      "deletions": 6,
+      "files": [
+        "docs/parsers/git_log.md",
+        "docs/utils.md",
+        "jc/parsers/git_log.py",
+        "jc/utils.py",
+        "man/jc.1"
+      ]
+    },
+    "message": "add calculated timestamp",
+    "epoch": 1650462282,
+    "epoch_utc": null
+  }
+]
+```
 ### /etc/group file
 ```bash
 cat /etc/group | jc --group -p
@@ -2149,6 +2211,29 @@ mount | jc --mount -p          # or:  jc -p mount
   }
 ]
 ```
+### mpstat
+```bash
+mpstat | jc --mpstat -p          # or  jc -p mpstat
+```
+```json
+[
+  {
+    "cpu": "all",
+    "percent_usr": 12.94,
+    "percent_nice": 0.0,
+    "percent_sys": 26.42,
+    "percent_iowait": 0.43,
+    "percent_irq": 0.0,
+    "percent_soft": 0.16,
+    "percent_steal": 0.0,
+    "percent_guest": 0.0,
+    "percent_gnice": 0.0,
+    "percent_idle": 60.05,
+    "type": "cpu",
+    "time": "01:58:14 PM"
+  }
+]
+```
 ### netstat
 ```bash
 netstat -apee | jc --netstat -p          # or:  jc -p netstat -apee
@@ -2497,6 +2582,47 @@ cat /etc/passwd | jc --passwd -p
   }
 ]
 ```
+### pidstat
+```bash
+pidstat -hl | jc --pidstat -p          # or  jc -p pidstat -hl
+```
+```json
+[
+  {
+    "time": 1646859134,
+    "uid": 0,
+    "pid": 1,
+    "percent_usr": 0.0,
+    "percent_system": 0.03,
+    "percent_guest": 0.0,
+    "percent_cpu": 0.03,
+    "cpu": 0,
+    "command": "/usr/lib/systemd/systemd --switched-root --system..."
+  },
+  {
+    "time": 1646859134,
+    "uid": 0,
+    "pid": 6,
+    "percent_usr": 0.0,
+    "percent_system": 0.0,
+    "percent_guest": 0.0,
+    "percent_cpu": 0.0,
+    "cpu": 0,
+    "command": "ksoftirqd/0"
+  },
+  {
+    "time": 1646859134,
+    "uid": 0,
+    "pid": 2263,
+    "percent_usr": 0.0,
+    "percent_system": 0.0,
+    "percent_guest": 0.0,
+    "percent_cpu": 0.0,
+    "cpu": 0,
+    "command": "kworker/0:0"
+  }
+]
+```
 ### ping
 ```bash
 ping 8.8.8.8 -c 3 | jc --ping -p          # or:  jc -p ping 8.8.8.8 -c 3
@@ -3581,6 +3707,69 @@ uname -a | jc --uname -p          # or:  jc -p uname -a
   "kernel_version": "#74-Ubuntu SMP Tue Sep 17 17:06:04 UTC 2019"
 }
 ```
+### update-alternatives --get-selections
+```bash
+update-alternatives --get-selections | jc --update-alt-gs -p          # or:  jc -p update-alternatives --get-selections
+```
+```json
+[
+  {
+    "name": "arptables",
+    "status": "auto",
+    "current": "/usr/sbin/arptables-nft"
+  },
+  {
+    "name": "awk",
+    "status": "auto",
+    "current": "/usr/bin/gawk"
+  }
+]
+```
+### update-alternatives --query
+```bash
+update-alternatives --query editor | jc --update-alt-q -p          # or:  jc -p update-alternatives --query editor
+```
+```json
+{
+  "name": "editor",
+  "link": "/usr/bin/editor",
+  "slaves": [
+    {
+      "name": "editor.1.gz",
+      "path": "/usr/share/man/man1/editor.1.gz"
+    },
+    {
+      "name": "editor.da.1.gz",
+      "path": "/usr/share/man/da/man1/editor.1.gz"
+    }
+  ],
+  "status": "auto",
+  "best": "/bin/nano",
+  "value": "/bin/nano",
+  "alternatives": [
+    {
+      "name": "/bin/ed",
+      "priority": -100,
+      "slaves": [
+        {
+          "name": "editor.1.gz",
+          "path": "/usr/share/man/man1/ed.1.gz"
+        }
+      ]
+    },
+    {
+      "name": "/bin/nano",
+      "priority": 40,
+      "slaves": [
+        {
+          "name": "editor.1.gz",
+          "path": "/usr/share/man/man1/nano.1.gz"
+        }
+      ]
+    }
+  ]
+}
+```
 ### upower
 ```bash
 upower -i /org/freedesktop/UPower/devices/battery | jc --upower -p          # or jc -p upower -i /org/freedesktop/UPower/devices/battery

README.md

@@ -1,5 +1,5 @@
-![Tests](https://github.com/kellyjonbrazil/jc/workflows/Tests/badge.svg?branch=master)
-![Pypi](https://img.shields.io/pypi/v/jc.svg)
+[![Tests](https://github.com/kellyjonbrazil/jc/workflows/Tests/badge.svg?branch=master)](https://github.com/kellyjonbrazil/jc/actions)
+[![Pypi](https://img.shields.io/pypi/v/jc.svg)](https://pypi.org/project/jc/)
 
 > Check out the `jc` Python [package documentation](https://github.com/kellyjonbrazil/jc/tree/master/docs) for developers
 
@@ -99,23 +99,25 @@ correct [binary](https://github.com/kellyjonbrazil/jc/releases) for your
 architecture and running it anywhere on your filesystem.
 
 ### Pip (macOS, linux, unix, Windows)
+[![Pypi](https://img.shields.io/pypi/v/jc.svg)](https://pypi.org/project/jc/)
 ```bash
 pip3 install jc
 ```
 
 ### OS Package Repositories
 
-| OS                    | Command                                                                       |
-|-----------------------|-------------------------------------------------------------------------------|
-| Debian/Ubuntu linux   | `apt-get install jc`                                                          |
-| Fedora linux          | `dnf install jc`                                                              |
-| openSUSE linux        | `zypper install jc`                                                           |
-| Arch linux            | `pacman -S jc`                                                                |
-| NixOS linux           | `nix-env -iA nixpkgs.jc` or `nix-env -iA nixos.jc`                            |
-| Guix System linux     | `guix install jc`                                                             |
-| macOS                 | `brew install jc`                                                             |
-| FreeBSD               | `portsnap fetch update && cd /usr/ports/textproc/py-jc && make install clean` |
-| Ansible filter plugin | `ansible-galaxy collection install community.general`                         |
+| OS                                   | Command                                                                       |
+|--------------------------------------|-------------------------------------------------------------------------------|
+| Debian/Ubuntu linux                  | `apt-get install jc`                                                          |
+| Fedora linux                         | `dnf install jc`                                                              |
+| openSUSE linux                       | `zypper install jc`                                                           |
+| Archlinux Community Repository       | `paru -S jc` or `aura -S jc` or `yay -S jc`                                   |
+| NixOS linux                          | `nix-env -iA nixpkgs.jc` or `nix-env -iA nixos.jc`                            |
+| Guix System linux                    | `guix install jc`                                                             |
+| Gentoo Linux                         | `emerge dev-python/jc`                                                        |
+| macOS                                | `brew install jc`                                                             |
+| FreeBSD                              | `portsnap fetch update && cd /usr/ports/textproc/py-jc && make install clean` |
+| Ansible filter plugin                | `ansible-galaxy collection install community.general`                         |
 
 > For more OS Packages, see https://repology.org/project/jc/versions.
 
@@ -142,99 +144,114 @@ option.
 
 ### Parsers
 
-- `--acpi` enables the `acpi` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/acpi))
-- `--airport` enables the `airport -I` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/airport))
-- `--airport-s` enables the `airport -s` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/airport_s))
-- `--arp` enables the `arp` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/arp))
-- `--blkid` enables the `blkid` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/blkid))
-- `--cksum` enables the `cksum` and `sum` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/cksum))
-- `--crontab` enables the `crontab` command and file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/crontab))
-- `--crontab-u` enables the `crontab` file parser with user support ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/crontab_u))
-- `--csv` enables the CSV file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/csv))
-- `--csv-s` enables the CSV file streaming parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/csv_s))
-- `--date` enables the `date` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/date))
-- `--df` enables the `df` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/df))
-- `--dig` enables the `dig` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/dig))
-- `--dir` enables the `dir` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/dir))
-- `--dmidecode` enables the `dmidecode` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/dmidecode))
-- `--dpkg-l` enables the `dpkg -l` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/dpkg_l))
-- `--du` enables the `du` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/du))
-- `--env` enables the `env` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/env))
-- `--file` enables the `file` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/file))
-- `--finger` enables the `finger` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/finger))
-- `--free` enables the `free` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/free))
-- `--fstab` enables the `/etc/fstab` file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/fstab))
-- `--group` enables the `/etc/group` file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/group))
-- `--gshadow` enables the `/etc/gshadow` file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/gshadow))
-- `--hash` enables the `hash` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/hash))
-- `--hashsum` enables the hashsum command parser (`md5sum`, `shasum`, etc.) ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/hashsum))
-- `--hciconfig` enables the `hciconfig` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/hciconfig))
-- `--history` enables the `history` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/history))
-- `--hosts` enables the `/etc/hosts` file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/hosts))
-- `--id` enables the `id` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/id))
-- `--ifconfig` enables the `ifconfig` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ifconfig))
-- `--ini` enables the INI file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ini))
-- `--iostat` enables the `iostat` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/iostat))
-- `--iostat-s` enables the `iostat` command streaming parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/iostat_s))
-- `--iptables` enables the `iptables` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/iptables))
-- `--iw-scan` enables the `iw dev [device] scan` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/iw_scan))
-- `--jar-manifest` enables the MANIFEST.MF file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/jar_manifest))
-- `--jobs` enables the `jobs` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/jobs))
-- `--kv` enables the Key/Value file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/kv))
-- `--last` enables the `last` and `lastb` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/last))
-- `--ls` enables the `ls` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ls))
-- `--ls-s` enables the `ls` command streaming parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ls_s))
-- `--lsblk` enables the `lsblk` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/lsblk))
-- `--lsmod` enables the `lsmod` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/lsmod))
-- `--lsof` enables the `lsof` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/lsof))
-- `--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))
-- `--ping-s` enables the `ping` and `ping6` command streaming parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ping_s))
-- `--pip-list` enables the `pip list` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/pip_list))
-- `--pip-show` enables the `pip show` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/pip_show))
-- `--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))
-- `--stat` enables the `stat` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/stat))
-- `--stat-s` enables the `stat` command streaming parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/stat_s))
-- `--sysctl` enables the `sysctl` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/sysctl))
-- `--systemctl` enables the `systemctl` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/systemctl))
-- `--systemctl-lj` enables the `systemctl list-jobs` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/systemctl_lj))
-- `--systemctl-ls` enables the `systemctl list-sockets` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/systemctl_ls))
-- `--systemctl-luf` enables the `systemctl list-unit-files` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/systemctl_luf))
-- `--systeminfo` enables the `systeminfo` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/systeminfo))
-- `--time` enables the `/usr/bin/time` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/time))
-- `--timedatectl` enables the `timedatectl status` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/timedatectl))
-- `--tracepath` enables the `tracepath` and `tracepath6` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/tracepath))
-- `--traceroute` enables the `traceroute` and `traceroute6` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/traceroute))
-- `--ufw` enables the `ufw status` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ufw))
-- `--ufw-appinfo` enables the `ufw app info [application]` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/ufw_appinfo))
-- `--uname` enables the `uname -a` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/uname))
-- `--upower` enables the `upower` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/upower))
-- `--uptime` enables the `uptime` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/uptime))
-- `--vmstat` enables the `vmstat` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/vmstat))
-- `--vmstat-s` enables the `vmstat` command streaming parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/vmstat_s))
-- `--w` enables the `w` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/w))
-- `--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))
+| Argument          | Command or Filetype                                     | Documentation                                                           |
+|-------------------|---------------------------------------------------------|-------------------------------------------------------------------------|
+| `         --acpi` | `acpi` command parser                                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/acpi)             |
+| `      --airport` | `airport -I` command parser                             | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/airport)          |
+| `    --airport-s` | `airport -s` command parser                             | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/airport_s)        |
+| `          --arp` | `arp` command parser                                    | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/arp)              |
+| `   --asciitable` | ASCII and Unicode table parser                          | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/asciitable)       |
+| ` --asciitable-m` | multi-line ASCII and Unicode table parser               | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/asciitable_m)     |
+| `        --blkid` | `blkid` command parser                                  | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/blkid)            |
+| `        --chage` | `chage --list` command parser                           | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/chage)            |
+| `        --cksum` | `cksum` and `sum` command parser                        | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/cksum)            |
+| `      --crontab` | `crontab` command and file parser                       | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/crontab)          |
+| `    --crontab-u` | `crontab` file parser with user support                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/crontab_u)        |
+| `          --csv` | CSV file parser                                         | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/csv)              |
+| `        --csv-s` | CSV file streaming parser                               | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/csv_s)            |
+| `         --date` | `date` command parser                                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/date)             |
+| `           --df` | `df` command parser                                     | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/df)               |
+| `          --dig` | `dig` command parser                                    | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/dig)              |
+| `          --dir` | `dir` command parser                                    | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/dir)              |
+| `    --dmidecode` | `dmidecode` command parser                              | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/dmidecode)        |
+| `       --dpkg-l` | `dpkg -l` command parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/dpkg_l)           |
+| `           --du` | `du` command parser                                     | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/du)               |
+| `          --env` | `env` command parser                                    | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/env)              |
+| `         --file` | `file` command parser                                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/file)             |
+| `       --finger` | `finger` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/finger)           |
+| `         --free` | `free` command parser                                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/free)             |
+| `        --fstab` | `/etc/fstab` file parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/fstab)            |
+| `      --git-log` | `git log` command parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/git_log)          |
+| `    --git-log-s` | `git log` command streaming parser                      | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/git_log_s)        |
+| `        --group` | `/etc/group` file parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/group)            |
+| `      --gshadow` | `/etc/gshadow` file parser                              | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/gshadow)          |
+| `         --hash` | `hash` command parser                                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/hash)             |
+| `      --hashsum` | hashsum command parser (`md5sum`, `shasum`, etc.)       | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/hashsum)          |
+| `    --hciconfig` | `hciconfig` command parser                              | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/hciconfig)        |
+| `      --history` | `history` command parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/history)          |
+| `        --hosts` | `/etc/hosts` file parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/hosts)            |
+| `           --id` | `id` command parser                                     | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/id)               |
+| `     --ifconfig` | `ifconfig` command parser                               | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ifconfig)         |
+| `          --ini` | INI file parser                                         | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ini)              |
+| `       --iostat` | `iostat` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/iostat)           |
+| `     --iostat-s` | `iostat` command streaming parser                       | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/iostat_s)         |
+| `     --iptables` | `iptables` command parser                               | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/iptables)         |
+| `      --iw-scan` | `iw dev [device] scan` command parser                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/iw_scan)          |
+| ` --jar-manifest` | MANIFEST.MF file parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/jar_manifest)     |
+| `         --jobs` | `jobs` command parser                                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/jobs)             |
+| `           --kv` | Key/Value file parser                                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/kv)               |
+| `         --last` | `last` and `lastb` command parser                       | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/last)             |
+| `           --ls` | `ls` command parser                                     | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ls)               |
+| `         --ls-s` | `ls` command streaming parser                           | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ls_s)             |
+| `        --lsblk` | `lsblk` command parser                                  | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/lsblk)            |
+| `        --lsmod` | `lsmod` command parser                                  | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/lsmod)            |
+| `         --lsof` | `lsof` command parser                                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/lsof)             |
+| `        --lsusb` | `lsusb` command parser                                  | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/lsusb)            |
+| `        --mount` | `mount` command parser                                  | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/mount)            |
+| `       --mpstat` | `mpstat` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/mpstat)           |
+| `     --mpstat-s` | `mpstat` command streaming parser                       | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/mpstat_s)         |
+| `      --netstat` | `netstat` command parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/netstat)          |
+| `        --nmcli` | `nmcli` command parser                                  | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/nmcli)            |
+| `         --ntpq` | `ntpq -p` command parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ntpq)             |
+| `       --passwd` | `/etc/passwd` file parser                               | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/passwd)           |
+| `      --pidstat` | `pidstat -h` command parser                             | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/pidstat)          |
+| `    --pidstat-s` | `pidstat -h` command streaming parser                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/pidstat_s)        |
+| `         --ping` | `ping` and `ping6` command parser                       | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ping)             |
+| `       --ping-s` | `ping` and `ping6` command streaming parser             | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ping_s)           |
+| `     --pip-list` | `pip list` command parser                               | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/pip_list)         |
+| `     --pip-show` | `pip show` command parser                               | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/pip_show)         |
+| `           --ps` | `ps` command parser                                     | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ps)               |
+| `        --route` | `route` command parser                                  | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/route)            |
+| `       --rpm-qi` | `rpm -qi` command parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/rpm_qi)           |
+| `        --rsync` | `rsync` command parser                                  | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/rsync)            |
+| `      --rsync-s` | `rsync` command streaming parser                        | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/rsync_s)          |
+| `       --sfdisk` | `sfdisk` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/sfdisk)           |
+| `       --shadow` | `/etc/shadow` file parser                               | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/shadow)           |
+| `           --ss` | `ss` command parser                                     | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ss)               |
+| `         --stat` | `stat` command parser                                   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/stat)             |
+| `       --stat-s` | `stat` command streaming parser                         | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/stat_s)           |
+| `       --sysctl` | `sysctl` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/sysctl)           |
+| `    --systemctl` | `systemctl` command parser                              | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/systemctl)        |
+| ` --systemctl-lj` | `systemctl list-jobs` command parser                    | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/systemctl_lj)     |
+| ` --systemctl-ls` | `systemctl list-sockets` command parser                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/systemctl_ls)     |
+| `--systemctl-luf` | `systemctl list-unit-files` command parser              | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/systemctl_luf)    |
+| `   --systeminfo` | `systeminfo` command parser                             | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/systeminfo)       |
+| `         --time` | `/usr/bin/time` command parser                          | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/time)             |
+| `  --timedatectl` | `timedatectl status` command parser                     | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/timedatectl)      |
+| `          --top` | `top -b` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/top)              |
+| `        --top-s` | `top -b` command streaming parser                       | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/top_s)            |
+| `    --tracepath` | `tracepath` and `tracepath6` command parser             | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/tracepath)        |
+| `   --traceroute` | `traceroute` and `traceroute6` command parser           | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/traceroute)       |
+| `          --ufw` | `ufw status` command parser                             | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ufw)              |
+| `  --ufw-appinfo` | `ufw app info [application]` command parser             | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/ufw_appinfo)      |
+| `        --uname` | `uname -a` command parser                               | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/uname)            |
+| `--update-alt-gs` | `update-alternatives --get-selections` command parser   | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/update_alt_gs)    |
+| ` --update-alt-q` | `update-alternatives --query` command parser            | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/update_alt_q)     |
+| `       --upower` | `upower` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/upower)           |
+| `       --uptime` | `uptime` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/uptime)           |
+| `       --vmstat` | `vmstat` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/vmstat)           |
+| `     --vmstat-s` | `vmstat` command streaming parser                       | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/vmstat_s)         |
+| `            --w` | `w` command parser                                      | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/w)                |
+| `           --wc` | `wc` command parser                                     | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/wc)               |
+| `          --who` | `who` command parser                                    | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/who)              |
+| `          --xml` | XML file parser                                         | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/xml)              |
+| `       --xrandr` | `xrandr` command parser                                 | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/xrandr)           |
+| `         --yaml` | YAML file parser                                        | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/yaml)             |
+| `      --zipinfo` | `zipinfo` command parser                                | [📃](https://kellyjonbrazil.github.io/jc/docs/parsers/zipinfo)          |
 
 ### Options
-- `-a` about `jc`. Prints information about `jc` and the parsers (in JSON, of
-       course!)
+- `-a` about `jc`. Prints information about `jc` and the parsers (in JSON or
+       YAML, of course!)
 - `-C` force color output even when using pipes (overrides `-m` and the
        `NO_COLOR` env variable)
 - `-d` debug mode. Prints trace messages if parsing issues are encountered (use
@@ -248,6 +265,7 @@ option.
        values and no additional semantic processing
 - `-u` unbuffer output
 - `-v` version information
+- `-y` YAML output
 
 ### Exit Codes
 Any fatal errors within `jc` will generate an exit code of `100`, otherwise the
@@ -294,11 +312,11 @@ color output will override both the `NO_COLOR` environment variable and the `-m`
 option.
 
 ### Streaming Parsers
-Most parsers load all of the data from STDIN, parse it, then output the entire
+Most parsers load all of the data from `STDIN`, parse it, then output the entire
 JSON document serially. There are some streaming parsers (e.g. `ls-s` and
 `ping-s`) that immediately start processing and outputing the data line-by-line
 as [JSON Lines](https://jsonlines.org/) (aka [NDJSON](http://ndjson.org/)) while
-it is being received from STDIN. This can significantly reduce the amount of
+it is being received from `STDIN`. This can significantly reduce the amount of
 memory required to parse large amounts of command output (e.g. `ls -lR /`) and
 can sometimes process the data more quickly. Streaming parsers have slightly
 different behavior than standard parsers as outlined below.
@@ -363,14 +381,14 @@ $ ping 1.1.1.1 | jc --ping-s -u | jq
 
 #### Using Streaming Parsers as Python Modules
 
-Streaming parsers accept any iterable object and return an iterator object
-(generator) allowing lazy processing of the data. The input data should
-iterate on lines of string data. Examples of good input data are `sys.stdin` or
+Streaming parsers accept any iterable object and return an iterable object
+allowing lazy processing of the data. The input data should iterate on lines
+of string data. Examples of good input data are `sys.stdin` or
 `str.splitlines()`.
 
-To use the generator object in your code, simply loop through it or use the
-[next()](https://docs.python.org/3/library/functions.html#next) builtin
-function:
+To use the returned iterable object in your code, simply loop through it or
+use the [next()](https://docs.python.org/3/library/functions.html#next)
+builtin function:
 ```python
 import jc
 
@@ -392,9 +410,9 @@ Local parser plugins are standard python module files. Use the
 or [`jc/parsers/foo_s.py (streaming)`](https://github.com/kellyjonbrazil/jc/blob/master/jc/parsers/foo_s.py)
 parser as a template and simply place a `.py` file in the `jcparsers` subfolder.
 
-Local plugin filenames must be valid python module names, therefore must consist
-entirely of alphanumerics and start with a letter. Local plugins may override
-default parsers.
+Local plugin filenames must be valid python module names and therefore must
+start with a letter and consist entirely of alphanumerics and underscores.
+Local plugins may override default parsers.
 
 > Note: The application data directory follows the
 [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
@@ -414,6 +432,9 @@ or by exporting to the environment before running commands:
 $ export LANG=C
 ```
 
+On some older systems UTF-8 output will be downgraded to ASCII with `\\u`
+escape sequences if the `C` locale does not support UTF-8 encoding.
+
 #### Timezones
 
 Some parsers have calculated epoch timestamp fields added to the output. Unless
@@ -424,15 +445,30 @@ If a UTC timezone can be detected in the text of the command output, the
 timestamp will be timezone aware and have a `_utc` suffix on the key name.
 (e.g. `epoch_utc`) No other timezones are supported for aware timestamps.
 
+## Use In Other Shells
+`jc` can be used in most any shell. Some modern shells have JSON deserialization
+and filtering capabilities built-in which makes using `jc` even more convenient.
+
+For example, the following is possible in [NGS](https://ngs-lang.org/)
+(Next Generation Shell):
+```bash
+myvar = ``jc dig www.google.com``[0].answer[0].data
+```
+This runs `jc`, parses the output JSON, and assigs the resulting data structure
+to a variable in a single line of code.
+
+For more examples of how to use `jc` in other shells, see this
+[wiki page](https://github.com/kellyjonbrazil/jc/wiki/Using-jc-With-Different-Shells).
+
 ## Compatibility
 Some parsers like `dig`, `xml`, `csv`, etc. will work on any platform. Other
 parsers that convert platform-specific output will generate a warning message if
 they are run on an unsupported platform. To see all parser information,
 including compatibility, run `jc -ap`.
 
-You may still use a parser on an unsupported platform - for example, you may want
-to parse a file with linux `lsof` output on an macOS or Windows laptop. In that
-case you can suppress the warning message with the `-q` cli option or the
+You may still use a parser on an unsupported platform - for example, you may
+want to parse a file with linux `lsof` output on an macOS or Windows laptop. In
+that case you can suppress the warning message with the `-q` cli option or the
 `quiet=True` function parameter in `parse()`:
 
 macOS:
@@ -461,7 +497,8 @@ Tested on:
 ## Contributions
 Feel free to add/improve code or parsers! You can use the
 [`jc/parsers/foo.py`](https://github.com/kellyjonbrazil/jc/blob/master/jc/parsers/foo.py)
-or [`jc/parsers/foo_s.py (streaming)`](https://github.com/kellyjonbrazil/jc/blob/master/jc/parsers/foo_s.py) parsers as a template and submit your parser with a pull request.
+or [`jc/parsers/foo_s.py (streaming)`](https://github.com/kellyjonbrazil/jc/blob/master/jc/parsers/foo_s.py) parsers as a template and submit your parser with a pull
+request.
 
 Please see the [Contributing Guidelines](https://github.com/kellyjonbrazil/jc/blob/master/CONTRIBUTING.md) for more information.
 

docgen.sh

@@ -76,20 +76,30 @@ EOF
 )
 
 cd jc
-echo Building docs for: package
-pydoc-markdown -m jc "${readme_config}" > ../docs/readme.md
+(
+    echo Building docs for: package
+    pydoc-markdown -m jc "${readme_config}" > ../docs/readme.md; echo "+++ package docs complete"
+) &
 
-echo Building docs for: lib
-pydoc-markdown -m jc.lib "${toc_config}" > ../docs/lib.md
+(
+    echo Building docs for: lib
+    pydoc-markdown -m jc.lib "${toc_config}" > ../docs/lib.md; echo "+++ lib docs complete"
+) &
 
-echo Building docs for: utils
-pydoc-markdown -m jc.utils "${toc_config}" > ../docs/utils.md
+(
+    echo Building docs for: utils
+    pydoc-markdown -m jc.utils "${toc_config}" > ../docs/utils.md; echo "+++ utils docs complete"
+) &
 
-echo Building docs for: streaming
-pydoc-markdown -m jc.streaming "${toc_config}" > ../docs/streaming.md
+(
+    echo Building docs for: streaming
+    pydoc-markdown -m jc.streaming "${toc_config}" > ../docs/streaming.md; echo "+++ streaming docs complete"
+) &
 
-echo Building docs for: universal parser
-pydoc-markdown -m jc.parsers.universal "${toc_config}" > ../docs/parsers/universal.md
+(
+    echo Building docs for: universal parser
+    pydoc-markdown -m jc.parsers.universal "${toc_config}" > ../docs/parsers/universal.md; echo "+++ universal parser docs complete"
+) &
 
 # a bit of inception here... jc is being used to help
 # automate the generation of its own documentation. :)
@@ -103,7 +113,7 @@ do
 done < <(jc -a | jq -c '.parsers[] | select(.plugin != true)')
 
 for parser in "${parsers[@]}"
-do
+do (
     parser_name=$(jq -r '.name' <<< "$parser")
     compatible=$(jq -r '.compatible | join(", ")' <<< "$parser")
     version=$(jq -r '.version' <<< "$parser")
@@ -117,4 +127,8 @@ do
     echo "Compatibility:  ${compatible}" >> ../docs/parsers/"${parser_name}".md
     echo >> ../docs/parsers/"${parser_name}".md
     echo "Version ${version} by ${author} (${author_email})" >> ../docs/parsers/"${parser_name}".md
+    echo "+++ ${parser_name} docs complete"
+) &
 done
+wait
+echo "Document Generation Complete"

docs/lib.md

@@ -14,8 +14,7 @@
 
 # jc.lib
 
-jc - JSON Convert
-JC lib module
+jc - JSON Convert lib module
 
 <a id="jc.lib.parse"></a>
 
@@ -69,7 +68,7 @@ Parameters:
                                      variants of the module name.
 
     data:               (string or   data to parse (string for normal
-                        iterator)    parsers, iterator of strings for
+                        iterable)    parsers, iterable of strings for
                                      streaming parsers)
 
     raw:                (boolean)    output preprocessed JSON if True
@@ -133,23 +132,34 @@ subset of `parser_mod_list()`.
 ### parser\_info
 
 ```python
-def parser_info(parser_mod_name: str) -> Dict
+def parser_info(parser_mod_name: str, documentation: bool = False) -> Dict
 ```
 
-Returns a dictionary that includes the module metadata.
+Returns a dictionary that includes the parser module metadata.
 
-This function will accept **module_name**, **cli-name**, and
-**--argument-name** variants of the module name string.
+Parameters:
+
+    parser_mod_name:    (string)     name of the parser module. This
+                                     function will accept module_name,
+                                     cli-name, and --argument-name
+                                     variants of the module name.
+
+    documentation:      (boolean)    include parser docstring if True
 
 <a id="jc.lib.all_parser_info"></a>
 
 ### all\_parser\_info
 
 ```python
-def all_parser_info() -> List[Dict]
+def all_parser_info(documentation: bool = False) -> List[Dict]
 ```
 
-Returns a list of dictionaries that includes metadata for all modules.
+Returns a list of dictionaries that includes metadata for all parser
+modules.
+
+Parameters:
+
+    documentation:      (boolean)    include parser docstrings if True
 
 <a id="jc.lib.get_help"></a>
 

docs/parsers/acpi.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('acpi', acpi_command_output)
 
-    or
-
-    import jc.parsers.acpi
-    result = jc.parsers.acpi.parse(acpi_command_output)
-
 Schema:
 
     [

docs/parsers/airport.md

@@ -20,11 +20,6 @@ Usage (module):
     import jc
     result = jc.parse('airport', airport_command_output)
 
-    or
-
-    import jc.parsers.airport
-    result = jc.parsers.airport.parse(airport_command_output)
-
 Schema:
 
     {

docs/parsers/airport_s.md

@@ -20,11 +20,6 @@ Usage (module):
     import jc
     result = jc.parse('airport_s', airport_s_command_output)
 
-    or
-
-    import jc.parsers.airport_s
-    result = jc.parsers.airport_s.parse(airport_s_command_output)
-
 Schema:
 
     [

docs/parsers/arp.md

@@ -20,11 +20,6 @@ Usage (module):
     import jc
     result = jc.parse('arp', arp_command_output)
 
-    or
-
-    import jc.parsers.arp
-    result = jc.parsers.arp.parse(arp_command_output)
-
 Schema:
 
     [
@@ -127,7 +122,7 @@ Examples:
 ### parse
 
 ```python
-def parse(data, raw=False, quiet=False)
+def parse(data: str, raw: bool = False, quiet: bool = False) -> List[Dict]
 ```
 
 Main text parsing function
@@ -145,4 +140,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, aix, freebsd, darwin
 
-Version 1.8 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.9 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/asciitable.md

@@ -0,0 +1,144 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.asciitable"></a>
+
+# jc.parsers.asciitable
+
+jc - JSON Convert `asciitable` parser
+
+This parser converts ASCII and Unicode text tables with single-line rows.
+
+Column headers must be at least two spaces apart from each other and must
+be unique. For best results, column headers should be left-justified. If
+column separators are present, then non-left-justified headers will be fixed
+automatically.
+
+Row separators are optional and are ignored. Each non-row-separator line is
+considered a separate row in the table.
+
+For example:
+
+    ╒══════════╤═════════╤════════╕
+    │ foo      │ bar     │ baz    │
+    ╞══════════╪═════════╪════════╡
+    │ good day │         │ 12345  │
+    ├──────────┼─────────┼────────┤
+    │ hi there │ abc def │ 3.14   │
+    ╘══════════╧═════════╧════════╛
+
+or
+
+    +-----------------------------+
+    | foo        bar       baz    |
+    +-----------------------------+
+    | good day             12345  |
+    | hi there   abc def   3.14   |
+    +-----------------------------+
+
+or
+
+    | foo      | bar     | baz    |
+    |----------|---------|--------|
+    | good day |         | 12345  |
+    | hi there | abc def | 3.14   |
+
+or
+
+    foo        bar       baz
+    ---------  --------  ------
+    good day             12345
+    hi there   abc def   3.14
+
+or
+
+    foo        bar       baz
+    good day             12345
+    hi there   abc def   3.14
+
+etc...
+
+Headers (keys) are converted to snake-case. All values are returned as
+strings, except empty strings, which are converted to None/null.
+
+Usage (cli):
+
+    $ cat table.txt | jc --asciitable
+
+Usage (module):
+
+    import jc
+    result = jc.parse('asciitable', asciitable_string)
+
+Schema:
+
+    [
+      {
+        "column_name1":     string,    # empty string is null
+        "column_name2":     string     # empty string is null
+      }
+    ]
+
+Examples:
+
+    $ echo '
+    >     ╒══════════╤═════════╤════════╕
+    >     │ foo      │ bar     │ baz    │
+    >     ╞══════════╪═════════╪════════╡
+    >     │ good day │         │ 12345  │
+    >     ├──────────┼─────────┼────────┤
+    >     │ hi there │ abc def │ 3.14   │
+    >     ╘══════════╧═════════╧════════╛' | jc --asciitable -p
+    [
+      {
+        "foo": "good day",
+        "bar": null,
+        "baz": "12345"
+      },
+      {
+        "foo": "hi there",
+        "bar": "abc def",
+        "baz": "3.14"
+      }
+    ]
+
+    $ echo '
+    >     foo        bar       baz
+    >     ---------  --------  ------
+    >     good day             12345
+    >     hi there   abc def   3.14'  | jc --asciitable -p
+    [
+      {
+        "foo": "good day",
+        "bar": null,
+        "baz": "12345"
+      },
+      {
+        "foo": "hi there",
+        "bar": "abc def",
+        "baz": "3.14"
+      }
+    ]
+
+<a id="jc.parsers.asciitable.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, cygwin, win32, aix, freebsd
+
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/asciitable_m.md

@@ -0,0 +1,129 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.asciitable_m"></a>
+
+# jc.parsers.asciitable\_m
+
+jc - JSON Convert `asciitable-m` parser
+
+This parser converts various styles of ASCII and Unicode text tables with
+multi-line rows. Tables must have a header row and separator line between
+rows.
+
+For example:
+
+    ╒══════════╤═════════╤════════╕
+    │ foo      │ bar baz │ fiz    │
+    │          │         │ buz    │
+    ╞══════════╪═════════╪════════╡
+    │ good day │ 12345   │        │
+    │ mate     │         │        │
+    ├──────────┼─────────┼────────┤
+    │ hi there │ abc def │ 3.14   │
+    │          │         │        │
+    ╘══════════╧═════════╧════════╛
+
+Cells with multiple lines within rows will be joined with a newline
+character ('\\n').
+
+Headers (keys) are converted to snake-case and newlines between multi-line
+headers are joined with an underscore. All values are returned as strings,
+except empty strings, which are converted to None/null.
+
+> Note: table column separator characters (e.g. `|`) cannot be present
+> inside the cell data. If detected, a warning message will be printed to
+> `STDERR` and the line will be skipped. The warning message can be
+> suppressed by using the `-q` command option or by setting `quiet=True` in
+> `parse()`.
+
+Usage (cli):
+
+    $ cat table.txt | jc --asciitable-m
+
+Usage (module):
+
+    import jc
+    result = jc.parse('asciitable_m', asciitable-string)
+
+Schema:
+
+    [
+      {
+        "column_name1":     string,    # empty string is null
+        "column_name2":     string     # empty string is null
+      }
+    ]
+
+Examples:
+
+    $ echo '
+    > +----------+---------+--------+
+    > | foo      | bar     | baz    |
+    > |          |         | buz    |
+    > +==========+=========+========+
+    > | good day | 12345   |        |
+    > | mate     |         |        |
+    > +----------+---------+--------+
+    > | hi there | abc def | 3.14   |
+    > |          |         |        |
+    > +==========+=========+========+' | jc --asciitable-m -p
+    [
+      {
+        "foo": "good day\\nmate",
+        "bar": "12345",
+        "baz_buz": null
+      },
+      {
+        "foo": "hi there",
+        "bar": "abc def",
+        "baz_buz": "3.14"
+      }
+    ]
+
+    $ echo '
+    > ╒══════════╤═════════╤════════╕
+    > │ foo      │ bar     │ baz    │
+    > │          │         │ buz    │
+    > ╞══════════╪═════════╪════════╡
+    > │ good day │ 12345   │        │
+    > │ mate     │         │        │
+    > ├──────────┼─────────┼────────┤
+    > │ hi there │ abc def │ 3.14   │
+    > │          │         │        │
+    > ╘══════════╧═════════╧════════╛' | jc --asciitable-m -p
+    [
+      {
+        "foo": "good day\\nmate",
+        "bar": "12345",
+        "baz_buz": null
+      },
+      {
+        "foo": "hi there",
+        "bar": "abc def",
+        "baz_buz": "3.14"
+      }
+    ]
+
+<a id="jc.parsers.asciitable_m.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, cygwin, win32, aix, freebsd
+
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/blkid.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('blkid', blkid_command_output)
 
-    or
-
-    import jc.parsers.blkid
-    result = jc.parsers.blkid.parse(blkid_command_output)
-
 Schema:
 
     [

docs/parsers/chage.md

@@ -0,0 +1,82 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.chage"></a>
+
+# jc.parsers.chage
+
+jc - JSON Convert `chage --list` command output parser
+
+Supports `chage -l <username>` or `chage --list <username>`
+
+Usage (cli):
+
+    $ chage -l johndoe | jc --chage
+
+    or
+
+    $ jc chage -l johndoe
+
+Usage (module):
+
+    import jc
+    result = jc.parse('chage', chage_command_output)
+
+Schema:
+
+    {
+      "password_last_changed":                      string,
+      "password_expires":                           string,
+      "password_inactive":                          string,
+      "account_expires":                            string,
+      "min_days_between_password_change":           integer,
+      "max_days_between_password_change":           integer,
+      "warning_days_before_password_expires":       integer
+    }
+
+Examples:
+
+    $ chage --list joeuser | jc --chage -p
+    {
+      "password_last_changed": "never",
+      "password_expires": "never",
+      "password_inactive": "never",
+      "account_expires": "never",
+      "min_days_between_password_change": 0,
+      "max_days_between_password_change": 99999,
+      "warning_days_before_password_expires": 7
+    }
+
+    $ chage --list joeuser | jc --chage -p -r
+    {
+      "password_last_changed": "never",
+      "password_expires": "never",
+      "password_inactive": "never",
+      "account_expires": "never",
+      "min_days_between_password_change": "0",
+      "max_days_between_password_change": "99999",
+      "warning_days_before_password_expires": "7"
+    }
+
+<a id="jc.parsers.chage.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
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/cksum.md

@@ -22,11 +22,6 @@ Usage (module):
     import jc
     result = jc.parse('cksum', cksum_command_output)
 
-    or
-
-    import jc.parsers.cksum
-    result = jc.parsers.cksum.parse(cksum_command_output)
-
 Schema:
 
     [

docs/parsers/crontab.md

@@ -21,11 +21,6 @@ Usage (module):
     import jc
     result = jc.parse('crontab', crontab_output)
 
-    or
-
-    import jc.parsers.crontab
-    result = jc.parsers.crontab.parse(crontab_output)
-
 Schema:
 
     {

docs/parsers/crontab_u.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('crontab_u', crontab_u_output)
 
-    or
-
-    import jc.parsers.crontab_u
-    result = jc.parsers.crontab_u.parse(crontab_u_output)
-
 Schema:
 
     {

docs/parsers/csv.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('csv', csv_output)
 
-    or
-
-    import jc.parsers.csv
-    result = jc.parsers.csv.parse(csv_output)
-
 Schema:
 
     csv file converted to a Dictionary:

docs/parsers/csv_s.md

@@ -5,14 +5,15 @@
 
 jc - JSON Convert `csv` file streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
 
 The `csv` streaming parser will attempt to automatically detect the
 delimiter character. If the delimiter cannot be detected it will default
 to comma. The first row of the file must be a header row.
 
-Note: The first 100 rows are read into memory to enable delimiter detection,
-then the rest of the rows are loaded lazily.
+> Note: The first 100 rows are read into memory to enable delimiter
+> detection, then the rest of the rows are loaded lazily.
 
 Usage (cli):
 
@@ -21,19 +22,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # result is an iterable object (generator)
+
     result = jc.parse('csv_s', csv_output.splitlines())
     for item in result:
         # do something
 
-    or
-
-    import jc.parsers.csv_s
-    # result is an iterable object (generator)
-    result = jc.parsers.csv_s.parse(csv_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     csv file converted to a Dictionary:
@@ -44,13 +37,11 @@ Schema:
       "column_name2":     string,
 
       # 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
-        }
+      "_jc_meta": {
+        "success":        boolean,     # false if error parsing
+        "error":          string,      # exists if "success" is false
+        "line":           string       # exists if "success" is false
+      }
     }
 
 Examples:
@@ -77,7 +68,7 @@ Examples:
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
-Main text parsing generator function. Returns an iterator object.
+Main text parsing generator function. Returns an iterable object.
 
 Parameters:
 
@@ -88,13 +79,9 @@ Parameters:
     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)
+    Iterable of Dictionaries
 
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd

docs/parsers/date.md

@@ -24,11 +24,6 @@ Usage (module):
     import jc
     result = jc.parse('date', date_command_output)
 
-    or
-
-    import jc.parsers.date
-    result = jc.parsers.date.parse(date_command_output)
-
 Schema:
 
     {
@@ -105,4 +100,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 2.3 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 2.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/df.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('df', df_command_output)
 
-    or
-
-    import jc.parsers.df
-    result = jc.parsers.df.parse(df_command_output)
-
 Schema:
 
     [
@@ -125,4 +120,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 1.9 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.10 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/dig.md

@@ -29,11 +29,6 @@ Usage (module):
     import jc
     result = jc.parse('dig', dig_command_output)
 
-    or
-
-    import jc.parsers.dig
-    result = jc.parsers.dig.parse(dig_command_output)
-
 Schema:
 
     [

docs/parsers/dir.md

@@ -19,18 +19,13 @@ time of the system the parser is run on)
 
 Usage (cli):
 
-    C:> dir | jc --dir
+    C:\> dir | jc --dir
 
 Usage (module):
 
     import jc
     result = jc.parse('dir', dir_command_output)
 
-    or
-
-    import jc.parsers.dir
-    result = jc.parsers.dir.parse(dir_command_output)
-
 Schema:
 
     [
@@ -47,7 +42,7 @@ Schema:
 
 Examples:
 
-    C:> dir | jc --dir -p
+    C:\> dir | jc --dir -p
     [
       {
         "date": "03/24/2021",
@@ -88,7 +83,7 @@ Examples:
       ...
     ]
 
-    C:> dir | jc --dir -p -r
+    C:\> dir | jc --dir -p -r
     [
       {
         "date": "03/24/2021",

docs/parsers/dmidecode.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('dmidecode', dmidecode_command_output)
 
-    or
-
-    import jc.parsers.dmidecode
-    result = jc.parsers.dmidecode.parse(dmidecode_command_output)
-
 Schema:
 
     [

docs/parsers/dpkg_l.md

@@ -23,11 +23,6 @@ Usage (module):
     import jc
     result = jc.parse('dpkg_l', dpkg_command_output)
 
-    or
-
-    import jc.parsers.dpkg_l
-    result = jc.parsers.dpkg_l.parse(dpkg_command_output)
-
 Schema:
 
     [

docs/parsers/du.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('du', du_command_output)
 
-    or
-
-    import jc.parsers.du
-    result = jc.parsers.du.parse(du_command_output)
-
 Schema:
 
     [

docs/parsers/env.md

@@ -23,11 +23,6 @@ Usage (module):
     import jc
     result = jc.parse('env', env_command_output)
 
-    or
-
-    import jc.parsers.env
-    result = jc.parsers.env.parse(env_command_output)
-
 Schema:
 
     [

docs/parsers/file.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('file', file_command_output)
 
-    or
-
-    import jc.parsers.file
-    result = jc.parsers.file.parse(file_command_output)
-
 Schema:
 
     [

docs/parsers/finger.md

@@ -20,11 +20,6 @@ Usage (module):
     import jc
     result = jc.parse('finger', finger_command_output)
 
-    or
-
-    import jc.parsers.finger
-    result = jc.parsers.finger.parse(finger_command_output)
-
 Schema:
 
     [

docs/parsers/free.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('free', free_command_output)
 
-    or
-
-    import jc.parsers.free
-    result = jc.parsers.free.parse(free_command_output)
-
 Schema:
 
     [

docs/parsers/fstab.md

@@ -14,11 +14,6 @@ Usage (module):
     import jc
     result = jc.parse('fstab', fstab_command_output)
 
-    or
-
-    import jc.parsers.fstab
-    result = jc.parsers.fstab.parse(fstab_command_output)
-
 Schema:
 
     [

docs/parsers/git_log.md

@@ -0,0 +1,175 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.git_log"></a>
+
+# jc.parsers.git\_log
+
+jc - JSON Convert `git log` command output parser
+
+Can be used with the following format options:
+- `oneline`
+- `short`
+- `medium`
+- `full`
+- `fuller`
+
+Additional options supported:
+- `--stat`
+- `--shortstat`
+
+The `epoch` calculated timestamp field is naive. (i.e. based on the
+local time of the system the parser is run on)
+
+The `epoch_utc` calculated timestamp field is timezone-aware and is
+only available if the timezone field is UTC.
+
+Usage (cli):
+
+    $ git log | jc --git-log
+
+    or
+
+    $ jc git log
+
+Usage (module):
+
+    import jc
+    result = jc.parse('git_log', git_log_command_output)
+
+Schema:
+
+    [
+      {
+        "commit":               string,
+        "author":               string,
+        "author_email":         string,
+        "date":                 string,
+        "epoch":                integer,  # [0]
+        "epoch_utc":            integer,  # [1]
+        "commit_by":            string,
+        "commit_by_email":      string,
+        "commit_by_date":       string,
+        "message":              string,
+        "stats" : {
+          "files_changed":      integer,
+          "insertions":         integer,
+          "deletions":          integer,
+          "files": [
+                                string
+          ]
+        }
+      }
+    ]
+
+    [0] naive timestamp if "date" field is parsable, else null
+    [1] timezone aware timestamp availabe for UTC, else null
+
+Examples:
+
+    $ git log --stat | jc --git-log -p
+    [
+      {
+        "commit": "728d882ed007b3c8b785018874a0eb06e1143b66",
+        "author": "Kelly Brazil",
+        "author_email": "kellyjonbrazil@gmail.com",
+        "date": "Wed Apr 20 09:50:19 2022 -0400",
+        "stats": {
+          "files_changed": 2,
+          "insertions": 90,
+          "deletions": 12,
+          "files": [
+            "docs/parsers/git_log.md",
+            "jc/parsers/git_log.py"
+          ]
+        },
+        "message": "add timestamp docs and examples",
+        "epoch": 1650462619,
+        "epoch_utc": null
+      },
+      {
+        "commit": "b53e42aca623181aa9bc72194e6eeef1e9a3a237",
+        "author": "Kelly Brazil",
+        "author_email": "kellyjonbrazil@gmail.com",
+        "date": "Wed Apr 20 09:44:42 2022 -0400",
+        "stats": {
+          "files_changed": 5,
+          "insertions": 29,
+          "deletions": 6,
+          "files": [
+            "docs/parsers/git_log.md",
+            "docs/utils.md",
+            "jc/parsers/git_log.py",
+            "jc/utils.py",
+            "man/jc.1"
+          ]
+        },
+        "message": "add calculated timestamp",
+        "epoch": 1650462282,
+        "epoch_utc": null
+      },
+      ...
+    ]
+
+    $ git log --stat | jc --git-log -p -r
+    [
+      {
+        "commit": "728d882ed007b3c8b785018874a0eb06e1143b66",
+        "author": "Kelly Brazil",
+        "author_email": "kellyjonbrazil@gmail.com",
+        "date": "Wed Apr 20 09:50:19 2022 -0400",
+        "stats": {
+          "files_changed": "2",
+          "insertions": "90",
+          "deletions": "12",
+          "files": [
+            "docs/parsers/git_log.md",
+            "jc/parsers/git_log.py"
+          ]
+        },
+        "message": "add timestamp docs and examples"
+      },
+      {
+        "commit": "b53e42aca623181aa9bc72194e6eeef1e9a3a237",
+        "author": "Kelly Brazil",
+        "author_email": "kellyjonbrazil@gmail.com",
+        "date": "Wed Apr 20 09:44:42 2022 -0400",
+        "stats": {
+          "files_changed": "5",
+          "insertions": "29",
+          "deletions": "6",
+          "files": [
+            "docs/parsers/git_log.md",
+            "docs/utils.md",
+            "jc/parsers/git_log.py",
+            "jc/utils.py",
+            "man/jc.1"
+          ]
+        },
+        "message": "add calculated timestamp"
+      },
+      ...
+    ]
+
+<a id="jc.parsers.git_log.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, cygwin, win32, aix, freebsd
+
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/git_log_s.md

@@ -0,0 +1,111 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.git_log_s"></a>
+
+# jc.parsers.git\_log\_s
+
+jc - JSON Convert `git log` command output streaming parser
+
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
+
+Can be used with the following format options:
+- `oneline`
+- `short`
+- `medium`
+- `full`
+- `fuller`
+
+Additional options supported:
+- `--stat`
+- `--shortstat`
+
+The `epoch` calculated timestamp field is naive. (i.e. based on the
+local time of the system the parser is run on)
+
+The `epoch_utc` calculated timestamp field is timezone-aware and is
+only available if the timezone field is UTC.
+
+Usage (cli):
+
+    $ git log | jc --git-log-s
+
+Usage (module):
+
+    import jc
+
+    result = jc.parse('git_log_s', git_log_command_output.splitlines())
+    for item in result:
+        # do something
+
+Schema:
+
+    {
+      "commit":               string,
+      "author":               string,
+      "author_email":         string,
+      "date":                 string,
+      "epoch":                integer,  # [0]
+      "epoch_utc":            integer,  # [1]
+      "commit_by":            string,
+      "commit_by_email":      string,
+      "commit_by_date":       string,
+      "message":              string,
+      "stats" : {
+        "files_changed":      integer,
+        "insertions":         integer,
+        "deletions":          integer,
+        "files": [
+                              string
+        ]
+      }
+
+      # 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] naive timestamp if "date" field is parsable, else null
+    [1] timezone aware timestamp availabe for UTC, else null
+
+Examples:
+
+    $ git log | jc --git-log-s
+    {"commit":"a730ae18c8e81c5261db132df73cd74f272a0a26","author":"Kelly...}
+    {"commit":"930bf439c06c48a952baec05a9896c8d92b7693e","author":"Kelly...}
+    ...
+
+<a id="jc.parsers.git_log_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 iterable 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
+
+
+Returns:
+
+    Iterable of Dictionaries
+
+### Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/group.md

@@ -14,11 +14,6 @@ Usage (module):
     import jc
     result = jc.parse('group', group_file_output)
 
-    or
-
-    import jc.parsers.group
-    result = jc.parsers.group.parse(group_file_output)
-
 Schema:
 
     [

docs/parsers/gshadow.md

@@ -14,11 +14,6 @@ Usage (module):
     import jc
     result = jc.parse('gshadow', gshadow_file_output)
 
-    or
-
-    import jc.parsers.gshadow
-    result = jc.parsers.gshadow.parse(gshadow_file_output)
-
 Schema:
 
     [

docs/parsers/hash.md

@@ -14,11 +14,6 @@ Usage (module):
     import jc
     result = jc.parse('hash', hash_command_output)
 
-    or
-
-    import jc.parsers.hash
-    result = jc.parsers.hash.parse(hash_command_output)
-
 Schema:
 
     [

docs/parsers/hashsum.md

@@ -28,11 +28,6 @@ Usage (module):
     import jc
     result = jc.parse('hashsum', md5sum_command_output)
 
-    or
-
-    import jc.parsers.hashsum
-    result = jc.parsers.hashsum.parse(md5sum_command_output)
-
 Schema:
 
     [

docs/parsers/hciconfig.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('hciconfig', hciconfig_command_output)
 
-    or
-
-    import jc.parsers.hciconfig
-    result = jc.parsers.hciconfig.parse(hciconfig_command_output)
-
 Schema:
 
     [

docs/parsers/history.md

@@ -22,11 +22,6 @@ Usage (module):
     import jc
     result = jc.parse('history', history_command_output)
 
-    or
-
-    import jc.parsers.history
-    result = jc.parsers.history.parse(history_command_output)
-
 Schema:
 
     [
@@ -92,4 +87,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, aix, freebsd
 
-Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.7 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/hosts.md

@@ -14,11 +14,6 @@ Usage (module):
     import jc
     result = jc.parse('hosts', hosts_file_output)
 
-    or
-
-    import jc.parsers.hosts
-    result = jc.parsers.hosts.parse(hosts_file_output)
-
 Schema:
 
     [

docs/parsers/id.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('id', id_command_output)
 
-    or
-
-    import jc.parsers.id
-    result = jc.parsers.id.parse(id_command_output)
-
 Schema:
 
     {

docs/parsers/ifconfig.md

@@ -5,7 +5,7 @@
 
 jc - JSON Convert `ifconfig` command output parser
 
-Note: No `ifconfig` options are supported.
+> Note: No `ifconfig` options are supported.
 
 Usage (cli):
 
@@ -20,11 +20,6 @@ Usage (module):
     import jc
     result = jc.parse('ifconfig', ifconfig_command_output)
 
-    or
-
-    import jc.parsers.ifconfig
-    result = jc.parsers.ifconfig.parse(ifconfig_command_output)
-
 Schema:
 
     [

docs/parsers/ini.md

@@ -6,12 +6,14 @@
 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
-can be `#` or `;`. Comments must be on their own line.
 
-Note: Values starting and ending with quotation marks will have the marks
-removed. If you would like to keep the quotation marks, use the `-r`
-command-line argument or the `raw=True` argument in `parse()`.
+- Delimiter can be `=` or `:`. Missing values are supported.
+- Comment prefix can be `#` or `;`. Comments must be on their own line.
+- If duplicate keys are found, only the last value will be used.
+
+> Note: Values starting and ending with quotation marks will have the marks
+> removed. If you would like to keep the quotation marks, use the `-r`
+> command-line argument or the `raw=True` argument in `parse()`.
 
 Usage (cli):
 
@@ -22,15 +24,10 @@ Usage (module):
     import jc
     result = jc.parse('ini', ini_file_output)
 
-    or
-
-    import jc.parsers.ini
-    result = jc.parsers.ini.parse(ini_file_output)
-
 Schema:
 
-    ini or key/value document converted to a dictionary - see the
-    configparser standard library documentation for more details.
+ini or key/value document converted to a dictionary - see the configparser
+standard library documentation for more details.
 
     {
       "key1":       string,
@@ -94,4 +91,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
 
-Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/iostat.md

@@ -5,7 +5,7 @@
 
 jc - JSON Convert `iostat` command output parser
 
-Note: `iostat` version 11 and higher include a JSON output option
+> Note: `iostat` version 11 and higher include a JSON output option
 
 Usage (cli):
 
@@ -20,11 +20,6 @@ Usage (module):
     import jc
     result = jc.parse('iostat', iostat_command_output)
 
-    or
-
-    import jc.parsers.iostat
-    result = jc.parsers.iostat.parse(iostat_command_output)
-
 Schema:
 
     [

docs/parsers/iostat_s.md

@@ -5,30 +5,30 @@
 
 jc - JSON Convert `iostat` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
 
-Note: `iostat` version 11 and higher include a JSON output option
+> Note: `iostat` version 11 and higher include a JSON output option
 
 Usage (cli):
 
     $ iostat | jc --iostat-s
 
+> Note: When piping `jc` converted `iostat` output to other processes it may
+> appear the output is hanging due to the OS pipe buffers. This is because
+> `iostat` output is too small to quickly fill up the buffer. Use the `-u`
+> option to unbuffer the `jc` output if you would like immediate output. See
+> the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output)
+> for more information.
+
 Usage (module):
 
     import jc
-    # result is an iterable object (generator)
+
     result = jc.parse('iostat_s', iostat_command_output.splitlines())
     for item in result:
         # do something
 
-    or
-
-    import jc.parsers.iostat_s
-    # result is an iterable object (generator)
-    result = jc.parsers.iostat_s.parse(iostat_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {
@@ -83,14 +83,12 @@ Schema:
       "percent_rrqm":     float,
       "percent_wrqm":     float,
 
-      # 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
-        }
+      # 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
+      }
     }
 
 Examples:
@@ -114,7 +112,7 @@ Examples:
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
-Main text parsing generator function. Returns an iterator object.
+Main text parsing generator function. Returns an iterable object.
 
 Parameters:
 
@@ -125,13 +123,9 @@ Parameters:
     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)
+    Iterable of Dictionaries
 
 ### Parser Information
 Compatibility:  linux

docs/parsers/iptables.md

@@ -20,11 +20,6 @@ Usage (module):
     import jc
     result = jc.parse('iptables', iptables_command_output)
 
-    or
-
-    import jc.parsers.iptables
-    result = jc.parsers.iptables.parse(iptables_command_output)
-
 Schema:
 
     [

docs/parsers/iw_scan.md

@@ -21,11 +21,6 @@ Usage (module):
     import jc
     result = jc.parse('iw_scan', iw_scan_command_output)
 
-    or
-
-    import jc.parsers.iw_scan
-    result = jc.parsers.iw_scan.parse(iw_scan_command_output)
-
 Schema:
 
     [

docs/parsers/jar_manifest.md

@@ -14,11 +14,6 @@ Usage (module):
     import jc
     result = jc.parse('jar_manifest', jar_manifest_file_output)
 
-    or
-
-    import jc.parsers.jar_manifest
-    result = jc.parsers.jar_manifest.parse(jar_manifest_file_output)
-
 Schema:
 
     [

docs/parsers/jobs.md

@@ -19,11 +19,6 @@ Usage (module):
     import jc
     result = jc.parse('jobs', jobs_command_output)
 
-    or
-
-    import jc.parsers.jobs
-    result = jc.parsers.jobs.parse(jobs_command_output)
-
 Schema:
 
     [

docs/parsers/kv.md

@@ -5,13 +5,15 @@
 
 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 `;`.
-Comments must be on their own line.
+Supports files containing simple key/value pairs.
 
-Note: Values starting and ending with quotation marks will have the marks
-removed. If you would like to keep the quotation marks, use the `-r`
-command-line argument or the `raw=True` argument in `parse()`.
+- Delimiter can be `=` or `:`. Missing values are supported.
+- Comment prefix can be `#` or `;`. Comments must be on their own line.
+- If duplicate keys are found, only the last value will be used.
+
+> Note: Values starting and ending with quotation marks will have the marks
+> removed. If you would like to keep the quotation marks, use the `-r`
+> command-line argument or the `raw=True` argument in `parse()`.
 
 Usage (cli):
 
@@ -22,15 +24,10 @@ Usage (module):
     import jc
     result = jc.parse('kv', kv_file_output)
 
-    or
-
-    import jc.parsers.kv
-    result = jc.parsers.kv.parse(kv_file_output)
-
 Schema:
 
-    key/value document converted to a dictionary - see the
-    configparser standard library documentation for more details.
+key/value document converted to a dictionary - see the configparser standard
+library documentation for more details.
 
     {
       "key1":       string,
@@ -83,4 +80,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
 
-Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/last.md

@@ -24,11 +24,6 @@ Usage (module):
     import jc
     result = jc.parse('last', last_command_output)
 
-    or
-
-    import jc.parsers.last
-    result = jc.parsers.last.parse(last_command_output)
-
 Schema:
 
     [

docs/parsers/ls.md

@@ -9,11 +9,12 @@ Options supported:
 - `lbaR1`
 - `--time-style=full-iso`
 
-Note: The `-1`, `-l`, or `-b` option of `ls` should be used to correctly
-parse filenames that include newline characters. Since `ls` does not encode
-newlines in filenames when outputting to a pipe it will cause `jc` to see
-multiple files instead of a single file if `-1`, `-l`, or `-b` is not used.
-Alternatively, `vdir` can be used, which is the same as running `ls -lb`.
+> Note: The `-1`, `-l`, or `-b` option of `ls` should be used to correctly
+> parse filenames that include newline characters. Since `ls` does not
+> encode newlines in filenames when outputting to a pipe it will cause `jc`
+> to see multiple files instead of a single file if `-1`, `-l`, or `-b` is
+> not used. Alternatively, `vdir` can be used, which is the same as running
+> `ls -lb`.
 
 The `epoch` calculated timestamp field is naive. (i.e. based on the local
 time of the system the parser is run on)
@@ -34,11 +35,6 @@ Usage (module):
     import jc
     result = jc.parse('ls', ls_command_output)
 
-    or
-
-    import jc.parsers.ls
-    result = jc.parsers.ls.parse(ls_command_output)
-
 Schema:
 
     [

docs/parsers/ls_s.md

@@ -3,10 +3,10 @@
 
 # jc.parsers.ls\_s
 
-jc - JSON Convert `ls` and `vdir` command output streaming
-parser
+jc - JSON Convert `ls` and `vdir` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
 
 Requires the `-l` option to be used on `ls`. If there are newline characters
 in the filename, then make sure to use the `-b` option on `ls`.
@@ -27,19 +27,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # result is an iterable object (generator)
+
     result = jc.parse('ls_s', ls_command_output.splitlines())
     for item in result:
         # do something
 
-    or
-
-    import jc.parsers.ls_s
-    # result is an iterable object (generator)
-    result = jc.parsers.ls_s.parse(ls_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {
@@ -54,14 +46,12 @@ Schema:
       "epoch":          integer,     # [0]
       "epoch_utc":      integer,     # [1]
 
-      # 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
-        }
+      # 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] naive timestamp if date field exists and can be converted.
@@ -91,7 +81,7 @@ Examples:
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
-Main text parsing generator function. Returns an iterator object.
+Main text parsing generator function. Returns an iterable object.
 
 Parameters:
 
@@ -102,13 +92,9 @@ Parameters:
     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)
+    Iterable of Dictionaries
 
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, aix, freebsd

docs/parsers/lsblk.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('lsblk', lsblk_command_output)
 
-    or
-
-    import jc.parsers.lsblk
-    result = jc.parsers.lsblk.parse(lsblk_command_output)
-
 Schema:
 
     [

docs/parsers/lsmod.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('lsmod', lsmod_command_output)
 
-    or
-
-    import jc.parsers.lsmod
-    result = jc.parsers.lsmod.parse(lsmod_command_output)
-
 Schema:
 
     [

docs/parsers/lsof.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('lsof', lsof_command_output)
 
-    or
-
-    import jc.parsers.lsof
-    result = jc.parsers.lsof.parse(lsof_command_output)
-
 Schema:
 
     [

docs/parsers/lsusb.md

@@ -20,16 +20,11 @@ Usage (module):
     import jc
     result = jc.parse('lsusb', lsusb_command_output)
 
-    or
-
-    import jc.parsers.lsusb
-    result = jc.parsers.lsusb.parse(lsusb_command_output)
-
 Schema:
 
-    Note: <item> object keynames are assigned directly from the lsusb
-          output. If there are duplicate <item> names in a section, only the
-          last one is converted.
+> Note: <item> object keynames are assigned directly from the lsusb
+> output. If there are duplicate <item> names in a section, only the
+> last one is converted.
 
     [
       {

docs/parsers/mount.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('mount', mount_command_output)
 
-    or
-
-    import jc.parsers.mount
-    result = jc.parsers.mount.parse(mount_command_output)
-
 Schema:
 
     [

docs/parsers/mpstat.md

@@ -0,0 +1,140 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.mpstat"></a>
+
+# jc.parsers.mpstat
+
+jc - JSON Convert `mpstat` command output parser
+
+> Note: Latest versions of `mpstat` support JSON output (v11.5.1+)
+
+Usage (cli):
+
+    $ mpstat | jc --mpstat
+
+    or
+
+    $ jc mpstat
+
+Usage (module):
+
+    import jc
+    result = jc.parse('mpstat', mpstat_command_output)
+
+Schema:
+
+    [
+      {
+        "type":               string,
+        "time":               string,
+        "cpu":                string,
+        "node":               string,
+        "average":            boolean,
+        "percent_usr":        float,
+        "percent_nice":       float,
+        "percent_sys":        float,
+        "percent_iowait":     float,
+        "percent_irq":        float,
+        "percent_soft":       float,
+        "percent_steal":      float,
+        "percent_guest":      float,
+        "percent_gnice":      float,
+        "percent_idle":       float,
+        "intr_s":             float,
+        "<x>_s":              float,      # <x> is an integer
+        "nmi_s":              float,
+        "loc_s":              float,
+        "spu_s":              float,
+        "pmi_s":              float,
+        "iwi_s":              float,
+        "rtr_s":              float,
+        "res_s":              float,
+        "cal_s":              float,
+        "tlb_s":              float,
+        "trm_s":              float,
+        "thr_s":              float,
+        "dfr_s":              float,
+        "mce_s":              float,
+        "mcp_s":              float,
+        "err_s":              float,
+        "mis_s":              float,
+        "pin_s":              float,
+        "npi_s":              float,
+        "piw_s":              float,
+        "hi_s":               float,
+        "timer_s":            float,
+        "net_tx_s":           float,
+        "net_rx_s":           float,
+        "block_s":            float,
+        "irq_poll_s":         float,
+        "block_iopoll_s":     float,
+        "tasklet_s":          float,
+        "sched_s":            float,
+        "hrtimer_s":          float,
+        "rcu_s":              float
+      }
+    ]
+
+Examples:
+
+    $ mpstat | jc --mpstat -p
+    [
+      {
+        "cpu": "all",
+        "percent_usr": 12.94,
+        "percent_nice": 0.0,
+        "percent_sys": 26.42,
+        "percent_iowait": 0.43,
+        "percent_irq": 0.0,
+        "percent_soft": 0.16,
+        "percent_steal": 0.0,
+        "percent_guest": 0.0,
+        "percent_gnice": 0.0,
+        "percent_idle": 60.05,
+        "type": "cpu",
+        "time": "01:58:14 PM"
+      }
+    ]
+
+    $ mpstat | jc --mpstat -p -r
+    [
+      {
+        "cpu": "all",
+        "percent_usr": "12.94",
+        "percent_nice": "0.00",
+        "percent_sys": "26.42",
+        "percent_iowait": "0.43",
+        "percent_irq": "0.00",
+        "percent_soft": "0.16",
+        "percent_steal": "0.00",
+        "percent_guest": "0.00",
+        "percent_gnice": "0.00",
+        "percent_idle": "60.05",
+        "type": "cpu",
+        "time": "01:58:14 PM"
+      }
+    ]
+
+<a id="jc.parsers.mpstat.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/mpstat_s.md

@@ -0,0 +1,128 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.mpstat_s"></a>
+
+# jc.parsers.mpstat\_s
+
+jc - JSON Convert `mpstat` command output streaming parser
+
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
+
+> Note: Latest versions of `mpstat` support JSON output (v11.5.1+)
+
+Usage (cli):
+
+    $ mpstat | jc --mpstat-s
+
+Usage (module):
+
+    import jc
+
+    result = jc.parse('mpstat_s', mpstat_command_output.splitlines())
+    for item in result:
+        # do something
+
+Schema:
+
+    {
+      "type":               string,
+      "time":               string,
+      "cpu":                string,
+      "node":               string,
+      "average":            boolean,
+      "percent_usr":        float,
+      "percent_nice":       float,
+      "percent_sys":        float,
+      "percent_iowait":     float,
+      "percent_irq":        float,
+      "percent_soft":       float,
+      "percent_steal":      float,
+      "percent_guest":      float,
+      "percent_gnice":      float,
+      "percent_idle":       float,
+      "intr_s":             float,
+      "<x>_s":              float,      # <x> is an integer
+      "nmi_s":              float,
+      "loc_s":              float,
+      "spu_s":              float,
+      "pmi_s":              float,
+      "iwi_s":              float,
+      "rtr_s":              float,
+      "res_s":              float,
+      "cal_s":              float,
+      "tlb_s":              float,
+      "trm_s":              float,
+      "thr_s":              float,
+      "dfr_s":              float,
+      "mce_s":              float,
+      "mcp_s":              float,
+      "err_s":              float,
+      "mis_s":              float,
+      "pin_s":              float,
+      "npi_s":              float,
+      "piw_s":              float,
+      "hi_s":               float,
+      "timer_s":            float,
+      "net_tx_s":           float,
+      "net_rx_s":           float,
+      "block_s":            float,
+      "irq_poll_s":         float,
+      "block_iopoll_s":     float,
+      "tasklet_s":          float,
+      "sched_s":            float,
+      "hrtimer_s":          float,
+      "rcu_s":              float,
+
+      # 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
+      }
+    }
+
+Examples:
+
+    $ mpstat -A | jc --mpstat-s
+    {"cpu":"all","percent_usr":0.22,"percent_nice":0.0,"percent_sys":...}
+    {"cpu":"0","percent_usr":0.22,"percent_nice":0.0,"percent_sys":0....}
+    {"cpu":"all","intr_s":37.61,"type":"interrupts","time":"03:15:06 PM"}
+    ...
+
+    $ mpstat -A | jc --mpstat-s -r
+    {"cpu":"all","percent_usr":"0.22","percent_nice":"0.00","percent_...}
+    {"cpu":"0","percent_usr":"0.22","percent_nice":"0.00","percent_sy...}
+    {"cpu":"all","intr_s":"37.61","type":"interrupts","time":"03:15:06 PM"}
+    ...
+
+<a id="jc.parsers.mpstat_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 iterable 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
+
+Returns:
+
+    Iterable of Dictionaries
+
+### Parser Information
+Compatibility:  linux
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/netstat.md

@@ -23,11 +23,6 @@ Usage (module):
     import jc
     result = jc.parse('netstat', netstat_command_output)
 
-    or
-
-    import jc.parsers.netstat
-    result = jc.parsers.netstat.parse(netstat_command_output)
-
 Schema:
 
     [

docs/parsers/nmcli.md

@@ -27,25 +27,20 @@ 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.
+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.
+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]
+        "<key>":                  string/integer/float,   # [0]
         "dhcp4_option_x": {
           "name":                 string,
           "value":                string/integer/float,

docs/parsers/ntpq.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('ntpq', ntpq_command_output)
 
-    or
-
-    import jc.parsers.ntpq
-    result = jc.parsers.ntpq.parse(ntpq_command_output)
-
 Schema:
 
     [

docs/parsers/passwd.md

@@ -14,11 +14,6 @@ Usage (module):
     import jc
     result = jc.parse('passwd', passwd_file_output)
 
-    or
-
-    import jc.parsers.passwd
-    result = jc.parsers.passwd.parse(passwd_file_output)
-
 Schema:
 
     [

docs/parsers/pidstat.md

@@ -0,0 +1,151 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.pidstat"></a>
+
+# jc.parsers.pidstat
+
+jc - JSON Convert `pidstat -h` command output parser
+
+Must use the `-h` option in `pidstat`. All other `pidstat` options are
+supported in combination with `-h`.
+
+Usage (cli):
+
+    $ pidstat -h | jc --pidstat
+
+    or
+
+    $ jc pidstat -h
+
+Usage (module):
+
+    import jc
+    result = jc.parse('pidstat', pidstat_command_output)
+
+Schema:
+
+    [
+      {
+        "time":             integer,
+        "uid":              integer,
+        "pid":              integer,
+        "percent_usr":      float,
+        "percent_system":   float,
+        "percent_guest":    float,
+        "percent_cpu":      float,
+        "cpu":              integer,
+        "minflt_s":         float,
+        "majflt_s":         float,
+        "vsz":              integer,
+        "rss":              integer,
+        "percent_mem":      float,
+        "stksize":          integer,
+        "stkref":           integer,
+        "kb_rd_s":          float,
+        "kb_wr_s":          float,
+        "kb_ccwr_s":        float,
+        "cswch_s":          float,
+        "nvcswch_s":        float,
+        "command":          string
+      }
+    ]
+
+Examples:
+
+    $ pidstat -hl | jc --pidstat -p
+    [
+      {
+        "time": 1646859134,
+        "uid": 0,
+        "pid": 1,
+        "percent_usr": 0.0,
+        "percent_system": 0.03,
+        "percent_guest": 0.0,
+        "percent_cpu": 0.03,
+        "cpu": 0,
+        "command": "/usr/lib/systemd/systemd --switched-root --system..."
+      },
+      {
+        "time": 1646859134,
+        "uid": 0,
+        "pid": 6,
+        "percent_usr": 0.0,
+        "percent_system": 0.0,
+        "percent_guest": 0.0,
+        "percent_cpu": 0.0,
+        "cpu": 0,
+        "command": "ksoftirqd/0"
+      },
+      {
+        "time": 1646859134,
+        "uid": 0,
+        "pid": 2263,
+        "percent_usr": 0.0,
+        "percent_system": 0.0,
+        "percent_guest": 0.0,
+        "percent_cpu": 0.0,
+        "cpu": 0,
+        "command": "kworker/0:0"
+      }
+    ]
+
+    $ pidstat -hl | jc --pidstat -p -r
+    [
+      {
+        "time": "1646859134",
+        "uid": "0",
+        "pid": "1",
+        "percent_usr": "0.00",
+        "percent_system": "0.03",
+        "percent_guest": "0.00",
+        "percent_cpu": "0.03",
+        "cpu": "0",
+        "command": "/usr/lib/systemd/systemd --switched-root --system..."
+      },
+      {
+        "time": "1646859134",
+        "uid": "0",
+        "pid": "6",
+        "percent_usr": "0.00",
+        "percent_system": "0.00",
+        "percent_guest": "0.00",
+        "percent_cpu": "0.00",
+        "cpu": "0",
+        "command": "ksoftirqd/0"
+      },
+      {
+        "time": "1646859134",
+        "uid": "0",
+        "pid": "2263",
+        "percent_usr": "0.00",
+        "percent_system": "0.00",
+        "percent_guest": "0.00",
+        "percent_cpu": "0.00",
+        "cpu": "0",
+        "command": "kworker/0:0"
+      }
+    ]
+
+<a id="jc.parsers.pidstat.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/pidstat_s.md

@@ -0,0 +1,110 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.pidstat_s"></a>
+
+# jc.parsers.pidstat\_s
+
+jc - JSON Convert `pidstat -h` command output streaming parser
+
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
+
+Must use the `-h` option in `pidstat`. All other `pidstat` options are
+supported in combination with `-h`.
+
+Usage (cli):
+
+    $ pidstat | jc --pidstat-s
+
+> Note: When piping `jc` converted `pidstat` output to other processes it
+> may appear the output is hanging due to the OS pipe buffers. This is
+> because `pidstat` output is too small to quickly fill up the buffer. Use
+> the `-u` option to unbuffer the `jc` output if you would like immediate
+> output. See the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output)
+> for more information.
+
+Usage (module):
+
+    import jc
+
+    result = jc.parse('pidstat_s', pidstat_command_output.splitlines())
+    for item in result:
+        # do something
+
+Schema:
+
+    {
+      "time":             integer,
+      "uid":              integer,
+      "pid":              integer,
+      "percent_usr":      float,
+      "percent_system":   float,
+      "percent_guest":    float,
+      "percent_cpu":      float,
+      "cpu":              integer,
+      "minflt_s":         float,
+      "majflt_s":         float,
+      "vsz":              integer,
+      "rss":              integer,
+      "percent_mem":      float,
+      "stksize":          integer,
+      "stkref":           integer,
+      "kb_rd_s":          float,
+      "kb_wr_s":          float,
+      "kb_ccwr_s":        float,
+      "cswch_s":          float,
+      "nvcswch_s":        float,
+      "command":          string,
+
+      # 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
+      }
+    }
+
+Examples:
+
+    $ pidstat -hl | jc --pidstat-s
+    {"time":1646859134,"uid":0,"pid":1,"percent_usr":0.0,"percent_syste...}
+    {"time":1646859134,"uid":0,"pid":6,"percent_usr":0.0,"percent_syste...}
+    {"time":1646859134,"uid":0,"pid":9,"percent_usr":0.0,"percent_syste...}
+    ...
+
+    $ pidstat -hl | jc --pidstat-s -r
+    {"time":"1646859134","uid":"0","pid":"1","percent_usr":"0.00","perc...}
+    {"time":"1646859134","uid":"0","pid":"6","percent_usr":"0.00","perc...}
+    {"time":"1646859134","uid":"0","pid":"9","percent_usr":"0.00","perc...}
+    ...
+
+<a id="jc.parsers.pidstat_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 iterable 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
+
+Returns:
+
+    Iterable of Dictionaries
+
+### Parser Information
+Compatibility:  linux
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ping.md

@@ -9,8 +9,8 @@ Supports `ping` and `ping6` output.
 
 Usage (cli):
 
-    Note:  Use the ping `-c` (count) option, otherwise data will not be
-           piped to `jc`.
+> Note:  Use the ping `-c` (count) option, otherwise data will not be
+> piped to `jc`.
 
     $ ping -c 3 1.2.3.4 | jc --ping
 
@@ -23,11 +23,6 @@ Usage (module):
     import jc
     result = jc.parse('ping', ping_command_output)
 
-    or
-
-    import jc.parsers.ping
-    result = jc.parsers.ping.parse(ping_command_output)
-
 Schema:
 
     {

docs/parsers/ping_s.md

@@ -5,37 +5,30 @@
 
 jc - JSON Convert `ping` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
 
 Supports `ping` and `ping6` output.
 
 Usage (cli):
 
-    $ ping | jc --ping-s
+    $ ping 1.2.3.4 | jc --ping-s
 
 > Note: When piping `jc` converted `ping` output to other processes it may
-  appear the output is hanging due to the OS pipe buffers. This is because
-  `ping` output is too small to quickly fill up the buffer. Use the `-u`
-  option to unbuffer the `jc` output if you would like immediate output.
-  See the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output)
-  for more information.
+> appear the output is hanging due to the OS pipe buffers. This is because
+> `ping` output is too small to quickly fill up the buffer. Use the `-u`
+> option to unbuffer the `jc` output if you would like immediate output.
+> See the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output)
+> for more information.
 
 Usage (module):
 
     import jc
-    # result is an iterable object (generator)
+
     result = jc.parse('ping_s', ping_command_output.splitlines())
     for item in result:
         # do something
 
-    or
-
-    import jc.parsers.ping_s
-    # result is an iterable object (generator)
-    result = jc.parsers.ping_s.parse(ping_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {
@@ -61,14 +54,12 @@ Schema:
       "round_trip_ms_max":          float,
       "round_trip_ms_stddev":       float,
 
-      # 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
-        }
+      # 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] 'reply', 'timeout', 'summary', etc. See `_error_type.type_map`
@@ -97,7 +88,7 @@ Examples:
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
-Main text parsing generator function. Returns an iterator object.
+Main text parsing generator function. Returns an iterable object.
 
 Parameters:
 
@@ -108,13 +99,9 @@ Parameters:
     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)
+    Iterable of Dictionaries
 
 ### Parser Information
 Compatibility:  linux, darwin, freebsd

docs/parsers/pip_list.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('pip_list', pip_list_command_output)
 
-    or
-
-    import jc.parsers.pip_list
-    result = jc.parsers.pip_list.parse(pip_list_command_output)
-
 Schema:
 
     [

docs/parsers/pip_show.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('pip_show', pip_show_command_output)
 
-    or
-
-    import jc.parsers.pip_show
-    result = jc.parsers.pip_show.parse(pip_show_command_output)
-
 Schema:
 
     [
@@ -75,7 +70,7 @@ Examples:
 ### parse
 
 ```python
-def parse(data, raw=False, quiet=False)
+def parse(data: str, raw: bool = False, quiet: bool = False) -> List[Dict]
 ```
 
 Main text parsing function
@@ -93,4 +88,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
 
-Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ps.md

@@ -22,11 +22,6 @@ Usage (module):
     import jc
     result = jc.parse('ps', ps_command_output)
 
-    or
-
-    import jc.parsers.ps
-    result = jc.parsers.ps.parse(ps_command_output)
-
 Schema:
 
     [

docs/parsers/route.md

@@ -18,29 +18,24 @@ Usage (module):
     import jc
     result = jc.parse('route', route_command_output)
 
-    or
-
-    import jc.parsers.route
-    result = jc.parsers.route.parse(route_command_output)
-
 Schema:
 
     [
       {
-        "destination":     string,
-        "gateway":         string,
-        "genmask":         string,
-        "flags":           string,
+        "destination":        string,
+        "gateway":            string,
+        "genmask":            string,
+        "flags":              string,
         "flags_pretty": [
-                           string
+                              string
         ]
-        "metric":          integer,
-        "ref":             integer,
-        "use":             integer,
-        "mss":             integer,
-        "window":          integer,
-        "irtt":            integer,
-        "iface":           string
+        "metric":             integer,
+        "ref":                integer,
+        "use":                integer,
+        "mss":                integer,
+        "window":             integer,
+        "irtt":               integer,
+        "iface":              string
       }
     ]
 

docs/parsers/rpm_qi.md

@@ -10,7 +10,7 @@ Works with `rpm -qi [package]` or `rpm -qia`.
 The `..._epoch` calculated timestamp fields are naive. (i.e. based on the
 local time of the system the parser is run on)
 
-The `..._epoch_utc` calculated timestamp fields are timezone-aware and is
+The `..._epoch_utc` calculated timestamp fields are timezone-aware and are
 only available if the timezone field is UTC.
 
 Usage (cli):
@@ -26,11 +26,6 @@ Usage (module):
     import jc
     result = jc.parse('rpm_qi', rpm_qi_command_output)
 
-    or
-
-    import jc.parsers.rpm_qi
-    result = jc.parsers.rpm_qi.parse(rpm_qi_command_output)
-
 Schema:
 
     [

docs/parsers/rsync.md

@@ -6,7 +6,7 @@
 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
+verbosity. This parser will process the `STDOUT` output or a log file
 generated with the `--log-file` option.
 
 Usage (cli):
@@ -26,11 +26,6 @@ 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:
 
     [
@@ -56,8 +51,8 @@ Schema:
             "time":                           string,
             "process":                        integer,
             "metadata":                       string,
-            "update_type":                    string/null,  [0]
-            "file_type":                      string/null,  [1]
+            "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,
@@ -66,7 +61,7 @@ Schema:
             "group_different":                bool/null,
             "acl_different":                  bool/null,
             "extended_attribute_different":   bool/null,
-            "epoch":                          integer,      [2]
+            "epoch":                          integer,      # [2]
           }
         ]
       }

docs/parsers/rsync_s.md

@@ -5,10 +5,11 @@
 
 jc - JSON Convert `rsync` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
 
 Supports the `-i` or `--itemize-changes` options with all levels of
-verbosity. This parser will process the STDOUT output or a log file
+verbosity. This parser will process the `STDOUT` output or a log file
 generated with the `--log-file` option.
 
 Usage (cli):
@@ -22,19 +23,11 @@ Usage (cli):
 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:
 
     {
@@ -56,8 +49,8 @@ Schema:
       "time":                           string,
       "process":                        integer,
       "metadata":                       string,
-      "update_type":                    string/null,  [0]
-      "file_type":                      string/null,  [1]
+      "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,
@@ -66,16 +59,14 @@ Schema:
       "group_different":                bool/null,
       "acl_different":                  bool/null,
       "extended_attribute_different":   bool/null,
-      "epoch":                          integer,      [2]
+      "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
-        }
+      # 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',
@@ -105,7 +96,7 @@ def parse(data: Iterable[str],
           ignore_exceptions: bool = False) -> Union[Iterable[Dict], tuple]
 ```
 
-Main text parsing generator function. Returns an iterator object.
+Main text parsing generator function. Returns an iterable object.
 
 Parameters:
 
@@ -116,13 +107,9 @@ Parameters:
     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)
+    Iterable of Dictionaries
 
 ### Parser Information
 Compatibility:  linux, darwin, freebsd

docs/parsers/sfdisk.md

@@ -27,11 +27,6 @@ Usage (module):
     import jc
     result = jc.parse('sfdisk', sfdisk_command_output)
 
-    or
-
-    import jc.parsers.sfdisk
-    result = jc.parsers.sfdisk.parse(sfdisk_command_output)
-
 Schema:
 
     [

docs/parsers/shadow.md

@@ -14,11 +14,6 @@ Usage (module):
     import jc
     result = jc.parse('shadow', shadow_file_output)
 
-    or
-
-    import jc.parsers.shadow
-    result = jc.parsers.shadow.parse(shadow_file_output)
-
 Schema:
 
     [

docs/parsers/ss.md

@@ -5,8 +5,8 @@
 
 jc - JSON Convert `ss` command output parser
 
-Extended information options like -e and -p are not supported and may cause
-parsing irregularities.
+Extended information options like `-e` and `-p` are not supported and may
+cause parsing irregularities.
 
 Usage (cli):
 
@@ -21,15 +21,10 @@ Usage (module):
     import jc
     result = jc.parse('ss', ss_command_output)
 
-    or
-
-    import jc.parsers.ss
-    result = jc.parsers.ss.parse(ss_command_output)
-
 Schema:
 
-    Information from https://www.cyberciti.biz/files/ss.html used to define
-    field names
+Information from https://www.cyberciti.biz/files/ss.html used to define
+field names
 
     [
       {

docs/parsers/stat.md

@@ -24,11 +24,6 @@ Usage (module):
     import jc
     result = jc.parse('stat', stat_command_output)
 
-    or
-
-    import jc.parsers.stat
-    result = jc.parsers.stat.parse(stat_command_output)
-
 Schema:
 
     [

docs/parsers/stat_s.md

@@ -5,7 +5,8 @@
 
 jc - JSON Convert `stat` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
 
 The `xxx_epoch` calculated timestamp fields are naive. (i.e. based on the
 local time of the system the parser is run on).
@@ -20,19 +21,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # result is an iterable object (generator)
+
     result = jc.parse('stat_s', stat_command_output.splitlines())
     for item in result:
         # do something
 
-    or
-
-    import jc.parsers.stat_s
-    # result is an iterable object (generator)
-    result = jc.parsers.stat_s.parse(stat_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {
@@ -68,14 +61,12 @@ Schema:
       "block_size":               integer,
       "unix_flags":               string,
 
-      # 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
-        }
+      # 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
+      }
     }
 
 Examples:
@@ -95,7 +86,7 @@ Examples:
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
-Main text parsing generator function. Returns an iterator object.
+Main text parsing generator function. Returns an iterable object.
 
 Parameters:
 
@@ -106,13 +97,9 @@ Parameters:
     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)
+    Iterable of Dictionaries
 
 ### Parser Information
 Compatibility:  linux, darwin, freebsd

docs/parsers/sysctl.md

@@ -5,10 +5,10 @@
 
 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
-      integers and floats. If no conversion is desired, use the `-r`
-      command-line argument or the `raw=True` argument in `parse()`.
+> 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
+> integers and floats. If no conversion is desired, use the `-r`
+> command-line argument or the `raw=True` argument in `parse()`.
 
 Usage (cli):
 
@@ -23,11 +23,6 @@ Usage (module):
     import jc
     result = jc.parse('sysctl', sysctl_command_output)
 
-    or
-
-    import jc.parsers.sysctl
-    result = jc.parsers.sysctl.parse(sysctl_command_output)
-
 Schema:
 
     {

docs/parsers/systemctl.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('systemctl', systemctl_command_output)
 
-    or
-
-    import jc.parsers.systemctl
-    result = jc.parsers.systemctl.parse(systemctl_command_output)
-
 Schema:
 
     [

docs/parsers/systemctl_lj.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('systemctl_lj', systemctl_lj_command_output)
 
-    or
-
-    import jc.parsers.systemctl_lj
-    result = jc.parsers.systemctl_lj.parse(systemctl_lj_command_output)
-
 Schema:
 
     [

docs/parsers/systemctl_ls.md

@@ -19,11 +19,6 @@ Usage (module):
     import jc
     result = jc.parse('systemctl_ls', systemctl_ls_command_output)
 
-    or
-
-    import jc.parsers.systemctl_ls
-    result = jc.parsers.systemctl_ls.parse(systemctl_ls_command_output)
-
 Schema:
 
     [

docs/parsers/systemctl_luf.md

@@ -19,11 +19,6 @@ Usage (module):
     import jc
     result = jc.parse('systemctl_luf', systemctl_luf_command_output)
 
-    or
-
-    import jc.parsers.systemctl_luf
-    result = jc.parsers.systemctl_luf.parse(systemctl_luf_command_output)
-
 Schema:
 
     [

docs/parsers/systeminfo.md

@@ -24,11 +24,6 @@ Usage (module):
     import jc
     result = jc.parse('systeminfo', systeminfo_command_output)
 
-    or
-
-    import jc.parsers.systeminfo
-    result = jc.parsers.systeminfo.parse(systeminfo_command_output)
-
 Schema:
 
     {

docs/parsers/time.md

@@ -11,8 +11,8 @@ used to redirect the output to a file that can be read by `jc`.
 Alternatively, the output from `/usr/bin/time` can be redirected to `STDOUT`
 so `jc` can receive it.
 
-Note: `/usr/bin/time` is similar but different from the Bash builtin
-      `time` command.
+> Note: `/usr/bin/time` is similar but different from the Bash builtin
+> `time` command.
 
 Usage (cli):
 
@@ -24,15 +24,10 @@ Usage (module):
     import jc
     result = jc.parse('time', time_command_output)
 
-    or
-
-    import jc.parsers.time
-    result = jc.parsers.time.parse(time_command_output)
-
 Schema:
 
-    Source: https://www.freebsd.org/cgi/man.cgi?query=getrusage
-            https://man7.org/linux/man-pages/man1/time.1.html
+Source: https://www.freebsd.org/cgi/man.cgi?query=getrusage,
+https://man7.org/linux/man-pages/man1/time.1.html
 
     {
       "real_time":                          float,

docs/parsers/timedatectl.md

@@ -21,11 +21,6 @@ Usage (module):
     import jc
     result = jc.parse('timedatectl', timedatectl_command_output)
 
-    or
-
-    import jc.parsers.timedatectl
-    result = jc.parsers.timedatectl.parse(timedatectl_command_output)
-
 Schema:
 
     {

docs/parsers/top.md

@@ -0,0 +1,339 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.top"></a>
+
+# jc.parsers.top
+
+jc - JSON Convert `top -b` command output parser
+
+Requires batch mode (`-b`). The `-n` option must also be used to limit
+the number of times `top` is run.
+
+Warning messages will be printed to `STDERR` if truncated fields are
+detected. These warnings can be suppressed with the `-q` or `quiet=True`
+option.
+
+Usage (cli):
+
+    $ top -b -n 3 | jc --top
+
+    or
+
+    $ jc top -b -n 3
+
+Usage (module):
+
+    import jc
+    result = jc.parse('top', top_command_output)
+
+Schema:
+
+All `-` values are converted to `null`
+
+    [
+      {
+        "time":                                         string,
+        "uptime":                                       integer,
+        "users":                                        integer,
+        "load_1m":                                      float,
+        "load_5m":                                      float,
+        "load_15m":                                     float,
+        "tasks_total":                                  integer,
+        "tasks_running":                                integer,
+        "tasks_sleeping":                               integer,
+        "tasks_stopped":                                integer,
+        "tasks_zombie":                                 integer,
+        "cpu_user":                                     float,
+        "cpu_sys":                                      float,
+        "cpu_nice":                                     float,
+        "cpu_idle":                                     float,
+        "cpu_wait":                                     float,
+        "cpu_hardware":                                 float,
+        "cpu_software":                                 float,
+        "cpu_steal":                                    float,
+        "mem_total":                                    float,    # [0]
+        "mem_free":                                     float,    # [0]
+        "mem_used":                                     float,    # [0]
+        "mem_buff_cache":                               float,    # [0]
+        "swap_total":                                   float,    # [0]
+        "swap_free":                                    float,    # [0]
+        "swap_used":                                    float,    # [0]
+        "mem_available":                                float,    # [0]
+        "processes": [
+          {
+            "pid":                                      integer,
+            "user":                                     string,
+            "priority":                                 integer,
+            "nice":                                     integer,
+            "virtual_mem":                              float,    # [1]
+            "resident_mem":                             float,    # [1]
+            "shared_mem":                               float,    # [1]
+            "status":                                   string,
+            "percent_cpu":                              float,
+            "percent_mem":                              float,
+            "time_hundredths":                          string,
+            "command":                                  string,
+            "parent_pid":                               integer,
+            "uid":                                      integer,
+            "real_uid":                                 integer,
+            "real_user":                                string,
+            "saved_uid":                                integer,
+            "saved_user":                               string,
+            "gid":                                      integer,
+            "group":                                    string,
+            "pgrp":                                     integer,
+            "tty":                                      string,
+            "tty_process_gid":                          integer,
+            "session_id":                               integer,
+            "thread_count":                             integer,
+            "last_used_processor":                      integer,
+            "time":                                     string,
+            "swap":                                     float,    # [1]
+            "code":                                     float,    # [1]
+            "data":                                     float,    # [1]
+            "major_page_fault_count":                   integer,
+            "minor_page_fault_count":                   integer,
+            "dirty_pages_count":                        integer,
+            "sleeping_in_function":                     string,
+            "flags":                                    string,
+            "cgroups":                                  string,
+            "supplementary_gids": [
+                                                        integer
+            ],
+            "supplementary_groups": [
+                                                        string
+            ],
+            "thread_gid":                               integer,
+            "environment_variables": [
+                                                        string
+            ]
+            "major_page_fault_count_delta":             integer,
+            "minor_page_fault_count_delta":             integer,
+            "used":                                     float,    # [1]
+            "ipc_namespace_inode":                      integer,
+            "mount_namespace_inode":                    integer,
+            "net_namespace_inode":                      integer,
+            "pid_namespace_inode":                      integer,
+            "user_namespace_inode":                     integer,
+            "nts_namespace_inode":                      integer,
+            "control_group_name":                       string,
+            "lxc_container_name":                       string,
+            "numa_node":                                integer,
+            "out_of_mem_adjustment":                    integer,
+            "out_of_mem_score":                         integer,
+            "resident_anon_mem":                        integer,
+            "resident_file_backed_mem":                 integer,
+            "resident_locked_mem":                      integer,
+            "resident_shared_mem":                      integer
+          }
+        ]
+      }
+    ]
+
+    [0] Values are in the units output by `top`
+    [1] Unit suffix stripped during float conversion
+
+Examples:
+
+    $ top -b -n 3 | jc --top -p
+    [
+      {
+        "time": "11:20:43",
+        "uptime": 118,
+        "users": 2,
+        "load_1m": 0.0,
+        "load_5m": 0.01,
+        "load_15m": 0.05,
+        "tasks_total": 108,
+        "tasks_running": 2,
+        "tasks_sleeping": 106,
+        "tasks_stopped": 0,
+        "tasks_zombie": 0,
+        "cpu_user": 5.6,
+        "cpu_sys": 11.1,
+        "cpu_nice": 0.0,
+        "cpu_idle": 83.3,
+        "cpu_wait": 0.0,
+        "cpu_hardware": 0.0,
+        "cpu_software": 0.0,
+        "cpu_steal": 0.0,
+        "mem_total": 3.7,
+        "mem_free": 3.3,
+        "mem_used": 0.2,
+        "mem_buff_cache": 0.2,
+        "swap_total": 2.0,
+        "swap_free": 2.0,
+        "swap_used": 0.0,
+        "mem_available": 3.3,
+        "processes": [
+          {
+            "pid": 2225,
+            "user": "kbrazil",
+            "priority": 20,
+            "nice": 0,
+            "virtual_mem": 158.1,
+            "resident_mem": 2.2,
+            "shared_mem": 1.6,
+            "status": "running",
+            "percent_cpu": 12.5,
+            "percent_mem": 0.1,
+            "time_hundredths": "0:00.02",
+            "command": "top",
+            "parent_pid": 1884,
+            "uid": 1000,
+            "real_uid": 1000,
+            "real_user": "kbrazil",
+            "saved_uid": 1000,
+            "saved_user": "kbrazil",
+            "gid": 1000,
+            "group": "kbrazil",
+            "pgrp": 2225,
+            "tty": "pts/0",
+            "tty_process_gid": 2225,
+            "session_id": 1884,
+            "thread_count": 1,
+            "last_used_processor": 0,
+            "time": "0:00",
+            "swap": 0.0,
+            "code": 0.1,
+            "data": 1.0,
+            "major_page_fault_count": 0,
+            "minor_page_fault_count": 736,
+            "dirty_pages_count": 0,
+            "sleeping_in_function": null,
+            "flags": "..4.2...",
+            "cgroups": "1:name=systemd:/user.slice/user-1000.+",
+            "supplementary_gids": [
+              10,
+              1000
+            ],
+            "supplementary_groups": [
+              "wheel",
+              "kbrazil"
+            ],
+            "thread_gid": 2225,
+            "environment_variables": [
+              "XDG_SESSION_ID=2",
+              "HOSTNAME=localhost"
+            ],
+            "major_page_fault_count_delta": 0,
+            "minor_page_fault_count_delta": 4,
+            "used": 2.2,
+            "ipc_namespace_inode": 4026531839,
+            "mount_namespace_inode": 4026531840,
+            "net_namespace_inode": 4026531956,
+            "pid_namespace_inode": 4026531836,
+            "user_namespace_inode": 4026531837,
+            "nts_namespace_inode": 4026531838
+          },
+          ...
+        ]
+      }
+    ]
+
+    $ top -b -n 3 | jc --top -p -r
+    [
+      {
+        "time": "11:20:43",
+        "uptime": "1:18",
+        "users": "2",
+        "load_1m": "0.00",
+        "load_5m": "0.01",
+        "load_15m": "0.05",
+        "tasks_total": "108",
+        "tasks_running": "2",
+        "tasks_sleeping": "106",
+        "tasks_stopped": "0",
+        "tasks_zombie": "0",
+        "cpu_user": "5.6",
+        "cpu_sys": "11.1",
+        "cpu_nice": "0.0",
+        "cpu_idle": "83.3",
+        "cpu_wait": "0.0",
+        "cpu_hardware": "0.0",
+        "cpu_software": "0.0",
+        "cpu_steal": "0.0",
+        "swap_total": "2.0",
+        "swap_free": "2.0",
+        "swap_used": "0.0",
+        "mem_available": "3.3",
+        "processes": [
+          {
+            "PID": "2225",
+            "USER": "kbrazil",
+            "PR": "20",
+            "NI": "0",
+            "VIRT": "158.1m",
+            "RES": "2.2m",
+            "SHR": "1.6m",
+            "S": "R",
+            "%CPU": "12.5",
+            "%MEM": "0.1",
+            "TIME+": "0:00.02",
+            "COMMAND": "top",
+            "PPID": "1884",
+            "UID": "1000",
+            "RUID": "1000",
+            "RUSER": "kbrazil",
+            "SUID": "1000",
+            "SUSER": "kbrazil",
+            "GID": "1000",
+            "GROUP": "kbrazil",
+            "PGRP": "2225",
+            "TTY": "pts/0",
+            "TPGID": "2225",
+            "SID": "1884",
+            "nTH": "1",
+            "P": "0",
+            "TIME": "0:00",
+            "SWAP": "0.0m",
+            "CODE": "0.1m",
+            "DATA": "1.0m",
+            "nMaj": "0",
+            "nMin": "736",
+            "nDRT": "0",
+            "WCHAN": "-",
+            "Flags": "..4.2...",
+            "CGROUPS": "1:name=systemd:/user.slice/user-1000.+",
+            "SUPGIDS": "10,1000",
+            "SUPGRPS": "wheel,kbrazil",
+            "TGID": "2225",
+            "ENVIRON": "XDG_SESSION_ID=2 HOSTNAME=localhost S+",
+            "vMj": "0",
+            "vMn": "4",
+            "USED": "2.2m",
+            "nsIPC": "4026531839",
+            "nsMNT": "4026531840",
+            "nsNET": "4026531956",
+            "nsPID": "4026531836",
+            "nsUSER": "4026531837",
+            "nsUTS": "4026531838"
+          },
+          ...
+        ]
+      }
+    ]
+
+<a id="jc.parsers.top.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/top_s.md

@@ -0,0 +1,180 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.top_s"></a>
+
+# jc.parsers.top\_s
+
+jc - JSON Convert `top -b` command output streaming parser
+
+> This streaming parser outputs JSON Lines (cli) or returns an Iterable of
+> Dictionaries (module)
+
+Requires batch mode (`-b`).
+
+Warning messages will be printed to `STDERR` if truncated fields are
+detected. These warnings can be suppressed with the `-q` or `quiet=True`
+option.
+
+Usage (cli):
+
+    $ top -b | jc --top-s
+
+Usage (module):
+
+    import jc
+
+    result = jc.parse('top_s', top_command_output.splitlines())
+    for item in result:
+        # do something
+
+Schema:
+
+    {
+      "time":                                         string,
+      "uptime":                                       integer,
+      "users":                                        integer,
+      "load_1m":                                      float,
+      "load_5m":                                      float,
+      "load_15m":                                     float,
+      "tasks_total":                                  integer,
+      "tasks_running":                                integer,
+      "tasks_sleeping":                               integer,
+      "tasks_stopped":                                integer,
+      "tasks_zombie":                                 integer,
+      "cpu_user":                                     float,
+      "cpu_sys":                                      float,
+      "cpu_nice":                                     float,
+      "cpu_idle":                                     float,
+      "cpu_wait":                                     float,
+      "cpu_hardware":                                 float,
+      "cpu_software":                                 float,
+      "cpu_steal":                                    float,
+      "mem_total":                                    float,    # [0]
+      "mem_free":                                     float,    # [0]
+      "mem_used":                                     float,    # [0]
+      "mem_buff_cache":                               float,    # [0]
+      "swap_total":                                   float,    # [0]
+      "swap_free":                                    float,    # [0]
+      "swap_used":                                    float,    # [0]
+      "mem_available":                                float,    # [0]
+      "processes": [
+        {
+          "pid":                                      integer,
+          "user":                                     string,
+          "priority":                                 integer,
+          "nice":                                     integer,
+          "virtual_mem":                              float,    # [1]
+          "resident_mem":                             float,    # [1]
+          "shared_mem":                               float,    # [1]
+          "status":                                   string,
+          "percent_cpu":                              float,
+          "percent_mem":                              float,
+          "time_hundredths":                          string,
+          "command":                                  string,
+          "parent_pid":                               integer,
+          "uid":                                      integer,
+          "real_uid":                                 integer,
+          "real_user":                                string,
+          "saved_uid":                                integer,
+          "saved_user":                               string,
+          "gid":                                      integer,
+          "group":                                    string,
+          "pgrp":                                     integer,
+          "tty":                                      string,
+          "tty_process_gid":                          integer,
+          "session_id":                               integer,
+          "thread_count":                             integer,
+          "last_used_processor":                      integer,
+          "time":                                     string,
+          "swap":                                     float,    # [1]
+          "code":                                     float,    # [1]
+          "data":                                     float,    # [1]
+          "major_page_fault_count":                   integer,
+          "minor_page_fault_count":                   integer,
+          "dirty_pages_count":                        integer,
+          "sleeping_in_function":                     string,
+          "flags":                                    string,
+          "cgroups":                                  string,
+          "supplementary_gids": [
+                                                      integer
+          ],
+          "supplementary_groups": [
+                                                      string
+          ],
+          "thread_gid":                               integer,
+          "environment_variables": [
+                                                      string
+          ]
+          "major_page_fault_count_delta":             integer,
+          "minor_page_fault_count_delta":             integer,
+          "used":                                     float,    # [1]
+          "ipc_namespace_inode":                      integer,
+          "mount_namespace_inode":                    integer,
+          "net_namespace_inode":                      integer,
+          "pid_namespace_inode":                      integer,
+          "user_namespace_inode":                     integer,
+          "nts_namespace_inode":                      integer,
+          "control_group_name":                       string,
+          "lxc_container_name":                       string,
+          "numa_node":                                integer,
+          "out_of_mem_adjustment":                    integer,
+          "out_of_mem_score":                         integer,
+          "resident_anon_mem":                        integer,
+          "resident_file_backed_mem":                 integer,
+          "resident_locked_mem":                      integer,
+          "resident_shared_mem":                      integer
+        }
+      ],
+
+      # 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] Values are in the units output by `top`
+    [1] Unit suffix stripped during float conversion
+
+Examples:
+
+    $ top -b | jc --top-s
+    {"time":"11:24:50","uptime":2,"users":2,"load_1m":0.23,"load_5m":...}
+    ...
+
+    $ top -b | jc --top-s -r
+    {"time":"11:24:50","uptime":"2 min","users":"2","load_1m":"0.23","lo...}
+    ...
+
+<a id="jc.parsers.top_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 iterable 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
+
+
+Returns:
+
+    Iterable of Dictionaries
+
+### Parser Information
+Compatibility:  linux
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/tracepath.md

@@ -20,11 +20,6 @@ Usage (module):
     import jc
     result = jc.parse('tracepath', tracepath_command_output)
 
-    or
-
-    import jc.parsers.tracepath
-    result = jc.parsers.tracepath.parse(tracepath_command_output)
-
 Schema:
 
     {

docs/parsers/traceroute.md

@@ -7,12 +7,12 @@ jc - JSON Convert `traceroute` command output parser
 
 Supports `traceroute` and `traceroute6` output.
 
-Note: On some operating systems you will need to redirect `STDERR` to
-      `STDOUT` for destination info since the header line is sent to
-      `STDERR`. A warning message will be printed to `STDERR` if the
-      header row is not found.
-
-      e.g. `$ traceroute 8.8.8.8 2>&1 | jc --traceroute`
+> Note: On some operating systems you will need to redirect `STDERR` to
+> `STDOUT` for destination info since the header line is sent to
+> `STDERR`. A warning message will be printed to `STDERR` if the
+> header row is not found.
+>
+> e.g. `$ traceroute 8.8.8.8 2>&1 | jc --traceroute`
 
 Usage (cli):
 
@@ -27,11 +27,6 @@ Usage (module):
     import jc
     result = jc.parse('traceroute', traceroute_command_output)
 
-    or
-
-    import jc.parsers.traceroute
-    result = jc.parsers.traceroute.parse(traceroute_command_output)
-
 Schema:
 
     {

docs/parsers/ufw.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('ufw', ufw_command_output)
 
-    or
-
-    import jc.parsers.ufw
-    result = jc.parsers.ufw.parse(ufw_command_output)
-
 Schema:
 
     {

docs/parsers/ufw_appinfo.md

@@ -26,11 +26,6 @@ Usage (module):
     import jc
     result = jc.parse('ufw_appinfo', ufw_appinfo_command_output)
 
-    or
-
-    import jc.parsers.ufw_appinfo
-    result = jc.parsers.ufw_appinfo.parse(ufw_appinfo_command_output)
-
 Schema:
 
     [

docs/parsers/uname.md

@@ -5,7 +5,7 @@
 
 jc - JSON Convert `uname -a` command output parser
 
-Note: Must use `uname -a`
+> Note: Must use `uname -a`
 
 Usage (cli):
 
@@ -20,11 +20,6 @@ Usage (module):
     import jc
     result = jc.parse('uname', uname_command_output)
 
-    or
-
-    import jc.parsers.uname
-    result = jc.parsers.uname.parse(uname_command_output)
-
 Schema:
 
     {

docs/parsers/universal.md

@@ -15,14 +15,28 @@ jc - JSON Convert universal parsers
 ### simple\_table\_parse
 
 ```python
-def simple_table_parse(data: List[str]) -> List[Dict]
+def simple_table_parse(data: Iterable[str]) -> List[Dict]
 ```
 
-Parse simple tables. The last column may contain data with spaces.
+Parse simple tables. There should be no blank cells. The last column
+may contain data with spaces.
+
+Example Table:
+
+    col_1     col_2     col_3     col_4     col_5
+    apple     orange    pear      banana    my favorite fruits
+    carrot    squash    celery    spinach   my favorite veggies
+    chicken   beef      pork      eggs      my favorite proteins
+
+    [{'col_1': 'apple', 'col_2': 'orange', 'col_3': 'pear', 'col_4':
+    'banana', 'col_5': 'my favorite fruits'}, {'col_1': 'carrot',
+    'col_2': 'squash', 'col_3': 'celery', 'col_4': 'spinach', 'col_5':
+    'my favorite veggies'}, {'col_1': 'chicken', 'col_2': 'beef',
+    'col_3': 'pork', 'col_4': 'eggs', 'col_5': 'my favorite proteins'}]
 
 Parameters:
 
-    data:   (list)   Text data to parse that has been split into lines
+    data:   (iter)   Text data to parse that has been split into lines
                      via .splitlines(). Item 0 must be the header row.
                      Any spaces in header names should be changed to
                      underscore '_'. You should also ensure headers are
@@ -40,23 +54,38 @@ Returns:
 ### sparse\_table\_parse
 
 ```python
-def sparse_table_parse(data: List[str], delim: str = '\u2063') -> List[Dict]
+def sparse_table_parse(data: Iterable[str],
+                       delim: str = '\u2063') -> List[Dict]
 ```
 
 Parse tables with missing column data or with spaces in column data.
+Blank cells are converted to None in the resulting dictionary. Data
+elements must line up within column boundaries.
+
+Example Table:
+
+    col_1        col_2     col_3     col_4         col_5
+    apple        orange              fuzzy peach   my favorite fruits
+    green beans            celery    spinach       my favorite veggies
+    chicken      beef                brown eggs    my favorite proteins
+
+    [{'col_1': 'apple', 'col_2': 'orange', 'col_3': None, 'col_4':
+    'fuzzy peach', 'col_5': 'my favorite fruits'}, {'col_1':
+    'green beans', 'col_2': None, 'col_3': 'celery', 'col_4': 'spinach',
+    'col_5': 'my favorite veggies'}, {'col_1': 'chicken', 'col_2':
+    'beef', 'col_3': None, 'col_4': 'brown eggs', 'col_5':
+    'my favorite proteins'}]
 
 Parameters:
 
-    data:   (list)   Text data to parse that has been split into lines
-                     via .splitlines(). Item 0 must be the header row.
-                     Any spaces in header names should be changed to
-                     underscore '_'. You should also ensure headers are
-                     lowercase by using .lower(). Do not change the
-                     position of header names as the positions are used
-                     to find the data.
+    data:   (iter)   An iterable of string lines (e.g. str.splitlines())
+                     Item 0 must be the header row. Any spaces in header
+                     names should be changed to underscore '_'. You
+                     should also ensure headers are lowercase by using
+                     .lower(). Do not change the position of header
+                     names as the positions are used to find the data.
 
-                     Also, ensure there are no blank lines (list items)
-                     in the data.
+                     Also, ensure there are no blank line items.
 
     delim:  (string) Delimiter to use. By default `u\\2063`
                      (invisible separator) is used since it is unlikely

docs/parsers/update_alt_gs.md

@@ -0,0 +1,71 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.update_alt_gs"></a>
+
+# jc.parsers.update\_alt\_gs
+
+jc - JSON Convert `update-alternatives --get-selections` command output parser
+
+Usage (cli):
+
+    $ update-alternatives --get-selections | jc --update-alt-gs
+
+    or
+
+    $ jc update-alternatives --get-selections
+
+Usage (module):
+
+    import jc
+    result = jc.parse('update-alt-gs',
+                      update_alternatives_get_selections_command_output)
+
+Schema:
+
+    [
+      {
+        "name":     string,
+        "status":   string,
+        "current":  string
+      }
+    ]
+
+Examples:
+
+    $ update-alternatives --get-selections | jc --update-alt-gs -p
+    [
+      {
+        "name": "arptables",
+        "status": "auto",
+        "current": "/usr/sbin/arptables-nft"
+      },
+      {
+        "name": "awk",
+        "status": "auto",
+        "current": "/usr/bin/gawk"
+      }
+    ]
+
+<a id="jc.parsers.update_alt_gs.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/update_alt_q.md

@@ -0,0 +1,157 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.update_alt_q"></a>
+
+# jc.parsers.update\_alt\_q
+
+jc - JSON Convert `update-alternatives --query` command output parser
+
+Usage (cli):
+
+    $ update-alternatives --query | jc --update-alt-q
+
+    or
+
+    $ jc update-alternatives --query
+
+Usage (module):
+
+    import jc
+    result = jc.parse('update_alt_q',
+                      update_alternatives_query_command_output)
+
+Schema:
+
+    {
+      "name":                 string,
+      "link":                 string,
+      "slaves": [
+        {
+          "name":             string,
+          "path":             string
+        }
+      ],
+      "status":               string,
+      "best":                 string,
+      "value":                string,   # (null if 'none')
+      "alternatives": [
+        {
+          "alternative":      string,
+          "priority":         integer,
+          "slaves": [
+            {
+              "name":         string,
+              "path":         string
+            }
+          ]
+        }
+      ]
+    }
+
+Examples:
+
+    $ update-alternatives --query editor | jc --update-alt-q -p
+    {
+      "name": "editor",
+      "link": "/usr/bin/editor",
+      "slaves": [
+        {
+          "name": "editor.1.gz",
+          "path": "/usr/share/man/man1/editor.1.gz"
+        },
+        {
+          "name": "editor.da.1.gz",
+          "path": "/usr/share/man/da/man1/editor.1.gz"
+        }
+      ],
+      "status": "auto",
+      "best": "/bin/nano",
+      "value": "/bin/nano",
+      "alternatives": [
+        {
+          "alternative": "/bin/ed",
+          "priority": -100,
+          "slaves": [
+            {
+              "name": "editor.1.gz",
+              "path": "/usr/share/man/man1/ed.1.gz"
+            }
+          ]
+        },
+        {
+          "alternative": "/bin/nano",
+          "priority": 40,
+          "slaves": [
+            {
+              "name": "editor.1.gz",
+              "path": "/usr/share/man/man1/nano.1.gz"
+            }
+          ]
+        }
+      ]
+    }
+
+    $ update-alternatives --query | jc --update-alt-q -p -r
+    {
+      "name": "editor",
+      "link": "/usr/bin/editor",
+      "slaves": [
+        {
+          "name": "editor.1.gz",
+          "path": "/usr/share/man/man1/editor.1.gz"
+        },
+        {
+          "name": "editor.da.1.gz",
+          "path": "/usr/share/man/da/man1/editor.1.gz"
+        }
+      ],
+      "status": "auto",
+      "best": "/bin/nano",
+      "value": "/bin/nano",
+      "alternatives": [
+        {
+          "alternative": "/bin/ed",
+          "priority": "-100",
+          "slaves": [
+            {
+              "name": "editor.1.gz",
+              "path": "/usr/share/man/man1/ed.1.gz"
+            }
+          ]
+        },
+        {
+          "alternative": "/bin/nano",
+          "priority": "40",
+          "slaves": [
+            {
+              "name": "editor.1.gz",
+              "path": "/usr/share/man/man1/nano.1.gz"
+            }
+          ]
+        }
+      ]
+    }
+
+<a id="jc.parsers.update_alt_q.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
+
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/upower.md

@@ -24,11 +24,6 @@ Usage (module):
     import jc
     result = jc.parse('upower', upower_command_output)
 
-    or
-
-    import jc.parsers.upower
-    result = jc.parsers.upower.parse(upower_command_output)
-
 Schema:
 
     [

docs/parsers/uptime.md

@@ -18,11 +18,6 @@ Usage (module):
     import jc
     result = jc.parse('uptime', uptime_command_output)
 
-    or
-
-    import jc.parsers.uptime
-    result = jc.parsers.uptime.parse(uptime_command_output)
-
 Schema:
 
     {

docs/parsers/vmstat.md

@@ -26,11 +26,6 @@ Usage (module):
     import jc
     result = jc.parse('vmstat', vmstat_command_output)
 
-    or
-
-    import jc.parsers.vmstat
-    result = jc.parsers.vmstat.parse(vmstat_command_output)
-
 Schema:
 
     [