Merge pull request #198 from kellyjonbrazil/dev

Dev v1.18.0

.github/workflows/pythonapp.yml

@@ -14,10 +14,16 @@ jobs:
     strategy:
       matrix:
         os: [macos-latest, ubuntu-latest, windows-latest]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: ["3.7", "3.8", "3.9", "3.10"]
 
     steps:
     - uses: actions/checkout@v2
+    - name: "Set up timezone to America/Los_Angeles"
+      uses: szenius/set-timezone@v1.0
+      with:
+        timezoneLinux: "America/Los_Angeles"
+        timezoneMacos: "America/Los_Angeles"
+        timezoneWindows: "Pacific Standard Time"
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v1
       with:

.gitignore

@@ -4,3 +4,5 @@ dist/
 build/
 *.egg-info/
 .github/
+.vscode/
+_config.yml

CHANGELOG

@@ -1,5 +1,173 @@
 jc changelog
 
+20220121 v1.18.0
+- Add high-level parse API for built-in and plugin parsers
+- Add python module developer documentation
+- Enhance magic syntax exception messages
+- Enhance documentation formatting
+
+20220106 v1.17.7
+- Add stat command streaming parser tested on linux and macOS
+
+20220103 v1.17.6
+- Add jar-manifest file parser (for MANIFEST.MF files)
+- Fix CSV parsers for some files that include doublequotes
+
+20211221 v1.17.5
+- Add zipinfo parser tested on linux and macOS
+
+20211207 v1.17.4
+- Add support for the NO_COLOR environment variable to set mono (http://no-color.org/)
+- Add -C option to force color output even when using pipes (overrides -m and NO_COLOR)
+
+20211202 v1.17.3
+- Update parsers to exit with error if non-string input is detected (raise TypeError)
+- Update streaming parsers to exit with error if non-iterable input is detected (raise TypeError)
+- Simplify quiet-checking in parsers
+- Add iostat parser tested on linux
+- Add iostat streaming parser tested on linux
+
+20211117 v1.17.2
+- Fix ping parser to add Alpine linux support
+- Fix netstat parser for older versions of netstat on linux
+- Fix df parser for cases where the filesystem field overflows the column length
+
+20211030 v1.17.1
+- Fix file parser for gzip files
+- Fix uname parser for cases where the 'processor' and/or 'hardware_platform' fields are missing on linux
+- Fix uname parser on FreeBSD
+- Add lsusb parser tested on linux
+- Add CSV file streaming parser
+- Add testing for Python 3.10.0
+
+20210923 v1.17.0
+- Note to Package Maintainers: please see note at 20210720 v1.16.0
+- Add wrapping of warning and error messages
+- Add vmstat parser tested on linux
+- Add support for streaming parsers
+- Add ls command streaming parser tested on linux, macOS, and freeBSD
+- Add ping command streaming parser tested on linux, macOS, and freeBSD
+- Add vmstat command streaming parser tested on linux
+- Add -u option to allow unbuffered output
+
+20210830 v1.16.2
+- Note to Package Maintainers: please see note at 20210720 v1.16.0
+- Update sfdisk parser to support the -F option and newer versions of sfdisk
+
+20210813 v1.16.1
+- Note to Package Maintainers: please see note at 20210720 v1.16.0
+- Fix issue with process substitution with the magic syntax
+- Fix issue with globs not including filenames with spaces with magic syntax
+- Fix stat parser to properly handle filenames with spaces on macOS/BSD
+
+20210720 v1.16.0
+- Note to Package Maintainers:
+    TL;DR: `/man/jc.1.gz` and `/jc/man/jc.1.gz` are deprecated and only `/man/jc.1` should be used.
+
+    The Man page in the PyPi source packages will be moving from `/jc/man/jc.1.gz` to `/man/jc.1`
+    in version 1.17.0. For now the Man pages will be available in both locations, but be aware that
+    the Man page at `/jc/man/jc.1.gz` is now considered deprecated.
+
+    Also, starting in v1.17.0, the Man page will no longer be compressed in the source package,
+    therefore `/man/jc.1.gz` should also be considered deprecated and will no longer be available
+    after v1.17.0. Please use `/man/jc.1` and compress downstream if you would like.
+- Include CHANGELOG in source distribution
+- Fix Man page location in source packages
+- Add sfdisk command parser tested on linux
+- Update unit test files to change the timezone when needed (POSIX only)
+- Binaries and DEB/RPM/MSI packages now include Python 3.9.5 interpreter
+
+20210628 v1.15.6
+- Fix issue to only load local plugin parsers that have filenames that end in .py
+
+20210520 v1.15.5
+- Fix issue where help and about information would not display if a 3rd party parser library was missing. (e.g. xmltodict)
+- Add more error message detail when encountering ParseError and LibraryNotFound exceptions
+
+20210517 v1.15.4
+- Update ping parser to support error responses in OSX and BSD
+- Update ping parser to be more resilient against parsing errors for unknown error types
+- Update dig parser to support `+noall +answer` use case
+- Update dig parser compatibility to all platforms
+- Fix colors in Windows terminals (cmd.exe and PowerShell)
+- Fix epoch calculations when UTC is referenced as "Coordinated Universal Time"
+- Add Windows time format for systeminfo output
+- Add exceptions module to standardize parser exceptions
+- JC no longer swallows exit codes when using the "magic" syntax. See the Exit Codes section of the README and man page for details
+
+20210426 v1.15.3
+- Add ufw status command parser tested on linux
+- Add ufw-appinfo command parser tested on linux
+- Fix deb package name to conform to standard
+- Add Caveats section to readme and manpage
+
+20210418 v1.15.2
+- Add systeminfo parser tested on Windows
+- Update dig parser to fix an issue with IPv6 addresses in the server field
+- Update dig parser to fix an issue when axfr entries contain a semicolon
+- Update dig parser to add support for Additional Section and Opt Pseudosection
+- Update dig parser to add query_size field
+- Use dig parser as the main example in readme, documentation, and man page
+- Standardize int, float, and boolean conversion rules with functions in jc.utils
+
+20210413 v1.15.1
+- New feature to show parser documentation interactively with -h --parser_name
+  for example: $ jc -h --arp
+- Add man page to pypi package for easier packaging in homebrew
+- Update rpm-qi parser to add two calculated timestamp fields: install_date_epoch and install_date_epoch_utc
+- Clean up documentation and autogenerate the Parser Information section from metadata
+
+20210407 v1.15.0
+- Add acpi command parser tested on linux
+- Add upower command parser tested on linux
+- Add /usr/bin/time command parser tested on linux and macOS
+- Add dpkg -l command parser tested on linux
+- Add rpm -qi command parser tested on linux
+- Add finger command parser tested on linux and macOS
+- Add dir command parser tested on Windows 10
+- Update date parser: complete rewrite (v2.0) providing many enhancements:
+    - Make weekday numbering ISO 8601 compliant
+    - Add a calculated naive timestamp field
+    - Add a calculated UTC timestamp field (only if date output is in UTC)
+    - Add several fields, including: hour_24, utc_offset, day_of_year, week_of_year, iso, and timezone_aware
+- Update uptime parser to add uptime_days, uptime_hours, uptime_minutes, uptime_total_seconds, time_hour,
+      time_minute, and time_second fields
+- Update last parser to use new timestamp function
+- Update stat parser to add access_time_epoch, access_time_epoch_utc, modify_time_epoch, modify_time_epoch_utc,
+      change_time_epoch, change_time_epoch_utc, birth_time_epoch, birth_time_epoch_utc fields
+- Update timedatectl parser to add epoch_utc field
+- Update who parser to add epoch field
+- Update dig parser to add when_epoch and when_epoch_utc fields
+- Update ls parser to add epoch and epoch_utc fields
+- Add -h option to display the help text. Piping errors no longer show the help text.
+- Add -v option to display version information.
+- Add contributing information to project root
+- Make all external python library dependencies optional: pygments, ruamel.yaml, xmltodict
+- JSON output now supports unencoded unicode characters
+- JSON output is now more compact unless the -p (pretty) option is used
+- Developer scripts added and enhanced to automate documentation and man page creation
+- Enhanced man page
+
+20210305 v1.14.4
+- Packaging fix only for binaries and RPMs hosted on https://github.com/kellyjonbrazil/jc-packaging.
+  Packages from PyPi and OS repositories are not affected. This fixes an issue that kept the YAML
+  parser from initializing.
+
+20210210 v1.14.3
+- Add hciconfig parser tested on linux
+- Update dig parser to simplify answer data logic
+
+20210205 v1.14.2
+- Update dig parser to fix cases where there are spaces in the answer data (e.g. TXT records)
+
+20210106 v1.14.1
+- Add iw-scan parser tested on linux (beta)
+- Update date parser for Ubuntu 20.04 support
+- Update last parser for last -F support
+- Update last parser to add convenience fields and augment data for easier parsing
+- Update man page
+- Minor documentation updates
+
 20201231 v1.14.0
 - Add hashsum parser tested on linux, macos
 - Add hash parser tested on linux, macos

CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to jc
+We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+- Proposing a new parser
+
+## We Develop with Github
+We use github to host code, to track issues and feature requests, as well as accept pull requests.
+
+## We Use Github Flow, So All Code Changes Happen Through Pull Requests
+Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
+
+1. Open an issue to discuss the new feature, bug fix, or parser before opening a pull request. For new parsers, it is important to agree upon a schema before developing the parser.
+2. Fork the repo and create your branch from `dev`, if available, otherwise `master`.
+3. For new parsers: 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 to get started. You can even place a new parser python module file in the [parser plugin directory](https://github.com/kellyjonbrazil/jc#custom-parsers) to get started right away with just a standard `jc` installation.
+4. If you've added code that should be tested, add tests. All new parsers should have several sample outputs and tests.
+5. Documentation is auto-generated from docstrings, so ensure they are clear and accurate.
+6. Ensure the test suite passes. (Note: "**America/Los_Angeles**" timezone should be configured on the test system)
+7. Make sure your code lints.
+8. Issue that pull request!
+
+## Parser Schema Guidelines
+- Try to keep the schema as flat as possible - typically a list of flat dictionaries
+- Keys should be lowercase, contain no special characters, and spaces should be converted to underscores
+- Keys should be static, if possible. If they have to be dynamic, then they should not contain lists or dictionaries
+
+This will make it easier to use tools like `jq` without requiring escaping of special characters, encapsulating key names in [""], keeps paths predictable, and makes iterating and searching for values easier.
+
+**Examples**
+
+Bad:
+```json
+{
+  "Interface 1": [
+    "192.168.1.1",
+    "172.16.1.1"
+  ],
+  "Wifi Interface 1": [
+    "10.1.1.1"
+  ]
+}
+```
+Good:
+```json
+[
+  {
+    "interface": "Interface 1",
+    "ip_addresses": [
+      "192.168.1.1",
+      "172.16.1.1"
+    ]
+  },
+  {
+    "interface": "Wifi Interface 1",
+    "ip_addresses": [
+      "10.1.1.1"
+    ]
+  }
+]
+```
+
+## Tests
+It is essential to have good command output sample coverage and tests to keep the `jc` parser quality high.
+
+Many parsers include calculated timestamp fields using the `jc.utils.timestamp` class. Naive timestamps created with this class should be generated on a system configured with the "**America/Los_Angeles**" timezone on linux/macOS/unix and "**Pacific Standard Time**" timezone on Windows for tests to pass on the Github Actions CI tests. This timezone should be configured on your local system before running the tests locally, as well.
+
+## Any contributions you make will be under the MIT Software License
+In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
+
+## Report bugs using Github's Issues
+We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/kellyjonbrazil/jc/issues); it's that easy!
+
+## Write bug reports with detail, background, and sample code
+**Great Bug Reports** tend to have:
+
+- A quick summary and/or background
+- Steps to reproduce
+  - Be specific!
+  - Give sample code if you can.
+- What you expected would happen
+- What actually happens
+- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
+
+## Use a Consistent Coding Style
+* 4 spaces for indentation rather than tabs
+* Use a Python linter that will enforce PEP 8 and other best practices

MANIFEST.in

@@ -0,0 +1,3 @@
+include jc/man/jc.1.gz
+include man/jc.1
+include CHANGELOG

README.md

@@ -1,89 +1,79 @@
 ![Tests](https://github.com/kellyjonbrazil/jc/workflows/Tests/badge.svg?branch=master)
 ![Pypi](https://img.shields.io/pypi/v/jc.svg)
 
-> Try the new `jc` [web demo](https://jc-web-demo.herokuapp.com/)!
+> Try the `jc` [web demo](https://jc-web-demo.herokuapp.com/)
 
-> JC is [now available](https://galaxy.ansible.com/community/general) as an Ansible filter plugin in the `community.general` collection! See this [blog post](https://blog.kellybrazil.com/2020/08/30/parsing-command-output-in-ansible-with-jc/) for an example.
+> JC is [now available](https://galaxy.ansible.com/community/general) as an Ansible filter plugin in the `community.general` collection. See this [blog post](https://blog.kellybrazil.com/2020/08/30/parsing-command-output-in-ansible-with-jc/) for an example.
 
 # JC
 JSON CLI output utility
 
 `jc` JSONifies the output of many CLI tools and file-types for easier parsing in scripts. See the [**Parsers**](#parsers) section for supported commands and file-types.
-
-This allows further command-line processing of output with tools like `jq` by piping commands:
 ```bash
-ls -l /usr/bin | jc --ls | jq '.[] | select(.size > 50000000)'
+dig example.com | jc --dig
 ```
 ```json
-{
-  "filename": "docker",
-  "flags": "-rwxr-xr-x",
-  "links": 1,
-  "owner": "root",
-  "group": "root",
-  "size": 68677120,
-  "date": "Aug 14 19:41"
-}
+[{"id":38052,"opcode":"QUERY","status":"NOERROR","flags":["qr","rd","ra"],"query_num":1,"answer_num":1,
+"authority_num":0,"additional_num":1,"opt_pseudosection":{"edns":{"version":0,"flags":[],"udp":4096}},"question":
+{"name":"example.com.","class":"IN","type":"A"},"answer":[{"name":"example.com.","class":"IN","type":"A","ttl":
+39049,"data":"93.184.216.34"}],"query_time":49,"server":"2600:1700:bab0:d40::1#53(2600:1700:bab0:d40::1)","when":
+"Fri Apr 16 16:09:00 PDT 2021","rcvd":56,"when_epoch":1618614540,"when_epoch_utc":null}]
+```
+This allows further command-line processing of output with tools like `jq` or [`jello`](https://github.com/kellyjonbrazil/jello) by piping commands:
+```bash
+$ dig example.com | jc --dig | jq -r '.[].answer[].data'
+93.184.216.34
 ```
 or using the alternative "magic" syntax:
 ```bash
-jc ls -l /usr/bin | jq '.[] | select(.size > 50000000)'
-```
-```json
-{
-  "filename": "docker",
-  "flags": "-rwxr-xr-x",
-  "links": 1,
-  "owner": "root",
-  "group": "root",
-  "size": 68677120,
-  "date": "Aug 14 19:41"
-}
+$ jc dig example.com | jq -r '.[].answer[].data'
+93.184.216.34
 ```
 The `jc` parsers can also be used as python modules. In this case the output will be a python dictionary, or list of dictionaries, instead of JSON:
 ```python
->>> import jc.parsers.ls
->>> 
->>> data='''-rwxr-xr-x  1 root  wheel    23648 May  3 22:26 cat
-... -rwxr-xr-x  1 root  wheel    30016 May  3 22:26 chmod
-... -rwxr-xr-x  1 root  wheel    29024 May  3 22:26 cp
-... -rwxr-xr-x  1 root  wheel   375824 May  3 22:26 csh
-... -rwxr-xr-x  1 root  wheel    28608 May  3 22:26 date
-... -rwxr-xr-x  1 root  wheel    32000 May  3 22:26 dd
-... -rwxr-xr-x  1 root  wheel    23392 May  3 22:26 df
-... -rwxr-xr-x  1 root  wheel    18128 May  3 22:26 echo'''
+>>> import subprocess
+>>> import jc
 >>>
->>> jc.parsers.ls.parse(data)
-[{'filename': 'cat', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 23648,
-'date': 'May 3 22:26'}, {'filename': 'chmod', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root',
-'group': 'wheel', 'size': 30016, 'date': 'May 3 22:26'}, {'filename': 'cp', 'flags': '-rwxr-xr-x',
-'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 29024, 'date': 'May 3 22:26'}, {'filename': 'csh',
-'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 375824, 'date': 'May 3
-22:26'}, {'filename': 'date', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel',
-'size': 28608, 'date': 'May 3 22:26'}, {'filename': 'dd', 'flags': '-rwxr-xr-x', 'links': 1, 'owner':
-'root', 'group': 'wheel', 'size': 32000, 'date': 'May 3 22:26'}, {'filename': 'df', 'flags':
-'-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 23392, 'date': 'May 3 22:26'},
-{'filename': 'echo', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 18128,
-'date': 'May 3 22:26'}]
+>>> cmd_output = subprocess.check_output(['dig', 'example.com'], text=True)
+>>> data = jc.parse('dig', cmd_output)
+>>>
+>>> data
+[{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', 'flags': ['qr', 'rd', 'ra'], 'query_num': 1, 'answer_num':
+1, 'authority_num': 0, 'additional_num': 1, 'opt_pseudosection': {'edns': {'version': 0, 'flags': [], 'udp':
+4096}}, 'question': {'name': 'example.com.', 'class': 'IN', 'type': 'A'}, 'answer': [{'name': 'example.com.',
+'class': 'IN', 'type': 'A', 'ttl': 29658, 'data': '93.184.216.34'}], 'query_time': 52, 'server':
+'2600:1700:bab0:d40::1#53(2600:1700:bab0:d40::1)', 'when': 'Fri Apr 16 16:13:00 PDT 2021', 'rcvd': 56,
+'when_epoch': 1618614780, 'when_epoch_utc': None}]
 ```
-Two representations of the data are possible. The default representation uses a strict schema per parser and converts known numbers to int/float JSON values. Certain known values of `None` are converted to JSON `null`, known boolean values are converted, and, in some cases, additional semantic context fields are added.
+
+> For `jc` Python package documentation, use `help('jc')`, `help('jc.lib')`, or see the [online documentation](https://github.com/kellyjonbrazil/jc/tree/master/docs).
+
+Two representations of the data are available. The default representation uses a strict schema per parser and converts known numbers to int/float JSON values. Certain known values of `None` are converted to JSON `null`, known boolean values are converted, and, in some cases, additional semantic context fields are added.
 
 To access the raw, pre-processed JSON, use the `-r` cli option or the `raw=True` function parameter in `parse()`.
 
-Schemas for each parser can be found in the [`docs/parsers`](https://github.com/kellyjonbrazil/jc/tree/master/docs/parsers) folder. 
+Schemas for each parser can be found at the documentation link beside each [**Parser**](#parsers) below.
 
 Release notes can be found [here](https://blog.kellybrazil.com/category/jc-news/).
 
 ## Why Would Anyone Do This!?
-For more information on the motivations for this project, please see my [blog post](https://blog.kellybrazil.com/2019/11/26/bringing-the-unix-philosophy-to-the-21st-century/).
+For more information on the motivations for this project, please see my blog post on [Bringing the Unix Philosophy to the 21st Century](https://blog.kellybrazil.com/2019/11/26/bringing-the-unix-philosophy-to-the-21st-century/).
 
 See also:
 - [libxo on FreeBSD](http://juniper.github.io/libxo/libxo-manual.html)
 - [powershell](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/convertto-json?view=powershell-7)
 - [blog: linux apps should have a json flag](https://thomashunter.name/posts/2012-06-06-linux-cli-apps-should-have-a-json-flag)
+- [Hacker News discussion](https://news.ycombinator.com/item?id=28266193)
+- [Reddit discussion](https://www.reddit.com/r/programming/comments/pa4cbb/bringing_the_unix_philosophy_to_the_21st_century/)
+
+Use Cases:
+- [Bash scripting](https://blog.kellybrazil.com/2021/04/12/practical-json-at-the-command-line/)
+- [Ansible command output parsing](https://blog.kellybrazil.com/2020/08/30/parsing-command-output-in-ansible-with-jc/)
+- [Saltstack command output parsing](https://blog.kellybrazil.com/2020/09/15/parsing-command-output-in-saltstack-with-jc/)
+- [Nornir command output parsing](https://blog.kellybrazil.com/2020/12/09/parsing-command-output-in-nornir-with-jc/)
 
 ## Installation
-There are several ways to get `jc`. You can install via `pip`; other OS package repositories like `apt-get`, `dnf`, `zypper`, `pacman`, `nix-env`, `guix`, `brew`, or `portsnap`; via DEB/RPM packages; or by downloading the correct binary for your architecture and running it anywhere on your filesystem.
+There are several ways to get `jc`. You can install via `pip`, OS package repositories, via DEB/RPM/MSI packaged binaries for linux and Windows, or by downloading the correct binary for your architecture and running it anywhere on your filesystem.
 
 ### Pip (macOS, linux, unix, Windows)
 ```bash
@@ -98,95 +88,140 @@ pip3 install jc
 | Fedora linux          | `dnf install jc`                                                              |
 | openSUSE linux        | `zypper install jc`                                                           |
 | Arch linux            | `pacman -S jc`                                                                |
-| NixOS linux           | `nix-env -iA nixpkgs.jc`                                                      |
+| NixOS linux           | `nix-env -iA nixpkgs.jc` or `nix-env -iA nixos.jc`                            |
 | Guix System linux     | `guix install jc`                                                             |
-| MacOS                 | `brew 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`                         |
 
-> For more packages and binaries, see https://kellyjonbrazil.github.io/jc-packaging/.
+> For more OS Packages, see https://repology.org/project/jc/versions.
+
+### Binaries and Packages
+For precompiled binaries and packages, see [Releases](https://github.com/kellyjonbrazil/jc/releases) on Github.
 
 ## Usage
 `jc` accepts piped input from `STDIN` and outputs a JSON representation of the previous command's output to `STDOUT`.
 ```bash
 COMMAND | jc PARSER [OPTIONS]
 ```
-Alternatively, the "magic" syntax can be used by prepending `jc` to the command to be converted. Options can be passed to `jc` immediately before the command is given. (Note: command aliases are not supported)
+Alternatively, the "magic" syntax can be used by prepending `jc` to the command to be converted. Options can be passed to `jc` immediately before the command is given. (Note: command aliases and shell builtins are not supported)
 ```bash
 jc [OPTIONS] COMMAND
 ```
 The JSON output can be compact (default) or pretty formatted with the `-p` option.
 
 ### Parsers
-- `--airport` enables the `airport -I` command parser (OSX)
-- `--airport-s` enables the `airport -s` command parser (OSX)
-- `--arp` enables the `arp` command parser
-- `--blkid` enables the `blkid` command parser
-- `--cksum` enables the `cksum` and `sum` command parser
-- `--crontab` enables the `crontab` command and file parser
-- `--crontab-u` enables the `crontab` file parser with user support
-- `--csv` enables the `CSV` file parser
-- `--date` enables the `date` command parser
-- `--df` enables the `df` command parser
-- `--dig` enables the `dig` command parser
-- `--dmidecode` enables the `dmidecode` command parser
-- `--du` enables the `du` command parser
-- `--env` enables the `env` and `printenv` command parser
-- `--file` enables the `file` command parser
-- `--free` enables the `free` command parser
-- `--fstab` enables the `/etc/fstab` file parser
-- `--group` enables the `/etc/group` file parser
-- `--gshadow` enables the `/etc/gshadow` file parser
-- `--hash` enables the `hash` command parser
-- `--hashsum` enables the `hashsum` command parser (`md5sum`, `shasum`, etc.)
-- `--history` enables the `history` command parser
-- `--hosts` enables the `/etc/hosts` file parser
-- `--id` enables the `id` command parser
-- `--ifconfig` enables the `ifconfig` command parser
-- `--ini` enables the `INI` file parser
-- `--iptables` enables the `iptables` command parser
-- `--jobs` enables the `jobs` command parser
-- `--kv` enables the `Key/Value` file parser
-- `--last` enables the `last` and `lastb` command parser
-- `--ls` enables the `ls` and `vdir` command parser
-- `--lsblk` enables the `lsblk` command parser
-- `--lsmod` enables the `lsmod` command parser
-- `--lsof` enables the `lsof` command parser
-- `--mount` enables the `mount` command parser
-- `--netstat` enables the `netstat` command parser
-- `--ntpq` enables the `ntpq -p` command parser
-- `--passwd` enables the `/etc/passwd` file parser
-- `--ping` enables the `ping` and `ping6` command parser
-- `--pip-list` enables the `pip list` command parser
-- `--pip-show` enables the `pip show` command parser
-- `--ps` enables the `ps` command parser
-- `--route` enables the `route` command parser
-- `--shadow` enables the `/etc/shadow` file parser
-- `--ss` enables the `ss` command parser
-- `--stat` enables the `stat` command parser
-- `--sysctl` enables the `sysctl -a` command parser
-- `--systemctl` enables the `systemctl` command parser
-- `--systemctl-lj` enables the `systemctl list-jobs` command parser
-- `--systemctl-ls` enables the `systemctl list-sockets` command parser
-- `--systemctl-luf` enables the `systemctl list-unit-files` command parser
-- `--timedatectl` enables the `timedatectl status` command parser
-- `--tracepath` enables the `tracepath` and `tracepath6` command parser
-- `--traceroute` enables the `traceroute` and `traceroute6` command parser
-- `--uname` enables the `uname -a` command parser
-- `--uptime` enables the `uptime` command parser
-- `--w` enables the `w` command parser
-- `--wc` enables the `wc` command parser
-- `--who` enables the `who` command parser
-- `--xml` enables the `XML` file parser
-- `--yaml` enables the `YAML` file parser
+
+- `--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))
+- `--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))
+- `--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))
+- `--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))
 
 ### Options
 - `-a` about `jc`. Prints information about `jc` and the parsers (in JSON, of course!)
-- `-d` debug mode. Prints trace messages if parsing issues encountered (use `-dd` for verbose debugging)
+- `-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 `-dd` for verbose debugging)
+- `-h` help. Use `jc -h --parser_name` for parser documentation
 - `-m` monochrome JSON output
 - `-p` pretty format the JSON output
-- `-q` quiet mode. Suppresses warning messages
-- `-r` raw output. Provides a more literal JSON output with all values as strings and no additional semantic processing
+- `-q` quiet mode. Suppresses parser warning messages (use `-qq` to ignore streaming parser errors)
+- `-r` raw output. Provides a more literal JSON output, typically with string values and no additional semantic processing
+- `-u` unbuffer output
+- `-v` version information
+
+### Exit Codes
+Any fatal errors within `jc` will generate an exit code of `100`, otherwise the exit code will be `0`. When using the "magic" syntax (e.g. `jc ifconfig eth0`), `jc` will store the exit code of the program being parsed and add it to the `jc` exit code. This way it is easier to determine if an error was from the parsed program or `jc`.
+
+Consider the following examples using `ifconfig`:
+
+| `ifconfig` exit code | `jc` exit code | Combined exit code | Interpretation                     | 
+|----------------------|----------------|--------------------|------------------------------------|
+| `0`                  | `0`            | `0`                | No errors                          |
+| `1`                  | `0`            | `1`                | Error in  `ifconfig`               |
+| `0`                  | `100`          | `100`              | Error in  `jc`                     |
+| `1`                  | `100`          | `101`              | Error in  both `ifconfig` and `jc` |
+
 
 ### Setting Custom Colors via Environment Variable
 You can specify custom colors via the `JC_COLORS` environment variable. The `JC_COLORS` environment variable takes four comma separated string values in the following format:
@@ -204,6 +239,67 @@ or
 JC_COLORS=default,default,default,default
 ```
 
+### Disable Colors via Environment Variable
+You can set the [`NO_COLOR`](http://no-color.org/) environment variable to any value to disable color output in `jc`. Note that using the `-C` option to force 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 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 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.
+
+> Note: Streaming parsers cannot be used with the "magic" syntax
+
+#### Ignoring Errors
+
+You may want to ignore parsing errors when using streaming parsers since these may be used in long-lived processing pipelines and errors can break the pipe. To ignore parsing errors, use the `-qq` cli option or the `ignore_exceptions=True` argument with the `parse()` function. This will add a `_jc_meta` object to the JSON output with a `success` attribute. If `success` is `true`, then there were no issues parsing the line. If `success` is `false`, then a parsing issue was found and `error` and `line` fields will be added to include a short error description and the contents of the unparsable line, respectively:
+
+Successfully parsed line with `-qq` option:
+```json
+{
+  "command_data": "data",
+  "_jc_meta": {
+    "success": true
+  }
+}
+```
+Unsuccessfully parsed line with `-qq` option:
+```json
+{
+  "_jc_meta": {
+    "success": false,
+    "error": "error message",
+    "line": "original line data"
+  }
+}
+```
+
+#### Unbuffering Output
+
+Most operating systems will buffer output that is being piped from process to process. The buffer is usually around 4KB. When viewing the output in the terminal the OS buffer is not engaged so output is immediately displayed on the screen. When piping multiple processes together, though, it may seem as if the output is hanging when the input data is very slow (e.g. `ping`):
+```
+$ ping 1.1.1.1 | jc --ping-s | jq
+<slow output>
+```
+This is because the OS engages the 4KB buffer between `jc` and `jq` in this example. To display the data on the terminal in realtime, you can disable the buffer with the `-u` (unbuffer) cli option:
+```
+$ ping 1.1.1.1 | jc --ping-s -u | jq
+{"type":"reply","pattern":null,"timestamp":null,"bytes":"64","response_ip":"1.1.1.1","icmp_seq":"1","ttl":"128","time_ms":"24.6","duplicate":false}
+{"type":"reply","pattern":null,"timestamp":null,"bytes":"64","response_ip":"1.1.1.1","icmp_seq":"2","ttl":"128","time_ms":"26.8","duplicate":false}
+...
+```
+> Note: Unbuffered output can be slower for large data streams.
+
+#### Using Streaming Parsers as Python Modules
+
+Streaming parsers accept any iterable object and return a generator iterator 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:
+```python
+import jc
+
+result = jc.parse('ls_s', ls_command_output.splitlines())
+for item in result:
+    print(item["filename"])
+```
+
 ### Custom Parsers
 Custom local parser plugins may be placed in a `jc/jcparsers` folder in your local **"App data directory"**:
 
@@ -211,32 +307,62 @@ Custom local parser plugins may be placed in a `jc/jcparsers` folder in your loc
 - macOS: `$HOME/Library/Application Support/jc/jcparsers`
 - Windows: `$LOCALAPPDATA\jc\jc\jcparsers`
 
-Local parser plugins are standard python module files. Use the [`jc/parsers/foo.py`](https://github.com/kellyjonbrazil/jc/blob/master/jc/parsers/foo.py) parser as a template and simply place a `.py` file in the `jcparsers` subfolder.
+Local parser plugins are standard python module files. 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) 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 plugins.
+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.
 
 > Note: The application data directory follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
 
+### Caveats
+
+#### Locale
+
+For best results set the `LANG` locale environment variable to `C` or `en_US.UTF-8`. For example, either by setting directly on the command-line:
+```
+$ LANG=C date | jc --date
+```
+or by exporting to the environment before running commands:
+```
+$ export LANG=C
+```
+
+#### Timezones
+
+Some parsers have calculated epoch timestamp fields added to the output. Unless a timestamp field name has a `_utc` suffix it is considered naive. (i.e. based on the local timezone of the system the `jc` parser was run on).
+
+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.
+
 ## Compatibility
-Some parsers like `ls`, `ps`, `dig`, etc. will work on any platform. Other parsers that are platform-specific will generate a warning message if they are used on an unsupported platform. To see all parser information, including compatibility, run `jc -ap`.
+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 OSX laptop. In that case you can suppress the warning message with the `-q` cli option or the `quiet=True` function parameter in `parse()`:
+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:
 ```bash
 cat lsof.out | jc --lsof -q
 ```
+or Windows:
+```bash
+type lsof.out | jc --lsof -q
+```
 
 Tested on:
 - Centos 7.7
-- Ubuntu 18.4
+- Ubuntu 18.04
+- Ubuntu 20.04
 - Fedora32
-- OSX 10.11.6
-- OSX 10.14.6
+- macOS 10.11.6
+- macOS 10.14.6
 - NixOS
 - FreeBSD12
+- Windows 10
+- Windows 2016 Server
+- Windows 2019 Server
 
 ## 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) parser as a template and submit your parser with a pull request.
+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.
+
+Please see the [Contributing Guidelines](https://github.com/kellyjonbrazil/jc/blob/master/CONTRIBUTING.md) for more information.
 
 ## Acknowledgments
 - Local parser plugin feature contributed by [Dean Serenevy](https://github.com/duelafn)
@@ -249,7 +375,7 @@ Feel free to add/improve code or parsers! You can use the [`jc/parsers/foo.py`](
 - Excellent constructive feedback from [Ilya Sher](https://github.com/ilyash-b)
 
 ## Examples
-Here are some examples of `jc` output. For more examples, see [EXAMPLES.md](https://github.com/kellyjonbrazil/jc/blob/master/EXAMPLES.md) or the [parser documentation](https://github.com/kellyjonbrazil/jc/tree/master/docs/parsers).
+Here are some examples of `jc` output. For more examples, see [here](https://kellyjonbrazil.github.io/jc/EXAMPLES) or the parser documentation.
 ### arp
 ```bash
 arp | jc --arp -p          # or:  jc -p arp
@@ -330,46 +456,6 @@ cat homes.csv | jc --csv -p
   }
 ]
 ```
-### dig
-```bash
-dig cnn.com @205.251.194.64 | jc --dig -p          # or:  jc -p dig cnn.com @205.251.194.64
-```
-```json
-[
-  {
-    "id": 5509,
-    "opcode": "QUERY",
-    "status": "NOERROR",
-    "flags": [
-      "qr",
-      "rd",
-      "ra"
-    ],
-    "query_num": 1,
-    "answer_num": 1,
-    "authority_num": 0,
-    "additional_num": 1,
-    "question": {
-      "name": "cnn.com.",
-      "class": "IN",
-      "type": "A"
-    },
-    "answer": [
-      {
-        "name": "cnn.com.",
-        "class": "IN",
-        "type": "A",
-        "ttl": 60,
-        "data": "151.101.129.67"
-      }
-    ],
-    "query_time": 28,
-    "server": "2600",
-    "when": "Tue Nov 12 07:13:03 PST 2019",
-    "rcvd": 100
-  }
-]
-```
 ### /etc/hosts file
 ```bash
 cat /etc/hosts | jc --hosts -p
@@ -797,12 +883,19 @@ uptime | jc --uptime -p          # or:  jc -p uptime
 ```
 ```json
 {
-  "time": "11:30:44",
-  "uptime": "1 day, 21:17",
-  "users": 1,
-  "load_1m": 0.01,
-  "load_5m": 0.04,
-  "load_15m": 0.05
+  "time": "11:35",
+  "uptime": "3 days, 4:03",
+  "users": 5,
+  "load_1m": 1.88,
+  "load_5m": 2.0,
+  "load_15m": 1.94,
+  "time_hour": 11,
+  "time_minute": 35,
+  "time_second": null,
+  "uptime_days": 3,
+  "uptime_hours": 4,
+  "uptime_minutes": 3,
+  "uptime_total_seconds": 273780
 }
 ```
 ### XML files
@@ -919,4 +1012,6 @@ cat istio.yaml | jc --yaml -p
     }
   }
 ]
-```
+```
+
+© 2019-2022 Kelly Brazil

docgen.sh

@@ -3,65 +3,42 @@
 # requires pydoc-markdown 2.1.0.post1
 
 cd jc
+echo Building docs for: package
 pydocmd simple jc+ > ../docs/readme.md
+
+echo Building docs for: lib
+pydocmd simple lib+ > ../docs/lib.md
+
+echo Building docs for: utils
 pydocmd simple utils+ > ../docs/utils.md
-pydocmd simple jc.parsers.airport+ > ../docs/parsers/airport.md
-pydocmd simple jc.parsers.airport_s+ > ../docs/parsers/airport_s.md
-pydocmd simple jc.parsers.arp+ > ../docs/parsers/arp.md
-pydocmd simple jc.parsers.blkid+ > ../docs/parsers/blkid.md
-pydocmd simple jc.parsers.cksum+ > ../docs/parsers/cksum.md
-pydocmd simple jc.parsers.crontab+ > ../docs/parsers/crontab.md
-pydocmd simple jc.parsers.crontab_u+ > ../docs/parsers/crontab_u.md
-pydocmd simple jc.parsers.csv+ > ../docs/parsers/csv.md
-pydocmd simple jc.parsers.date+ > ../docs/parsers/date.md
-pydocmd simple jc.parsers.df+ > ../docs/parsers/df.md
-pydocmd simple jc.parsers.dig+ > ../docs/parsers/dig.md
-pydocmd simple jc.parsers.dmidecode+ > ../docs/parsers/dmidecode.md
-pydocmd simple jc.parsers.du+ > ../docs/parsers/du.md
-pydocmd simple jc.parsers.env+ > ../docs/parsers/env.md
-pydocmd simple jc.parsers.file+ > ../docs/parsers/file.md
-pydocmd simple jc.parsers.free+ > ../docs/parsers/free.md
-pydocmd simple jc.parsers.fstab+ > ../docs/parsers/fstab.md
-pydocmd simple jc.parsers.group+ > ../docs/parsers/group.md
-pydocmd simple jc.parsers.gshadow+ > ../docs/parsers/gshadow.md
-pydocmd simple jc.parsers.hash+ > ../docs/parsers/hash.md
-pydocmd simple jc.parsers.hashsum+ > ../docs/parsers/hashsum.md
-pydocmd simple jc.parsers.history+ > ../docs/parsers/history.md
-pydocmd simple jc.parsers.hosts+ > ../docs/parsers/hosts.md
-pydocmd simple jc.parsers.id+ > ../docs/parsers/id.md
-pydocmd simple jc.parsers.ifconfig+ > ../docs/parsers/ifconfig.md
-pydocmd simple jc.parsers.ini+ > ../docs/parsers/ini.md
-pydocmd simple jc.parsers.iptables+ > ../docs/parsers/iptables.md
-pydocmd simple jc.parsers.jobs+ > ../docs/parsers/jobs.md
-pydocmd simple jc.parsers.kv+ > ../docs/parsers/kv.md
-pydocmd simple jc.parsers.last+ > ../docs/parsers/last.md
-pydocmd simple jc.parsers.ls+ > ../docs/parsers/ls.md
-pydocmd simple jc.parsers.lsblk+ > ../docs/parsers/lsblk.md
-pydocmd simple jc.parsers.lsmod+ > ../docs/parsers/lsmod.md
-pydocmd simple jc.parsers.lsof+ > ../docs/parsers/lsof.md
-pydocmd simple jc.parsers.mount+ > ../docs/parsers/mount.md
-pydocmd simple jc.parsers.netstat+ > ../docs/parsers/netstat.md
-pydocmd simple jc.parsers.ntpq+ > ../docs/parsers/ntpq.md
-pydocmd simple jc.parsers.passwd+ > ../docs/parsers/passwd.md
-pydocmd simple jc.parsers.ping+ > ../docs/parsers/ping.md
-pydocmd simple jc.parsers.pip_list+ > ../docs/parsers/pip_list.md
-pydocmd simple jc.parsers.pip_show+ > ../docs/parsers/pip_show.md
-pydocmd simple jc.parsers.ps+ > ../docs/parsers/ps.md
-pydocmd simple jc.parsers.route+ > ../docs/parsers/route.md
-pydocmd simple jc.parsers.shadow+ > ../docs/parsers/shadow.md
-pydocmd simple jc.parsers.ss+ > ../docs/parsers/ss.md
-pydocmd simple jc.parsers.stat+ > ../docs/parsers/stat.md
-pydocmd simple jc.parsers.sysctl+ > ../docs/parsers/sysctl.md
-pydocmd simple jc.parsers.systemctl+ > ../docs/parsers/systemctl.md
-pydocmd simple jc.parsers.systemctl_lj+ > ../docs/parsers/systemctl_lj.md
-pydocmd simple jc.parsers.systemctl_ls+ > ../docs/parsers/systemctl_ls.md
-pydocmd simple jc.parsers.systemctl_luf+ > ../docs/parsers/systemctl_luf.md
-pydocmd simple jc.parsers.timedatectl+ > ../docs/parsers/timedatectl.md
-pydocmd simple jc.parsers.tracepath+ > ../docs/parsers/tracepath.md
-pydocmd simple jc.parsers.traceroute+ > ../docs/parsers/traceroute.md
-pydocmd simple jc.parsers.uname+ > ../docs/parsers/uname.md
-pydocmd simple jc.parsers.uptime+ > ../docs/parsers/uptime.md
-pydocmd simple jc.parsers.w+ > ../docs/parsers/w.md
-pydocmd simple jc.parsers.who+ > ../docs/parsers/who.md
-pydocmd simple jc.parsers.xml+ > ../docs/parsers/xml.md
-pydocmd simple jc.parsers.yaml+ > ../docs/parsers/yaml.md
+
+echo Building docs for: universal parser
+pydocmd simple jc.parsers.universal+ > ../docs/parsers/universal.md
+
+# a bit of inception here... jc is being used to help
+# automate the generation of its own documentation. :)
+
+# pull jc parser objects into a bash array from jq
+parsers=()
+while read -r value
+do
+    parsers+=("$value")
+done < <(jc -a | jq -c '.parsers[]')
+
+# iterate over the bash array
+for parser in "${parsers[@]}"
+do
+    parser_name=$(jq -r '.name' <<< "$parser")
+    compatible=$(jq -r '.compatible | join(", ")' <<< "$parser")
+    version=$(jq -r '.version' <<< "$parser")
+    author=$(jq -r '.author' <<< "$parser")
+    author_email=$(jq -r '.author_email' <<< "$parser")
+
+    echo "Building docs for: ${parser_name}"
+    echo "[Home](https://kellyjonbrazil.github.io/jc/)" > ../docs/parsers/"${parser_name}".md
+    pydocmd simple jc.parsers."${parser_name}"+ >> ../docs/parsers/"${parser_name}".md
+    echo "## Parser Information" >> ../docs/parsers/"${parser_name}".md
+    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
+done

docs/lib.md

@@ -0,0 +1,90 @@
+
+# lib
+jc - JSON CLI output utility
+JC lib module
+
+
+## parse
+```python
+parse(parser_mod_name,
+      data,
+      quiet=False,
+      raw=False,
+      ignore_exceptions=None,
+      **kwargs)
+```
+
+Parse the string data using the supplied parser module.
+
+This function provides a high-level API to simplify parser use. This
+function will call built-in parsers and custom plugin parsers.
+
+Example:
+
+    >>> import jc
+    >>> jc.parse('date', 'Tue Jan 18 10:23:07 PST 2022')
+    {'year': 2022, 'month': 'Jan', 'month_num': 1, 'day'...}
+
+To get a list of available parser module names, use `parser_mod_list()`
+or `plugin_parser_mod_list()`. `plugin_parser_mod_list()` is a subset
+of `parser_mod_list()`.
+
+You can also use the lower-level parser modules directly:
+
+    >>> import jc.parsers.date
+    >>> jc.parsers.date.parse('Tue Jan 18 10:23:07 PST 2022')
+
+Though, accessing plugin parsers directly is a bit more cumbersome, so
+this higher-level API is recommended. Here is how you can access plugin
+parsers without this API:
+
+    >>> import os
+    >>> import sys
+    >>> import jc.appdirs
+    >>> data_dir = jc.appdirs.user_data_dir('jc', 'jc')
+    >>> local_parsers_dir = os.path.join(data_dir, 'jcparsers')
+    >>> sys.path.append(local_parsers_dir)
+    >>> import my_custom_parser
+    >>> my_custom_parser.parse('command_data')
+
+Parameters:
+
+    parser_mod_name:    (string)     name of the parser module
+
+    data:               (string or   data to parse (string for normal
+                        iterator)    parsers, iterator of strings for
+                                     streaming parsers)
+
+    raw:                (boolean)    output preprocessed JSON if True
+
+    quiet:              (boolean)    suppress warning messages if True
+
+    ignore_exceptions:  (boolean)    ignore parsing exceptions if True
+                                     (streaming parsers only)
+
+Returns:
+
+    Standard Parsers:   Dictionary or List of Dictionaries
+    Streaming Parsers:  Generator Object containing Dictionaries
+
+
+## parser_mod_list
+```python
+parser_mod_list()
+```
+Returns a list of all available parser module names.
+
+## plugin_parser_mod_list
+```python
+plugin_parser_mod_list()
+```
+
+Returns a list of plugin parser module names. This function is a
+subset of `parser_mod_list()`.
+
+
+## get_help
+```python
+get_help(parser_mod_name)
+```
+Show help screen for the selected parser.

docs/parsers/acpi.md

@@ -0,0 +1,260 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.acpi
+jc - JSON CLI output utility `acpi` command output parser
+
+Usage (cli):
+
+    $ acpi -V | jc --acpi
+
+    or
+
+    $ jc acpi -V
+
+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:
+
+    [
+      {
+        "type":                             string,
+        "id":                               integer,
+        "state":                            string,
+        "charge_percent":                   integer,
+        "until_charged":                    string,
+        "until_charged_hours":              integer,
+        "until_charged_minuts":             integer,
+        "until_charged_seconds":            integer,
+        "until_charged_total_seconds":      integer,
+        "charge_remaining":                 string,
+        "charge_remaining_hours":           integer,
+        "charge_remaining_minutes":         integer,
+        "charge_remaining_seconds":         integer,
+        "charge_remaining_total_seconds":   integer,
+        "design_capacity_mah":              integer,
+        "last_full_capacity":               integer,
+        "last_full_capacity_percent":       integer,
+        "on-line":                          boolean,
+        "mode":                             string,
+        "temperature":                      float,
+        "temperature_unit":                 string,
+        "trip_points": [
+          {
+            "id":                           integer,
+            "switches_to_mode":             string,
+            "temperature":                  float,
+            "temperature_unit":             string
+          }
+        ],
+        "messages": [
+                                            string
+        ]
+      }
+    ]
+
+Examples:
+
+    $ acpi -V | jc --acpi -p
+    [
+      {
+        "type": "Battery",
+        "id": 0,
+        "state": "Charging",
+        "charge_percent": 71,
+        "until_charged": "00:29:20",
+        "design_capacity_mah": 2110,
+        "last_full_capacity": 2271,
+        "last_full_capacity_percent": 100,
+        "until_charged_hours": 0,
+        "until_charged_minutes": 29,
+        "until_charged_seconds": 20,
+        "until_charged_total_seconds": 1760
+      },
+      {
+        "type": "Adapter",
+        "id": 0,
+        "on-line": true
+      },
+      {
+        "type": "Thermal",
+        "id": 0,
+        "mode": "ok",
+        "temperature": 46.0,
+        "temperature_unit": "C",
+        "trip_points": [
+          {
+            "id": 0,
+            "switches_to_mode": "critical",
+            "temperature": 127.0,
+            "temperature_unit": "C"
+          },
+          {
+            "id": 1,
+            "switches_to_mode": "hot",
+            "temperature": 127.0,
+            "temperature_unit": "C"
+          }
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": 0,
+        "messages": [
+          "Processor 0 of 10"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": 1,
+        "messages": [
+          "Processor 0 of 10"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": 2,
+        "messages": [
+          "x86_pkg_temp no state information available"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": 3,
+        "messages": [
+          "Processor 0 of 10"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": 4,
+        "messages": [
+          "intel_powerclamp no state information available"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": 5,
+        "messages": [
+          "Processor 0 of 10"
+        ]
+      }
+    ]
+
+    $ acpi -V | jc --acpi -p -r
+    [
+      {
+        "type": "Battery",
+        "id": "0",
+        "state": "Charging",
+        "charge_percent": "71",
+        "until_charged": "00:29:20",
+        "design_capacity_mah": "2110",
+        "last_full_capacity": "2271",
+        "last_full_capacity_percent": "100"
+      },
+      {
+        "type": "Adapter",
+        "id": "0",
+        "on-line": true
+      },
+      {
+        "type": "Thermal",
+        "id": "0",
+        "mode": "ok",
+        "temperature": "46.0",
+        "temperature_unit": "C",
+        "trip_points": [
+          {
+            "id": "0",
+            "switches_to_mode": "critical",
+            "temperature": "127.0",
+            "temperature_unit": "C"
+          },
+          {
+            "id": "1",
+            "switches_to_mode": "hot",
+            "temperature": "127.0",
+            "temperature_unit": "C"
+          }
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": "0",
+        "messages": [
+          "Processor 0 of 10"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": "1",
+        "messages": [
+          "Processor 0 of 10"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": "2",
+        "messages": [
+          "x86_pkg_temp no state information available"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": "3",
+        "messages": [
+          "Processor 0 of 10"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": "4",
+        "messages": [
+          "intel_powerclamp no state information available"
+        ]
+      },
+      {
+        "type": "Cooling",
+        "id": "5",
+        "messages": [
+          "Processor 0 of 10"
+        ]
+      }
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/airport.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.airport
 jc - JSON CLI output utility `airport -I` command output parser
@@ -14,12 +15,33 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('airport', airport_command_output)
+
+    or
+
     import jc.parsers.airport
     result = jc.parsers.airport.parse(airport_command_output)
 
-Compatibility:
+Schema:
 
-    'darwin'
+    {
+      "agrctlrssi":        integer,
+      "agrextrssi":        integer,
+      "agrctlnoise":       integer,
+      "agrextnoise":       integer,
+      "state":             string,
+      "op_mode":           string,
+      "lasttxrate":        integer,
+      "maxrate":           integer,
+      "lastassocstatus":   integer,
+      "802_11_auth":       string,
+      "link_auth":         string,
+      "bssid":             string,
+      "ssid":              string,
+      "mcs":               integer,
+      "channel":           string
+    }
 
 Examples:
 
@@ -66,41 +88,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "agrctlrssi":        integer,
-      "agrextrssi":        integer,
-      "agrctlnoise":       integer,
-      "agrextnoise":       integer,
-      "state":             string,
-      "op_mode":           string,
-      "lasttxrate":        integer,
-      "maxrate":           integer,
-      "lastassocstatus":   integer,
-      "802_11_auth":       string,
-      "link_auth":         string,
-      "bssid":             string,
-      "ssid":              string,
-      "mcs":               integer,
-      "channel":           string
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -112,10 +100,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  darwin
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/airport_s.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.airport_s
 jc - JSON CLI output utility `airport -s` command output parser
@@ -14,12 +15,29 @@ Usage (cli):
 
 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)
 
-Compatibility:
+Schema:
 
-    'darwin'
+    [
+      {
+        "ssid":         string,
+        "bssid":        string,
+        "rssi":         integer,
+        "channel":      string,
+        "ht":           boolean,
+        "cc":           string,
+        "security": [
+                        string,
+        ]
+      }
+    ]
 
 Examples:
 
@@ -98,36 +116,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-    [
-      {
-        "ssid":      string,
-        "bssid":     string,
-        "rssi":      integer,
-        "channel":   string,
-        "ht":        boolean,
-        "cc":        string,
-        "security": [
-                     string,
-        ]
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -139,10 +128,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  darwin
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/arp.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.arp
 jc - JSON CLI output utility `arp` command output parser
@@ -14,12 +15,28 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('arp', arp_command_output)
+
+    or
+
     import jc.parsers.arp
     result = jc.parsers.arp.parse(arp_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'aix', 'freebsd', 'darwin'
+    [
+      {
+        "name":         string,
+        "address":      string,
+        "hwtype":       string,
+        "hwaddress":    string,
+        "flags_mask":   string,
+        "iface":        string,
+        "permanent":    boolean,
+        "expires":      integer
+      }
+    ]
 
 Examples:
 
@@ -108,36 +125,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "name":       string,
-        "address":    string,
-        "hwtype":     string,
-        "hwaddress":  string,
-        "flags_mask": string,
-        "iface":      string,
-        "permanent":  boolean,
-        "expires":    integer
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -149,10 +137,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, aix, freebsd, darwin
+
+Version 1.8 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/blkid.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.blkid
 jc - JSON CLI output utility `blkid` command output parser
@@ -12,12 +13,49 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('blkid', blkid_command_output)
+
+    or
+
     import jc.parsers.blkid
     result = jc.parsers.blkid.parse(blkid_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "device":                            string,
+        "uuid":                              string,
+        "type":                              string,
+        "usage":                             string,
+        "part_entry_scheme":                 string,
+        "part_entry_type":                   string,
+        "part_entry_flags":                  string,
+        "part_entry_number":                 integer,
+        "part_entry_offset":                 integer,
+        "part_entry_size":                   integer,
+        "part_entry_disk":                   string,
+        "id_fs_uuid":                        string,
+        "id_fs_uuid_enc":                    string,
+        "id_fs_version":                     string,
+        "id_fs_type":                        string,
+        "id_fs_usage":                       string,
+        "id_part_entry_scheme":              string,
+        "id_part_entry_type":                string,
+        "id_part_entry_flags":               string,
+        "id_part_entry_number":              integer,
+        "id_part_entry_offset":              integer,
+        "id_part_entry_size":                integer,
+        "id_iolimit_minimum_io_size":        integer,
+        "id_iolimit_physical_sector_size":   integer,
+        "id_iolimit_logical_sector_size":    integer,
+        "id_part_entry_disk":                string,
+        "minimum_io_size":                   integer,
+        "physical_sector_size":              integer,
+        "logical_sector_size":               integer
+      }
+    ]
 
 Examples:
 
@@ -90,57 +128,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "device":                            string,
-        "uuid":                              string,
-        "type":                              string,
-        "usage":                             string,
-        "part_entry_scheme":                 string,
-        "part_entry_type":                   string,
-        "part_entry_flags":                  string,
-        "part_entry_number":                 integer,
-        "part_entry_offset":                 integer,
-        "part_entry_size":                   integer,
-        "part_entry_disk":                   string,
-        "id_fs_uuid":                        string,
-        "id_fs_uuid_enc":                    string,
-        "id_fs_version":                     string,
-        "id_fs_type":                        string,
-        "id_fs_usage":                       string,
-        "id_part_entry_scheme":              string,
-        "id_part_entry_type":                string,
-        "id_part_entry_flags":               string,
-        "id_part_entry_number":              integer,
-        "id_part_entry_offset":              integer,
-        "id_part_entry_size":                integer,
-        "id_iolimit_minimum_io_size":        integer,
-        "id_iolimit_physical_sector_size":   integer,
-        "id_iolimit_logical_sector_size":    integer,
-        "id_part_entry_disk":                string,
-        "minimum_io_size":                   integer,
-        "physical_sector_size":              integer,
-        "logical_sector_size":               integer
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -152,10 +140,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/cksum.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.cksum
 jc - JSON CLI output utility `cksum` command output parser
@@ -16,12 +17,23 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('cksum', cksum_command_output)
+
+    or
+
     import jc.parsers.cksum
     result = jc.parsers.cksum.parse(cksum_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    [
+      {
+        "filename":     string,
+        "checksum":     integer,
+        "blocks":       integer
+      }
+    ]
 
 Examples:
 
@@ -50,31 +62,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "filename":     string,
-        "checksum":     integer,
-        "blocks":       integer
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -86,10 +74,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/crontab.md

@@ -1,6 +1,8 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.crontab
-jc - JSON CLI output utility `crontab -l` command output and crontab file parser
+jc - JSON CLI output utility `crontab -l` command output and crontab
+file parser
 
 Supports `crontab -l` command output and crontab files.
 
@@ -14,12 +16,46 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('crontab', crontab_output)
+
+    or
+
     import jc.parsers.crontab
     result = jc.parsers.crontab.parse(crontab_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'aix', 'freebsd'
+    {
+      "variables": [
+        {
+          "name":             string,
+          "value":            string
+        }
+      ],
+      "schedule": [
+        {
+          "occurrence"        string,
+          "minute": [
+                              string
+          ],
+          "hour": [
+                              string
+          ],
+          "day_of_month": [
+                              string
+          ],
+          "month": [
+                              string
+          ],
+          "day_of_week": [
+                              string
+          ],
+          "occurrence":       string,
+          "command":          string
+        }
+      ]
+    }
 
 Examples:
 
@@ -145,53 +181,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "variables": [
-        "name":               string,
-        "value":              string
-      ],
-      "schedule": [
-        {
-          "occurrence"        string,
-          "minute": [
-                              string
-          ],
-          "hour": [
-                              string
-          ],
-          "day_of_month": [
-                              string
-          ],
-          "month": [
-                              string
-          ],
-          "day_of_week": [
-                              string
-          ],
-          "occurrence":       string,
-          "command":          string
-        }
-      ]
-    }
-
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -203,10 +193,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, aix, freebsd
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/crontab_u.md

@@ -1,8 +1,11 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.crontab_u
-jc - JSON CLI output utility `crontab -l` command output and crontab file parser
+jc - JSON CLI output utility `crontab -l` command output and crontab
+file parser
 
-This version of the `crontab -l` parser supports output that contains user information for processes.
+This version of the `crontab -l` parser supports output that contains user
+information for processes.
 
 Usage (cli):
 
@@ -10,159 +13,22 @@ Usage (cli):
 
 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)
 
-Compatibility:
-
-    'linux', 'darwin', 'aix', 'freebsd'
-
-Examples:
-
-    $ cat /etc/crontab | jc --crontab-u -p
-    {
-      "variables": [
-        {
-          "name": "PATH",
-          "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin"
-        },
-        {
-          "name": "SHELL",
-          "value": "/bin/sh"
-        }
-      ],
-      "schedule": [
-        {
-          "minute": [
-            "25"
-          ],
-          "hour": [
-            "6"
-          ],
-          "day_of_month": [
-            "*"
-          ],
-          "month": [
-            "*"
-          ],
-          "day_of_week": [
-            "*"
-          ],
-          "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily )"
-        },
-        {
-          "minute": [
-            "47"
-          ],
-          "hour": [
-            "6"
-          ],
-          "day_of_month": [
-            "*"
-          ],
-          "month": [
-            "*"
-          ],
-          "day_of_week": [
-            "7"
-          ],
-          "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly )"
-        },
-        {
-          "minute": [
-            "52"
-          ],
-          "hour": [
-            "6"
-          ],
-          "day_of_month": [
-            "1"
-          ],
-          "month": [
-            "*"
-          ],
-          "day_of_week": [
-            "*"
-          ],
-          "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )"
-        }
-      ]
-    }
-
-    $ cat /etc/crontab | jc --crontab-u -p -r
-    {
-      "variables": [
-        {
-          "name": "PATH",
-          "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin"
-        },
-        {
-          "name": "SHELL",
-          "value": "/bin/sh"
-        }
-      ],
-      "schedule": [
-        {
-          "minute": "25",
-          "hour": "6",
-          "day_of_month": "*",
-          "month": "*",
-          "day_of_week": "*",
-          "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily )"
-        },
-        {
-          "minute": "47",
-          "hour": "6",
-          "day_of_month": "*",
-          "month": "*",
-          "day_of_week": "7",
-          "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly )"
-        },
-        {
-          "minute": "52",
-          "hour": "6",
-          "day_of_month": "1",
-          "month": "*",
-          "day_of_week": "*",
-          "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )"
-        }
-      ]
-    }
-
-
-
-
-## info
-```python
-info()
-```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
+Schema:
 
     {
       "variables": [
-        "name":               string,
-        "value":              string
+        {
+          "name":             string,
+          "value":            string
+        }
       ],
       "schedule": [
         {
@@ -189,7 +55,130 @@ Returns:
       ]
     }
 
+Examples:
 
+    $ cat /etc/crontab | jc --crontab-u -p
+    {
+      "variables": [
+        {
+          "name": "PATH",
+          "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sb..."
+        },
+        {
+          "name": "SHELL",
+          "value": "/bin/sh"
+        }
+      ],
+      "schedule": [
+        {
+          "minute": [
+            "25"
+          ],
+          "hour": [
+            "6"
+          ],
+          "day_of_month": [
+            "*"
+          ],
+          "month": [
+            "*"
+          ],
+          "day_of_week": [
+            "*"
+          ],
+          "user": "root",
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
+        },
+        {
+          "minute": [
+            "47"
+          ],
+          "hour": [
+            "6"
+          ],
+          "day_of_month": [
+            "*"
+          ],
+          "month": [
+            "*"
+          ],
+          "day_of_week": [
+            "7"
+          ],
+          "user": "root",
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
+        },
+        {
+          "minute": [
+            "52"
+          ],
+          "hour": [
+            "6"
+          ],
+          "day_of_month": [
+            "1"
+          ],
+          "month": [
+            "*"
+          ],
+          "day_of_week": [
+            "*"
+          ],
+          "user": "root",
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
+        }
+      ]
+    }
+
+    $ cat /etc/crontab | jc --crontab-u -p -r
+    {
+      "variables": [
+        {
+          "name": "PATH",
+          "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/..."
+        },
+        {
+          "name": "SHELL",
+          "value": "/bin/sh"
+        }
+      ],
+      "schedule": [
+        {
+          "minute": "25",
+          "hour": "6",
+          "day_of_month": "*",
+          "month": "*",
+          "day_of_week": "*",
+          "user": "root",
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
+        },
+        {
+          "minute": "47",
+          "hour": "6",
+          "day_of_month": "*",
+          "month": "*",
+          "day_of_week": "7",
+          "user": "root",
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
+        },
+        {
+          "minute": "52",
+          "hour": "6",
+          "day_of_month": "1",
+          "month": "*",
+          "day_of_week": "*",
+          "user": "root",
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
+        }
+      ]
+    }
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -201,10 +190,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, aix, freebsd
+
+Version 1.7 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/csv.md

@@ -1,8 +1,11 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.csv
 jc - JSON CLI output utility `csv` file parser
 
-The `csv` parser will attempt to automatically detect the delimiter character. If the delimiter cannot be detected it will default to comma. The first row of the file must be a header row.
+The `csv` 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.
 
 Usage (cli):
 
@@ -10,17 +13,30 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('csv', csv_output)
+
+    or
+
     import jc.parsers.csv
     result = jc.parsers.csv.parse(csv_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    csv file converted to a Dictionary:
+    https://docs.python.org/3/library/csv.html
+
+    [
+      {
+        "column_name1":     string,
+        "column_name2":     string
+      }
+    ]
 
 Examples:
 
     $ cat homes.csv
-    "Sell", "List", "Living", "Rooms", "Beds", "Baths", "Age", "Acres", "Taxes"
+    "Sell", "List", "Living", "Rooms", "Beds", "Baths", "Age", "Acres"...
     142, 160, 28, 10, 5, 3,  60, 0.28,  3167
     175, 180, 18,  8, 4, 1,  12, 0.43,  4033
     129, 132, 13,  6, 3, 1,  41, 0.33,  1471
@@ -69,30 +85,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Each dictionary represents a row in the csv file:
-
-    [
-      {
-        csv file converted to a Dictionary
-        https://docs.python.org/3/library/csv.html
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -104,10 +97,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/csv_s.md

@@ -0,0 +1,103 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.csv_s
+jc - JSON CLI output utility `csv` file streaming parser
+
+> This streaming parser outputs JSON Lines
+
+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.
+
+Usage (cli):
+
+    $ cat file.csv | jc --csv-s
+
+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:
+    https://docs.python.org/3/library/csv.html
+
+    {
+      "column_name1":     string,
+      "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
+        }
+    }
+
+Examples:
+
+    $ cat homes.csv
+    "Sell", "List", "Living", "Rooms", "Beds", "Baths", "Age", "Acres"...
+    142, 160, 28, 10, 5, 3,  60, 0.28,  3167
+    175, 180, 18,  8, 4, 1,  12, 0.43,  4033
+    129, 132, 13,  6, 3, 1,  41, 0.33,  1471
+    ...
+
+    $ cat homes.csv | jc --csv-s
+    {"Sell":"142","List":"160","Living":"28","Rooms":"10","Beds":"5"...}
+    {"Sell":"175","List":"180","Living":"18","Rooms":"8","Beds":"4"...}
+    {"Sell":"129","List":"132","Living":"13","Rooms":"6","Beds":"3"...}
+    ...
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False, ignore_exceptions=False)
+```
+
+Main text parsing generator function. Returns an iterator object.
+
+Parameters:
+
+    data:              (iterable)  line-based text data to parse
+                                   (e.g. sys.stdin or str.splitlines())
+
+    raw:               (boolean)   unprocessed output if True
+    quiet:             (boolean)   suppress warning messages if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+
+Yields:
+
+    Dictionary. Raw or processed structured data.
+
+Returns:
+
+    Iterator object
+
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/date.md

@@ -1,7 +1,14 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.date
 jc - JSON CLI output utility `date` command output parser
 
+The `epoch` calculated timestamp field is naive. (i.e. based on the local
+time of the system the parser is run on)
+
+The `epoch_utc` calculated timestamp field is timezone-aware and is only
+available if the timezone field is UTC.
+
 Usage (cli):
 
     $ date | jc --date
@@ -12,39 +19,65 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('date', date_command_output)
+
+    or
+
     import jc.parsers.date
     result = jc.parsers.date.parse(date_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'freebsd'
+    {
+      "year":               integer,
+      "month":              string,
+      "month_num":          integer,
+      "day":                integer,
+      "weekday":            string,
+      "weekday_num":        integer,
+      "hour":               integer,
+      "hour_24":            integer,
+      "minute":             integer,
+      "second":             integer,
+      "period":             string,
+      "timezone":           string,
+      "utc_offset":         string,      # null if timezone field is not UTC
+      "day_of_year":        integer,
+      "week_of_year":       integer,
+      "iso":                string,
+      "epoch":              integer,     # [0]
+      "epoch_utc":          integer,     # [1]
+      "timezone_aware":     boolean      # [2]
+    }
+
+    [0] naive timestamp
+    [1] timezone-aware timestamp. Only available if timezone field is UTC
+    [2] if true, all fields are correctly based on UTC
 
 Examples:
 
     $ date | jc --date -p
     {
-      "year": 2020,
-      "month_num": 7,
-      "day": 31,
-      "hour": 16,
-      "minute": 48,
-      "second": 11,
-      "month": "Jul",
-      "weekday": "Fri",
-      "weekday_num": 6,
-      "timezone": "PDT"
-    }
-
-    $ date | jc --date -p -r
-    {
-      "year": "2020",
-      "month": "Jul",
-      "day": "31",
-      "weekday": "Fri",
-      "hour": "16",
-      "minute": "50",
-      "second": "01",
-      "timezone": "PDT"
+      "year": 2021,
+      "month": "Mar",
+      "month_num": 3,
+      "day": 25,
+      "weekday": "Thu",
+      "weekday_num": 4,
+      "hour": 2,
+      "hour_24": 2,
+      "minute": 2,
+      "second": 26,
+      "period": "AM",
+      "timezone": "UTC",
+      "utc_offset": "+0000",
+      "day_of_year": 84,
+      "week_of_year": 12,
+      "iso": "2021-03-25T02:02:26+00:00",
+      "epoch": 1616662946,
+      "epoch_utc": 1616637746,
+      "timezone_aware": true
     }
 
 
@@ -52,36 +85,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "year":         integer,
-      "month_num":    integer,
-      "day":          integer,
-      "hour":         integer,
-      "minute":       integer,
-      "second":       integer,
-      "month":        string,
-      "weekday":      string,
-      "weekday_num":  integer,
-      "timezone":     string
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -93,10 +97,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 2.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/df.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.df
 jc - JSON CLI output utility `df` command output parser
@@ -12,12 +13,32 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('df', df_command_output)
+
+    or
+
     import jc.parsers.df
     result = jc.parsers.df.parse(df_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'freebsd'
+    [
+      {
+        "filesystem":        string,
+        "size":              string,
+        "1k_blocks":         integer,
+        "512_blocks":        integer,
+        "used":              integer,
+        "available":         integer,
+        "capacity_percent":  integer,
+        "ifree":             integer,
+        "iused":             integer,
+        "use_percent":       integer,
+        "iused_percent":     integer,
+        "mounted_on":        string
+      }
+    ]
 
 Examples:
 
@@ -84,40 +105,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "filesystem":        string,
-        "size":              string,
-        "1k_blocks":         integer,
-        "512_blocks":        integer,
-        "used":              integer,
-        "available":         integer,
-        "capacity_percent":  integer,
-        "ifree":             integer,
-        "iused":             integer,
-        "use_percent":       integer,
-        "iused_percent":     integer,
-        "mounted_on":        string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -129,10 +117,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.9 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/dig.md

@@ -1,7 +1,19 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.dig
 jc - JSON CLI output utility `dig` command output parser
 
+Options supported:
+- `+noall +answer` options are supported in cases where only the answer
+  information is desired.
+- `+axfr` option is supported on its own
+
+The `when_epoch` calculated timestamp field is naive. (i.e. based on the
+local time of the system the parser is run on)
+
+The `when_epoch_utc` calculated timestamp field is timezone-aware and is
+only available if the timezone field is UTC.
+
 Usage (cli):
 
     $ dig example.com | jc --dig
@@ -12,19 +24,99 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('dig', dig_command_output)
+
+    or
+
     import jc.parsers.dig
     result = jc.parsers.dig.parse(dig_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    [
+      {
+        "id":                   integer,
+        "opcode":               string,
+        "status":               string,
+        "flags": [
+                                string
+        ],
+        "query_num":            integer,
+        "answer_num":           integer,
+        "authority_num":        integer,
+        "additional_num":       integer,
+        "axfr": [
+          {
+            "name":             string,
+            "class":            string,
+            "type":             string,
+            "ttl":              integer,
+            "data":             string
+          }
+        ],
+        "opt_pseudosection": {
+          "edns": {
+            "version":          integer,
+            "flags": [
+                                string
+            ],
+            "udp":              integer
+          },
+          "cookie":             string
+        },
+        "question": {
+          "name":               string,
+          "class":              string,
+          "type":               string
+        },
+        "answer": [
+          {
+            "name":             string,
+            "class":            string,
+            "type":             string,
+            "ttl":              integer,
+            "data":             string
+          }
+        ],
+        "additional": [
+          {
+            "name":             string,
+            "class":            string,
+            "type":             string,
+            "ttl":              integer,
+            "data":             string
+          }
+        ],
+        "authority": [
+          {
+            "name":             string,
+            "class":            string,
+            "type":             string,
+            "ttl":              integer,
+            "data":             string
+          }
+        ],
+        "query_size":           integer,
+        "query_time":           integer,   # in msec
+        "server":               string,
+        "when":                 string,
+        "when_epoch":           integer,   # [0]
+        "when_epoch_utc":       integer,   # [1]
+        "rcvd":                 integer
+        "size":                 string
+      }
+    ]
+
+    [0] naive timestamp if "when" field is parsable, else null
+    [1] timezone aware timestamp availabe for UTC, else null
 
 Examples:
 
-    $ dig cnn.com www.cnn.com @205.251.194.64 | jc --dig -p
+    $ dig example.com | jc --dig -p
     [
       {
-        "id": 34128,
+        "id": 2951,
         "opcode": "QUERY",
         "status": "NOERROR",
         "flags": [
@@ -33,117 +125,43 @@ Examples:
           "ra"
         ],
         "query_num": 1,
-        "answer_num": 4,
+        "answer_num": 1,
         "authority_num": 0,
         "additional_num": 1,
+        "opt_pseudosection": {
+          "edns": {
+            "version": 0,
+            "flags": [],
+            "udp": 4096
+          }
+        },
         "question": {
-          "name": "cnn.com.",
+          "name": "example.com.",
           "class": "IN",
           "type": "A"
         },
         "answer": [
           {
-            "name": "cnn.com.",
+            "name": "example.com.",
             "class": "IN",
             "type": "A",
-            "ttl": 60,
-            "data": "151.101.65.67"
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "A",
-            "ttl": 60,
-            "data": "151.101.193.67"
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "A",
-            "ttl": 60,
-            "data": "151.101.1.67"
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "A",
-            "ttl": 60,
-            "data": "151.101.129.67"
+            "ttl": 39302,
+            "data": "93.184.216.34"
           }
         ],
-        "query_time": 37,
-        "server": "2600",
-        "when": "Tue Nov 12 07:14:42 PST 2019",
-        "rcvd": 100
-      },
-      {
-        "id": 15273,
-        "opcode": "QUERY",
-        "status": "NOERROR",
-        "flags": [
-          "qr",
-          "aa",
-          "rd"
-        ],
-        "query_num": 1,
-        "answer_num": 1,
-        "authority_num": 4,
-        "additional_num": 1,
-        "question": {
-          "name": "www.cnn.com.",
-          "class": "IN",
-          "type": "A"
-        },
-        "answer": [
-          {
-            "name": "www.cnn.com.",
-            "class": "IN",
-            "type": "CNAME",
-            "ttl": 300,
-            "data": "turner-tls.map.fastly.net."
-          }
-        ],
-        "authority": [
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "NS",
-            "ttl": 3600,
-            "data": "ns-1086.awsdns-07.org."
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "NS",
-            "ttl": 3600,
-            "data": "ns-1630.awsdns-11.co.uk."
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "NS",
-            "ttl": 3600,
-            "data": "ns-47.awsdns-05.com."
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "NS",
-            "ttl": 3600,
-            "data": "ns-576.awsdns-08.net."
-          }
-        ],
-        "query_time": 23,
-        "server": "205.251.194.64#53(205.251.194.64)",
-        "when": "Tue Nov 12 07:14:42 PST 2019",
-        "rcvd": 212
+        "query_time": 49,
+        "server": "2600:1700:bab0:d40::1#53(2600:1700:bab0:d40::1)",
+        "when": "Fri Apr 16 16:05:10 PDT 2021",
+        "rcvd": 56,
+        "when_epoch": 1618614310,
+        "when_epoch_utc": null
       }
     ]
 
     $ dig cnn.com www.cnn.com @205.251.194.64 | jc --dig -p -r
     [
       {
-        "id": "23843",
+        "id": "46052",
         "opcode": "QUERY",
         "status": "NOERROR",
         "flags": [
@@ -152,117 +170,41 @@ Examples:
           "ra"
         ],
         "query_num": "1",
-        "answer_num": "4",
+        "answer_num": "1",
         "authority_num": "0",
         "additional_num": "1",
+        "opt_pseudosection": {
+          "edns": {
+            "version": "0",
+            "flags": [],
+            "udp": "4096"
+          }
+        },
         "question": {
-          "name": "cnn.com.",
+          "name": "example.com.",
           "class": "IN",
           "type": "A"
         },
         "answer": [
           {
-            "name": "cnn.com.",
+            "name": "example.com.",
             "class": "IN",
             "type": "A",
-            "ttl": "30",
-            "data": "151.101.193.67"
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "A",
-            "ttl": "30",
-            "data": "151.101.1.67"
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "A",
-            "ttl": "30",
-            "data": "151.101.65.67"
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "A",
-            "ttl": "30",
-            "data": "151.101.129.67"
+            "ttl": "40426",
+            "data": "93.184.216.34"
           }
         ],
-        "query_time": "24 msec",
-        "server": "192.168.1.254#53(192.168.1.254)",
-        "when": "Tue Nov 12 07:16:19 PST 2019",
-        "rcvd": "100"
-      },
-      {
-        "id": "8266",
-        "opcode": "QUERY",
-        "status": "NOERROR",
-        "flags": [
-          "qr",
-          "aa",
-          "rd"
-        ],
-        "query_num": "1",
-        "answer_num": "1",
-        "authority_num": "4",
-        "additional_num": "1",
-        "question": {
-          "name": "www.cnn.com.",
-          "class": "IN",
-          "type": "A"
-        },
-        "answer": [
-          {
-            "name": "www.cnn.com.",
-            "class": "IN",
-            "type": "CNAME",
-            "ttl": "300",
-            "data": "turner-tls.map.fastly.net."
-          }
-        ],
-        "authority": [
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "NS",
-            "ttl": "3600",
-            "data": "ns-1086.awsdns-07.org."
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "NS",
-            "ttl": "3600",
-            "data": "ns-1630.awsdns-11.co.uk."
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "NS",
-            "ttl": "3600",
-            "data": "ns-47.awsdns-05.com."
-          },
-          {
-            "name": "cnn.com.",
-            "class": "IN",
-            "type": "NS",
-            "ttl": "3600",
-            "data": "ns-576.awsdns-08.net."
-          }
-        ],
-        "query_time": "26 msec",
-        "server": "205.251.194.64#53(205.251.194.64)",
-        "when": "Tue Nov 12 07:16:19 PST 2019",
-        "rcvd": "212"
+        "query_time": "48 msec",
+        "server": "2600:1700:bab0:d40::1#53(2600:1700:bab0:d40::1)",
+        "when": "Fri Apr 16 16:06:12 PDT 2021",
+        "rcvd": "56"
       }
     ]
 
     $ dig -x 1.1.1.1 | jc --dig -p
     [
       {
-        "id": 34898,
+        "id": 20785,
         "opcode": "QUERY",
         "status": "NOERROR",
         "flags": [
@@ -274,6 +216,13 @@ Examples:
         "answer_num": 1,
         "authority_num": 0,
         "additional_num": 1,
+        "opt_pseudosection": {
+          "edns": {
+            "version": 0,
+            "flags": [],
+            "udp": 4096
+          }
+        },
         "question": {
           "name": "1.1.1.1.in-addr.arpa.",
           "class": "IN",
@@ -284,21 +233,23 @@ Examples:
             "name": "1.1.1.1.in-addr.arpa.",
             "class": "IN",
             "type": "PTR",
-            "ttl": 952,
+            "ttl": 1800,
             "data": "one.one.one.one."
           }
         ],
-        "query_time": 103,
-        "server": "2600",
-        "when": "Tue Nov 12 07:15:33 PST 2019",
-        "rcvd": 78
+        "query_time": 40,
+        "server": "2600:1700:bab0:d40::1#53(2600:1700:bab0:d40::1)",
+        "when": "Sat Apr 17 14:50:50 PDT 2021",
+        "rcvd": 78,
+        "when_epoch": 1618696250,
+        "when_epoch_utc": null
       }
     ]
 
     $ dig -x 1.1.1.1 | jc --dig -p -r
     [
       {
-        "id": "50986",
+        "id": "32644",
         "opcode": "QUERY",
         "status": "NOERROR",
         "flags": [
@@ -310,6 +261,13 @@ Examples:
         "answer_num": "1",
         "authority_num": "0",
         "additional_num": "1",
+        "opt_pseudosection": {
+          "edns": {
+            "version": "0",
+            "flags": [],
+            "udp": "4096"
+          }
+        },
         "question": {
           "name": "1.1.1.1.in-addr.arpa.",
           "class": "IN",
@@ -324,87 +282,55 @@ Examples:
             "data": "one.one.one.one."
           }
         ],
-        "query_time": "38 msec",
-        "server": "2600",
-        "when": "Tue Nov 12 07:17:19 PST 2019",
+        "query_time": "52 msec",
+        "server": "2600:1700:bab0:d40::1#53(2600:1700:bab0:d40::1)",
+        "when": "Sat Apr 17 14:51:46 PDT 2021",
         "rcvd": "78"
       }
     ]
 
+    $ dig +noall +answer cnn.com | jc --dig -p
+    [
+      {
+        "answer": [
+          {
+            "name": "cnn.com.",
+            "class": "IN",
+            "type": "A",
+            "ttl": 60,
+            "data": "151.101.193.67"
+          },
+          {
+            "name": "cnn.com.",
+            "class": "IN",
+            "type": "A",
+            "ttl": 60,
+            "data": "151.101.65.67"
+          },
+          {
+            "name": "cnn.com.",
+            "class": "IN",
+            "type": "A",
+            "ttl": 60,
+            "data": "151.101.1.67"
+          },
+          {
+            "name": "cnn.com.",
+            "class": "IN",
+            "type": "A",
+            "ttl": 60,
+            "data": "151.101.129.67"
+          }
+        ]
+      }
+    ]
+
 
 ## info
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "id":             integer,
-        "opcode":         string,
-        "status":         string,
-        "flags": [
-                          string
-        ],
-        "query_num":      integer,
-        "answer_num":     integer,
-        "authority_num":  integer,
-        "additional_num": integer,
-        "axfr": [
-          {
-            "name":       string,
-            "class":      string,
-            "type":       string,
-            "ttl":        integer,
-            "data":       string
-          }
-        ],
-        "question": {
-          "name":         string,
-          "class":        string,
-          "type":         string
-        },
-        "answer": [
-          {
-            "name":       string,
-            "class":      string,
-            "type":       string,
-            "ttl":        integer,
-            "data":       string
-          }
-        ],
-        "authority": [
-          {
-            "name":       string,
-            "class":      string,
-            "type":       string,
-            "ttl":        integer,
-            "data":       string
-          }
-        ],
-        "query_time":     integer,   # in msec
-        "server":         string,
-        "when":           string,
-        "rcvd":           integer
-        "size":           string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -416,10 +342,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, aix, freebsd, darwin, win32, cygwin
+
+Version 2.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/dir.md

@@ -0,0 +1,153 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.dir
+jc - JSON CLI output utility `dir` command output parser
+
+Options supported:
+- `/T timefield`
+- `/O sortorder`
+- `/C, /-C`
+- `/S`
+
+The "Magic" syntax is not supported since the `dir` command is a shell
+builtin.
+
+The `epoch` calculated timestamp field is naive. (i.e. based on the local
+time of the system the parser is run on)
+
+Usage (cli):
+
+    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:
+
+    [
+      {
+        "date":         string,
+        "time":         string,
+        "epoch":        integer,    # naive timestamp
+        "dir":          boolean,
+        "size":         integer,
+        "filename:      string,
+        "parent":       string
+      }
+    ]
+
+Examples:
+
+    C:> dir | jc --dir -p
+    [
+      {
+        "date": "03/24/2021",
+        "time": "03:15 PM",
+        "dir": true,
+        "size": null,
+        "filename": ".",
+        "parent": "C:\Program Files\Internet Explorer",
+        "epoch": 1616624100
+      },
+      {
+        "date": "03/24/2021",
+        "time": "03:15 PM",
+        "dir": true,
+        "size": null,
+        "filename": "..",
+        "parent": "C:\Program Files\Internet Explorer",
+        "epoch": 1616624100
+      },
+      {
+        "date": "12/07/2019",
+        "time": "02:49 AM",
+        "dir": true,
+        "size": null,
+        "filename": "en-US",
+        "parent": "C:\Program Files\Internet Explorer",
+        "epoch": 1575715740
+      },
+      {
+        "date": "12/07/2019",
+        "time": "02:09 AM",
+        "dir": false,
+        "size": 54784,
+        "filename": "ExtExport.exe",
+        "parent": "C:\Program Files\Internet Explorer",
+        "epoch": 1575713340
+      },
+      ...
+    ]
+
+    C:> dir | jc --dir -p -r
+    [
+      {
+        "date": "03/24/2021",
+        "time": "03:15 PM",
+        "dir": true,
+        "size": null,
+        "filename": ".",
+        "parent": "C:\Program Files\Internet Explorer"
+      },
+      {
+        "date": "03/24/2021",
+        "time": "03:15 PM",
+        "dir": true,
+        "size": null,
+        "filename": "..",
+        "parent": "C:\Program Files\Internet Explorer"
+      },
+      {
+        "date": "12/07/2019",
+        "time": "02:49 AM",
+        "dir": true,
+        "size": null,
+        "filename": "en-US",
+        "parent": "C:\Program Files\Internet Explorer"
+      },
+      {
+        "date": "12/07/2019",
+        "time": "02:09 AM",
+        "dir": false,
+        "size": "54,784",
+        "filename": "ExtExport.exe",
+        "parent": "C:\Program Files\Internet Explorer"
+      },
+      ...
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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:  win32
+
+Version 1.4 by Rasheed Elsaleh (rasheed@rebelliondefense.com)

docs/parsers/dmidecode.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.dmidecode
 jc - JSON CLI output utility `dmidecode` command output parser
@@ -12,12 +13,30 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('dmidecode', dmidecode_command_output)
+
+    or
+
     import jc.parsers.dmidecode
     result = jc.parsers.dmidecode.parse(dmidecode_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "handle":                      string,
+        "type":                        integer,
+        "bytes":                       integer,
+        "description":                 string,
+        "values": {                                 # null if empty
+          "lowercase_no_spaces_keys":  string,
+          "multiline_key_values": [
+                                       string,
+          ]
+        }
+      }
+    ]
 
 Examples:
 
@@ -114,38 +133,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "handle":                      string,
-        "type":                        integer,
-        "bytes":                       integer,
-        "description":                 string,
-        "values": {                               (null if empty)
-          "lowercase_no_spaces_keys":  string,
-          "multiline_key_values": [
-                                       string,
-          ]
-        }
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -157,10 +145,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/dpkg_l.md

@@ -0,0 +1,164 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.dpkg_l
+jc - JSON CLI output utility `dpkg -l` command output parser
+
+Set the `COLUMNS` environment variable to a large value to avoid field
+truncation. For example:
+
+    $ COLUMNS=500 dpkg -l | jc --dpkg-l
+
+Usage (cli):
+
+    $ dpkg -l | jc --dpkg-l
+
+    or
+
+    $ jc dpkg -l
+
+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:
+
+    [
+      {
+        "codes":            string,
+        "name":             string,
+        "version":          string,
+        "architecture":     string,
+        "description":      string,
+        "desired":          string,
+        "status":           string,
+        "error":            string
+      }
+    ]
+
+Examples:
+
+    $ dpkg -l | jc --dpkg-l -p
+    [
+      {
+        "codes": "ii",
+        "name": "accountsservice",
+        "version": "0.6.45-1ubuntu1.3",
+        "architecture": "amd64",
+        "description": "query and manipulate user account information",
+        "desired": "install",
+        "status": "installed"
+      },
+      {
+        "codes": "rc",
+        "name": "acl",
+        "version": "2.2.52-3build1",
+        "architecture": "amd64",
+        "description": "Access control list utilities",
+        "desired": "remove",
+        "status": "config-files"
+      },
+      {
+        "codes": "uWR",
+        "name": "acpi",
+        "version": "1.7-1.1",
+        "architecture": "amd64",
+        "description": "displays information on ACPI devices",
+        "desired": "unknown",
+        "status": "trigger await",
+        "error": "reinstall required"
+      },
+      {
+        "codes": "rh",
+        "name": "acpid",
+        "version": "1:2.0.28-1ubuntu1",
+        "architecture": "amd64",
+        "description": "Advanced Configuration and Power Interface...",
+        "desired": "remove",
+        "status": "half installed"
+      },
+      {
+        "codes": "pn",
+        "name": "adduser",
+        "version": "3.116ubuntu1",
+        "architecture": "all",
+        "description": "add and remove users and groups",
+        "desired": "purge",
+        "status": "not installed"
+      },
+      ...
+    ]
+
+    $ dpkg -l | jc --dpkg-l -p -r
+    [
+      {
+        "codes": "ii",
+        "name": "accountsservice",
+        "version": "0.6.45-1ubuntu1.3",
+        "architecture": "amd64",
+        "description": "query and manipulate user account information"
+      },
+      {
+        "codes": "rc",
+        "name": "acl",
+        "version": "2.2.52-3build1",
+        "architecture": "amd64",
+        "description": "Access control list utilities"
+      },
+      {
+        "codes": "uWR",
+        "name": "acpi",
+        "version": "1.7-1.1",
+        "architecture": "amd64",
+        "description": "displays information on ACPI devices"
+      },
+      {
+        "codes": "rh",
+        "name": "acpid",
+        "version": "1:2.0.28-1ubuntu1",
+        "architecture": "amd64",
+        "description": "Advanced Configuration and Power Interface..."
+      },
+      {
+        "codes": "pn",
+        "name": "adduser",
+        "version": "3.116ubuntu1",
+        "architecture": "all",
+        "description": "add and remove users and groups"
+      },
+      ...
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/du.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.du
 jc - JSON CLI output utility `du` command output parser
@@ -12,12 +13,22 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('du', du_command_output)
+
+    or
+
     import jc.parsers.du
     result = jc.parsers.du.parse(du_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'aix', 'freebsd'
+    [
+      {
+        "size":     integer,
+        "name":     string
+      }
+    ]
 
 Examples:
 
@@ -29,23 +40,23 @@ Examples:
       },
       {
         "size": 56,
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/_CodeSignature"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       {
         "size": 0,
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr/local/standalone"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       {
         "size": 0,
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr/local"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       {
         "size": 0,
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       {
         "size": 1008,
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/dfu"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       ...
     ]
@@ -58,23 +69,23 @@ Examples:
       },
       {
         "size": "56",
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/_CodeSignature"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       {
         "size": "0",
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr/local/standalone"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       {
         "size": "0",
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr/local"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       {
         "size": "0",
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       {
         "size": "1008",
-        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/dfu"
+        "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..."
       },
       ...
     ]
@@ -84,30 +95,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "size":     integer,
-        "name":     string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -119,10 +107,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, aix, freebsd
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/env.md

@@ -1,8 +1,12 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.env
 jc - JSON CLI output utility `env` and `printenv` command output parser
 
-This parser will output a list of dictionaries each containing `name` and `value` keys. If you would like a simple dictionary output, then use the `-r` command-line option or the `raw=True` argument in the `parse()` function.
+This parser will output a list of dictionaries each containing `name` and
+`value` keys. If you would like a simple dictionary output, then use the
+`-r` command-line option or the `raw=True` argument in the `parse()`
+function.
 
 Usage (cli):
 
@@ -14,12 +18,22 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('env', env_command_output)
+
+    or
+
     import jc.parsers.env
     result = jc.parsers.env.parse(env_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    [
+      {
+        "name":     string,
+        "value":    string
+      }
+    ]
 
 Examples:
 
@@ -66,30 +80,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "name":     string,
-        "value":    string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -101,11 +92,15 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary of raw structured data or
-    list of dictionaries of processed structured data
+    List of Dictionaries of processed structured data
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/file.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.file
 jc - JSON CLI output utility `file` command output parser
@@ -12,12 +13,22 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('file', file_command_output)
+
+    or
+
     import jc.parsers.file
     result = jc.parsers.file.parse(file_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'aix', 'freebsd', 'darwin'
+    [
+      {
+        "filename":   string,
+        "type":       string
+      }
+    ]
 
 Examples:
 
@@ -45,11 +56,11 @@ Examples:
       },
       {
         "filename": "cd_catalog.xml",
-        "type": "XML 1.0 document text, ASCII text, with CRLF line terminators"
+        "type": "XML 1.0 document text, ASCII text, with CRLF line ..."
       },
       {
         "filename": "centosserial.sh",
-        "type": "Bourne-Again shell script text executable, UTF-8 Unicode text"
+        "type": "Bourne-Again shell script text executable, UTF-8 ..."
       },
       ...
     ]
@@ -59,30 +70,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "filename":   string,
-        "type   ":    string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -94,10 +82,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, aix, freebsd, darwin
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/finger.md

@@ -0,0 +1,123 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.finger
+jc - JSON CLI output utility `finger` command output parser
+
+Supports `-s` output option. Does not support the `-l` detail option.
+
+Usage (cli):
+
+    $ finger | jc --finger
+
+    or
+
+    $ jc finger
+
+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:
+
+    [
+      {
+        "login":                string,
+        "name":                 string,
+        "tty":                  string,
+        "idle":                 string,     # null if empty
+        "login_time":           string,
+        "details":              string,
+        "tty_writeable":        boolean,
+        "idle_minutes":         integer,
+        "idle_hours":           integer,
+        "idle_days":            integer,
+        "total_idle_minutes":   integer
+      }
+    ]
+
+Examples:
+
+    $ finger | jc --finger -p
+    [
+      {
+        "login": "jdoe",
+        "name": "John Doe",
+        "tty": "tty1",
+        "idle": "14d",
+        "login_time": "Mar 22 21:14",
+        "tty_writeable": false,
+        "idle_minutes": 0,
+        "idle_hours": 0,
+        "idle_days": 14,
+        "total_idle_minutes": 20160
+      },
+      {
+        "login": "jdoe",
+        "name": "John Doe",
+        "tty": "pts/0",
+        "idle": null,
+        "login_time": "Apr  5 15:33",
+        "details": "(192.168.1.22)",
+        "tty_writeable": true,
+        "idle_minutes": 0,
+        "idle_hours": 0,
+        "idle_days": 0,
+        "total_idle_minutes": 0
+      },
+      ...
+    ]
+
+    $ finger | jc --finger -p -r
+    [
+      {
+        "login": "jdoe",
+        "name": "John Doe",
+        "tty": "*tty1",
+        "idle": "14d",
+        "login_time": "Mar 22 21:14"
+      },
+      {
+        "login": "jdoe",
+        "name": "John Doe",
+        "tty": "pts/0",
+        "idle": null,
+        "login_time": "Apr  5 15:33",
+        "details": "(192.168.1.22)"
+      },
+      ...
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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, freebsd
+
+Version 1.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/free.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.free
 jc - JSON CLI output utility `free` command output parser
@@ -12,12 +13,27 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('free', free_command_output)
+
+    or
+
     import jc.parsers.free
     result = jc.parsers.free.parse(free_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "type":         string,
+        "total":        integer,
+        "used":         integer,
+        "free":         integer,
+        "shared":       integer,
+        "buff_cache":   integer,
+        "available":    integer
+      }
+    ]
 
 Examples:
 
@@ -64,35 +80,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "type":         string,
-        "total":        integer,
-        "used":         integer,
-        "free":         integer,
-        "shared":       integer,
-        "buff_cache":   integer,
-        "available":    integer
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -104,10 +92,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/fstab.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.fstab
 jc - JSON CLI output utility `fstab` file parser
@@ -8,12 +9,26 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('fstab', fstab_command_output)
+
+    or
+
     import jc.parsers.fstab
     result = jc.parsers.fstab.parse(fstab_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'freebsd'
+    [
+      {
+        "fs_spec":      string,
+        "fs_file":      string,
+        "fs_vfstype":   string,
+        "fs_mntops":    string,
+        "fs_freq":      integer,
+        "fs_passno":    integer
+      }
+    ]
 
 Examples:
 
@@ -78,34 +93,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "fs_spec":      string,
-        "fs_file":      string,
-        "fs_vfstype":   string,
-        "fs_mntops":    string,
-        "fs_freq":      integer,
-        "fs_passno":    integer
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -117,10 +105,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, freebsd
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/group.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.group
 jc - JSON CLI output utility `/etc/group` file parser
@@ -8,12 +9,26 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('group', group_file_output)
+
+    or
+
     import jc.parsers.group
     result = jc.parsers.group.parse(group_file_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'aix', 'freebsd'
+    [
+      {
+        "group_name":    string,
+        "password":      string,
+        "gid":           integer,
+        "members": [
+                         string
+        ]
+      }
+    ]
 
 Examples:
 
@@ -102,34 +117,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "group_name":    string,
-        "password":      string,
-        "gid":           integer,
-        "members": [
-                         string
-        ]
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -141,10 +129,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, aix, freebsd
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/gshadow.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.gshadow
 jc - JSON CLI output utility `/etc/gshadow` file parser
@@ -8,12 +9,28 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('gshadow', gshadow_file_output)
+
+    or
+
     import jc.parsers.gshadow
     result = jc.parsers.gshadow.parse(gshadow_file_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'aix', 'freebsd'
+    [
+      {
+        "group_name":       string,
+        "password":         string,
+        "administrators": [
+                            string
+        ],
+        "members": [
+                            string
+        ]
+      }
+    ]
 
 Examples:
 
@@ -68,36 +85,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "group_name":       string,
-        "password":         string,
-        "administrators": [
-                            string
-        ],
-        "members": [
-                            string
-        ]
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -109,10 +97,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, aix, freebsd
+
+Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/hash.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.hash
 jc - JSON CLI output utility `hash` command output parser
@@ -8,12 +9,22 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('hash', hash_command_output)
+
+    or
+
     import jc.parsers.hash
     result = jc.parsers.hash.parse(hash_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    [
+      {
+        "command":       string,
+        "hits":          integer
+      }
+    ]
 
 Examples:
 
@@ -34,30 +45,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "command":       string,
-        "hits":          integer
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -69,10 +57,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/hashsum.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.hashsum
 jc - JSON CLI output utility `hash sum` command output parser
@@ -22,12 +23,22 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('hashsum', md5sum_command_output)
+
+    or
+
     import jc.parsers.hashsum
     result = jc.parsers.hashsum.parse(md5sum_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    [
+      {
+        "filename":     string,
+        "hash":         string,
+      }
+    ]
 
 Examples:
 
@@ -65,30 +76,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "filename":     string,
-        "hash":         string,
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -100,10 +88,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/hciconfig.md

@@ -0,0 +1,350 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.hciconfig
+jc - JSON CLI output utility `hciconfig` command output parser
+
+Usage (cli):
+
+    $ hciconfig | jc --hciconfig
+
+    or
+
+    $ jc hciconfig
+
+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:
+
+    [
+      {
+        "device":               string,
+        "type":                 string,
+        "bus":                  string,
+        "bd_address":           string,
+        "acl_mtu":              integer,
+        "acl_mtu_packets":      integer,
+        "sco_mtu":              integer,
+        "sco_mtu_packets":      integer,
+        "state": [
+                                string
+        ],
+        "rx_bytes":             integer,
+        "rx_acl":               integer,
+        "rx_sco":               integer,
+        "rx_events":            integer,
+        "rx_errors":            integer,
+        "tx_bytes":             integer,
+        "tx_acl":               integer,
+        "tx_sco":               integer,
+        "tx_commands":          integer,
+        "tx_errors":            integer,
+        "features": [
+                                string
+        ],
+        "packet_type": [
+                                string
+        ],
+        "link_policy": [
+                                string
+        ],
+        "link_mode": [
+                                string
+        ],
+        "name":                 string,
+        "class":                string,
+        "service_classes": [
+                                string       # 'Unspecified' is null
+        ],
+        "device_class":         string,
+        "hci_version":          string,
+        "hci_revision":         string,
+        "lmp_version":          string,
+        "lmp_subversion":       string,
+        "manufacturer":         string
+      }
+    ]
+
+Examples:
+
+    $ hciconfig -a | jc --hciconfig -p
+    [
+      {
+        "device": "hci0",
+        "type": "Primary",
+        "bus": "USB",
+        "bd_address": "00:1A:7D:DA:71:13",
+        "acl_mtu": 310,
+        "acl_mtu_packets": 10,
+        "sco_mtu": 64,
+        "sco_mtu_packets": 8,
+        "state": [
+          "UP",
+          "RUNNING"
+        ],
+        "rx_bytes": 13905869,
+        "rx_acl": 0,
+        "rx_sco": 0,
+        "rx_events": 393300,
+        "rx_errors": 0,
+        "tx_bytes": 62629,
+        "tx_acl": 0,
+        "tx_sco": 0,
+        "tx_commands": 3893,
+        "tx_errors": 0,
+        "features": [
+          "0xff",
+          "0xff",
+          "0x8f",
+          "0xfe",
+          "0xdb",
+          "0xff",
+          "0x5b",
+          "0x87"
+        ],
+        "packet_type": [
+          "DM1",
+          "DM3",
+          "DM5",
+          "DH1",
+          "DH3",
+          "DH5",
+          "HV1",
+          "HV2",
+          "HV3"
+        ],
+        "link_policy": [
+          "RSWITCH",
+          "HOLD",
+          "SNIFF",
+          "PARK"
+        ],
+        "link_mode": [
+          "SLAVE",
+          "ACCEPT"
+        ],
+        "name": "CSR8510 A10",
+        "class": "0x000000",
+        "service_classes": null,
+        "device_class": "Miscellaneous",
+        "hci_version": "4.0 (0x6)",
+        "hci_revision": "0x22bb",
+        "lmp_version": "4.0 (0x6)",
+        "lmp_subversion": "0x22bb",
+        "manufacturer": "Cambridge Silicon Radio (10)"
+      },
+      {
+        "device": "hci1",
+        "type": "Primary",
+        "bus": "USB",
+        "bd_address": "00:1A:7D:DA:71:13",
+        "acl_mtu": 310,
+        "acl_mtu_packets": 10,
+        "sco_mtu": 64,
+        "sco_mtu_packets": 8,
+        "state": [
+          "DOWN"
+        ],
+        "rx_bytes": 4388363,
+        "rx_acl": 0,
+        "rx_sco": 0,
+        "rx_events": 122021,
+        "rx_errors": 0,
+        "tx_bytes": 52350,
+        "tx_acl": 0,
+        "tx_sco": 0,
+        "tx_commands": 3480,
+        "tx_errors": 2,
+        "features": [
+          "0xff",
+          "0xff",
+          "0x8f",
+          "0xfe",
+          "0xdb",
+          "0xff",
+          "0x5b",
+          "0x87"
+        ],
+        "packet_type": [
+          "DM1",
+          "DM3",
+          "DM5",
+          "DH1",
+          "DH3",
+          "DH5",
+          "HV1",
+          "HV2",
+          "HV3"
+        ],
+        "link_policy": [
+          "RSWITCH",
+          "HOLD",
+          "SNIFF",
+          "PARK"
+        ],
+        "link_mode": [
+          "SLAVE",
+          "ACCEPT"
+        ]
+      }
+    ]
+
+    $ hciconfig -a | jc --hciconfig -p -r
+    [
+      {
+        "device": "hci0",
+        "type": "Primary",
+        "bus": "USB",
+        "bd_address": "00:1A:7D:DA:71:13",
+        "acl_mtu": "310",
+        "acl_mtu_packets": "10",
+        "sco_mtu": "64",
+        "sco_mtu_packets": "8",
+        "state": [
+          "UP",
+          "RUNNING"
+        ],
+        "rx_bytes": "13905869",
+        "rx_acl": "0",
+        "rx_sco": "0",
+        "rx_events": "393300",
+        "rx_errors": "0",
+        "tx_bytes": "62629",
+        "tx_acl": "0",
+        "tx_sco": "0",
+        "tx_commands": "3893",
+        "tx_errors": "0",
+        "features": [
+          "0xff",
+          "0xff",
+          "0x8f",
+          "0xfe",
+          "0xdb",
+          "0xff",
+          "0x5b",
+          "0x87"
+        ],
+        "packet_type": [
+          "DM1",
+          "DM3",
+          "DM5",
+          "DH1",
+          "DH3",
+          "DH5",
+          "HV1",
+          "HV2",
+          "HV3"
+        ],
+        "link_policy": [
+          "RSWITCH",
+          "HOLD",
+          "SNIFF",
+          "PARK"
+        ],
+        "link_mode": [
+          "SLAVE",
+          "ACCEPT"
+        ],
+        "name": "CSR8510 A10",
+        "class": "0x000000",
+        "service_classes": [
+          "Unspecified"
+        ],
+        "device_class": "Miscellaneous",
+        "hci_version": "4.0 (0x6)",
+        "hci_revision": "0x22bb",
+        "lmp_version": "4.0 (0x6)",
+        "lmp_subversion": "0x22bb",
+        "manufacturer": "Cambridge Silicon Radio (10)"
+      },
+      {
+        "device": "hci1",
+        "type": "Primary",
+        "bus": "USB",
+        "bd_address": "00:1A:7D:DA:71:13",
+        "acl_mtu": "310",
+        "acl_mtu_packets": "10",
+        "sco_mtu": "64",
+        "sco_mtu_packets": "8",
+        "state": [
+          "DOWN"
+        ],
+        "rx_bytes": "4388363",
+        "rx_acl": "0",
+        "rx_sco": "0",
+        "rx_events": "122021",
+        "rx_errors": "0",
+        "tx_bytes": "52350",
+        "tx_acl": "0",
+        "tx_sco": "0",
+        "tx_commands": "3480",
+        "tx_errors": "2",
+        "features": [
+          "0xff",
+          "0xff",
+          "0x8f",
+          "0xfe",
+          "0xdb",
+          "0xff",
+          "0x5b",
+          "0x87"
+        ],
+        "packet_type": [
+          "DM1",
+          "DM3",
+          "DM5",
+          "DH1",
+          "DH3",
+          "DH5",
+          "HV1",
+          "HV2",
+          "HV3"
+        ],
+        "link_policy": [
+          "RSWITCH",
+          "HOLD",
+          "SNIFF",
+          "PARK"
+        ],
+        "link_mode": [
+          "SLAVE",
+          "ACCEPT"
+        ]
+      }
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/history.md

@@ -1,8 +1,15 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.history
 jc - JSON CLI output utility `history` command output parser
 
-This parser will output a list of dictionaries each containing `line` and `command` keys. If you would like a simple dictionary output, then use the `-r` command-line option or the `raw=True` argument in the `parse()` function.
+This parser will output a list of dictionaries each containing `line` and
+`command` keys. If you would like a simple dictionary output, then use the
+`-r` command-line option or the `raw=True` argument in the `parse()`
+function.
+
+The "Magic" syntax is not supported since the `history` command is a shell
+builtin.
 
 Usage (cli):
 
@@ -10,12 +17,22 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('history', history_command_output)
+
+    or
+
     import jc.parsers.history
     result = jc.parsers.history.parse(history_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    [
+      {
+        "line":     integer,
+        "command":  string
+      }
+    ]
 
 Examples:
 
@@ -54,30 +71,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "line":     integer,
-        "command":  string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -89,11 +83,15 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary of raw structured data or
-    list of dictionaries of processed structured data
+    List of Dictionaries of processed structured data
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/hosts.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.hosts
 jc - JSON CLI output utility `/etc/hosts` file parser
@@ -8,12 +9,24 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('hosts', hosts_file_output)
+
+    or
+
     import jc.parsers.hosts
     result = jc.parsers.hosts.parse(hosts_file_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    [
+      {
+        "ip":           string,
+        "hostname": [
+                        string
+        ]
+      }
+    ]
 
 Examples:
 
@@ -69,32 +82,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "ip":           string,
-        "hostname": [
-                        string
-        ]
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -106,10 +94,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/id.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.id
 jc - JSON CLI output utility `id` command output parser
@@ -12,12 +13,42 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('id', id_command_output)
+
+    or
+
     import jc.parsers.id
     result = jc.parsers.id.parse(id_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'aix', 'freebsd'
+    {
+      "uid": {
+        "id":       integer,
+        "name":     string
+      },
+      "gid": {
+        "id":       integer,
+        "name":     string
+      },
+      "groups": [
+        {
+          "id":     integer,
+          "name":   string
+        },
+        {
+          "id":     integer,
+          "name":   string
+        }
+      ],
+      "context": {
+        "user":     string,
+        "role":     string,
+        "type":     string,
+        "level":    string
+      }
+    }
 
 Examples:
 
@@ -82,50 +113,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "uid": {
-        "id":       integer,
-        "name":     string
-      },
-      "gid": {
-        "id":       integer,
-        "name":     string
-      },
-      "groups": [
-        {
-          "id":     integer,
-          "name":   string
-        },
-        {
-          "id":     integer,
-          "name":   string
-        }
-      ],
-      "context": {
-        "user":     string,
-        "role":     string,
-        "type":     string,
-        "level":    string
-      }
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -137,10 +125,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, aix, freebsd
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ifconfig.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.ifconfig
 jc - JSON CLI output utility `ifconfig` command output parser
@@ -14,12 +15,48 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('ifconfig', ifconfig_command_output)
+
+    or
+
     import jc.parsers.ifconfig
     result = jc.parsers.ifconfig.parse(ifconfig_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'aix', 'freebsd', 'darwin'
+    [
+      {
+        "name":             string,
+        "flags":            integer,
+        "state": [
+                            string
+        ],
+        "mtu":              integer,
+        "ipv4_addr":        string,
+        "ipv4_mask":        string,
+        "ipv4_bcast":       string,
+        "ipv6_addr":        string,
+        "ipv6_mask":        integer,
+        "ipv6_scope":       string,
+        "mac_addr":         string,
+        "type":             string,
+        "rx_packets":       integer,
+        "rx_bytes":         integer,
+        "rx_errors":        integer,
+        "rx_dropped":       integer,
+        "rx_overruns":      integer,
+        "rx_frame":         integer,
+        "tx_packets":       integer,
+        "tx_bytes":         integer,
+        "tx_errors":        integer,
+        "tx_dropped":       integer,
+        "tx_overruns":      integer,
+        "tx_carrier":       integer,
+        "tx_collisions":    integer,
+        "metric":           integer
+      }
+    ]
 
 Examples:
 
@@ -157,62 +194,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## IfconfigParser
-```python
-IfconfigParser(console_output)
-```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "name":             string,
-        "flags":            integer,
-        "state": [
-                            string
-        ],
-        "mtu":              integer,
-        "ipv4_addr":        string,
-        "ipv4_mask":        string,
-        "ipv4_bcast":       string,
-        "ipv6_addr":        string,
-        "ipv6_mask":        integer,
-        "ipv6_scope":       string,
-        "mac_addr":         string,
-        "type":             string,
-        "rx_packets":       integer,
-        "rx_bytes":         integer,
-        "rx_errors":        integer,
-        "rx_dropped":       integer,
-        "rx_overruns":      integer,
-        "rx_frame":         integer,
-        "tx_packets":       integer,
-        "tx_bytes":         integer,
-        "tx_errors":        integer,
-        "tx_dropped":       integer,
-        "tx_overruns":      integer,
-        "tx_carrier":       integer,
-        "tx_collisions":    integer,
-        "metric":           integer
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -224,10 +206,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, aix, freebsd, darwin
+
+Version 1.11 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ini.md

@@ -1,10 +1,15 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.ini
 jc - JSON CLI output utility `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.
+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()`.
+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):
 
@@ -12,12 +17,23 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('ini', ini_file_output)
+
+    or
+
     import jc.parsers.ini
     result = jc.parsers.ini.parse(ini_file_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    ini or key/value document converted to a dictionary - see the
+    configparser standard library documentation for more details.
+
+    {
+      "key1":       string,
+      "key2":       string
+    }
 
 Examples:
 
@@ -58,31 +74,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary representing an ini or simple key/value pair document:
-
-    {
-      ini or key/value document converted to a dictionary - see configparser standard
-      library documentation for more details.
-
-      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 or raw=True argument.
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -94,10 +86,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary representing the ini file
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/iostat.md

@@ -0,0 +1,192 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.iostat
+jc - JSON CLI output utility `iostat` command output parser
+
+Note: `iostat` version 11 and higher include a JSON output option
+
+Usage (cli):
+
+    $ iostat | jc --iostat
+
+    or
+
+    $ jc iostat
+
+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:
+
+    [
+      {
+        "type":             string,
+        "percent_user":     float,
+        "percent_nice":     float,
+        "percent_system":   float,
+        "percent_iowait":   float,
+        "percent_steal":    float,
+        "percent_idle":     float,
+        "device":           string,
+        "tps":              float,
+        "kb_read_s":        float,
+        "mb_read_s":        float,
+        "kb_wrtn_s":        float,
+        "mb_wrtn_s":        float,
+        "kb_read":          integer,
+        "mb_read":          integer,
+        "kb_wrtn":          integer,
+        "mb_wrtn":          integer,
+        'kb_dscd':          integer,
+        'mb_dscd':          integer,
+        "rrqm_s":           float,
+        "wrqm_s":           float,
+        "r_s":              float,
+        "w_s":              float,
+        "rmb_s":            float,
+        "rkb_s":            float,
+        "wmb_s":            float,
+        "wkb_s":            float,
+        "avgrq_sz":         float,
+        "avgqu_sz":         float,
+        "await":            float,
+        "r_await":          float,
+        "w_await":          float,
+        "svctm":            float,
+        "aqu_sz":           float,
+        "rareq_sz":         float,
+        "wareq_sz":         float,
+        "d_s":              float,
+        "dkb_s":            float,
+        "dmb_s":            float,
+        "drqm_s":           float,
+        "percent_drqm":     float,
+        "d_await":          float,
+        "dareq_sz":         float,
+        "f_s":              float,
+        "f_await":          float,
+        "kb_dscd_s":        float,
+        "mb_dscd_s":        float,
+        "percent_util":     float,
+        "percent_rrqm":     float,
+        "percent_wrqm":     float
+      }
+    ]
+
+Examples:
+
+    $ iostat | jc --iostat -p
+    [
+      {
+          "percent_user": 0.15,
+          "percent_nice": 0.0,
+          "percent_system": 0.18,
+          "percent_iowait": 0.0,
+          "percent_steal": 0.0,
+          "percent_idle": 99.67,
+          "type": "cpu"
+      },
+      {
+          "device": "sda",
+          "tps": 0.29,
+          "kb_read_s": 7.22,
+          "kb_wrtn_s": 1.25,
+          "kb_read": 194341,
+          "kb_wrtn": 33590,
+          "type": "device"
+      },
+      {
+          "device": "dm-0",
+          "tps": 0.29,
+          "kb_read_s": 5.99,
+          "kb_wrtn_s": 1.17,
+          "kb_read": 161361,
+          "kb_wrtn": 31522,
+          "type": "device"
+      },
+      {
+          "device": "dm-1",
+          "tps": 0.0,
+          "kb_read_s": 0.08,
+          "kb_wrtn_s": 0.0,
+          "kb_read": 2204,
+          "kb_wrtn": 0,
+          "type": "device"
+      }
+    ]
+
+    $ iostat | jc --iostat -p -r
+    [
+      {
+        "percent_user": "0.15",
+        "percent_nice": "0.00",
+        "percent_system": "0.18",
+        "percent_iowait": "0.00",
+        "percent_steal": "0.00",
+        "percent_idle": "99.67",
+        "type": "cpu"
+      },
+      {
+        "device": "sda",
+        "tps": "0.29",
+        "kb_read_s": "7.22",
+        "kb_wrtn_s": "1.25",
+        "kb_read": "194341",
+        "kb_wrtn": "33590",
+        "type": "device"
+      },
+      {
+        "device": "dm-0",
+        "tps": "0.29",
+        "kb_read_s": "5.99",
+        "kb_wrtn_s": "1.17",
+        "kb_read": "161361",
+        "kb_wrtn": "31522",
+        "type": "device"
+      },
+      {
+        "device": "dm-1",
+        "tps": "0.00",
+        "kb_read_s": "0.08",
+        "kb_wrtn_s": "0.00",
+        "kb_read": "2204",
+        "kb_wrtn": "0",
+        "type": "device"
+      }
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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/iostat_s.md

@@ -0,0 +1,140 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.iostat_s
+jc - JSON CLI output utility `iostat` command output streaming parser
+
+> This streaming parser outputs JSON Lines
+
+Note: `iostat` version 11 and higher include a JSON output option
+
+Usage (cli):
+
+    $ iostat | jc --iostat-s
+
+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:
+
+    {
+      "type":             string,
+      "percent_user":     float,
+      "percent_nice":     float,
+      "percent_system":   float,
+      "percent_iowait":   float,
+      "percent_steal":    float,
+      "percent_idle":     float,
+      "device":           string,
+      "tps":              float,
+      "kb_read_s":        float,
+      "mb_read_s":        float,
+      "kb_wrtn_s":        float,
+      "mb_wrtn_s":        float,
+      "kb_read":          integer,
+      "mb_read":          integer,
+      "kb_wrtn":          integer,
+      "mb_wrtn":          integer,
+      'kb_dscd':          integer,
+      'mb_dscd':          integer,
+      "rrqm_s":           float,
+      "wrqm_s":           float,
+      "r_s":              float,
+      "w_s":              float,
+      "rmb_s":            float,
+      "rkb_s":            float,
+      "wmb_s":            float,
+      "wkb_s":            float,
+      "avgrq_sz":         float,
+      "avgqu_sz":         float,
+      "await":            float,
+      "r_await":          float,
+      "w_await":          float,
+      "svctm":            float,
+      "aqu_sz":           float,
+      "rareq_sz":         float,
+      "wareq_sz":         float,
+      "d_s":              float,
+      "dkb_s":            float,
+      "dmb_s":            float,
+      "drqm_s":           float,
+      "percent_drqm":     float,
+      "d_await":          float,
+      "dareq_sz":         float,
+      "f_s":              float,
+      "f_await":          float,
+      "kb_dscd_s":        float,
+      "mb_dscd_s":        float,
+      "percent_util":     float,
+      "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
+        }
+    }
+
+Examples:
+
+    $ iostat | jc --iostat-s
+    {"percent_user":0.14,"percent_nice":0.0,"percent_system":0.16,...}
+    {"device":"sda","tps":0.24,"kb_read_s":5.28,"kb_wrtn_s":1.1...}
+    ...
+
+    $ iostat | jc --iostat-s -r
+    {"percent_user":"0.14","percent_nice":"0.00","percent_system":"0.16"...}
+    {"device":"sda","tps":"0.24","kb_read_s":"5.28","kb_wrtn_s":"1.10"...}
+    ...
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False, ignore_exceptions=False)
+```
+
+Main text parsing generator function. Returns an iterator object.
+
+Parameters:
+
+    data:              (iterable)  line-based text data to parse
+                                   (e.g. sys.stdin or str.splitlines())
+
+    raw:               (boolean)   unprocessed output if True
+    quiet:             (boolean)   suppress warning messages if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+
+Yields:
+
+    Dictionary. Raw or processed structured data.
+
+Returns:
+
+    Iterator object
+
+## Parser Information
+Compatibility:  linux
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/iptables.md

@@ -1,6 +1,7 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.iptables
-jc - JSON CLI output utility `ipables` command output parser
+jc - JSON CLI output utility `iptables` command output parser
 
 Supports `-vLn` and `--line-numbers` for all tables.
 
@@ -14,12 +15,36 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('iptables', iptables_command_output)
+
+    or
+
     import jc.parsers.iptables
     result = jc.parsers.iptables.parse(iptables_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "chain":                string,
+        "rules": [
+          {
+            "num"               integer,
+            "pkts":             integer,
+            "bytes":            integer,  # converted based on suffix
+            "target":           string,
+            "prot":             string,
+            "opt":              string,   # "--" = Null
+            "in":               string,
+            "out":              string,
+            "source":           string,
+            "destination":      string,
+            "options":          string
+          }
+        ]
+      }
+    ]
 
 Examples:
 
@@ -146,44 +171,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "chain":                string,
-        "rules": [
-          {
-            "num"               integer,
-            "pkts":             integer,
-            "bytes":            integer,  # converted based on suffix
-            "target":           string,
-            "prot":             string,
-            "opt":              string,   # "--" = Null
-            "in":               string,
-            "out":              string,
-            "source":           string,
-            "destination":      string,
-            "options":          string
-          }
-        ]
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -195,10 +183,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.7 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/iw_scan.md

@@ -0,0 +1,154 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.iw_scan
+jc - JSON CLI output utility `iw dev <device> scan` command output parser
+
+This parser is considered beta quality. Not all fields are parsed and there
+are not enough samples to test.
+
+Usage (cli):
+
+    $ iw dev wlan0 scan | jc --iw-scan
+
+    or
+
+    $ jc iw dev wlan0 scan
+
+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:
+
+    [
+      {
+        "foo":     string/integer/float,      # best guess based on value
+        "bar":     string/integer/float,
+        "baz":     string/integer/float
+      }
+    ]
+
+Examples:
+
+    $ iw dev wlan0 scan | jc --iw-scan -p
+    [
+      {
+        "bssid": "71:31:72:65:e1:a2",
+        "interface": "wlan0",
+        "freq": 2462,
+        "capability": "ESS Privacy ShortSlotTime (0x0411)",
+        "ssid": "WLAN-1234",
+        "supported_rates": [
+          1.0,
+          2.0,
+          5.5,
+          11.0,
+          18.0,
+          24.0,
+          36.0,
+          54.0
+        ],
+        "erp": "<no flags>",
+        "erp_d4.0": "<no flags>",
+        "rsn": "Version: 1",
+        "group_cipher": "CCMP",
+        "pairwise_ciphers": "CCMP",
+        "authentication_suites": "PSK",
+        "capabilities": "0x186c",
+        "extended_supported_rates": [
+          6.0,
+          9.0,
+          12.0,
+          48.0
+        ],
+        "ht_rx_mcs_rate_indexes_supported": "0-15",
+        "primary_channel": 11,
+        "secondary_channel_offset": "no secondary",
+        "rifs": 1,
+        "ht_protection": "no",
+        "non-gf_present": 1,
+        "obss_non-gf_present": 0,
+        "dual_beacon": 0,
+        "dual_cts_protection": 0,
+        "stbc_beacon": 0,
+        "l-sig_txop_prot": 0,
+        "pco_active": 0,
+        "pco_phase": 0,
+        "bss_width_channel_transition_delay_factor": 5,
+        "extended_capabilities": "HT Information Exchange Supported",
+        "wmm": "Parameter version 1",
+        "be": "CW 15-1023, AIFSN 3",
+        "bk": "CW 15-1023, AIFSN 7",
+        "vi": "CW 7-15, AIFSN 2, TXOP 3008 usec",
+        "vo": "CW 3-7, AIFSN 2, TXOP 1504 usec",
+        "wps": "Version: 1.0",
+        "wi-fi_protected_setup_state": "2 (Configured)",
+        "selected_registrar": "0x0",
+        "response_type": "3 (AP)",
+        "uuid": "00000000-0000-0003-0000-75317074f1a2",
+        "manufacturer": "Corporation",
+        "model": "VGV8539JW",
+        "model_number": "1.47.000",
+        "serial_number": "J144024542",
+        "primary_device_type": "6-0050f204-1",
+        "device_name": "Wireless Router(WFA)",
+        "config_methods": "Label, PBC",
+        "rf_bands": "0x3",
+        "tsf_usec": 212098649788,
+        "sta_channel_width_mhz": 20,
+        "passive_dwell_tus": 20,
+        "active_dwell_tus": 10,
+        "channel_width_trigger_scan_interval_s": 300,
+        "scan_passive_total_per_channel_tus": 200,
+        "scan_active_total_per_channel_tus": 20,
+        "beacon_interval_tus": 100,
+        "signal_dbm": -80.0,
+        "last_seen_ms": 11420,
+        "selected_rates": [
+          1.0,
+          2.0,
+          5.5,
+          11.0
+        ],
+        "obss_scan_activity_threshold_percent": 0.25,
+        "ds_parameter_set_channel": 11,
+        "max_amsdu_length_bytes": 7935,
+        "minimum_rx_ampdu_time_spacing_usec": 16
+      },
+      ...
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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 0.7 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/jar_manifest.md

@@ -0,0 +1,110 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.jar_manifest
+jc - JSON CLI output utility `MANIFEST.MF` file parser
+
+Usage (cli):
+
+    $ cat MANIFEST.MF | jc --jar-manifest
+
+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:
+
+    [
+      {
+        "key1":     string,
+        "key2":     string
+      }
+    ]
+
+Examples:
+
+    $ cat MANIFEST.MF | jc --jar-manifest -p
+    $ unzip -c log4j-core-2.16.0.jar META-INF/MANIFEST.MF | \
+      jc --jar-manifest -p
+    $ unzip -c 'apache-log4j-2.16.0-bin/*.jar' META-INF/MANIFEST.MF | \
+      jc --jar-manifest -p
+
+    $ cat MANIFEST.MF | jc --jar-manifest -p
+    [
+      {
+        "Import_Package": "com.conversantmedia.util.concurrent;resoluti...",
+        "Export_Package": "org.apache.logging.log4j.core;uses:="org.ap...",
+        "Manifest_Version": "1.0",
+        "Bundle_License": "https://www.apache.org/licenses/LICENSE-2.0.txt",
+        "Bundle_SymbolicName": "org.apache.logging.log4j.core",
+        "Built_By": "matt",
+        "Bnd_LastModified": "1639373735804",
+        "Implementation_Vendor_Id": "org.apache.logging.log4j",
+        "Specification_Title": "Apache Log4j Core",
+        "Log4jReleaseManager": "Matt Sicker",
+        ...
+      }
+    ]
+
+    $ unzip -c 'apache-log4j-2.16.0-bin/*.jar' META-INF/MANIFEST.MF | \
+      jc --jar-manifest -p
+    [
+      ...
+      {
+        "Archive": "apache-log4j-2.16.0-bin/log4j-spring-boot-2.16.0-so...",
+        "Manifest_Version": "1.0",
+        "Built_By": "matt",
+        "Created_By": "Apache Maven 3.8.4",
+        "Build_Jdk": "1.8.0_312"
+      },
+      {
+        "Archive": "apache-log4j-2.16.0-bin/log4j-spring-boot-2.16.0-ja...",
+        "Manifest_Version": "1.0",
+        "Built_By": "matt",
+        "Created_By": "Apache Maven 3.8.4",
+        "Build_Jdk": "1.8.0_312"
+      },
+      {
+        "Bundle_SymbolicName": "org.apache.logging.log4j.spring-cloud-c...",
+        "Export_Package": "org.apache.logging.log4j.spring.cloud.config...",
+        "Archive": "apache-log4j-2.16.0-bin/log4j-spring-cloud-config-c...",
+        "Manifest_Version": "1.0",
+        "Bundle_License": "https://www.apache.org/licenses/LICENSE-2.0.txt",
+        ...
+      }
+      ...
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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 0.01 by Matt J (https://github.com/listuser)

docs/parsers/jobs.md

@@ -1,25 +1,38 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.jobs
 jc - JSON CLI output utility `jobs` command output parser
 
 Also supports the `-l` option.
 
+The "Magic" syntax is not supported since the `jobs` command is a shell
+builtin.
+
 Usage (cli):
 
     $ jobs | jc --jobs
 
-    or
-
-    $ jc jobs
-
 Usage (module):
 
+    import jc
+    result = jc.parse('jobs', jobs_command_output)
+
+    or
+
     import jc.parsers.jobs
     result = jc.parsers.jobs.parse(jobs_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    [
+      {
+        "job_number":   integer,
+        "pid":          integer,
+        "history":      string,
+        "status":       string,
+        "command":      string
+      }
+    ]
 
 Example:
 
@@ -88,33 +101,7 @@ Example:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "job_number":   integer,
-        "pid":          integer,
-        "history":      string,
-        "status":       string,
-        "command":      string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -126,10 +113,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/kv.md

@@ -1,11 +1,15 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.kv
 jc - JSON CLI output utility `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.
-
-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()`.
+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.
 
+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):
 
@@ -13,12 +17,23 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('kv', kv_file_output)
+
+    or
+
     import jc.parsers.kv
     result = jc.parsers.kv.parse(kv_file_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    key/value document converted to a dictionary - see the
+    configparser standard library documentation for more details.
+
+    {
+      "key1":       string,
+      "key2":       string
+    }
 
 Examples:
 
@@ -33,7 +48,7 @@ Examples:
     # but can be preserved with the -r argument
     occupation:"Engineer"
 
-    $ cat keyvalue.txt | jc --ini -p
+    $ cat keyvalue.txt | jc --kv -p
     {
       "name": "John Doe",
       "address": "555 California Drive",
@@ -46,7 +61,7 @@ Examples:
 ```python
 info()
 ```
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -60,10 +75,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary representing the key/value file
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/last.md

@@ -1,7 +1,14 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.last
 jc - JSON CLI output utility `last` and `lastb` command output parser
 
+Supports `-w` and `-F` options.
+
+Calculated epoch time fields are naive (i.e. based on the local time of the
+system the parser is run on) since there is no timezone information in the
+`last` command output.
+
 Usage (cli):
 
     $ last | jc --last
@@ -12,39 +19,62 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('last', last_command_output)
+
+    or
+
     import jc.parsers.last
     result = jc.parsers.last.parse(last_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'aix', 'freebsd'
+    [
+      {
+        "user":             string,
+        "tty":              string,
+        "hostname":         string,
+        "login":            string,
+        "logout":           string,
+        "duration":         string,
+        "login_epoch":      integer,  # (naive) available w/last -F option
+        "logout_epoch":     integer,  # (naive) available w/last -F option
+        "duration_seconds": integer   # available w/last -F option
+      }
+    ]
 
 Examples:
 
-    $ last | jc --last -p
+    $ last -F | jc --last -p
     [
       {
         "user": "kbrazil",
         "tty": "ttys002",
         "hostname": null,
-        "login": "Thu Feb 27 14:31",
+        "login": "Mon Dec 28 17:24:10 2020",
         "logout": "still logged in"
       },
       {
         "user": "kbrazil",
         "tty": "ttys003",
         "hostname": null,
-        "login": "Thu Feb 27 10:38",
-        "logout": "10:38",
-        "duration": "00:00"
+        "login": "Mon Dec 28 17:24:10 2020",
+        "logout": "Mon Dec 28 17:25:01 2020",
+        "duration": "00:00",
+        "login_epoch": 1565891826,
+        "logout_epoch": 1565895404,
+        "duration_seconds": 3578
       },
       {
         "user": "kbrazil",
         "tty": "ttys003",
         "hostname": null,
-        "login": "Thu Feb 27 10:18",
-        "logout": "10:18",
-        "duration": "00:00"
+        "login": "Mon Dec 28 17:24:10 2020",
+        "logout": "Mon Dec 28 17:25:01 2020",
+        "duration": "00:00",
+        "login_epoch": 1565891826,
+        "logout_epoch": 1565895404,
+        "duration_seconds": 3578
       },
       ...
     ]
@@ -83,34 +113,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "user":       string,
-        "tty":        string,
-        "hostname":   string,
-        "login":      string,
-        "logout":     string,
-        "duration":   string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -122,10 +125,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, aix, freebsd
+
+Version 1.8 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ls.md

@@ -1,13 +1,23 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.ls
 jc - JSON CLI output utility `ls` and `vdir` command output parser
 
 Options supported:
-- `lbaR`
+- `lbaR1`
 - `--time-style=full-iso`
-- `-h`: File sizes will be available in text form with `-r` but larger file sizes with human readable suffixes will be converted to `Null` in the default view since the parser attempts to convert this field to an integer.
 
-Note: The `-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 `-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)
+
+The `epoch_utc` calculated timestamp field is timezone-aware and is only
+available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -19,12 +29,34 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('ls', ls_command_output)
+
+    or
+
     import jc.parsers.ls
     result = jc.parsers.ls.parse(ls_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    [
+      {
+        "filename":     string,
+        "flags":        string,
+        "links":        integer,
+        "parent":       string,
+        "owner":        string,
+        "group":        string,
+        "size":         integer,
+        "date":         string,
+        "epoch":        integer,     # [0]
+        "epoch_utc":    integer      # [1]
+      }
+    ]
+
+    [0] naive timestamp if date field exists and can be converted.
+    [1] timezone aware timestamp if date field is in UTC and can
+        be converted.
 
 Examples:
 
@@ -36,12 +68,6 @@ Examples:
       {
         "filename": "arch"
       },
-      {
-        "filename": "awk"
-      },
-      {
-        "filename": "base64"
-      },
       ...
     ]
 
@@ -66,15 +92,6 @@ Examples:
         "size": 62744,
         "date": "Aug 8 16:14"
       },
-      {
-        "filename": "arch",
-        "flags": "-rwxr-xr-x.",
-        "links": 1,
-        "owner": "root",
-        "group": "root",
-        "size": 33080,
-        "date": "Aug 19 23:25"
-      },
       ...
     ]
 
@@ -99,92 +116,15 @@ Examples:
         "size": "33080",
         "date": "Aug 19 23:25"
       },
-      {
-        "filename": "awk",
-        "link_to": "gawk",
-        "flags": "lrwxrwxrwx.",
-        "links": "1",
-        "owner": "root",
-        "group": "root",
-        "size": "4",
-        "date": "Aug 15 10:53"
-      },
-      {
-        "filename": "base64",
-        "flags": "-rwxr-xr-x.",
-        "links": "1",
-        "owner": "root",
-        "group": "root",
-        "size": "37360",
-        "date": "Aug 19 23:25"
-      },
-      {
-        "filename": "basename",
-        "flags": "-rwxr-xr-x.",
-        "links": "1",
-        "owner": "root",
-        "group": "root",
-        "size": "29032",
-        "date": "Aug 19 23:25"
-      },
-      {
-        "filename": "bash",
-        "flags": "-rwxr-xr-x.",
-        "links": "1",
-        "owner": "root",
-        "group": "root",
-        "size": "964600",
-        "date": "Aug 8 05:06"
-      },
       ...
     ]
 
-    $ ls -l /usr/bin | jc --ls | jq '.[] | select(.size > 50000000)'
-    {
-      "filename": "emacs",
-      "flags": "-r-xr-xr-x",
-      "links": 1,
-      "owner": "root",
-      "group": "wheel",
-      "size": 117164432,
-      "date": "May 3 2019"
-    }
-
 
 ## info
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "filename": string,
-        "flags":    string,
-        "links":    integer,
-        "parent":   string,
-        "owner":    string,
-        "group":    string,
-        "size":     integer,
-        "date":     string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -196,10 +136,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.10 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ls_s.md

@@ -0,0 +1,117 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.ls_s
+jc - JSON CLI output utility `ls` and `vdir` command output streaming
+parser
+
+> This streaming parser outputs JSON Lines
+
+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`.
+
+The `jc` `-qq` option can be used to ignore parsing errors. (e.g. filenames
+with newline characters, but `-b` was not used)
+
+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):
+
+    $ ls | jc --ls-s
+
+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:
+
+    {
+      "filename":       string,
+      "flags":          string,
+      "links":          integer,
+      "parent":         string,
+      "owner":          string,
+      "group":          string,
+      "size":           integer,
+      "date":           string,
+      "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
+        }
+    }
+
+    [0] naive timestamp if date field exists and can be converted.
+    [1] timezone aware timestamp if date field is in UTC and can
+        be converted
+
+Examples:
+
+    $ ls -l /usr/bin | jc --ls-s
+    {"filename":"2to3-","flags":"-rwxr-xr-x","links":4,"owner":"root","...}
+    {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/P...}
+    {"filename":"AssetCacheLocatorUtil","flags":"-rwxr-xr-x","links":1,...}
+    ...
+
+    $ ls -l /usr/bin | jc --ls-s -r
+    {"filename":"2to3-","flags":"-rwxr-xr-x","links":"4","owner":"roo"..."}
+    {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/P...}
+    {"filename":"AssetCacheLocatorUtil","flags":"-rwxr-xr-x","links":"1...}
+    ...
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False, ignore_exceptions=False)
+```
+
+Main text parsing generator function. Returns an iterator object.
+
+Parameters:
+
+    data:              (iterable)  line-based text data to parse
+                                   (e.g. sys.stdin or str.splitlines())
+
+    raw:               (boolean)   unprocessed output if True
+    quiet:             (boolean)   suppress warning messages if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+
+Yields:
+
+    Dictionary. Raw or processed structured data.
+
+Returns:
+
+    Iterator object
+
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 0.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/lsblk.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.lsblk
 jc - JSON CLI output utility `lsblk` command output parser
@@ -12,12 +13,60 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('lsblk', lsblk_command_output)
+
+    or
+
     import jc.parsers.lsblk
     result = jc.parsers.lsblk.parse(lsblk_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "name":         string,
+        "maj_min":      string,
+        "rm":           boolean,
+        "size":         string,
+        "ro":           boolean,
+        "type":         string,
+        "mountpoint":   string,
+        "kname":        string,
+        "fstype":       string,
+        "label":        string,
+        "uuid":         string,
+        "partlabel":    string,
+        "partuuid":     string,
+        "ra":           integer,
+        "model":        string,
+        "serial":       string,
+        "state":        string,
+        "owner":        string,
+        "group":        string,
+        "mode":         string,
+        "alignment":    integer,
+        "min_io":       integer,
+        "opt_io":       integer,
+        "phy_sec":      integer,
+        "log_sec":      integer,
+        "rota":         boolean,
+        "sched":        string,
+        "rq_size":      integer,
+        "disc_aln":     integer,
+        "disc_gran":    string,
+        "disc_max":     string,
+        "disc_zero":    boolean,
+        "wsame":        string,
+        "wwn":          string,
+        "rand":         boolean,
+        "pkname":       string,
+        "hctl":         string,
+        "tran":         string,
+        "rev":          string,
+        "vendor":       string
+      }
+    ]
 
 Examples:
 
@@ -44,7 +93,10 @@ Examples:
       ...
     ]
 
-    $ lsblk -o +KNAME,FSTYPE,LABEL,UUID,PARTLABEL,PARTUUID,RA,MODEL,SERIAL,STATE,OWNER,GROUP,MODE,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,SCHED,RQ-SIZE,DISC-ALN,DISC-GRAN,DISC-MAX,DISC-ZERO,WSAME,WWN,RAND,PKNAME,HCTL,TRAN,REV,VENDOR | jc --lsblk -p
+    $ lsblk -o +KNAME,FSTYPE,LABEL,UUID,PARTLABEL,PARTUUID,RA,MODEL,SERIAL,\
+      STATE,OWNER,GROUP,MODE,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,\
+      SCHED,RQ-SIZE,DISC-ALN,DISC-GRAN,DISC-MAX,DISC-ZERO,WSAME,WWN,RAND,\
+      PKNAME,HCTL,TRAN,REV,VENDOR | jc --lsblk -p
     [
       {
         "name": "sda",
@@ -133,7 +185,10 @@ Examples:
       ...
     ]
 
-    $ lsblk -o +KNAME,FSTYPE,LABEL,UUID,PARTLABEL,PARTUUID,RA,MODEL,SERIAL,STATE,OWNER,GROUP,MODE,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,SCHED,RQ-SIZE,DISC-ALN,DISC-GRAN,DISC-MAX,DISC-ZERO,WSAME,WWN,RAND,PKNAME,HCTL,TRAN,REV,VENDOR | jc --lsblk -p -r
+    $ lsblk -o +KNAME,FSTYPE,LABEL,UUID,PARTLABEL,PARTUUID,RA,MODEL,SERIAL,\
+      STATE,OWNER,GROUP,MODE,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,\
+      SCHED,RQ-SIZE,DISC-ALN,DISC-GRAN,DISC-MAX,DISC-ZERO,WSAME,WWN,RAND,\
+      PKNAME,HCTL,TRAN,REV,VENDOR | jc --lsblk -p -r
     [
       {
         "name": "sda",
@@ -227,68 +282,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "name":         string,
-        "maj_min":      string,
-        "rm":           boolean,
-        "size":         string,
-        "ro":           boolean,
-        "type":         string,
-        "mountpoint":   string,
-        "kname":        string,
-        "fstype":       string,
-        "label":        string,
-        "uuid":         string,
-        "partlabel":    string,
-        "partuuid":     string,
-        "ra":           integer,
-        "model":        string,
-        "serial":       string,
-        "state":        string,
-        "owner":        string,
-        "group":        string,
-        "mode":         string,
-        "alignment":    integer,
-        "min_io":       integer,
-        "opt_io":       integer,
-        "phy_sec":      integer,
-        "log_sec":      integer,
-        "rota":         boolean,
-        "sched":        string,
-        "rq_size":      integer,
-        "disc_aln":     integer,
-        "disc_gran":    string,
-        "disc_max":     string,
-        "disc_zero":    boolean,
-        "wsame":        string,
-        "wwn":          string,
-        "rand":         boolean,
-        "pkname":       string,
-        "hctl":         string,
-        "tran":         string,
-        "rev":          string,
-        "vendor":       string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -300,10 +294,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.8 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/lsmod.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.lsmod
 jc - JSON CLI output utility `lsmod` command output parser
@@ -12,12 +13,26 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('lsmod', lsmod_command_output)
+
+    or
+
     import jc.parsers.lsmod
     result = jc.parsers.lsmod.parse(lsmod_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "module":     string,
+        "size":       integer,
+        "used":       integer,
+        "by": [
+                      string
+        ]
+      }
+    ]
 
 Examples:
 
@@ -118,34 +133,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "module": string,
-        "size":   integer,
-        "used":   integer,
-        "by": [
-                  string
-        ]
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -157,10 +145,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/lsof.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.lsof
 jc - JSON CLI output utility `lsof` command output parser
@@ -12,12 +13,30 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('lsof', lsof_command_output)
+
+    or
+
     import jc.parsers.lsof
     result = jc.parsers.lsof.parse(lsof_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "command":    string,
+        "pid":        integer,
+        "tid":        integer,
+        "user":       string,
+        "fd":         string,
+        "type":       string,
+        "device":     string,
+        "size_off":   integer,
+        "node":       integer,
+        "name":       string
+      }
+    ]
 
 Examples:
 
@@ -108,38 +127,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "command":    string,
-        "pid":        integer,
-        "tid":        integer,
-        "user":       string,
-        "fd":         string,
-        "type":       string,
-        "device":     string,
-        "size_off":   integer,
-        "node":       integer,
-        "name":       string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -151,10 +139,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/lsusb.md

@@ -0,0 +1,294 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.lsusb
+jc - JSON CLI output utility `lsusb` command output parser
+
+Supports the `-v` option or no options.
+
+Usage (cli):
+
+    $ lsusb -v | jc --lsusb
+
+    or
+
+    $ jc lsusb -v
+
+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.
+
+    [
+      {
+        "bus":                                string,
+        "device":                             string,
+        "id":                                 string,
+        "description":                        string,
+        "device_descriptor": {
+          "<item>": {
+            "value":                          string,
+            "description":                    string,
+            "attributes": [
+                                              string
+            ]
+          },
+          "configuration_descriptor": {
+            "<item>": {
+              "value":                        string,
+              "description":                  string,
+              "attributes": [
+                                              string
+              ]
+            },
+            "interface_association": {
+              "<item>": {
+                "value":                      string,
+                "description":                string,
+                "attributes": [
+                                              string
+                ]
+              }
+            },
+            "interface_descriptors": [
+              {
+                "<item>": {
+                  "value":                    string,
+                  "description":              string,
+                  "attributes": [
+                                              string
+                  ]
+                },
+                "cdc_header": {
+                  "<item>": {
+                    "value":                  string,
+                    "description":            string,
+                    "attributes": [
+                                              string
+                    ]
+                  }
+                },
+                "cdc_call_management": {
+                  "<item>": {
+                    "value":                  string,
+                    "description":            string,
+                    "attributes": [
+                                              string
+                    ]
+                  }
+                },
+                "cdc_acm": {
+                  "<item>": {
+                    "value":                  string,
+                    "description":            string,
+                    "attributes": [
+                                              string
+                    ]
+                  }
+                },
+                "cdc_union": {
+                  "<item>": {
+                    "value":                  string,
+                    "description":            string,
+                    "attributes": [
+                                              string
+                    ]
+                  }
+                },
+                "endpoint_descriptors": [
+                  {
+                    "<item>": {
+                      "value":                string,
+                      "description":          string,
+                      "attributes": [
+                                              string
+                      ]
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        "hub_descriptor": {
+          "<item>": {
+            "value":                          string,
+            "description":                    string,
+            "attributes": [
+                                              string,
+            ]
+          },
+          "hub_port_status": {
+            "<item>": {
+              "value":                        string,
+              "attributes": [
+                                              string
+              ]
+            }
+          }
+        },
+        "device_status": {
+          "value":                            string,
+          "description":                      string
+        }
+      }
+    ]
+
+Examples:
+
+    $ lsusb -v | jc --lsusb -p
+    [
+      {
+        "bus": "002",
+        "device": "001",
+        "id": "1d6b:0001",
+        "description": "Linux Foundation 1.1 root hub",
+        "device_descriptor": {
+          "bLength": {
+            "value": "18"
+          },
+          "bDescriptorType": {
+            "value": "1"
+          },
+          "bcdUSB": {
+            "value": "1.10"
+          },
+          ...
+          "bNumConfigurations": {
+            "value": "1"
+          },
+          "configuration_descriptor": {
+            "bLength": {
+              "value": "9"
+            },
+            ...
+            "iConfiguration": {
+              "value": "0"
+            },
+            "bmAttributes": {
+              "value": "0xe0",
+              "attributes": [
+                "Self Powered",
+                "Remote Wakeup"
+              ]
+            },
+            "MaxPower": {
+              "description": "0mA"
+            },
+            "interface_descriptors": [
+              {
+                "bLength": {
+                  "value": "9"
+                },
+                ...
+                "bInterfaceProtocol": {
+                  "value": "0",
+                  "description": "Full speed (or root) hub"
+                },
+                "iInterface": {
+                  "value": "0"
+                },
+                "endpoint_descriptors": [
+                  {
+                    "bLength": {
+                      "value": "7"
+                    },
+                    ...
+                    "bmAttributes": {
+                      "value": "3",
+                      "attributes": [
+                        "Transfer Type  Interrupt",
+                        "Synch Type  None",
+                        "Usage Type  Data"
+                      ]
+                    },
+                    "wMaxPacketSize": {
+                      "value": "0x0002",
+                      "description": "1x 2 bytes"
+                    },
+                    "bInterval": {
+                      "value": "255"
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        "hub_descriptor": {
+          "bLength": {
+            "value": "9"
+          },
+          ...
+          "wHubCharacteristic": {
+            "value": "0x000a",
+            "attributes": [
+              "No power switching (usb 1.0)",
+              "Per-port overcurrent protection"
+            ]
+          },
+          ...
+          "hub_port_status": {
+            "Port 1": {
+              "value": "0000.0103",
+              "attributes": [
+                "power",
+                "enable",
+                "connect"
+              ]
+            },
+            "Port 2": {
+              "value": "0000.0103",
+              "attributes": [
+                "power",
+                "enable",
+                "connect"
+              ]
+            }
+          }
+        },
+        "device_status": {
+          "value": "0x0001",
+          "description": "Self Powered"
+        }
+      }
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/mount.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.mount
 jc - JSON CLI output utility `mount` command output parser
@@ -12,12 +13,26 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('mount', mount_command_output)
+
+    or
+
     import jc.parsers.mount
     result = jc.parsers.mount.parse(mount_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'freebsd'
+    [
+      {
+        "filesystem":       string,
+        "mount_point":      string,
+        "type":             string,
+        "access": [
+                            string
+        ]
+      }
+    ]
 
 Example:
 
@@ -68,34 +83,7 @@ Example:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "filesystem":   string,
-        "mount_point":  string,
-        "type":         string,
-        "access": [
-                        string
-        ]
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -107,10 +95,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.7 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/netstat.md

@@ -1,10 +1,12 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.netstat
 jc - JSON CLI output utility `netstat` command output parser
 
 Caveats:
 - Use of multiple `l` options is not supported on OSX (e.g. `netstat -rlll`)
-- Use of the `A` option is not supported on OSX when using the `r` option (e.g. `netstat -rA`)
+- Use of the `A` option is not supported on OSX when using the `r` option
+  (e.g. `netstat -rA`)
 
 Usage (cli):
 
@@ -16,12 +18,114 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('netstat', netstat_command_output)
+
+    or
+
     import jc.parsers.netstat
     result = jc.parsers.netstat.parse(netstat_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'freebsd'
+    [
+      {
+        "proto":                  string,
+        "recv_q":                 integer,
+        "send_q":                 integer,
+        "transport_protocol"      string,
+        "network_protocol":       string,
+        "local_address":          string,
+        "local_port":             string,
+        "local_port_num":         integer,
+        "foreign_address":        string,
+        "foreign_port":           string,
+        "foreign_port_num":       integer,
+        "state":                  string,
+        "program_name":           string,
+        "pid":                    integer,
+        "user":                   string,
+        "security_context":       string,
+        "refcnt":                 integer,
+        "flags":                  string,
+        "type":                   string,
+        "inode":                  integer,
+        "path":                   string,
+        "kind":                   string,
+        "address":                string,
+        "unix_inode":             string,
+        "conn":                   string,
+        "refs":                   string,
+        "nextref":                string,
+        "name":                   string,
+        "unit":                   integer,
+        "vendor":                 integer,
+        "class":                  integer,
+        "subcla":                 integer,
+        "unix_flags":             integer,
+        "pcbcount":               integer,
+        "rcvbuf":                 integer,
+        "sndbuf":                 integer,
+        "rxbytes":                integer,
+        "txbytes":                integer,
+        "destination":            string,
+        "gateway":                string,
+        "route_flags":            string,
+        "route_flags_pretty": [
+                                  string,
+        ]
+        "route_refs":             integer,
+        "use":                    integer,
+        "mtu":                    integer,
+        "expire":                 string,
+        "genmask":                string,
+        "mss":                    integer,
+        "window":                 integer,
+        "irtt":                   integer,
+        "iface":                  string,
+        "metric":                 integer,
+        "network":                string,
+        "address":                string,
+        "ipkts":                  integer,    # - = null
+        "ierrs":                  integer,    # - = null
+        "idrop":                  integer,    # - = null
+        "opkts":                  integer,    # - = null
+        "oerrs":                  integer,    # - = null
+        "coll":                   integer,    # - = null
+        "rx_ok":                  integer,
+        "rx_err":                 integer,
+        "rx_drp":                 integer,
+        "rx_ovr":                 integer,
+        "tx_ok":                  integer,
+        "tx_err":                 integer,
+        "tx_drp":                 integer,
+        "tx_ovr":                 integer,
+        "flg":                    string,
+        "ibytes":                 integer,
+        "obytes":                 integer,
+        "r_mbuf":                 integer,
+        "s_mbuf":                 integer,
+        "r_clus":                 integer,
+        "s_clus":                 integer,
+        "r_hiwa":                 integer,
+        "s_hiwa":                 integer,
+        "r_lowa":                 integer,
+        "s_lowa":                 integer,
+        "r_bcnt":                 integer,
+        "s_bcnt":                 integer,
+        "r_bmax":                 integer,
+        "s_bmax":                 integer,
+        "rexmit":                 integer,
+        "ooorcv":                 integer,
+        "0_win":                  integer,
+        "rexmt":                  float,
+        "persist":                float,
+        "keep":                   float,
+        "2msl":                   float,
+        "delack":                 float,
+        "rcvtime":                float,
+      }
+    ]
 
 Examples:
 
@@ -259,122 +363,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "proto":                  string,
-        "recv_q":                 integer,
-        "send_q":                 integer,
-        "transport_protocol"      string,
-        "network_protocol":       string,
-        "local_address":          string,
-        "local_port":             string,
-        "local_port_num":         integer,
-        "foreign_address":        string,
-        "foreign_port":           string,
-        "foreign_port_num":       integer,
-        "state":                  string,
-        "program_name":           string,
-        "pid":                    integer,
-        "user":                   string,
-        "security_context":       string,
-        "refcnt":                 integer,
-        "flags":                  string,
-        "type":                   string,
-        "inode":                  integer,
-        "path":                   string,
-        "kind":                   string,
-        "address":                string,
-        "unix_inode":             string,
-        "conn":                   string,
-        "refs":                   string,
-        "nextref":                string,
-        "name":                   string,
-        "unit":                   integer,
-        "vendor":                 integer,
-        "class":                  integer,
-        "subcla":                 integer,
-        "unix_flags":             integer,
-        "pcbcount":               integer,
-        "rcvbuf":                 integer,
-        "sndbuf":                 integer,
-        "rxbytes":                integer,
-        "txbytes":                integer,
-        "destination":            string,
-        "gateway":                string,
-        "route_flags":            string,
-        "route_flags_pretty": [
-                                  string,
-        ]
-        "route_refs":             integer,
-        "use":                    integer,
-        "mtu":                    integer,
-        "expire":                 string,
-        "genmask":                string,
-        "mss":                    integer,
-        "window":                 integer,
-        "irtt":                   integer,
-        "iface":                  string,
-        "metric":                 integer,
-        "network":                string,
-        "address":                string,
-        "ipkts":                  integer,    - = null
-        "ierrs":                  integer,    - = null
-        "idrop":                  integer,    - = null
-        "opkts":                  integer,    - = null
-        "oerrs":                  integer,    - = null
-        "coll":                   integer,    - = null
-        "rx_ok":                  integer,
-        "rx_err":                 integer,
-        "rx_drp":                 integer,
-        "rx_ovr":                 integer,
-        "tx_ok":                  integer,
-        "tx_err":                 integer,
-        "tx_drp":                 integer,
-        "tx_ovr":                 integer,
-        "flg":                    string,
-        "ibytes":                 integer,
-        "obytes":                 integer,
-        "r_mbuf":                 integer,
-        "s_mbuf":                 integer,
-        "r_clus":                 integer,
-        "s_clus":                 integer,
-        "r_hiwa":                 integer,
-        "s_hiwa":                 integer,
-        "r_lowa":                 integer,
-        "s_lowa":                 integer,
-        "r_bcnt":                 integer,
-        "s_bcnt":                 integer,
-        "r_bmax":                 integer,
-        "s_bmax":                 integer,
-        "rexmit":                 integer,
-        "ooorcv":                 integer,
-        "0_win":                  integer,
-        "rexmt":                  float,
-        "persist":                float,
-        "keep":                   float,
-        "2msl":                   float,
-        "delack":                 float,
-        "rcvtime":                float,
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -386,10 +375,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.12 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ntpq.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.ntpq
 jc - JSON CLI output utility `ntpq -p` command output parser
@@ -12,12 +13,31 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('ntpq', ntpq_command_output)
+
+    or
+
     import jc.parsers.ntpq
     result = jc.parsers.ntpq.parse(ntpq_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'freebsd'
+    [
+      {
+        "state":            string,        # space/~ converted to null
+        "remote":           string,
+        "refid":            string,
+        "st":               integer,
+        "t":                string,
+        "when":             integer,       # - converted to null
+        "poll":             integer,
+        "reach":            integer,
+        "delay":            float,
+        "offset":           float,
+        "jitter":           float
+      },
+    ]
 
 Examples:
 
@@ -194,40 +214,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "state":            string,        # space/~ converted to null
-        "remote":           string,
-        "refid":            string,
-        "st":               integer,
-        "t":                string,
-        "when":             integer,       # - converted to null
-        "poll":             integer,
-        "reach":            integer,
-        "delay":            float,
-        "offset":           float,
-        "jitter":           float
-      },
-    ]
-
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -239,10 +226,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, freebsd
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/passwd.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.passwd
 jc - JSON CLI output utility `/etc/passwd` file Parser
@@ -8,12 +9,27 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('passwd', passwd_file_output)
+
+    or
+
     import jc.parsers.passwd
     result = jc.parsers.passwd.parse(passwd_file_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'aix', 'freebsd'
+    [
+      {
+        "username":     string,
+        "password":     string,
+        "uid":          integer,
+        "gid":          integer,
+        "comment":      string,
+        "home":         string,
+        "shell":        string
+      }
+    ]
 
 Examples:
 
@@ -86,35 +102,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "username":  string,
-        "password":  string,
-        "uid":       integer,
-        "gid":       integer,
-        "comment":   string,
-        "home":      string,
-        "shell":     string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -126,10 +114,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, aix, freebsd
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ping.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.ping
 jc - JSON CLI output utility `ping` command output parser
@@ -6,7 +7,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
 
@@ -16,12 +18,60 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('ping', ping_command_output)
+
+    or
+
     import jc.parsers.ping
     result = jc.parsers.ping.parse(ping_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'freebsd'
+    {
+      "source_ip":                   string,
+      "destination_ip":              string,
+      "data_bytes":                  integer,
+      "pattern":                     string,        # null if not set
+      "destination":                 string,
+      "packets_transmitted":         integer,
+      "packets_received":            integer,
+      "packet_loss_percent":         float,
+      "duplicates":                  integer,
+      "round_trip_ms_min":           float,
+      "round_trip_ms_avg":           float,
+      "round_trip_ms_max":           float,
+      "round_trip_ms_stddev":        float,
+      "responses": [
+        {
+          "type":                    string,        # [0]
+          "unparsed_line":           string,        # [1]
+          "timestamp":               float,
+          "bytes":                   integer,
+          "response_ip":             string,
+          "icmp_seq":                integer,
+          "ttl":                     integer,
+          "time_ms":                 float,
+          "duplicate":               boolean,
+          "vr":                      integer,       # [2]
+          "hl":                      integer,       # [2]
+          "tos":                     integer,       # [2]
+          "len":                     integer,       # [2]
+          "id":                      integer,       # [2]
+          "flg":                     integer,       # [2]
+          "off":                     integer,       # [2]
+          "pro":                     integer,       # [2]
+          "cks":                     ingeger,       # [2]
+          "src":                     string,
+          "dst":                     string
+        }
+      ]
+    }
+
+    [0] 'reply', 'timeout', 'unparsable_line', etc. See
+        `_error_type.type_map` for all options
+    [1] only if an 'unparsable_line' type
+    [2] hex value converted to decimal
 
 Examples:
 
@@ -70,7 +120,6 @@ Examples:
       ]
     }
 
-
     $ ping -c 3 -p ff cnn.com | jc --ping -p -r
     {
       "destination_ip": "151.101.129.67",
@@ -121,51 +170,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "source_ip":                   string,
-      "destination_ip":              string,
-      "data_bytes":                  integer,
-      "pattern":                     string,        (null if not set)
-      "destination":                 string,
-      "packets_transmitted":         integer,
-      "packets_received":            integer,
-      "packet_loss_percent":         float,
-      "duplicates":                  integer,
-      "round_trip_ms_min":           float,
-      "round_trip_ms_avg":           float,
-      "round_trip_ms_max":           float,
-      "round_trip_ms_stddev":        float,
-      "responses": [
-        {
-          "type":                    string,        ('reply' or 'timeout')
-          "timestamp":               float,
-          "bytes":                   integer,
-          "response_ip":             string,
-          "icmp_seq":                integer,
-          "ttl":                     integer,
-          "time_ms":                 float,
-          "duplicate":               boolean
-        }
-      ]
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -177,10 +182,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.7 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ping_s.md

@@ -0,0 +1,123 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.ping_s
+jc - JSON CLI output utility `ping` command output streaming parser
+
+> This streaming parser outputs JSON Lines
+
+Supports `ping` and `ping6` output.
+
+Usage (cli):
+
+    $ ping | 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.
+
+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:
+
+    {
+      "type":                       string,   # [0]
+      "source_ip":                  string,
+      "destination_ip":             string,
+      "sent_bytes":                 integer,
+      "pattern":                    string,   # (null if not set)
+      "destination":                string,
+      "timestamp":                  float,
+      "response_bytes":             integer,
+      "response_ip":                string,
+      "icmp_seq":                   integer,
+      "ttl":                        integer,
+      "time_ms":                    float,
+      "duplicate":                  boolean,
+      "packets_transmitted":        integer,
+      "packets_received":           integer,
+      "packet_loss_percent":        float,
+      "duplicates":                 integer,
+      "round_trip_ms_min":          float,
+      "round_trip_ms_avg":          float,
+      "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
+        }
+    }
+
+    [0] 'reply', 'timeout', 'summary', etc. See `_error_type.type_map`
+        for all options.
+
+Examples:
+
+    $ ping 1.1.1.1 | jc --ping-s
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"patte...}
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"patte...}
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"patte...}
+    ...
+
+    $ ping 1.1.1.1 | jc --ping-s -r
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","patte...}
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","patte...}
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","patte...}
+    ...
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False, ignore_exceptions=False)
+```
+
+Main text parsing generator function. Returns an iterator object.
+
+Parameters:
+
+    data:              (iterable)  line-based text data to parse
+                                   (e.g. sys.stdin or str.splitlines())
+
+    raw:               (boolean)   unprocessed output if True
+    quiet:             (boolean)   suppress warning messages if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+
+Yields:
+
+    Dictionary. Raw or processed structured data.
+
+Returns:
+
+    Iterator object
+
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 0.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/pip_list.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.pip_list
 jc - JSON CLI output utility `pip-list` command output parser
@@ -12,12 +13,23 @@ Usage (cli):
 
 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)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    [
+      {
+        "package":     string,
+        "version":     string,
+        "location":    string
+      }
+    ]
 
 Examples:
 
@@ -43,31 +55,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "package":     string,
-        "version":     string,
-        "location":    string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -79,10 +67,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/pip_show.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.pip_show
 jc - JSON CLI output utility `pip-show` command output parser
@@ -12,12 +13,30 @@ Usage (cli):
 
 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)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    [
+      {
+        "name":             string,
+        "version":          string,
+        "summary":          string,
+        "home_page":        string,
+        "author":           string,
+        "author_email":     string,
+        "license":          string,
+        "location":         string,
+        "requires":         string,
+        "required_by":      string
+      }
+    ]
 
 Examples:
 
@@ -54,39 +73,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "name":             string,
-        "version":          string,
-        "summary":          string,
-        "home_page":        string,
-        "author":           string,
-        "author_email":     string,
-        "license":          string,
-        "location":         string,
-        "requires":         string,
-        "required_by":      string
-      }
-    ]
-
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -98,10 +85,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ps.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.ps
 jc - JSON CLI output utility `ps` command output parser
@@ -16,12 +17,37 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('ps', ps_command_output)
+
+    or
+
     import jc.parsers.ps
     result = jc.parsers.ps.parse(ps_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    [
+      {
+        "uid":           string,
+        "pid":           integer,
+        "ppid":          integer,
+        "c":             integer,
+        "stime":         string,
+        "tty":           string,    # ? or ?? = Null
+        "tt":            string,    # ?? = Null
+        "time":          string,
+        "cmd":           string,
+        "user":          string,
+        "cpu_percent":   float,
+        "mem_percent":   float,
+        "vsz":           integer,
+        "rss":           integer,
+        "stat":          string,
+        "start":         string,
+        "command":       string
+      }
+    ]
 
 Examples:
 
@@ -35,7 +61,7 @@ Examples:
         "stime": "Nov01",
         "tty": null,
         "time": "00:00:11",
-        "cmd": "/usr/lib/systemd/systemd --switched-root --system --deserialize 22"
+        "cmd": "/usr/lib/systemd/systemd --switched-root --system --dese..."
       },
       {
         "uid": "root",
@@ -70,7 +96,7 @@ Examples:
         "stime": "Nov01",
         "tty": "?",
         "time": "00:00:11",
-        "cmd": "/usr/lib/systemd/systemd --switched-root --system --deserialize 22"
+        "cmd": "/usr/lib/systemd/systemd --switched-root --system --dese..."
       },
       {
         "uid": "root",
@@ -108,7 +134,7 @@ Examples:
         "stat": "Ss",
         "start": "Nov09",
         "time": "0:08",
-        "command": "/usr/lib/systemd/systemd --switched-root --system --deserialize 22"
+        "command": "/usr/lib/systemd/systemd --switched-root --system --..."
       },
       {
         "user": "root",
@@ -152,7 +178,7 @@ Examples:
         "stat": "Ss",
         "start": "Nov09",
         "time": "0:08",
-        "command": "/usr/lib/systemd/systemd --switched-root --system --deserialize 22"
+        "command": "/usr/lib/systemd/systemd --switched-root --system --..."
       },
       {
         "user": "root",
@@ -188,45 +214,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "uid":           string,
-        "pid":           integer,
-        "ppid":          integer,
-        "c":             integer,
-        "stime":         string,
-        "tty":           string,    # ? or ?? = Null
-        "tt":            string,    # ?? = Null
-        "time":          string,
-        "cmd":           string,
-        "user":          string,
-        "cpu_percent":   float,
-        "mem_percent":   float,
-        "vsz":           integer,
-        "rss":           integer,
-        "stat":          string,
-        "start":         string,
-        "command":       string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -238,10 +226,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/route.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.route
 jc - JSON CLI output utility `route` command output parser
@@ -12,12 +13,34 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('route', route_command_output)
+
+    or
+
     import jc.parsers.route
     result = jc.parsers.route.parse(route_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "destination":     string,
+        "gateway":         string,
+        "genmask":         string,
+        "flags":           string,
+        "flags_pretty": [
+                           string
+        ]
+        "metric":          integer,
+        "ref":             integer,
+        "use":             integer,
+        "mss":             integer,
+        "window":          integer,
+        "irtt":            integer,
+        "iface":           string
+      }
+    ]
 
 Examples:
 
@@ -58,7 +81,6 @@ Examples:
       }
     ]
 
-
     $ route -ee | jc --route -p -r
     [
       {
@@ -90,47 +112,11 @@ Examples:
     ]
 
 
-
 ## info
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "destination":     string,
-        "gateway":         string,
-        "genmask":         string,
-        "flags":           string,
-        "flags_pretty": [
-                           string,
-        ]
-        "metric":          integer,
-        "ref":             integer,
-        "use":             integer,
-        "mss":             integer,
-        "window":          integer,
-        "irtt":            integer,
-        "iface":           string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -142,10 +128,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.7 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/rpm_qi.md

@@ -0,0 +1,194 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.rpm_qi
+jc - JSON CLI output utility `rpm -qi` command output parser
+
+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
+only available if the timezone field is UTC.
+
+Usage (cli):
+
+    $ rpm -qia | jc --rpm-qi
+
+    or
+
+    $ jc rpm -qia
+
+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:
+
+    [
+      {
+        "name":                     string,
+        "epoch":                    integer,
+        "version":                  string,
+        "release":                  string,
+        "architecture":             string,
+        "install_date":             string,
+        "install_date_epoch":       integer,      # [0]
+        "install_date_epoch_utc":   integer,      # [1]
+        "group":                    string,
+        "size":                     integer,
+        "license":                  string,
+        "signature":                string,
+        "source_rpm":               string,
+        "build_date":               string,
+        "build_epoch":              integer,      # [0]
+        "build_epoch_utc":          integer,      # [1]
+        "build_host":               string,
+        "relocations":              string,
+        "packager":                 string,
+        "vendor":                   string,
+        "url":                      string,
+        "summary":                  string,
+        "description":              string
+      }
+    ]
+
+    [0] naive timestamp
+    [1] Aware timestamp if timezone is UTC
+
+Examples:
+
+    $ rpm -qia | jc --rpm-qi -p
+    [
+      {
+        "name": "make",
+        "epoch": 1,
+        "version": "3.82",
+        "release": "24.el7",
+        "architecture": "x86_64",
+        "install_date": "Wed 16 Oct 2019 09:21:42 AM PDT",
+        "group": "Development/Tools",
+        "size": 1160660,
+        "license": "GPLv2+",
+        "signature": "RSA/SHA256, Thu 22 Aug 2019 02:34:59 PM PDT, Key ...",
+        "source_rpm": "make-3.82-24.el7.src.rpm",
+        "build_date": "Thu 08 Aug 2019 05:47:25 PM PDT",
+        "build_host": "x86-01.bsys.centos.org",
+        "relocations": "(not relocatable)",
+        "packager": "CentOS BuildSystem <http://bugs.centos.org>",
+        "vendor": "CentOS",
+        "url": "http://www.gnu.org/software/make/",
+        "summary": "A GNU tool which simplifies the build process for ...",
+        "description": "A GNU tool for controlling the generation of ex...",
+        "build_epoch": 1565311645,
+        "build_epoch_utc": null,
+        "install_date_epoch": 1571242902,
+        "install_date_epoch_utc": null
+      },
+      {
+        "name": "kbd-legacy",
+        "version": "1.15.5",
+        "release": "15.el7",
+        "architecture": "noarch",
+        "install_date": "Thu 15 Aug 2019 10:53:08 AM PDT",
+        "group": "System Environment/Base",
+        "size": 503608,
+        "license": "GPLv2+",
+        "signature": "RSA/SHA256, Mon 12 Nov 2018 07:17:49 AM PST, Key ...",
+        "source_rpm": "kbd-1.15.5-15.el7.src.rpm",
+        "build_date": "Tue 30 Oct 2018 03:40:00 PM PDT",
+        "build_host": "x86-01.bsys.centos.org",
+        "relocations": "(not relocatable)",
+        "packager": "CentOS BuildSystem <http://bugs.centos.org>",
+        "vendor": "CentOS",
+        "url": "http://ftp.altlinux.org/pub/people/legion/kbd",
+        "summary": "Legacy data for kbd package",
+        "description": "The kbd-legacy package contains original keymap...",
+        "build_epoch": 1540939200,
+        "build_epoch_utc": null,
+        "install_date_epoch": 1565891588,
+        "install_date_epoch_utc": null
+      },
+      ...
+    ]
+
+    $ rpm -qia | jc --rpm-qi -p -r
+    [
+      {
+        "name": "make",
+        "epoch": "1",
+        "version": "3.82",
+        "release": "24.el7",
+        "architecture": "x86_64",
+        "install_date": "Wed 16 Oct 2019 09:21:42 AM PDT",
+        "group": "Development/Tools",
+        "size": "1160660",
+        "license": "GPLv2+",
+        "signature": "RSA/SHA256, Thu 22 Aug 2019 02:34:59 PM PDT, Key ...",
+        "source_rpm": "make-3.82-24.el7.src.rpm",
+        "build_date": "Thu 08 Aug 2019 05:47:25 PM PDT",
+        "build_host": "x86-01.bsys.centos.org",
+        "relocations": "(not relocatable)",
+        "packager": "CentOS BuildSystem <http://bugs.centos.org>",
+        "vendor": "CentOS",
+        "url": "http://www.gnu.org/software/make/",
+        "summary": "A GNU tool which simplifies the build process for...",
+        "description": "A GNU tool for controlling the generation of exe..."
+      },
+      {
+        "name": "kbd-legacy",
+        "version": "1.15.5",
+        "release": "15.el7",
+        "architecture": "noarch",
+        "install_date": "Thu 15 Aug 2019 10:53:08 AM PDT",
+        "group": "System Environment/Base",
+        "size": "503608",
+        "license": "GPLv2+",
+        "signature": "RSA/SHA256, Mon 12 Nov 2018 07:17:49 AM PST, Key ...",
+        "source_rpm": "kbd-1.15.5-15.el7.src.rpm",
+        "build_date": "Tue 30 Oct 2018 03:40:00 PM PDT",
+        "build_host": "x86-01.bsys.centos.org",
+        "relocations": "(not relocatable)",
+        "packager": "CentOS BuildSystem <http://bugs.centos.org>",
+        "vendor": "CentOS",
+        "url": "http://ftp.altlinux.org/pub/people/legion/kbd",
+        "summary": "Legacy data for kbd package",
+        "description": "The kbd-legacy package contains original keymaps..."
+      },
+      ...
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/sfdisk.md

@@ -0,0 +1,235 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.sfdisk
+jc - JSON CLI output utility `sfdisk` command output parser
+
+Supports the following `sfdisk` options:
+- `-l`
+- `-F`
+- `-d`   (deprecated - only for older versions of util-linux)
+- `-uM`  (deprecated - only for older versions of util-linux)
+- `-uC`  (deprecated - only for older versions of util-linux)
+- `-uS`  (deprecated - only for older versions of util-linux)
+- `-uB`  (deprecated - only for older versions of util-linux)
+
+Usage (cli):
+
+    # sfdisk -l | jc --sfdisk
+
+    or
+
+    # jc sfdisk -l
+
+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:
+
+    [
+      {
+        "disk":                     string,
+        "disk_size":                string,
+        "free_disk_size":           string,
+        "bytes":                    integer,
+        "free_bytes":               integer,
+        "sectors":                  integer,
+        "free_sectors":             integer,
+        "cylinders":                integer,
+        "heads":                    integer,
+        "sectors_per_track":        integer,
+        "units":                    string,
+        "logical_sector_size":      integer,
+        "physical_sector_size":     integer,
+        "min_io_size":              integer,
+        "optimal_io_size":          integer,
+        "disk_label_type":          string,
+        "disk_identifier":          string,
+        "disk_model":               string,
+        "partitions": [
+          {
+            "device":               string,
+            "boot":                 boolean,
+            "start":                integer,
+            "end":                  integer,
+            "size":                 string,    # [0]
+            "cyls":                 integer,
+            "mib":                  integer,
+            "blocks":               integer,
+            "sectors":              integer,
+            "id":                   string,
+            "system":               string,
+            "type":                 string
+          }
+        ]
+      }
+    ]
+
+    [0] will be integer when using deprecated -d sfdisk option
+
+Examples:
+
+    # sfdisk -l | jc --sfdisk -p
+    [
+      {
+        "disk": "/dev/sda",
+        "cylinders": 2610,
+        "heads": 255,
+        "sectors_per_track": 63,
+        "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, ...",
+        "partitions": [
+          {
+            "device": "/dev/sda1",
+            "boot": true,
+            "start": 0,
+            "end": 130,
+            "cyls": 131,
+            "blocks": 1048576,
+            "id": "83",
+            "system": "Linux"
+          },
+          {
+            "device": "/dev/sda2",
+            "boot": false,
+            "start": 130,
+            "end": 2610,
+            "cyls": 2481,
+            "blocks": 19921920,
+            "id": "8e",
+            "system": "Linux LVM"
+          },
+          {
+            "device": "/dev/sda3",
+            "boot": false,
+            "start": 0,
+            "end": null,
+            "cyls": 0,
+            "blocks": 0,
+            "id": "0",
+            "system": "Empty"
+          },
+          {
+            "device": "/dev/sda4",
+            "boot": false,
+            "start": 0,
+            "end": null,
+            "cyls": 0,
+            "blocks": 0,
+            "id": "0",
+            "system": "Empty"
+          }
+        ]
+      },
+      {
+        "disk": "/dev/mapper/centos-root",
+        "cylinders": 2218,
+        "heads": 255,
+        "sectors_per_track": 63
+      },
+      {
+        "disk": "/dev/mapper/centos-swap",
+        "cylinders": 261,
+        "heads": 255,
+        "sectors_per_track": 63
+      }
+    ]
+
+    # sfdisk -l | jc --sfdisk -p -r
+    [
+      {
+        "disk": "/dev/sda",
+        "cylinders": "2610",
+        "heads": "255",
+        "sectors_per_track": "63",
+        "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, co...",
+        "partitions": [
+          {
+            "device": "/dev/sda1",
+            "boot": "*",
+            "start": "0+",
+            "end": "130-",
+            "cyls": "131-",
+            "blocks": "1048576",
+            "id": "83",
+            "system": "Linux"
+          },
+          {
+            "device": "/dev/sda2",
+            "boot": null,
+            "start": "130+",
+            "end": "2610-",
+            "cyls": "2481-",
+            "blocks": "19921920",
+            "id": "8e",
+            "system": "Linux LVM"
+          },
+          {
+            "device": "/dev/sda3",
+            "boot": null,
+            "start": "0",
+            "end": "-",
+            "cyls": "0",
+            "blocks": "0",
+            "id": "0",
+            "system": "Empty"
+          },
+          {
+            "device": "/dev/sda4",
+            "boot": null,
+            "start": "0",
+            "end": "-",
+            "cyls": "0",
+            "blocks": "0",
+            "id": "0",
+            "system": "Empty"
+          }
+        ]
+      },
+      {
+        "disk": "/dev/mapper/centos-root",
+        "cylinders": "2218",
+        "heads": "255",
+        "sectors_per_track": "63"
+      },
+      {
+        "disk": "/dev/mapper/centos-swap",
+        "cylinders": "261",
+        "heads": "255",
+        "sectors_per_track": "63"
+      }
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/shadow.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.shadow
 jc - JSON CLI output utility `/etc/shadow` file parser
@@ -8,12 +9,28 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('shadow', shadow_file_output)
+
+    or
+
     import jc.parsers.shadow
     result = jc.parsers.shadow.parse(shadow_file_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'aix', 'freebsd'
+    [
+      {
+        "username":       string,
+        "password":       string,
+        "last_changed":   integer,
+        "minimum":        integer,
+        "maximum":        integer,
+        "warn":           integer,
+        "inactive":       integer,
+        "expire":         integer
+      }
+    ]
 
 Examples:
 
@@ -92,36 +109,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "username":       string,
-        "password":       string,
-        "last_changed":   integer,
-        "minimum":        integer,
-        "maximum":        integer,
-        "warn":           integer,
-        "inactive":       integer,
-        "expire":         integer
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -133,10 +121,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, aix, freebsd
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ss.md

@@ -1,7 +1,11 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.ss
 jc - JSON CLI output utility `ss` command output parser
 
+Extended information options like -e and -p are not supported and may cause
+parsing irregularities.
+
 Usage (cli):
 
     $ ss | jc --ss
@@ -12,16 +16,38 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('ss', ss_command_output)
+
+    or
+
     import jc.parsers.ss
     result = jc.parsers.ss.parse(ss_command_output)
 
-Limitations:
+Schema:
 
-    Extended information options like -e and -p are not supported and may cause parsing irregularities
+    Information from https://www.cyberciti.biz/files/ss.html used to define
+    field names
 
-Compatibility:
-
-    'linux'
+    [
+      {
+        "netid":            string,
+        "state":            string,
+        "recv_q":           integer,
+        "send_q":           integer,
+        "local_address":    string,
+        "local_port":       string,
+        "local_port_num":   integer,
+        "peer_address":     string,
+        "peer_port":        string,
+        "peer_port_num":    integer,
+        "interface":        string,
+        "link_layer"        string,
+        "channel":          string,
+        "path":             string,
+        "pid":              integer
+      }
+    ]
 
 Examples:
 
@@ -262,45 +288,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "netid":            string,
-        "state":            string,
-        "recv_q":           integer,
-        "send_q":           integer,
-        "local_address":    string,
-        "local_port":       string,
-        "local_port_num":   integer,
-        "peer_address":     string,
-        "peer_port":        string,
-        "peer_port_num":    integer,
-        "interface":        string,
-        "link_layer"        string,
-        "channel":          string,
-        "path":             string,
-        "pid":              integer
-      }
-    ]
-
-    Information from https://www.cyberciti.biz/files/ss.html used to define field names
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -312,10 +300,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/stat.md

@@ -1,7 +1,14 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.stat
 jc - JSON CLI output utility `stat` command output parser
 
+The `xxx_epoch` calculated timestamp fields are naive. (i.e. based on the
+local time of the system the parser is run on)
+
+The `xxx_epoch_utc` calculated timestamp fields are timezone-aware and are
+only available if the timezone field is UTC.
+
 Usage (cli):
 
     $ stat * | jc --stat
@@ -12,12 +19,51 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('stat', stat_command_output)
+
+    or
+
     import jc.parsers.stat
     result = jc.parsers.stat.parse(stat_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'freebsd'
+    [
+      {
+        "file":                     string,
+        "link_to"                   string,
+        "size":                     integer,
+        "blocks":                   integer,
+        "io_blocks":                integer,
+        "type":                     string,
+        "device":                   string,
+        "inode":                    integer,
+        "links":                    integer,
+        "access":                   string,
+        "flags":                    string,
+        "uid":                      integer,
+        "user":                     string,
+        "gid":                      integer,
+        "group":                    string,
+        "access_time":              string,    # - = null
+        "access_time_epoch":        integer,   # naive timestamp
+        "access_time_epoch_utc":    integer,   # timezone-aware timestamp
+        "modify_time":              string,    # - = null
+        "modify_time_epoch":        integer,   # naive timestamp
+        "modify_time_epoch_utc":    integer,   # timezone-aware timestamp
+        "change_time":              string,    # - = null
+        "change_time_epoch":        integer,   # naive timestamp
+        "change_time_epoch_utc":    integer,   # timezone-aware timestamp
+        "birth_time":               string,    # - = null
+        "birth_time_epoch":         integer,   # naive timestamp
+        "birth_time_epoch_utc":     integer,   # timezone-aware timestamp
+        "unix_device":              integer,
+        "rdev":                     integer,
+        "block_size":               integer,
+        "unix_flags":               string
+      }
+    ]
 
 Examples:
 
@@ -41,7 +87,15 @@ Examples:
         "access_time": "2019-11-14 08:18:03.509681766 +0000",
         "modify_time": "2019-06-06 22:28:15.000000000 +0000",
         "change_time": "2019-08-12 17:21:29.521945390 +0000",
-        "birth_time": null
+        "birth_time": null,
+        "access_time_epoch": 1573748283,
+        "access_time_epoch_utc": 1573719483,
+        "modify_time_epoch": 1559885295,
+        "modify_time_epoch_utc": 1559860095,
+        "change_time_epoch": 1565655689,
+        "change_time_epoch_utc": 1565630489,
+        "birth_time_epoch": null,
+        "birth_time_epoch_utc": null
       },
       {
         "file": "/bin/btrfs",
@@ -61,7 +115,15 @@ Examples:
         "access_time": "2019-11-14 08:18:28.990834276 +0000",
         "modify_time": "2018-03-12 23:04:27.000000000 +0000",
         "change_time": "2019-08-12 17:21:29.545944399 +0000",
-        "birth_time": null
+        "birth_time": null,
+        "access_time_epoch": 1573748308,
+        "access_time_epoch_utc": 1573719508,
+        "modify_time_epoch": 1520921067,
+        "modify_time_epoch_utc": 1520895867,
+        "change_time_epoch": 1565655689,
+        "change_time_epoch_utc": 1565630489,
+        "birth_time_epoch": null,
+        "birth_time_epoch_utc": null
       },
       ...
     ]
@@ -108,7 +170,7 @@ Examples:
         "change_time": "2019-08-12 17:21:29.545944399 +0000",
         "birth_time": null
       },
-      ..
+      ...
     ]
 
 
@@ -116,51 +178,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "file":         string,
-        "link_to"       string,
-        "size":         integer,
-        "blocks":       integer,
-        "io_blocks":    integer,
-        "type":         string,
-        "device":       string,
-        "inode":        integer,
-        "links":        integer,
-        "access":       string,
-        "flags":        string,
-        "uid":          integer,
-        "user":         string,
-        "gid":          integer,
-        "group":        string,
-        "access_time":  string,    # - = null
-        "modify_time":  string,    # - = null
-        "change_time":  string,    # - = null
-        "birth_time":   string,    # - = null
-        "unix_device":  integer,
-        "rdev":         integer,
-        "block_size":   integer,
-        "unix_flags":   string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -172,10 +190,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.10 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/stat_s.md

@@ -0,0 +1,121 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.stat_s
+jc - JSON CLI output utility `stat` command output streaming parser
+
+> This streaming parser outputs JSON Lines
+
+The `xxx_epoch` calculated timestamp fields are naive. (i.e. based on the
+local time of the system the parser is run on).
+
+The `xxx_epoch_utc` calculated timestamp fields are timezone-aware and are
+only available if the timezone field is UTC.
+
+Usage (cli):
+
+    $ stat * | jc --stat-s
+
+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:
+
+    {
+      "file":                     string,
+      "link_to"                   string,
+      "size":                     integer,
+      "blocks":                   integer,
+      "io_blocks":                integer,
+      "type":                     string,
+      "device":                   string,
+      "inode":                    integer,
+      "links":                    integer,
+      "access":                   string,
+      "flags":                    string,
+      "uid":                      integer,
+      "user":                     string,
+      "gid":                      integer,
+      "group":                    string,
+      "access_time":              string,    # - = null
+      "access_time_epoch":        integer,   # naive timestamp
+      "access_time_epoch_utc":    integer,   # timezone-aware timestamp
+      "modify_time":              string,    # - = null
+      "modify_time_epoch":        integer,   # naive timestamp
+      "modify_time_epoch_utc":    integer,   # timezone-aware timestamp
+      "change_time":              string,    # - = null
+      "change_time_epoch":        integer,   # naive timestamp
+      "change_time_epoch_utc":    integer,   # timezone-aware timestamp
+      "birth_time":               string,    # - = null
+      "birth_time_epoch":         integer,   # naive timestamp
+      "birth_time_epoch_utc":     integer,   # timezone-aware timestamp
+      "unix_device":              integer,
+      "rdev":                     integer,
+      "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
+        }
+    }
+
+Examples:
+
+    $ stat | jc --stat-s
+    {"file":"(stdin)","unix_device":1027739696,"inode":1155,"flags":"cr...}
+
+    $ stat | jc --stat-s -r
+    {"file":"(stdin)","unix_device":"1027739696","inode":"1155","flag...}
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False, ignore_exceptions=False)
+```
+
+Main text parsing generator function. Returns an iterator object.
+
+Parameters:
+
+    data:              (iterable)  line-based text data to parse
+                                   (e.g. sys.stdin or str.splitlines())
+
+    raw:               (boolean)   unprocessed output if True
+    quiet:             (boolean)   suppress warning messages if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+
+Yields:
+
+    Dictionary. Raw or processed structured data.
+
+Returns:
+
+    Iterator object
+
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 0.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/sysctl.md

@@ -1,8 +1,12 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.sysctl
 jc - JSON CLI output utility `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):
 
@@ -14,12 +18,21 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('sysctl', sysctl_command_output)
+
+    or
+
     import jc.parsers.sysctl
     result = jc.parsers.sysctl.parse(sysctl_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'freebsd'
+    {
+      "key1":     string/integer/float,     # best guess based on value
+      "key2":     string/integer/float,
+      "key3":     string/integer/float
+    }
 
 Examples:
 
@@ -52,29 +65,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "foo":     string/integer/float,         # best guess based on value
-      "bar":     string/integer/float,
-      "baz":     string/integer/float
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -86,10 +77,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.2 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/systemctl.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.systemctl
 jc - JSON CLI output utility `systemctl` command output parser
@@ -12,12 +13,25 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('systemctl', systemctl_command_output)
+
+    or
+
     import jc.parsers.systemctl
     result = jc.parsers.systemctl.parse(systemctl_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "unit":          string,
+        "load":          string,
+        "active":        string,
+        "sub":           string,
+        "description":   string
+      }
+    ]
 
 Examples:
 
@@ -28,14 +42,14 @@ Examples:
         "load": "loaded",
         "active": "active",
         "sub": "waiting",
-        "description": "Arbitrary Executable File Formats File System Automount Point"
+        "description": "Arbitrary Executable File Formats File System ..."
       },
       {
         "unit": "dev-block-8:2.device",
         "load": "loaded",
         "active": "active",
         "sub": "plugged",
-        "description": "LVM PV 3klkIj-w1qk-DkJi-0XBJ-y3o7-i2Ac-vHqWBM on /dev/sda2 2"
+        "description": "LVM PV 3klkIj-w1qk-DkJi-0XBJ-y3o7-i2Ac-vHqWBM o..."
       },
       {
         "unit": "dev-cdrom.device",
@@ -52,33 +66,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "unit":          string,
-        "load":          string,
-        "active":        string,
-        "sub":           string,
-        "description":   string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -90,10 +78,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/systemctl_lj.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.systemctl_lj
 jc - JSON CLI output utility `systemctl list-jobs` command output parser
@@ -12,12 +13,24 @@ Usage (cli):
 
 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)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "job":      integer,
+        "unit":     string,
+        "type":     string,
+        "state":    string
+      }
+    ]
 
 Examples:
 
@@ -66,37 +79,11 @@ Examples:
     ]
 
 
-
 ## info
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "job":      integer,
-        "unit":     string,
-        "type":     string,
-        "state":    string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -108,10 +95,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/systemctl_ls.md

@@ -1,6 +1,8 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.systemctl_ls
-jc - JSON CLI output utility `systemctl list-sockets` command output parser
+jc - JSON CLI output utility `systemctl list-sockets` command output
+parser
 
 Usage (cli):
 
@@ -12,12 +14,23 @@ Usage (cli):
 
 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)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "listen":       string,
+        "unit":         string,
+        "activates":    string
+      }
+    ]
 
 Examples:
 
@@ -46,31 +59,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "listen":       string,
-        "unit":         string,
-        "activates":    string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -82,10 +71,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/systemctl_luf.md

@@ -1,6 +1,8 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.systemctl_luf
-jc - JSON CLI output utility `systemctl list-unit-files` command output parser
+jc - JSON CLI output utility `systemctl list-unit-files` command output
+parser
 
 Usage (cli):
 
@@ -12,12 +14,22 @@ Usage (cli):
 
 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)
 
-Compatibility:
+Schema:
 
-    'linux'
+    [
+      {
+        "unit_file":   string,
+        "state":       string
+      }
+    ]
 
 Examples:
 
@@ -43,30 +55,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "unit_file":   string,
-        "state":       string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -78,10 +67,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/systeminfo.md

@@ -0,0 +1,244 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.systeminfo
+jc - JSON CLI output utility `systeminfo` command output parser
+
+Blank or missing elements are set to `null`.
+
+The `original_install_date_epoch` and `system_boot_time_epoch` calculated
+timestamp fields are naive. (i.e. based on the local time of the system the
+parser is run on)
+
+The `original_install_date_epoch_utc` and `system_boot_time_epoch_utc`
+calculated timestamp fields are timezone-aware and are only available if
+the timezone field is UTC.
+
+Usage (cli):
+
+    $ systeminfo | jc --systeminfo
+
+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:
+
+    {
+      "host_name":                                  string,
+      "os_name":                                    string,
+      "os_version":                                 string,
+      "os_manufacturer":                            string,
+      "os_configuration":                           string,
+      "os_build_type":                              string,
+      "registered_owner":                           string,
+      "registered_organization":                    string,
+      "product_id":                                 string,
+      "original_install_date":                      string,
+      "original_install_date_epoch":                integer,     # [0]
+      "original_install_date_epoch_utc":            integer,     # [1]
+      "system_boot_time":                           string,
+      "system_boot_time_epoch":                     integer,     # [0]
+      "system_boot_time_epoch_utc":                 integer,     # [1]
+      "system_manufacturer":                        string,
+      "system_model":                               string,
+      "system_type":                                string,
+      "processors": [
+                                                    string
+      ],
+      "bios_version":                               string,
+      "windows_directory":                          string,
+      "system_directory":                           string,
+      "boot_device":                                string,
+      "system_locale":                              string,
+      "input_locale":                               string,
+      "time_zone":                                  string,
+      "total_physical_memory_mb":                   string,
+      "available_physical_memory_mb":               integer,
+      "virtual_memory_max_size_mb":                 integer,
+      "virtual_memory_available_mb":                integer,
+      "virtual_memory_in_use_mb":                   integer,
+      "page_file_locations":                        string,
+      "domain":                                     string,
+      "logon_server":                               string,
+      "hotfixs": [
+                                                    string
+      ],
+      "network_cards": [
+        {
+          "name":                                   string,
+          "connection_name":                        string,
+          "status":                                 string,
+          "dhcp_enabled":                           boolean,
+          "dhcp_server":                            string,
+          "ip_addresses": [
+                                                    string
+          ]
+        }
+      ],
+      "hyperv_requirements": {
+        "vm_monitor_mode_extensions":               boolean,
+        "virtualization_enabled_in_firmware":       boolean,
+        "second_level_address_translation":         boolean,
+        "data_execution_prevention_available":      boolean
+      }
+    }
+
+    [0] naive timestamp
+    [1] timezone-aware timestamp
+
+Examples:
+
+    $ systeminfo | jc --systeminfo -p
+    {
+      "host_name": "TESTLAPTOP",
+      "os_name": "Microsoft Windows 10 Enterprise",
+      "os_version": "10.0.17134 N/A Build 17134",
+      "os_manufacturer": "Microsoft Corporation",
+      "os_configuration": "Member Workstation",
+      "os_build_type": "Multiprocessor Free",
+      "registered_owner": "Test, Inc.",
+      "registered_organization": "Test, Inc.",
+      "product_id": "11111-11111-11111-AA111",
+      "original_install_date": "3/26/2019, 3:51:30 PM",
+      "system_boot_time": "3/30/2021, 6:13:59 AM",
+      "system_manufacturer": "Dell Inc.",
+      "system_model": "Precision 5530",
+      "system_type": "x64-based PC",
+      "processors": [
+        "Intel64 Family 6 Model 158 Stepping 10 GenuineIntel ~2592 Mhz"
+      ],
+      "bios_version": "Dell Inc. 1.16.2, 4/21/2020",
+      "windows_directory": "C:\WINDOWS",
+      "system_directory": "C:\WINDOWS\system32",
+      "boot_device": "\Device\HarddiskVolume2",
+      "system_locale": "en-us;English (United States)",
+      "input_locale": "en-us;English (United States)",
+      "time_zone": "(UTC+00:00) UTC",
+      "total_physical_memory_mb": 32503,
+      "available_physical_memory_mb": 19743,
+      "virtual_memory_max_size_mb": 37367,
+      "virtual_memory_available_mb": 22266,
+      "virtual_memory_in_use_mb": 15101,
+      "page_file_locations": "C:\pagefile.sys",
+      "domain": "test.com",
+      "logon_server": "\\TESTDC01",
+      "hotfixs": [
+        "KB2693643",
+        "KB4601054"
+      ],
+      "network_cards": [
+        {
+          "name": "Intel(R) Wireless-AC 9260 160MHz",
+          "connection_name": "Wi-Fi",
+          "status": null,
+          "dhcp_enabled": true,
+          "dhcp_server": "192.168.2.1",
+          "ip_addresses": [
+            "192.168.2.219"
+          ]
+        }
+      ],
+      "hyperv_requirements": {
+        "vm_monitor_mode_extensions": true,
+        "virtualization_enabled_in_firmware": true,
+        "second_level_address_translation": false,
+        "data_execution_prevention_available": true
+      },
+      "original_install_date_epoch": 1553640690,
+      "original_install_date_epoch_utc": 1553615490,
+      "system_boot_time_epoch": 1617110039,
+      "system_boot_time_epoch_utc": 1617084839
+    }
+
+    $ systeminfo | jc --systeminfo -p -r
+    {
+      "host_name": "TESTLAPTOP",
+      "os_name": "Microsoft Windows 10 Enterprise",
+      "os_version": "10.0.17134 N/A Build 17134",
+      "os_manufacturer": "Microsoft Corporation",
+      "os_configuration": "Member Workstation",
+      "os_build_type": "Multiprocessor Free",
+      "registered_owner": "Test, Inc.",
+      "registered_organization": "Test, Inc.",
+      "product_id": "11111-11111-11111-AA111",
+      "original_install_date": "3/26/2019, 3:51:30 PM",
+      "system_boot_time": "3/30/2021, 6:13:59 AM",
+      "system_manufacturer": "Dell Inc.",
+      "system_model": "Precision 5530",
+      "system_type": "x64-based PC",
+      "processors": [
+        "Intel64 Family 6 Model 158 Stepping 10 GenuineIntel ~2592 Mhz"
+      ],
+      "bios_version": "Dell Inc. 1.16.2, 4/21/2020",
+      "windows_directory": "C:\WINDOWS",
+      "system_directory": "C:\WINDOWS\system32",
+      "boot_device": "\Device\HarddiskVolume2",
+      "system_locale": "en-us;English (United States)",
+      "input_locale": "en-us;English (United States)",
+      "time_zone": "(UTC+00:00) UTC",
+      "total_physical_memory_mb": "32,503 MB",
+      "available_physical_memory_mb": "19,743 MB",
+      "virtual_memory_max_size_mb": "37,367 MB",
+      "virtual_memory_available_mb": "22,266 MB",
+      "virtual_memory_in_use_mb": "15,101 MB",
+      "page_file_locations": "C:\pagefile.sys",
+      "domain": "test.com",
+      "logon_server": "\\TESTDC01",
+      "hotfixs": [
+        "KB2693643",
+        "KB4601054"
+      ],
+      "network_cards": [
+        {
+          "name": "Intel(R) Wireless-AC 9260 160MHz",
+          "connection_name": "Wi-Fi",
+          "status": "",
+          "dhcp_enabled": "Yes",
+          "dhcp_server": "192.168.2.1",
+          "ip_addresses": [
+            "192.168.2.219"
+          ]
+        }
+      ],
+      "hyperv_requirements": {
+        "vm_monitor_mode_extensions": "Yes",
+        "virtualization_enabled_in_firmware": "Yes",
+        "second_level_address_translation": "No",
+        "data_execution_prevention_available": "Yes"
+      }
+    }
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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:  win32
+
+Version 1.1 by Jon Smith (jon@rebelliondefense.com)

docs/parsers/time.md

@@ -0,0 +1,165 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.time
+jc - JSON CLI output utility `/usr/bin/time` command output parser
+
+Output from `/usr/bin/time` is sent to `STDERR`, so the `-o` option can be
+used to redirect the output to a file that can be read by `jc`.
+
+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.
+
+Usage (cli):
+
+    $ /usr/bin/time -o timefile.out sleep 2; cat timefile.out | \
+      jc --time -p
+
+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
+
+    {
+      "real_time":                          float,
+      "user_time":                          float,
+      "system_time":                        float,
+      "elapsed_time":                       string,
+      "elapsed_time_hours":                 integer,
+      "elapsed_time_minutes":               integer,
+      "elapsed_time_seconds":               integer,
+      "elapsed_time_centiseconds":          integer,
+      "elapsed_time_total_seconds":         float,
+      "cpu_percent":                        integer,   # null if ?
+      "average_shared_text_size":           integer,
+      "average_unshared_data_size":         integer,
+      "average_unshared_stack_size":        integer,
+      "average_shared_memory_size":         integer,
+      "maximum_resident_set_size":          integer,
+      "block_input_operations":             integer,   # [0]
+      "block_output_operations":            integer,   # [1]
+      "major_pagefaults":                   integer,
+      "minor_pagefaults":                   integer,
+      "swaps":                              integer,
+      "page_reclaims":                      integer,
+      "page_faults":                        integer,
+      "messages_sent":                      integer,
+      "messages_received":                  integer,
+      "signals_received":                   integer,
+      "voluntary_context_switches":         integer,
+      "involuntary_context_switches":       integer
+      "command_being_timed":                string,
+      "average_stack_size":                 integer,
+      "average_total_size":                 integer,
+      "average_resident_set_size":          integer,
+      "signals_delivered":                  integer,
+      "page_size":                          integer,
+      "exit_status":                        integer
+    }
+
+    [0] aka File system inputs
+    [1] aka File system outputs
+
+Examples:
+
+    $ /usr/bin/time --verbose -o timefile.out sleep 2; cat timefile.out | \
+      jc --time -p
+    {
+      "command_being_timed": "sleep 2",
+      "user_time": 0.0,
+      "system_time": 0.0,
+      "cpu_percent": 0,
+      "elapsed_time": "0:02.00",
+      "average_shared_text_size": 0,
+      "average_unshared_data_size": 0,
+      "average_stack_size": 0,
+      "average_total_size": 0,
+      "maximum_resident_set_size": 2084,
+      "average_resident_set_size": 0,
+      "major_pagefaults": 0,
+      "minor_pagefaults": 72,
+      "voluntary_context_switches": 2,
+      "involuntary_context_switches": 1,
+      "swaps": 0,
+      "block_input_operations": 0,
+      "block_output_operations": 0,
+      "messages_sent": 0,
+      "messages_received": 0,
+      "signals_delivered": 0,
+      "page_size": 4096,
+      "exit_status": 0,
+      "elapsed_time_hours": 0,
+      "elapsed_time_minutes": 0,
+      "elapsed_time_seconds": 2,
+      "elapsed_time_centiseconds": 50,
+      "elapsed_time_total_seconds": 2.5
+    }
+
+    $ /usr/bin/time --verbose -o timefile.out sleep 2; cat timefile.out | \
+      jc --time -p -r
+    {
+      "command_being_timed": ""sleep 2"",
+      "user_time": "0.00",
+      "system_time": "0.00",
+      "cpu_percent": "0",
+      "elapsed_time": "0:02.00",
+      "average_shared_text_size": "0",
+      "average_unshared_data_size": "0",
+      "average_stack_size": "0",
+      "average_total_size": "0",
+      "maximum_resident_set_size": "2084",
+      "average_resident_set_size": "0",
+      "major_pagefaults": "0",
+      "minor_pagefaults": "72",
+      "voluntary_context_switches": "2",
+      "involuntary_context_switches": "0",
+      "swaps": "0",
+      "block_input_operations": "0",
+      "block_output_operations": "0",
+      "messages_sent": "0",
+      "messages_received": "0",
+      "signals_delivered": "0",
+      "page_size": "4096",
+      "exit_status": "0"
+    }
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+Main text parsing function
+
+Parameters:
+
+    data:        (string)  text data to parse
+    raw:         (boolean) unprocessed output if True
+    quiet:       (boolean) suppress warning messages if True
+
+Returns:
+
+    Dictionary. Raw or processed structured data.
+
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/timedatectl.md

@@ -1,7 +1,11 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.timedatectl
 jc - JSON CLI output utility `timedatectl` command output parser
 
+The `epoch_utc` calculated timestamp field is timezone-aware and is only
+available if the `universal_time` field is available.
+
 Usage (cli):
 
     $ timedatectl | jc --timedatectl
@@ -12,12 +16,29 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('timedatectl', timedatectl_command_output)
+
+    or
+
     import jc.parsers.timedatectl
     result = jc.parsers.timedatectl.parse(timedatectl_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    {
+      "local_time":                        string,
+      "universal_time":                    string,
+      "epoch_utc":                         integer,     # timezone-aware
+      "rtc_time":                          string,
+      "time_zone":                         string,
+      "ntp_enabled":                       boolean,
+      "ntp_synchronized":                  boolean,
+      "system_clock_synchronized":         boolean,
+      "systemd-timesyncd.service_active":  boolean,
+      "rtc_in_local_tz":                   boolean,
+      "dst_active":                        boolean
+    }
 
 Examples:
 
@@ -30,7 +51,8 @@ Examples:
       "ntp_enabled": true,
       "ntp_synchronized": true,
       "rtc_in_local_tz": false,
-      "dst_active": true
+      "dst_active": true,
+      "epoch_utc": 1583888001
     }
 
     $ timedatectl | jc --timedatectl -p -r
@@ -50,36 +72,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "local_time":                        string,
-      "universal_time":                    string,
-      "rtc_time":                          string,
-      "time_zone":                         string,
-      "ntp_enabled":                       boolean,
-      "ntp_synchronized":                  boolean,
-      "system_clock_synchronized":         boolean,
-      "systemd-timesyncd.service_active":  boolean,
-      "rtc_in_local_tz":                   boolean,
-      "dst_active":                        boolean
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -91,10 +84,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    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.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/tracepath.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.tracepath
 jc - JSON CLI output utility `tracepath` command output parser
@@ -14,12 +15,32 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('tracepath', tracepath_command_output)
+
+    or
+
     import jc.parsers.tracepath
     result = jc.parsers.tracepath.parse(tracepath_command_output)
 
-Compatibility:
+Schema:
 
-    'linux'
+    {
+      "pmtu":                       integer,
+      "forward_hops":               integer,
+      "return_hops":                integer,
+      "hops": [
+        {
+          "ttl":                    integer,
+          "guess":                  boolean,
+          "host":                   string,
+          "reply_ms":               float,
+          "pmtu":                   integer,
+          "asymmetric_difference":  integer,
+          "reached":                boolean
+        }
+      ]
+    }
 
 Examples:
 
@@ -114,45 +135,11 @@ Examples:
     }
 
 
-
 ## info
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "pmtu":                       integer,
-      "forward_hops":               integer,
-      "return_hops":                integer,
-      "hops": [
-        {
-          "ttl":                    integer,
-          "guess":                  boolean,
-          "host":                   string,
-          "reply_ms":               float,
-          "pmtu":                   integer,
-          "asymmetric_difference":  integer,
-          "reached":                boolean
-        }
-      ]
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -164,10 +151,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    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.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/traceroute.md

@@ -1,12 +1,16 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.traceroute
 jc - JSON CLI output utility `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.
+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`
+      e.g. `$ traceroute 8.8.8.8 2>&1 | jc --traceroute`
 
 Usage (cli):
 
@@ -18,12 +22,34 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('traceroute', traceroute_command_output)
+
+    or
+
     import jc.parsers.traceroute
     result = jc.parsers.traceroute.parse(traceroute_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'freebsd'
+    {
+      "destination_ip":         string,
+      "destination_name":       string,
+      "hops": [
+        {
+          "hop":                integer,
+          "probes": [
+            {
+              "annotation":     string,
+              "asn":            integer,
+              "ip":             string,
+              "name":           string,
+              "rtt":            float
+            }
+          ]
+        }
+      ]
+    }
 
 Examples:
 
@@ -102,48 +128,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## Hop
-```python
-Hop(idx)
-```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "destination_ip":         string,
-      "destination_name":       string,
-      "hops": [
-        {
-          "hop":                integer,
-          "probes": [
-            {
-              "annotation":     string,
-              "asn":            integer,
-              "ip":             string,
-              "name":           string,
-              "rtt":            float
-            }
-          ]
-        }
-      ]
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -155,10 +140,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.4 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ufw.md

@@ -0,0 +1,233 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.ufw
+jc - JSON CLI output utility `ufw status` command output parser
+
+Usage (cli):
+
+    $ ufw status | jc --ufw
+
+    or
+
+    $ jc ufw status
+
+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:
+
+    {
+      "status":                     string,
+      "logging":                    string,
+      "logging_level":              string,
+      "default":                    string,
+      "new_profiles":               string,
+      "rules": [
+        {
+          "action":                 string,
+          "action_direction":       string,     # null if blank
+          "index":                  integer,    # null if blank
+          "network_protocol":       string,
+          "to_ip":                  string,
+          "to_ip_prefix":           integer,
+          "to_interface":           string,
+          "to_transport":           string,
+          "to_ports": [
+                                    integer
+          ],
+          "to_port_ranges": [
+            {
+              "start":              integer,
+              "end":                integer
+            }
+          ],
+          "to_service":             string,     # [0]
+          "from_ip":                string,
+          "from_ip_prefix":         integer,
+          "from_interface":         string,
+          "from_transport":         string,
+          "from_ports": [
+                                    integer
+          ],
+          "from_port_ranges": [
+            {
+              "start":              integer,
+              "end":                integer
+            }
+          ],
+          "from_service":           string,     # [1]
+          "comment":                string      # null if no comment
+        }
+      ]
+    }
+
+    [0] null if any 'to' ports or port_ranges are set
+    [1] null if any 'from' ports or port_ranges are set
+
+Examples:
+
+    $ ufw status verbose | jc --ufw -p
+    {
+      "status": "active",
+      "logging": "on",
+      "logging_level": "low",
+      "default": "deny (incoming), allow (outgoing), disabled (routed)",
+      "new_profiles": "skip",
+      "rules": [
+        {
+          "action": "ALLOW",
+          "action_direction": "IN",
+          "index": null,
+          "network_protocol": "ipv4",
+          "to_interface": "any",
+          "to_transport": "any",
+          "to_service": null,
+          "to_ports": [
+            22
+          ],
+          "to_ip": "0.0.0.0",
+          "to_ip_prefix": 0,
+          "comment": null,
+          "from_ip": "0.0.0.0",
+          "from_ip_prefix": 0,
+          "from_interface": "any",
+          "from_transport": "any",
+          "from_port_ranges": [
+            {
+              "start": 0,
+              "end": 65535
+            }
+          ],
+          "from_service": null
+        },
+        {
+          "action": "ALLOW",
+          "action_direction": "IN",
+          "index": null,
+          "network_protocol": "ipv4",
+          "to_interface": "any",
+          "to_transport": "tcp",
+          "to_service": null,
+          "to_ports": [
+            80,
+            443
+          ],
+          "to_ip": "0.0.0.0",
+          "to_ip_prefix": 0,
+          "comment": null,
+          "from_ip": "0.0.0.0",
+          "from_ip_prefix": 0,
+          "from_interface": "any",
+          "from_transport": "any",
+          "from_port_ranges": [
+            {
+              "start": 0,
+              "end": 65535
+            }
+          ],
+          "from_service": null
+        },
+        ...
+      ]
+    }
+
+    $ ufw status verbose | jc --ufw -p -r
+    {
+      "status": "active",
+      "logging": "on",
+      "logging_level": "low",
+      "default": "deny (incoming), allow (outgoing), disabled (routed)",
+      "new_profiles": "skip",
+      "rules": [
+        {
+          "action": "ALLOW",
+          "action_direction": "IN",
+          "index": null,
+          "network_protocol": "ipv4",
+          "to_interface": "any",
+          "to_transport": "any",
+          "to_service": null,
+          "to_ports": [
+            "22"
+          ],
+          "to_ip": "0.0.0.0",
+          "to_ip_prefix": "0",
+          "comment": null,
+          "from_ip": "0.0.0.0",
+          "from_ip_prefix": "0",
+          "from_interface": "any",
+          "from_transport": "any",
+          "from_port_ranges": [
+            {
+              "start": "0",
+              "end": "65535"
+            }
+          ],
+          "from_service": null
+        },
+        {
+          "action": "ALLOW",
+          "action_direction": "IN",
+          "index": null,
+          "network_protocol": "ipv4",
+          "to_interface": "any",
+          "to_transport": "tcp",
+          "to_service": null,
+          "to_ports": [
+            "80",
+            "443"
+          ],
+          "to_ip": "0.0.0.0",
+          "to_ip_prefix": "0",
+          "comment": null,
+          "from_ip": "0.0.0.0",
+          "from_ip_prefix": "0",
+          "from_interface": "any",
+          "from_transport": "any",
+          "from_port_ranges": [
+            {
+              "start": "0",
+              "end": "65535"
+            }
+          ],
+          "from_service": null
+        },
+        ...
+      ]
+    }
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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/ufw_appinfo.md

@@ -0,0 +1,171 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.ufw_appinfo
+jc - JSON CLI output utility `ufw app info [application]` command
+output parser
+
+Supports individual apps via `ufw app info [application]` and all apps list
+via `ufw app info all`.
+
+Because `ufw` application definitions allow overlapping ports and port
+ranges, this parser preserves that behavior, but also provides `normalized`
+lists and ranges that remove duplicate ports and merge overlapping ranges.
+
+Usage (cli):
+
+    $ ufw app info OpenSSH | jc --ufw-appinfo
+
+    or
+
+    $ jc ufw app info OpenSSH
+
+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:
+
+    [
+      {
+        "profile":                  string,
+        "title":                    string,
+        "description":              string,
+        "tcp_list": [
+                                    integer
+        ],
+        "tcp_ranges": [
+          {
+            "start":                integer,      # [0]
+            "end":                  integer
+          }
+        ],
+        "udp_list": [
+                                    integer
+        ],
+        "udp_ranges": [
+          {
+            "start":                integer,      # [0]
+            "end":                  integer
+          }
+        ],
+        "normalized_tcp_list": [
+                                    integers      # [1]
+        ],
+        "normalized_tcp_ranges": [
+          {
+            "start":                integer,      # [0]
+            "end":                  integers      # [2]
+          }
+        ],
+        "normalized_udp_list": [
+                                    integers      # [1]
+        ],
+        "normalized_udp_ranges": [
+          {
+            "start":                integer,      # [0]
+            "end":                  integers      # [2]
+          }
+        ]
+      }
+    ]
+
+    [0] 'any' is converted to start/end: 0/65535
+    [1] duplicates and overlapping are removed
+    [2] overlapping are merged
+
+Examples:
+
+    $ ufw app info MSN | jc --ufw-appinfo -p
+    [
+      {
+        "profile": "MSN",
+        "title": "MSN Chat",
+        "description": "MSN chat protocol (with file transfer and voice)",
+        "tcp_list": [
+          1863,
+          6901
+        ],
+        "udp_list": [
+          1863,
+          6901
+        ],
+        "tcp_ranges": [
+          {
+            "start": 6891,
+            "end": 6900
+          }
+        ],
+        "normalized_tcp_list": [
+          1863,
+          6901
+        ],
+        "normalized_tcp_ranges": [
+          {
+            "start": 6891,
+            "end": 6900
+          }
+        ],
+        "normalized_udp_list": [
+          1863,
+          6901
+        ]
+      }
+    ]
+
+    $ ufw app info MSN | jc --ufw-appinfo -p -r
+    [
+      {
+        "profile": "MSN",
+        "title": "MSN Chat",
+        "description": "MSN chat protocol (with file transfer and voice)",
+        "tcp_list": [
+          "1863",
+          "6901"
+        ],
+        "udp_list": [
+          "1863",
+          "6901"
+        ],
+        "tcp_ranges": [
+          {
+            "start": "6891",
+            "end": "6900"
+          }
+        ]
+      }
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/uname.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.uname
 jc - JSON CLI output utility `uname -a` command output parser
@@ -14,12 +15,26 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('uname', uname_command_output)
+
+    or
+
     import jc.parsers.uname
     result = jc.parsers.uname.parse(uname_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'freebsd'
+    {
+        "kernel_name":        string,
+        "node_name":          string,
+        "kernel_release":     string,
+        "operating_system":   string,
+        "hardware_platform":  string,
+        "processor":          string,
+        "machine":            string,
+        "kernel_version":     string
+    }
 
 Example:
 
@@ -40,34 +55,7 @@ Example:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-        "kernel_name":        string,
-        "node_name":          string,
-        "kernel_release":     string,
-        "operating_system":   string,
-        "hardware_platform":  string,
-        "processor":          string,
-        "machine":            string,
-        "kernel_version":     string
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -79,10 +67,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, freebsd
+
+Version 1.7 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/universal.md

@@ -0,0 +1,57 @@
+
+# jc.parsers.universal
+jc - JSON CLI output utility universal Parsers
+
+## simple_table_parse
+```python
+simple_table_parse(data)
+```
+
+Parse simple tables. The last column may contain data with spaces.
+
+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().
+
+                     Also, ensure there are no blank lines (list items)
+                     in the data.
+
+Returns:
+
+    List of Dictionaries
+
+
+## sparse_table_parse
+```python
+sparse_table_parse(data, delim='\u2063')
+```
+
+Parse tables with missing column data or with spaces in column data.
+
+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.
+
+                     Also, ensure there are no blank lines (list items)
+                     in the data.
+
+    delim:  (string) Delimiter to use. By default `u\2063`
+                     (invisible separator) is used since it is unlikely
+                     to ever be seen in terminal output. You can change
+                     this for troubleshooting purposes or if there is a
+                     delimiter conflict with your data.
+
+Returns:
+
+    List of Dictionaries
+

docs/parsers/upower.md

@@ -0,0 +1,231 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.upower
+jc - JSON CLI output utility `upower` command output parser
+
+The `updated_epoch` calculated timestamp field is naive. (i.e. based on the
+local time of the system the parser is run on)
+
+The `updated_epoch_utc` calculated timestamp field is timezone-aware and is
+only available if the timezone field is UTC.
+
+Usage (cli):
+
+    $ upower -d | jc --upower
+
+    or
+
+    $ jc upower -d
+
+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:
+
+    [
+      {
+        "type":                         string,
+        "device_name":                  string,
+        "native_path":                  string,
+        "power_supply":                 boolean,
+        "updated":                      string,
+        "updated_epoch":                integer,       # [0]
+        "updated_epoch_utc":            integer,       # [0]
+        "updated_seconds_ago":          integer,
+        "has_history":                  boolean,
+        "has_statistics":               boolean,
+        "detail": {
+          "type":                       string,
+          "warning_level":              string,        # null if none
+          "online":                     boolean,
+          "icon_name":                  string
+          "present":                    boolean,
+          "rechargeable":               boolean,
+          "state":                      string,
+          "energy":                     float,
+          "energy_unit":                string,
+          "energy_empty":               float,
+          "energy_empty_unit":          string,
+          "energy_full":                float,
+          "energy_full_unit":           string,
+          "energy_full_design":         float,
+          "energy_full_design_unit":    string,
+          "energy_rate":                float,
+          "energy_rate_unit":           string,
+          "voltage":                    float,
+          "voltage_unit":               string,
+          "time_to_full":               float,
+          "time_to_full_unit":          string,
+          "percentage":                 float,
+          "capacity":                   float,
+          "technology":                 string
+        },
+        "history_charge": [
+          {
+            "time":                     integer,
+            "percent_charged":          float,
+            "status":                   string
+          }
+        ],
+        "history_rate":[
+          {
+            "time":                     integer,
+            "percent_charged":          float,
+            "status":                   string
+          }
+        ],
+        "daemon_version":               string,
+        "on_battery":                   boolean,
+        "lid_is_closed":                boolean,
+        "lid_is_present":               boolean,
+        "critical_action":              string
+      }
+    ]
+
+    [0] null if date-time conversion fails
+
+Examples:
+
+    $ upower -i /org/freedesktop/UPower/devices/battery | jc --upower -p
+    [
+      {
+        "native_path": "/sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/p...",
+        "vendor": "NOTEBOOK",
+        "model": "BAT",
+        "serial": "0001",
+        "power_supply": true,
+        "updated": "Thu 11 Mar 2021 06:28:08 PM UTC",
+        "has_history": true,
+        "has_statistics": true,
+        "detail": {
+          "type": "battery",
+          "present": true,
+          "rechargeable": true,
+          "state": "charging",
+          "energy": 22.3998,
+          "energy_empty": 0.0,
+          "energy_full": 52.6473,
+          "energy_full_design": 62.16,
+          "energy_rate": 31.6905,
+          "voltage": 12.191,
+          "time_to_full": 57.3,
+          "percentage": 42.5469,
+          "capacity": 84.6964,
+          "technology": "lithium-ion",
+          "energy_unit": "Wh",
+          "energy_empty_unit": "Wh",
+          "energy_full_unit": "Wh",
+          "energy_full_design_unit": "Wh",
+          "energy_rate_unit": "W",
+          "voltage_unit": "V",
+          "time_to_full_unit": "minutes"
+        },
+        "history_charge": [
+          {
+            "time": 1328809335,
+            "percent_charged": 42.547,
+            "status": "charging"
+          },
+          {
+            "time": 1328809305,
+            "percent_charged": 42.02,
+            "status": "charging"
+          }
+        ],
+        "history_rate": [
+          {
+            "time": 1328809335,
+            "percent_charged": 31.691,
+            "status": "charging"
+          }
+        ],
+        "updated_seconds_ago": 441975,
+        "updated_epoch": 1615516088,
+        "updated_epoch_utc": 1615487288
+      }
+    ]
+
+    $ upower -i /org/freedesktop/UPower/devices/battery | jc --upower -p -r
+    [
+      {
+        "native_path": "/sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/p...",
+        "vendor": "NOTEBOOK",
+        "model": "BAT",
+        "serial": "0001",
+        "power_supply": "yes",
+        "updated": "Thu 11 Mar 2021 06:28:08 PM UTC (441975 seconds ago)",
+        "has_history": "yes",
+        "has_statistics": "yes",
+        "detail": {
+          "type": "battery",
+          "present": "yes",
+          "rechargeable": "yes",
+          "state": "charging",
+          "energy": "22.3998 Wh",
+          "energy_empty": "0 Wh",
+          "energy_full": "52.6473 Wh",
+          "energy_full_design": "62.16 Wh",
+          "energy_rate": "31.6905 W",
+          "voltage": "12.191 V",
+          "time_to_full": "57.3 minutes",
+          "percentage": "42.5469%",
+          "capacity": "84.6964%",
+          "technology": "lithium-ion"
+        },
+        "history_charge": [
+          {
+            "time": "1328809335",
+            "percent_charged": "42.547",
+            "status": "charging"
+          },
+          {
+            "time": "1328809305",
+            "percent_charged": "42.020",
+            "status": "charging"
+          }
+        ],
+        "history_rate": [
+          {
+            "time": "1328809335",
+            "percent_charged": "31.691",
+            "status": "charging"
+          }
+        ]
+      }
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/uptime.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.uptime
 jc - JSON CLI output utility `uptime` command output parser
@@ -12,33 +13,59 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('uptime', uptime_command_output)
+
+    or
+
     import jc.parsers.uptime
     result = jc.parsers.uptime.parse(uptime_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    {
+      "time":                   string,
+      "time_hour":              integer,
+      "time_minute":            integer,
+      "time_second":            integer,        # null if not displayed
+      "uptime":                 string,
+      "uptime_days":            integer,
+      "uptime_hours":           integer,
+      "uptime_minutes":         integer,
+      "uptime_total_seconds":   integer,
+      "users":                  integer,
+      "load_1m":                float,
+      "load_5m":                float,
+      "load_15m":               float
+    }
 
 Example:
 
     $ uptime | jc --uptime -p
     {
-      "time": "11:30:44",
-      "uptime": "1 day, 21:17",
-      "users": 1,
-      "load_1m": 0.01,
-      "load_5m": 0.04,
-      "load_15m": 0.05
+      "time": "11:35",
+      "uptime": "3 days, 4:03",
+      "users": 5,
+      "load_1m": 1.88,
+      "load_5m": 2.0,
+      "load_15m": 1.94,
+      "time_hour": 11,
+      "time_minute": 35,
+      "time_second": null,
+      "uptime_days": 3,
+      "uptime_hours": 4,
+      "uptime_minutes": 3,
+      "uptime_total_seconds": 273780
     }
 
     $ uptime | jc --uptime -p -r
     {
-      "time": "11:31:09",
-      "uptime": "1 day, 21:17",
-      "users": "1",
-      "load_1m": "0.00",
-      "load_5m": "0.04",
-      "load_15m": "0.05"
+      "time": "11:36",
+      "uptime": "3 days, 4:04",
+      "users": "5",
+      "load_1m": "1.88",
+      "load_5m": "1.99",
+      "load_15m": "1.94"
     }
 
 
@@ -46,32 +73,7 @@ Example:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary. Structured data with the following schema:
-
-    {
-      "time":     string,
-      "uptime":   string,
-      "users":    integer,
-      "load_1m":  float,
-      "load_5m":  float,
-      "load_15m": float
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -83,10 +85,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/vmstat.md

@@ -0,0 +1,159 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.vmstat
+jc - JSON CLI output utility `vmstat` command output parser
+
+Options supported: `-a`, `-w`, `-d`, `-t`
+
+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):
+
+    $ vmstat | jc --vmstat
+
+    or
+
+    $ jc vmstat
+
+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:
+
+    [
+      {
+        "runnable_procs":                    integer,
+        "uninterruptible_sleeping_procs":    integer,
+        "virtual_mem_used":                  integer,
+        "free_mem":                          integer,
+        "buffer_mem":                        integer,
+        "cache_mem":                         integer,
+        "inactive_mem":                      integer,
+        "active_mem":                        integer,
+        "swap_in":                           integer,
+        "swap_out":                          integer,
+        "blocks_in":                         integer,
+        "blocks_out":                        integer,
+        "interrupts":                        integer,
+        "context_switches":                  integer,
+        "user_time":                         integer,
+        "system_time":                       integer,
+        "idle_time":                         integer,
+        "io_wait_time":                      integer,
+        "stolen_time":                       integer,
+        "disk":                              string,
+        "total_reads":                       integer,
+        "merged_reads":                      integer,
+        "sectors_read":                      integer,
+        "reading_ms":                        integer,
+        "total_writes":                      integer,
+        "merged_writes":                     integer,
+        "sectors_written":                   integer,
+        "writing_ms":                        integer,
+        "current_io":                        integer,
+        "io_seconds":                        integer,
+        "timestamp":                         string,
+        "timezone":                          string,
+        "epoch":                             integer,     # [0]
+        "epoch_utc":                         integer      # [1]
+      }
+    ]
+
+    [0] naive timestamp if -t flag is used
+    [1] aware timestamp if -t flag is used and UTC TZ
+
+Examples:
+
+    $ vmstat | jc --vmstat -p
+    [
+      {
+        "runnable_procs": 2,
+        "uninterruptible_sleeping_procs": 0,
+        "virtual_mem_used": 0,
+        "free_mem": 2794468,
+        "buffer_mem": 2108,
+        "cache_mem": 741208,
+        "inactive_mem": null,
+        "active_mem": null,
+        "swap_in": 0,
+        "swap_out": 0,
+        "blocks_in": 1,
+        "blocks_out": 3,
+        "interrupts": 29,
+        "context_switches": 57,
+        "user_time": 0,
+        "system_time": 0,
+        "idle_time": 99,
+        "io_wait_time": 0,
+        "stolen_time": 0,
+        "timestamp": null,
+        "timezone": null
+      }
+    ]
+
+    $ vmstat | jc --vmstat -p -r
+    [
+      {
+        "runnable_procs": "2",
+        "uninterruptible_sleeping_procs": "0",
+        "virtual_mem_used": "0",
+        "free_mem": "2794468",
+        "buffer_mem": "2108",
+        "cache_mem": "741208",
+        "inactive_mem": null,
+        "active_mem": null,
+        "swap_in": "0",
+        "swap_out": "0",
+        "blocks_in": "1",
+        "blocks_out": "3",
+        "interrupts": "29",
+        "context_switches": "57",
+        "user_time": "0",
+        "system_time": "0",
+        "idle_time": "99",
+        "io_wait_time": "0",
+        "stolen_time": "0",
+        "timestamp": null,
+        "timezone": null
+      }
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/vmstat_s.md

@@ -0,0 +1,140 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.vmstat_s
+jc - JSON CLI output utility `vmstat` command output streaming parser
+
+> This streaming parser outputs JSON Lines
+
+Options supported: `-a`, `-w`, `-d`, `-t`
+
+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):
+
+    $ vmstat | jc --vmstat-s
+
+> Note: When piping `jc` converted `vmstat` output to other processes it may
+appear the output is hanging due to the OS pipe buffers. This is because
+`vmstat` 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('vmstat_s', vmstat_command_output.splitlines())
+    for item in result:
+        # do something
+
+    or
+
+    import jc.parsers.vmstat_s
+    # result is an iterable object (generator)
+    result = jc.parsers.vmstat_s.parse(vmstat_command_output.splitlines())
+    for item in result:
+        # do something
+
+Schema:
+
+    {
+      "runnable_procs":                   integer,
+      "uninterruptible_sleeping_procs":   integer,
+      "virtual_mem_used":                 integer,
+      "free_mem":                         integer,
+      "buffer_mem":                       integer,
+      "cache_mem":                        integer,
+      "inactive_mem":                     integer,
+      "active_mem":                       integer,
+      "swap_in":                          integer,
+      "swap_out":                         integer,
+      "blocks_in":                        integer,
+      "blocks_out":                       integer,
+      "interrupts":                       integer,
+      "context_switches":                 integer,
+      "user_time":                        integer,
+      "system_time":                      integer,
+      "idle_time":                        integer,
+      "io_wait_time":                     integer,
+      "stolen_time":                      integer,
+      "disk":                             string,
+      "total_reads":                      integer,
+      "merged_reads":                     integer,
+      "sectors_read":                     integer,
+      "reading_ms":                       integer,
+      "total_writes":                     integer,
+      "merged_writes":                    integer,
+      "sectors_written":                  integer,
+      "writing_ms":                       integer,
+      "current_io":                       integer,
+      "io_seconds":                       integer,
+      "timestamp":                        string,
+      "timezone":                         string,
+      "epoch":                            integer,     # [0]
+      "epoch_utc":                        integer      # [1]
+
+      # Below object only exists if using -qq or ignore_exceptions=True
+
+      "_jc_meta":
+        {
+          "success":                      boolean,  # [2]
+          "error":                        string,   # [3]
+          "line":                         string    # [3]
+        }
+    }
+
+    [0] naive timestamp if -t flag is used
+    [1] aware timestamp if -t flag is used and UTC TZ
+    [2] false if error parsing
+    [3] exists if "success" is false
+
+Examples:
+
+    $ vmstat | jc --vmstat-s
+    {"runnable_procs":2,"uninterruptible_sleeping_procs":0,"virtual_mem...}
+    ...
+
+    $ vmstat | jc --vmstat-s -r
+    {"runnable_procs":"2","uninterruptible_sleeping_procs":"0","virtua...}
+    ...
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False, ignore_exceptions=False)
+```
+
+Main text parsing generator function. Returns an iterator object.
+
+Parameters:
+
+    data:              (iterable)  line-based text data to parse
+                                   (e.g. sys.stdin or str.splitlines())
+
+    raw:               (boolean)   unprocessed output if True
+    quiet:             (boolean)   suppress warning messages if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+
+Yields:
+
+    Dictionary. Raw or processed structured data.
+
+Returns:
+
+    Iterator object
+
+## Parser Information
+Compatibility:  linux
+
+Version 0.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/w.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.w
 jc - JSON CLI output utility `w` command output parser
@@ -12,12 +13,28 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('w', w_command_output)
+
+    or
+
     import jc.parsers.w
     result = jc.parsers.w.parse(w_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    [
+      {
+        "user":         string,     # '-' = null
+        "tty":          string,     # '-' = null
+        "from":         string,     # '-' = null
+        "login_at":     string,     # '-' = null
+        "idle":         string,     # '-' = null
+        "jcpu":         string,
+        "pcpu":         string,
+        "what":         string      # '-' = null
+      }
+    ]
 
 Examples:
 
@@ -94,36 +111,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "user":     string,     # '-'' = null
-        "tty":      string,     # '-'' = null
-        "from":     string,     # '-'' = null
-        "login_at": string,     # '-'' = null
-        "idle":     string,     # '-'' = null
-        "jcpu":     string,
-        "pcpu":     string,
-        "what":     string      # '-'' = null
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -135,10 +123,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/wc.md

@@ -0,0 +1,87 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.wc
+jc - JSON CLI output utility `wc` command output parser
+
+Usage (cli):
+
+    $ wc file.txt | jc --wc
+
+    or
+
+    $ jc wc file.txt
+
+Usage (module):
+
+    import jc
+    result = jc.parse('wc', wc_command_output)
+
+    or
+
+    import jc.parsers.wc
+    result = jc.parsers.wc.parse(wc_command_output)
+
+Schema:
+
+    [
+      {
+        "filename":     string,
+        "lines":        integer,
+        "words":        integer,
+        "characters":   integer
+      }
+    ]
+
+Examples:
+
+    $ wc * | jc --wc -p
+    [
+      {
+        "filename": "airport-I.json",
+        "lines": 1,
+        "words": 30,
+        "characters": 307
+      },
+      {
+        "filename": "airport-I.out",
+        "lines": 15,
+        "words": 33,
+        "characters": 348
+      },
+      {
+        "filename": "airport-s.json",
+        "lines": 1,
+        "words": 202,
+        "characters": 2152
+      },
+      ...
+    ]
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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, aix, freebsd
+
+Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/who.md

@@ -1,9 +1,13 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.who
 jc - JSON CLI output utility `who` command output parser
 
 Accepts any of the following who options (or no options): `-aTH`
 
+The `epoch` calculated timestamp field is naive. (i.e. based on the local
+time of the system the parser is run on)
+
 Usage (cli):
 
     $ who | jc --who
@@ -14,12 +18,32 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('who', who_command_output)
+
+    or
+
     import jc.parsers.who
     result = jc.parsers.who.parse(who_command_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'aix', 'freebsd'
+    [
+      {
+        "user":            string,
+        "event":           string,
+        "writeable_tty":   string,
+        "tty":             string,
+        "time":            string,
+        "epoch":           integer,     # [0]
+        "idle":            string,
+        "pid":             integer,
+        "from":            string,
+        "comment":         string
+      }
+    ]
+
+    [0] naive timestamp. null if time cannot be converted
 
 Examples:
 
@@ -28,7 +52,8 @@ Examples:
       {
         "event": "reboot",
         "time": "Feb 7 23:31",
-        "pid": 1
+        "pid": 1,
+        "epoch": null
       },
       {
         "user": "joeuser",
@@ -36,7 +61,8 @@ Examples:
         "tty": "console",
         "time": "Feb 7 23:32",
         "idle": "old",
-        "pid": 105
+        "pid": 105,
+        "epoch": null
       },
       {
         "user": "joeuser",
@@ -45,7 +71,8 @@ Examples:
         "time": "Feb 13 16:44",
         "idle": ".",
         "pid": 51217,
-        "comment": "term=0 exit=0"
+        "comment": "term=0 exit=0",
+        "epoch": null
       },
       {
         "user": "joeuser",
@@ -53,7 +80,8 @@ Examples:
         "tty": "ttys003",
         "time": "Feb 28 08:59",
         "idle": "01:36",
-        "pid": 41402
+        "pid": 41402,
+        "epoch": null
       },
       {
         "user": "joeuser",
@@ -62,7 +90,8 @@ Examples:
         "time": "Mar 1 16:35",
         "idle": ".",
         "pid": 15679,
-        "from": "192.168.1.5"
+        "from": "192.168.1.5",
+        "epoch": null
       }
     ]
 
@@ -114,37 +143,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Structured data with the following schema:
-
-    [
-      {
-        "user":            string,
-        "event":           string,
-        "writeable_tty":   string,
-        "tty":             string,
-        "time":            string,
-        "idle":            string,
-        "pid":             integer,
-        "from":            string,
-        "comment":         string
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -156,10 +155,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, aix, freebsd
+
+Version 1.5 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/xml.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.xml
 jc - JSON CLI output utility `XML` file parser
@@ -8,12 +9,23 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('xml', xml_file_output)
+
+    or
+
     import jc.parsers.xml
     result = jc.parsers.xml.parse(xml_file_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    XML Document converted to a Dictionary
+    See https://github.com/martinblech/xmltodict for details
+
+    {
+      "key1":   string/object,
+      "key2":   string/object
+    }
 
 Examples:
 
@@ -66,28 +78,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    Dictionary representing an XML document:
-
-    {
-      XML Document converted to a Dictionary
-      See https://github.com/martinblech/xmltodict for details
-    }
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -99,10 +90,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
     Dictionary. Raw or processed structured data.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/yaml.md

@@ -1,3 +1,4 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.yaml
 jc - JSON CLI output utility `YAML` file parser
@@ -8,12 +9,25 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('yaml', yaml_file_output)
+
+    or
+
     import jc.parsers.yaml
     result = jc.parsers.yaml.parse(yaml_file_output)
 
-Compatibility:
+Schema:
 
-    'linux', 'darwin', 'cygwin', 'win32', 'aix', 'freebsd'
+    YAML Document converted to a Dictionary
+    See https://pypi.org/project/ruamel.yaml for details
+
+    [
+      {
+        "key1":     string/int/float/boolean/null/array/object,
+        "key2":     string/int/float/boolean/null/array/object
+      }
+    ]
 
 Examples:
 
@@ -78,30 +92,7 @@ Examples:
 ```python
 info()
 ```
-
-
-## process
-```python
-process(proc_data)
-```
-
-Final processing to conform to the schema.
-
-Parameters:
-
-    proc_data:   (dictionary) raw structured data to process
-
-Returns:
-
-    List of dictionaries. Each dictionary represents a YAML document:
-
-    [
-      {
-        YAML Document converted to a Dictionary
-        See https://pypi.org/project/ruamel.yaml for details
-      }
-    ]
-
+Provides parser metadata (version, author, etc.)
 
 ## parse
 ```python
@@ -113,10 +104,14 @@ Main text parsing function
 Parameters:
 
     data:        (string)  text data to parse
-    raw:         (boolean) output preprocessed JSON if True
+    raw:         (boolean) unprocessed output if True
     quiet:       (boolean) suppress warning messages if True
 
 Returns:
 
-    List of dictionaries. Raw or processed structured data.
+    List of Dictionaries representing the YAML documents.
 
+## Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.6 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/zipinfo.md

@@ -0,0 +1,112 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+
+# jc.parsers.zipinfo
+jc - JSON CLI output utility `zipinfo` command output parser
+
+Options supported:
+- none
+
+Note: The default listing format.
+
+Usage (cli):
+
+    $ zipinfo <archive> | jc --zipinfo
+
+    or
+
+    $ jc zipinfo
+
+Usage (module):
+
+    import jc
+    result = jc.parse('zipinfo', zipinfo_command_output)
+
+    or
+
+    import jc.parsers.zipinfo
+    result = jc.parsers.zipinfo.parse(zipinfo_command_output)
+
+Schema:
+
+    [
+      {
+        "archive":              string,
+        "size":                 integer,
+        "size_unit":            string,
+        "number_entries":       integer,
+        "number_files":         integer,
+        "bytes_uncompressed":   integer,
+        "bytes_compressed":     integer,
+        "percent_compressed":   float,
+        "files": [
+          {
+            "flags":            string,
+            "zipversion":       string,
+            "zipunder":         string
+            "filesize":         integer,
+            "type":             string,
+            "method":           string,
+            "date":             string,
+            "time":             string,
+            "filename":         string
+          }
+        ]
+      }
+    ]
+
+Examples:
+
+    $ zipinfo log4j-core-2.16.0.jar | jc --zipinfo -p
+
+    [
+      {
+        "archive": "log4j-core-2.16.0.jar",
+        "size": 1789565,
+        "size_unit": "bytes",
+        "number_entries": 1218,
+        "number_files": 1218,
+        "bytes_uncompressed": 3974141,
+        "bytes_compressed": 1515455,
+        "percent_compressed": 61.9,
+        "files": [
+          {
+            "flags": "-rw-r--r--",
+            "zipversion": "2.0",
+            "zipunder": "unx",
+            "filesize": 19810,
+            "type": "bl",
+            "method": "defN",
+            "date": "21-Dec-12",
+            "time": "23:35",
+            "filename": "META-INF/MANIFEST.MF"
+          },
+    ...
+
+
+## info
+```python
+info()
+```
+Provides parser metadata (version, author, etc.)
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+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
+
+Version 0.01 by Matt J (https://github.com/listuser)

docs/readme.md

@@ -4,68 +4,70 @@ JC - JSON CLI output utility
 
 * kellyjonbrazil@gmail.com
 
-This package serializes the output of many standard unix command line tools to JSON format.
+This package serializes the output of many standard unix command line tools
+to dictionaries and lists of dictionaries.
 
-For documentation on each parser, see [docs/parsers](https://github.com/kellyjonbrazil/jc/tree/master/docs/parsers).
+## Interactive Documentation
 
-CLI Example:
+    >>> help(jc)
+    >>> help(jc.lib)
+    >>> help(jc.util)
+    >>> jc.get_help('parser_module_name')
 
-    $ ls -l /usr/bin | jc --ls -p
-    [
-      {
-        "filename": "apropos",
-        "link_to": "whatis",
-        "flags": "lrwxrwxrwx.",
-        "links": 1,
-        "owner": "root",
-        "group": "root",
-        "size": 6,
-        "date": "Aug 15 10:53"
-      },
-      {
-        "filename": "ar",
-        "flags": "-rwxr-xr-x.",
-        "links": 1,
-        "owner": "root",
-        "group": "root",
-        "size": 62744,
-        "date": "Aug 8 16:14"
-      },
-      {
-        "filename": "arch",
-        "flags": "-rwxr-xr-x.",
-        "links": 1,
-        "owner": "root",
-        "group": "root",
-        "size": 33080,
-        "date": "Aug 19 23:25"
-      },
-      ...
-    ]
+## Online Documentation
 
-Module Example:
+### Latest:
 
-    >>> import jc.parsers.ls
+https://github.com/kellyjonbrazil/jc/tree/master/docs
+
+### Specific Version
+
+Replace `{{full_version_number}}` - e.g. `1.17.7`:
+
+`https://github.com/kellyjonbrazil/jc/tree/v{{full_version_number}}/docs`
+
+Specific versions can also be selected by tag in the branch dropdown menu.
+
+## Usage Example:
+
+    >>> import subprocess
+    >>> import jc
     >>>
-    >>> data='''-rwxr-xr-x  1 root  wheel    23648 May  3 22:26 cat
-    ... -rwxr-xr-x  1 root  wheel    30016 May  3 22:26 chmod
-    ... -rwxr-xr-x  1 root  wheel    29024 May  3 22:26 cp
-    ... -rwxr-xr-x  1 root  wheel   375824 May  3 22:26 csh
-    ... -rwxr-xr-x  1 root  wheel    28608 May  3 22:26 date
-    ... -rwxr-xr-x  1 root  wheel    32000 May  3 22:26 dd
-    ... -rwxr-xr-x  1 root  wheel    23392 May  3 22:26 df
-    ... -rwxr-xr-x  1 root  wheel    18128 May  3 22:26 echo'''
-    >>>
-    >>> jc.parsers.ls.parse(data)
-    [{'filename': 'cat', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 23648,
-    'date': 'May 3 22:26'}, {'filename': 'chmod', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root',
-    'group': 'wheel', 'size': 30016, 'date': 'May 3 22:26'}, {'filename': 'cp', 'flags': '-rwxr-xr-x',
-    'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 29024, 'date': 'May 3 22:26'}, {'filename': 'csh',
-    'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 375824, 'date': 'May 3
-    22:26'}, {'filename': 'date', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel',
-    'size': 28608, 'date': 'May 3 22:26'}, {'filename': 'dd', 'flags': '-rwxr-xr-x', 'links': 1, 'owner':
-    'root', 'group': 'wheel', 'size': 32000, 'date': 'May 3 22:26'}, {'filename': 'df', 'flags':
-    '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 23392, 'date': 'May 3 22:26'},
-    {'filename': 'echo', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 18128,
-    'date': 'May 3 22:26'}]
+    >>> cmd_output = subprocess.check_output(['dig', 'example.com'],
+                                             text=True)
+    >>> data = jc.parse('dig', cmd_output)
+    >>> data
+    [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', ...}]
+
+Alternatively, you can bypass the high-level API and call the parser
+modules directly:
+
+    >>> import subprocess
+    >>> import jc.parsers.dig
+    >>>
+    >>> cmd_output = subprocess.check_output(['dig', 'example.com'],
+                                             text=True)
+    >>> data = jc.parsers.dig.parse(cmd_output)
+    >>> data
+    [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', ...}]
+
+## Available Functions
+
+Use `help(jc.lib)` for details:
+
+    parse(parser_module_name: str, data: str | iterable)
+        High-level API to easily access the parser. This API will find both
+        built-in parsers and local plugin parsers.
+
+    get_help(parser_module_name: str)
+        Convenience function to display the help screen for a parser using
+        its module name.
+
+    parser_mod_list()
+        Get a list of all available parser module names to be used in
+        parse() and get_help().
+
+    plugin_parser_mod_list()
+        Get a list of plugin parser module names. This list is a subset of
+        parser_mod_list().
 

docs/utils.md

@@ -4,53 +4,61 @@ jc - JSON CLI output utility utils
 
 ## warning_message
 ```python
-warning_message(message)
+warning_message(message_lines)
 ```
 
-Prints a warning message for non-fatal issues
+Prints warning message for non-fatal issues. The first line is
+prepended with 'jc:  Warning - ' and subsequent lines are indented.
+Wraps text as needed based on the terminal width.
 
 Parameters:
 
-    message:        (string) text of message
+    message:   (list) list of string lines
 
 Returns:
 
-    no return, just prints output to STDERR
+    None - just prints output to STDERR
 
 
 ## error_message
 ```python
-error_message(message)
+error_message(message_lines)
 ```
 
-Prints an error message for fatal issues
+Prints an error message for fatal issues. The first line is
+prepended with 'jc:  Error - ' and subsequent lines are indented.
+Wraps text as needed based on the terminal width.
 
 Parameters:
 
-    message:        (string) text of message
+    message:   (list) list of string lines
 
 Returns:
 
-    no return, just prints output to STDERR
+    None - just prints output to STDERR
 
 
 ## compatibility
 ```python
-compatibility(mod_name, compatible)
+compatibility(mod_name, compatible, quiet=False)
 ```
-Checks for the parser's compatibility with the running OS platform.
+
+Checks for the parser's compatibility with the running OS
+platform.
 
 Parameters:
 
-    mod_name:       (string) __name__ of the calling module
+    mod_name:     (string) __name__ of the calling module
 
-    compatible:     (list) sys.platform name(s) compatible with the parser
-                    compatible options:
-                    linux, darwin, cygwin, win32, aix, freebsd
+    compatible:   (list) sys.platform name(s) compatible with
+                  the parser. compatible options:
+                  linux, darwin, cygwin, win32, aix, freebsd
+
+    quiet:        (bool) supress compatibility message if True
 
 Returns:
 
-    no return, just prints output to STDERR
+    None - just prints output to STDERR
 
 
 ## has_data
@@ -58,7 +66,8 @@ Returns:
 has_data(data)
 ```
 
-Checks if the input contains data. If there are any non-whitespace characters then return True, else return False
+Checks if the input contains data. If there are any non-whitespace
+characters then return True, else return False.
 
 Parameters:
 
@@ -66,5 +75,120 @@ Parameters:
 
 Returns:
 
-    Boolean      True if input string (data) contains non-whitespace characters, otherwise False
+    Boolean      True if input string (data) contains non-whitespace
+                 characters, otherwise False
+
+
+## convert_to_int
+```python
+convert_to_int(value)
+```
+
+Converts string and float input to int. Strips all non-numeric
+characters from strings.
+
+Parameters:
+
+    value:         (string/integer/float) Input value
+
+Returns:
+
+    integer/None   Integer if successful conversion, otherwise None
+
+
+## convert_to_float
+```python
+convert_to_float(value)
+```
+
+Converts string and int input to float. Strips all non-numeric
+characters from strings.
+
+Parameters:
+
+    value:         (string) Input value
+
+Returns:
+
+    float/None     Float if successful conversion, otherwise None
+
+
+## convert_to_bool
+```python
+convert_to_bool(value)
+```
+
+Converts string, integer, or float input to boolean by checking
+for 'truthy' values.
+
+Parameters:
+
+    value:          (string/integer/float) Input value
+
+Returns:
+
+    True/False      False unless a 'truthy' number or string is found
+                    ('y', 'yes', 'true', '1', 1, -1, etc.)
+
+
+## stream_success
+```python
+stream_success(output_line, ignore_exceptions)
+```
+Add `_jc_meta` object to output line if `ignore_exceptions=True`
+
+## stream_error
+```python
+stream_error(e, ignore_exceptions, line)
+```
+
+Reraise the stream exception with annotation or print an error
+`_jc_meta` field if `ignore_exceptions=True`.
+
+
+## input_type_check
+```python
+input_type_check(data)
+```
+Ensure input data is a string
+
+## streaming_input_type_check
+```python
+streaming_input_type_check(data)
+```
+Ensure input data is an iterable, but not a string or bytes
+
+## streaming_line_input_type_check
+```python
+streaming_line_input_type_check(line)
+```
+Ensure each line is a string
+
+## timestamp
+```python
+timestamp(datetime_string)
+```
+
+Input a date-time text string of several formats and convert to a
+naive or timezone-aware epoch timestamp in UTC.
+
+Parameters:
+
+    datetime_string:  (str)  a string representation of a
+                             date-time in several supported formats
+
+Attributes:
+
+    string            (str)   the input datetime string
+
+    format            (int)   the format rule that was used to
+                              decode the datetime string. None if
+                              conversion fails
+
+    naive             (int)   timestamp based on locally configured
+                              timezone. None if conversion fails
+
+    utc               (int)   aware timestamp only if UTC timezone
+                              detected in datetime string. None if
+                              conversion fails
 

jc/__init__.py

@@ -2,70 +2,72 @@
 
 * kellyjonbrazil@gmail.com
 
-This package serializes the output of many standard unix command line tools to JSON format.
+This package serializes the output of many standard unix command line tools
+to dictionaries and lists of dictionaries.
 
-For documentation on each parser, see [docs/parsers](https://github.com/kellyjonbrazil/jc/tree/master/docs/parsers).
+## Interactive Documentation
 
-CLI Example:
+    >>> help(jc)
+    >>> help(jc.lib)
+    >>> help(jc.util)
+    >>> jc.get_help('parser_module_name')
 
-    $ ls -l /usr/bin | jc --ls -p
-    [
-      {
-        "filename": "apropos",
-        "link_to": "whatis",
-        "flags": "lrwxrwxrwx.",
-        "links": 1,
-        "owner": "root",
-        "group": "root",
-        "size": 6,
-        "date": "Aug 15 10:53"
-      },
-      {
-        "filename": "ar",
-        "flags": "-rwxr-xr-x.",
-        "links": 1,
-        "owner": "root",
-        "group": "root",
-        "size": 62744,
-        "date": "Aug 8 16:14"
-      },
-      {
-        "filename": "arch",
-        "flags": "-rwxr-xr-x.",
-        "links": 1,
-        "owner": "root",
-        "group": "root",
-        "size": 33080,
-        "date": "Aug 19 23:25"
-      },
-      ...
-    ]
+## Online Documentation
 
-Module Example:
+### Latest:
 
-    >>> import jc.parsers.ls
-    >>> 
-    >>> data='''-rwxr-xr-x  1 root  wheel    23648 May  3 22:26 cat
-    ... -rwxr-xr-x  1 root  wheel    30016 May  3 22:26 chmod
-    ... -rwxr-xr-x  1 root  wheel    29024 May  3 22:26 cp
-    ... -rwxr-xr-x  1 root  wheel   375824 May  3 22:26 csh
-    ... -rwxr-xr-x  1 root  wheel    28608 May  3 22:26 date
-    ... -rwxr-xr-x  1 root  wheel    32000 May  3 22:26 dd
-    ... -rwxr-xr-x  1 root  wheel    23392 May  3 22:26 df
-    ... -rwxr-xr-x  1 root  wheel    18128 May  3 22:26 echo'''
+https://github.com/kellyjonbrazil/jc/tree/master/docs
+
+### Specific Version
+
+Replace `{{full_version_number}}` - e.g. `1.17.7`:
+
+`https://github.com/kellyjonbrazil/jc/tree/v{{full_version_number}}/docs`
+
+Specific versions can also be selected by tag in the branch dropdown menu.
+
+## Usage Example:
+
+    >>> import subprocess
+    >>> import jc
     >>>
-    >>> jc.parsers.ls.parse(data)
-    [{'filename': 'cat', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 23648,
-    'date': 'May 3 22:26'}, {'filename': 'chmod', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root',
-    'group': 'wheel', 'size': 30016, 'date': 'May 3 22:26'}, {'filename': 'cp', 'flags': '-rwxr-xr-x',
-    'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 29024, 'date': 'May 3 22:26'}, {'filename': 'csh',
-    'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 375824, 'date': 'May 3
-    22:26'}, {'filename': 'date', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel',
-    'size': 28608, 'date': 'May 3 22:26'}, {'filename': 'dd', 'flags': '-rwxr-xr-x', 'links': 1, 'owner':
-    'root', 'group': 'wheel', 'size': 32000, 'date': 'May 3 22:26'}, {'filename': 'df', 'flags':
-    '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 23392, 'date': 'May 3 22:26'},
-    {'filename': 'echo', 'flags': '-rwxr-xr-x', 'links': 1, 'owner': 'root', 'group': 'wheel', 'size': 18128,
-    'date': 'May 3 22:26'}]
-"""
+    >>> cmd_output = subprocess.check_output(['dig', 'example.com'],
+                                             text=True)
+    >>> data = jc.parse('dig', cmd_output)
+    >>> data
+    [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', ...}]
 
-name = 'jc'
+Alternatively, you can bypass the high-level API and call the parser
+modules directly:
+
+    >>> import subprocess
+    >>> import jc.parsers.dig
+    >>>
+    >>> cmd_output = subprocess.check_output(['dig', 'example.com'],
+                                             text=True)
+    >>> data = jc.parsers.dig.parse(cmd_output)
+    >>> data
+    [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', ...}]
+
+## Available Functions
+
+Use `help(jc.lib)` for details:
+
+    parse(parser_module_name: str, data: str | iterable)
+        High-level API to easily access the parser. This API will find both
+        built-in parsers and local plugin parsers.
+
+    get_help(parser_module_name: str)
+        Convenience function to display the help screen for a parser using
+        its module name.
+
+    parser_mod_list()
+        Get a list of all available parser module names to be used in
+        parse() and get_help().
+
+    plugin_parser_mod_list()
+        Get a list of plugin parser module names. This list is a subset of
+        parser_mod_list().
+"""
+from .lib import (__version__, parse, parser_mod_list,
+                  plugin_parser_mod_list, get_help)

jc/cli.py

@@ -4,150 +4,84 @@ JC cli module
 
 import sys
 import os
-import os.path
-import re
-import shlex
 import importlib
 import textwrap
 import signal
+import shlex
+import subprocess
 import json
-import pygments
-from pygments import highlight
-from pygments.style import Style
-from pygments.token import (Name, Number, String, Keyword)
-from pygments.lexers import JsonLexer
-from pygments.formatters import Terminal256Formatter
-import jc.appdirs as appdirs
+from .lib import __version__, parsers, local_parsers
+from . import utils
+from . import tracebackplus
+from .exceptions import LibraryNotInstalled, ParseError
+
+# make pygments import optional
+try:
+    import pygments
+    from pygments import highlight
+    from pygments.style import Style
+    from pygments.token import (Name, Number, String, Keyword)
+    from pygments.lexers import JsonLexer
+    from pygments.formatters import Terminal256Formatter
+    PYGMENTS_INSTALLED = True
+except Exception:
+    PYGMENTS_INSTALLED = False
+
+
+JC_ERROR_EXIT = 100
 
 
 class info():
-    version = '1.14.0'
+    version = __version__
     description = 'JSON CLI output utility'
     author = 'Kelly Brazil'
     author_email = 'kellyjonbrazil@gmail.com'
-
-
-__version__ = info.version
-
-parsers = [
-    'airport',
-    'airport-s',
-    'arp',
-    'blkid',
-    'cksum',
-    'crontab',
-    'crontab-u',
-    'csv',
-    'date',
-    'df',
-    'dig',
-    'dmidecode',
-    'du',
-    'env',
-    'file',
-    'free',
-    'fstab',
-    'group',
-    'gshadow',
-    'hash',
-    'hashsum',
-    'history',
-    'hosts',
-    'id',
-    'ifconfig',
-    'ini',
-    'iptables',
-    'jobs',
-    'kv',
-    'last',
-    'ls',
-    'lsblk',
-    'lsmod',
-    'lsof',
-    'mount',
-    'netstat',
-    'ntpq',
-    'passwd',
-    'ping',
-    'pip-list',
-    'pip-show',
-    'ps',
-    'route',
-    'shadow',
-    'ss',
-    'stat',
-    'sysctl',
-    'systemctl',
-    'systemctl-lj',
-    'systemctl-ls',
-    'systemctl-luf',
-    'timedatectl',
-    'tracepath',
-    'traceroute',
-    'uname',
-    'uptime',
-    'w',
-    'wc',
-    'who',
-    'xml',
-    'yaml'
-]
-
-# List of custom or override parsers.
-# Allow any <user_data_dir>/jc/jcparsers/*.py
-local_parsers = []
-data_dir = appdirs.user_data_dir('jc', 'jc')
-local_parsers_dir = os.path.join(data_dir, 'jcparsers')
-if os.path.isdir(local_parsers_dir):
-    sys.path.append(data_dir)
-    for name in os.listdir(local_parsers_dir):
-        if re.match(r'\w+\.py', name) and os.path.isfile(os.path.join(local_parsers_dir, name)):
-            plugin_name = name[0:-3]
-            local_parsers.append(plugin_name)
-            if plugin_name not in parsers:
-                parsers.append(plugin_name)
+    website = 'https://github.com/kellyjonbrazil/jc'
+    copyright = '© 2019-2022 Kelly Brazil'
+    license = 'MIT License'
 
 
 # We only support 2.3.0+, pygments changed color names in 2.4.0.
 # startswith is sufficient and avoids potential exceptions from split and int.
-if pygments.__version__.startswith('2.3.'):
-    PYGMENT_COLOR = {
-        'black': '#ansiblack',
-        'red': '#ansidarkred',
-        'green': '#ansidarkgreen',
-        'yellow': '#ansibrown',
-        'blue': '#ansidarkblue',
-        'magenta': '#ansipurple',
-        'cyan': '#ansiteal',
-        'gray': '#ansilightgray',
-        'brightblack': '#ansidarkgray',
-        'brightred': '#ansired',
-        'brightgreen': '#ansigreen',
-        'brightyellow': '#ansiyellow',
-        'brightblue': '#ansiblue',
-        'brightmagenta': '#ansifuchsia',
-        'brightcyan': '#ansiturquoise',
-        'white': '#ansiwhite',
-    }
-else:
-    PYGMENT_COLOR = {
-        'black': 'ansiblack',
-        'red': 'ansired',
-        'green': 'ansigreen',
-        'yellow': 'ansiyellow',
-        'blue': 'ansiblue',
-        'magenta': 'ansimagenta',
-        'cyan': 'ansicyan',
-        'gray': 'ansigray',
-        'brightblack': 'ansibrightblack',
-        'brightred': 'ansibrightred',
-        'brightgreen': 'ansibrightgreen',
-        'brightyellow': 'ansibrightyellow',
-        'brightblue': 'ansibrightblue',
-        'brightmagenta': 'ansibrightmagenta',
-        'brightcyan': 'ansibrightcyan',
-        'white': 'ansiwhite',
-    }
+if PYGMENTS_INSTALLED:
+    if pygments.__version__.startswith('2.3.'):
+        PYGMENT_COLOR = {
+            'black': '#ansiblack',
+            'red': '#ansidarkred',
+            'green': '#ansidarkgreen',
+            'yellow': '#ansibrown',
+            'blue': '#ansidarkblue',
+            'magenta': '#ansipurple',
+            'cyan': '#ansiteal',
+            'gray': '#ansilightgray',
+            'brightblack': '#ansidarkgray',
+            'brightred': '#ansired',
+            'brightgreen': '#ansigreen',
+            'brightyellow': '#ansiyellow',
+            'brightblue': '#ansiblue',
+            'brightmagenta': '#ansifuchsia',
+            'brightcyan': '#ansiturquoise',
+            'white': '#ansiwhite',
+        }
+    else:
+        PYGMENT_COLOR = {
+            'black': 'ansiblack',
+            'red': 'ansired',
+            'green': 'ansigreen',
+            'yellow': 'ansiyellow',
+            'blue': 'ansiblue',
+            'magenta': 'ansimagenta',
+            'cyan': 'ansicyan',
+            'gray': 'ansigray',
+            'brightblack': 'ansibrightblack',
+            'brightred': 'ansibrightred',
+            'brightgreen': 'ansibrightgreen',
+            'brightyellow': 'ansibrightyellow',
+            'brightblue': 'ansibrightblue',
+            'brightmagenta': 'ansibrightmagenta',
+            'brightcyan': 'ansibrightcyan',
+            'white': 'ansiwhite',
+        }
 
 
 def set_env_colors(env_colors=None):
@@ -164,10 +98,9 @@ def set_env_colors(env_colors=None):
 
     Default colors:
 
-    JC_COLORS=blue,brightblack,magenta,green
+        JC_COLORS=blue,brightblack,magenta,green
     or
-    JC_COLORS=default,default,default,default
-
+        JC_COLORS=default,default,default,default
     """
     input_error = False
 
@@ -185,34 +118,33 @@ def set_env_colors(env_colors=None):
 
     # if there is an issue with the env variable, just set all colors to default and move on
     if input_error:
-        print('jc:   Warning: could not parse JC_COLORS environment variable\n', file=sys.stderr)
+        utils.warning_message(['Could not parse JC_COLORS environment variable'])
         color_list = ['default', 'default', 'default', 'default']
 
     # Try the color set in the JC_COLORS env variable first. If it is set to default, then fall back to default colors
     return {
-        Name.Tag: f'bold {PYGMENT_COLOR[color_list[0]]}' if not color_list[0] == 'default' else f"bold {PYGMENT_COLOR['blue']}",   # key names
-        Keyword: PYGMENT_COLOR[color_list[1]] if not color_list[1] == 'default' else PYGMENT_COLOR['brightblack'],                 # true, false, null
-        Number: PYGMENT_COLOR[color_list[2]] if not color_list[2] == 'default' else PYGMENT_COLOR['magenta'],                      # numbers
-        String: PYGMENT_COLOR[color_list[3]] if not color_list[3] == 'default' else PYGMENT_COLOR['green']                         # strings
+        Name.Tag: f'bold {PYGMENT_COLOR[color_list[0]]}' if color_list[0] != 'default' else f"bold {PYGMENT_COLOR['blue']}",   # key names
+        Keyword: PYGMENT_COLOR[color_list[1]] if color_list[1] != 'default' else PYGMENT_COLOR['brightblack'],                 # true, false, null
+        Number: PYGMENT_COLOR[color_list[2]] if color_list[2] != 'default' else PYGMENT_COLOR['magenta'],                      # numbers
+        String: PYGMENT_COLOR[color_list[3]] if color_list[3] != 'default' else PYGMENT_COLOR['green']                         # strings
     }
 
 
-def piped_output():
-    """Return False if stdout is a TTY. True if output is being piped to another program"""
-    if sys.stdout.isatty():
-        return False
-    else:
-        return True
+def piped_output(force_color):
+    """Return False if stdout is a TTY. True if output is being piped to another program
+       and foce_color is True. This allows forcing of ANSI color codes even when using pipes.
+    """
+    return not sys.stdout.isatty() and not force_color
 
 
 def ctrlc(signum, frame):
     """Exit with error on SIGINT"""
-    sys.exit(1)
+    sys.exit(JC_ERROR_EXIT)
 
 
-def parser_shortname(parser_argument):
+def parser_shortname(parser_arg):
     """Return short name of the parser with dashes and no -- prefix"""
-    return parser_argument[2:]
+    return parser_arg[2:]
 
 
 def parser_argument(parser):
@@ -275,17 +207,20 @@ def about_jc():
         'description': info.description,
         'author': info.author,
         'author_email': info.author_email,
+        'website': info.website,
+        'copyright': info.copyright,
+        'license': info.license,
         'parser_count': len(parser_list),
         'parsers': parser_list
     }
 
 
-def helptext(message):
+def helptext():
     """Return the help text with the list of parsers"""
     parsers_string = parsers_text(indent=12, pad=17)
 
-    helptext_string = f'''
-    jc:     {message}
+    helptext_string = f'''\
+    jc converts the output of many commands and file-types to JSON
 
     Usage:  COMMAND | jc PARSER [OPTIONS]
 
@@ -296,72 +231,119 @@ def helptext(message):
     Parsers:
 {parsers_string}
     Options:
-            -a               about jc
-            -d               debug - show traceback (-dd for verbose traceback)
-            -m               monochrome output
-            -p               pretty print output
-            -q               quiet - suppress parser warnings
-            -r               raw JSON output
+            -a    about jc
+            -C    force color output even when using pipes (overrides -m)
+            -d    debug (-dd for verbose debug)
+            -h    help (-h --parser_name for parser documentation)
+            -m    monochrome output
+            -p    pretty print output
+            -q    quiet - suppress parser warnings (-qq to ignore streaming errors)
+            -r    raw JSON output
+            -u    unbuffer output
+            -v    version info
 
-    Example:
-            ls -al | jc --ls -p
+    Examples:
+            Standard Syntax:
+                $ dig www.google.com | jc --dig -p
 
-            or using the magic syntax:
+            Magic Syntax:
+                $ jc -p dig www.google.com
 
-            jc -p ls -al
+            Parser Documentation:
+                $ jc -h --dig
     '''
     return textwrap.dedent(helptext_string)
 
 
+def help_doc(options):
+    """
+    Returns the parser documentation if a parser is found in the arguments, otherwise
+    the general help text is returned.
+    """
+    for arg in options:
+        parser_name = parser_shortname(arg)
+
+        if parser_name in parsers:
+            # load parser module just in time so we don't need to load all modules
+            parser = parser_module(arg)
+            compatible = ', '.join(parser.info.compatible)
+            doc_text = \
+                f'{parser.__doc__}\n'\
+                f'Compatibility:  {compatible}\n\n'\
+                f'Version {parser.info.version} by {parser.info.author} ({parser.info.author_email})\n'
+
+            return doc_text
+
+    return helptext()
+
+
+def versiontext():
+    """Return the version text"""
+    versiontext_string = f'''\
+    jc version {info.version}
+    {info.website}
+    {info.copyright}'''
+    return textwrap.dedent(versiontext_string)
+
+
 def json_out(data, pretty=False, env_colors=None, mono=False, piped_out=False):
     """Return a JSON formatted string. String may include color codes or be pretty printed."""
+    separators = (',', ':')
+    indent = None
+
+    if pretty:
+        separators = None
+        indent = 2
+
     if not mono and not piped_out:
         # set colors
         class JcStyle(Style):
             styles = set_env_colors(env_colors)
 
-        if pretty:
-            return str(highlight(json.dumps(data, indent=2), JsonLexer(), Terminal256Formatter(style=JcStyle))[0:-1])
-        else:
-            return str(highlight(json.dumps(data), JsonLexer(), Terminal256Formatter(style=JcStyle))[0:-1])
-    else:
-        if pretty:
-            return json.dumps(data, indent=2)
-        else:
-            return json.dumps(data)
+        return str(highlight(json.dumps(data, indent=indent, separators=separators, ensure_ascii=False),
+                             JsonLexer(), Terminal256Formatter(style=JcStyle))[0:-1])
+
+    return json.dumps(data, indent=indent, separators=separators, ensure_ascii=False)
 
 
-def generate_magic_command(args):
-    """
-    Return a tuple with a boolean and a command, where the boolean signifies that
-    the command is valid, and the command is either a command string or None.
+def magic_parser(args):
     """
+    Parse command arguments for magic syntax: jc -p ls -al
 
-    # Parse with magic syntax: jc -p ls -al
+    Return a tuple:
+        valid_command   (bool)  is this a valid command? (exists in magic dict)
+        run_command     (list)  list of the user's command to run. None if no command.
+        jc_parser       (str)   parser to use for this user's command.
+        jc_options      (list)  list of jc options
+    """
+    # bail immediately if there are no args or a parser is defined
     if len(args) <= 1 or args[1].startswith('--'):
-        return False, None
+        return False, None, None, []
 
-    # correctly parse escape characters and spaces with shlex
-    args_given = ' '.join(map(shlex.quote, args[1:])).split()
+    args_given = args[1:]
     options = []
 
     # find the options
     for arg in list(args_given):
         # parser found - use standard syntax
         if arg.startswith('--'):
-            return False, None
+            return False, None, None, []
 
         # option found - populate option list
-        elif arg.startswith('-'):
+        if arg.startswith('-'):
             options.extend(args_given.pop(0)[1:])
 
         # command found if iterator didn't already stop - stop iterating
         else:
             break
 
-    # all options popped and no command found - for case like 'jc -a'
+    # if -h, -a, or -v found in options, then bail out
+    if 'h' in options or 'a' in options or 'v' in options:
+        return False, None, None, []
+
+    # all options popped and no command found - for case like 'jc -x'
     if len(args_given) == 0:
-        return False, None
+        return False, None, None, []
 
     magic_dict = {}
     parser_info = about_jc()['parsers']
@@ -378,26 +360,34 @@ def generate_magic_command(args):
     # try to get a parser for two_word_command, otherwise get one for one_word_command
     found_parser = magic_dict.get(two_word_command, magic_dict.get(one_word_command))
 
-    # construct a new command line using the standard syntax: COMMAND | jc --PARSER -OPTIONS
-    run_command = ' '.join(args_given)
-    if found_parser:
-        cmd_options = ('-' + ''.join(options)) if options else ''
-        return True, ' '.join([run_command, '|', 'jc', found_parser, cmd_options])
-    else:
-        return False, run_command
+    return (
+        bool(found_parser),                 # was a suitable parser found?
+        args_given,                         # run_command
+        found_parser,                       # the parser selected
+        options                             # jc options to preserve
+    )
 
 
-def magic():
-    """Runs the command generated by generate_magic_command() to support magic syntax"""
-    valid_command, run_command = generate_magic_command(sys.argv)
-    if valid_command:
-        os.system(run_command)
-        sys.exit(0)
-    elif run_command is None:
-        return
-    else:
-        print(helptext(f'parser not found for "{run_command}"'), file=sys.stderr)
-        sys.exit(1)
+def run_user_command(command):
+    """Use subprocess to run the user's command. Returns the STDOUT, STDERR, and the Exit Code as a tuple."""
+    proc = subprocess.Popen(command,
+                            stdout=subprocess.PIPE,
+                            stderr=subprocess.PIPE,
+                            close_fds=False,            # Allows inheriting file descriptors. Useful for process substitution
+                            universal_newlines=True)
+    stdout, stderr = proc.communicate()
+
+    return (
+        stdout or '\n',
+        stderr,
+        proc.returncode
+    )
+
+
+def combined_exit_code(program_exit=0, jc_exit=0):
+    exit_code = program_exit + jc_exit
+    exit_code = min(exit_code, 255)
+    return exit_code
 
 
 def main():
@@ -410,67 +400,184 @@ def main():
     except AttributeError:
         pass
 
+    # enable colors for Windows cmd.exe terminal
+    if sys.platform.startswith('win32'):
+        os.system('')
+
+    # parse magic syntax first: e.g. jc -p ls -al
+    magic_options = []
+    valid_command, run_command, magic_found_parser, magic_options = magic_parser(sys.argv)
+
+    # set colors
     jc_colors = os.getenv('JC_COLORS')
 
-    # try magic syntax first: e.g. jc -p ls -al
-    magic()
-
+    # set options
     options = []
+    options.extend(magic_options)
 
-    # options
-    for opt in sys.argv:
-        if opt.startswith('-') and not opt.startswith('--'):
-            options.extend(opt[1:])
+    # find options if magic_parser did not find a command
+    if not valid_command:
+        for opt in sys.argv:
+            if opt.startswith('-') and not opt.startswith('--'):
+                options.extend(opt[1:])
 
+    about = 'a' in options
     debug = 'd' in options
-    verbose_debug = True if options.count('d') > 1 else False
-    mono = 'm' in options
+    verbose_debug = options.count('d') > 1
+    force_color = 'C' in options
+    mono = ('m' in options or bool(os.getenv('NO_COLOR'))) and not force_color
+    help_me = 'h' in options
     pretty = 'p' in options
     quiet = 'q' in options
+    ignore_exceptions = options.count('q') > 1
     raw = 'r' in options
+    unbuffer = 'u' in options
+    version_info = 'v' in options
 
     if verbose_debug:
-        import jc.tracebackplus
-        jc.tracebackplus.enable(context=11)
+        tracebackplus.enable(context=11)
 
-    if 'a' in options:
-        print(json_out(about_jc(), pretty=pretty, env_colors=jc_colors, mono=mono, piped_out=piped_output()))
+    if not PYGMENTS_INSTALLED:
+        mono = True
+
+    if about:
+        print(json_out(about_jc(),
+              pretty=pretty,
+              env_colors=jc_colors,
+              mono=mono,
+              piped_out=piped_output(force_color)))
         sys.exit(0)
 
-    if sys.stdin.isatty():
-        print(helptext('missing piped data'), file=sys.stderr)
-        sys.exit(1)
+    if help_me:
+        print(help_doc(sys.argv))
+        sys.exit(0)
 
-    data = sys.stdin.read()
+    if version_info:
+        print(versiontext())
+        sys.exit(0)
 
-    found = False
+    # if magic syntax used, try to run the command and error if it's not found, etc.
+    magic_stdout, magic_stderr, magic_exit_code = None, None, 0
+    if run_command:
+        try:
+            run_command_str = shlex.join(run_command)      # python 3.8+
+        except AttributeError:
+            run_command_str = ' '.join(run_command)        # older python versions
 
-    for arg in sys.argv:
-        parser_name = parser_shortname(arg)
+    if valid_command:
+        try:
+            magic_stdout, magic_stderr, magic_exit_code = run_user_command(run_command)
+            if magic_stderr:
+                print(magic_stderr[:-1], file=sys.stderr)
 
-        if parser_name in parsers:
-            # load parser module just in time so we don't need to load all modules
-            parser = parser_module(arg)
-            try:
-                result = parser.parse(data, raw=raw, quiet=quiet)
+        except OSError as e:
+            if debug:
+                raise
+
+            error_msg = os.strerror(e.errno)
+            utils.error_message([f'"{run_command_str}" command could not be run: {error_msg}. For details use the -d or -dd option.'])
+            sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
+
+        except Exception:
+            if debug:
+                raise
+
+            utils.error_message([f'"{run_command_str}" command could not be run. For details use the -d or -dd option.'])
+            sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
+
+    elif run_command is not None:
+        utils.error_message([f'"{run_command_str}" cannot be used with Magic syntax. Use "jc -h" for help.'])
+        sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
+
+    # find the correct parser
+    if magic_found_parser:
+        parser = parser_module(magic_found_parser)
+        parser_name = parser_shortname(magic_found_parser)
+
+    else:
+        found = False
+        for arg in sys.argv:
+            parser_name = parser_shortname(arg)
+
+            if parser_name in parsers:
+                parser = parser_module(arg)
                 found = True
                 break
 
-            except Exception:
-                if debug:
-                    raise
-                else:
-                    import jc.utils
-                    jc.utils.error_message(
-                        f'{parser_name} parser could not parse the input data. Did you use the correct parser?\n'
-                        '                 For details use the -d or -dd option.')
-                    sys.exit(1)
+        if not found:
+            utils.error_message(['Missing or incorrect arguments. Use "jc -h" for help.'])
+            sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
 
-    if not found:
-        print(helptext('missing or incorrect arguments'), file=sys.stderr)
-        sys.exit(1)
+    # check for input errors (pipe vs magic)
+    if not sys.stdin.isatty() and magic_stdout:
+        utils.error_message(['Piped data and Magic syntax used simultaneously. Use "jc -h" for help.'])
+        sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
 
-    print(json_out(result, pretty=pretty, env_colors=jc_colors, mono=mono, piped_out=piped_output()))
+    elif sys.stdin.isatty() and magic_stdout is None:
+        utils.error_message(['Missing piped data. Use "jc -h" for help.'])
+        sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
+
+    # parse and print to stdout
+    try:
+        # differentiate between regular and streaming parsers
+
+        # streaming
+        if getattr(parser.info, 'streaming', None):
+            result = parser.parse(sys.stdin, raw=raw, quiet=quiet, ignore_exceptions=ignore_exceptions)
+            for line in result:
+                print(json_out(line,
+                               pretty=pretty,
+                               env_colors=jc_colors,
+                               mono=mono,
+                               piped_out=piped_output(force_color)),
+                      flush=unbuffer)
+
+            sys.exit(combined_exit_code(magic_exit_code, 0))
+
+        # regular
+        else:
+            data = magic_stdout or sys.stdin.read()
+            result = parser.parse(data, raw=raw, quiet=quiet)
+            print(json_out(result,
+                           pretty=pretty,
+                           env_colors=jc_colors,
+                           mono=mono,
+                           piped_out=piped_output(force_color)),
+                  flush=unbuffer)
+
+        sys.exit(combined_exit_code(magic_exit_code, 0))
+
+    except (ParseError, LibraryNotInstalled) as e:
+        if debug:
+            raise
+
+        utils.error_message([f'Parser issue with {parser_name}:',
+                             f'{e.__class__.__name__}: {e}',
+                             'For details use the -d or -dd option. Use "jc -h" for help.'])
+        sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
+
+    except json.JSONDecodeError:
+        if debug:
+            raise
+
+        utils.error_message(['There was an issue generating the JSON output.',
+                             'For details use the -d or -dd option.'])
+        sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
+
+    except Exception:
+        if debug:
+            raise
+
+        streaming_msg = ''
+        if getattr(parser.info, 'streaming', None):
+            streaming_msg = 'Use the -qq option to ignore streaming parser errors.'
+
+        utils.error_message([
+            f'{parser_name} parser could not parse the input data. Did you use the correct parser?',
+            f'{streaming_msg}',
+            'For details use the -d or -dd option. Use "jc -h" for help.'
+        ])
+        sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
 
 
 if __name__ == '__main__':

jc/exceptions.py

@@ -0,0 +1,9 @@
+"""jc - JSON CLI output utility exceptions"""
+
+
+class ParseError(Exception):
+    pass
+
+
+class LibraryNotInstalled(Exception):
+    pass