Merge pull request #198 from kellyjonbrazil/dev

Dev v1.18.0

CHANGELOG

@@ -1,5 +1,11 @@
 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
 

README.md

@@ -32,10 +32,10 @@ $ jc dig example.com | jq -r '.[].answer[].data'
 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 subprocess
->>> import jc.parsers.dig
+>>> import jc
 >>>
 >>> cmd_output = subprocess.check_output(['dig', 'example.com'], text=True)
->>> data = jc.parsers.dig.parse(cmd_output)
+>>> data = jc.parse('dig', cmd_output)
 >>>
 >>> data
 [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', 'flags': ['qr', 'rd', 'ra'], 'query_num': 1, 'answer_num':
@@ -45,6 +45,9 @@ The `jc` parsers can also be used as python modules. In this case the output wil
 '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}]
 ```
+
+> 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()`.
@@ -290,9 +293,9 @@ Streaming parsers accept any iterable object and return a generator iterator obj
 
 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.parsers.ls_s
+import jc
 
-result = jc.parsers.ls_s.parse(ls_command_output.splitlines())
+result = jc.parse('ls_s', ls_command_output.splitlines())
 for item in result:
     print(item["filename"])
 ```

docgen.sh

@@ -5,9 +5,16 @@
 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
 
+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. :)
 

docs/_config.yml

@@ -1 +0,0 @@
-theme: jekyll-theme-cayman

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

@@ -13,6 +13,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('acpi', acpi_command_output)
+
+    or
+
     import jc.parsers.acpi
     result = jc.parsers.acpi.parse(acpi_command_output)
 
@@ -242,7 +247,7 @@ 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:

docs/parsers/airport.md

@@ -15,6 +15,11 @@ 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)
 
@@ -95,7 +100,7 @@ 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:

docs/parsers/airport_s.md

@@ -15,6 +15,11 @@ 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)
 
@@ -123,7 +128,7 @@ 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:

docs/parsers/arp.md

@@ -15,6 +15,11 @@ 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)
 
@@ -132,7 +137,7 @@ 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:

docs/parsers/blkid.md

@@ -13,6 +13,11 @@ 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)
 
@@ -135,7 +140,7 @@ 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:

docs/parsers/cksum.md

@@ -17,6 +17,11 @@ 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)
 
@@ -69,7 +74,7 @@ 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:

docs/parsers/crontab.md

@@ -1,7 +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.
 
@@ -15,6 +16,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('crontab', crontab_output)
+
+    or
+
     import jc.parsers.crontab
     result = jc.parsers.crontab.parse(crontab_output)
 
@@ -187,7 +193,7 @@ 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:

docs/parsers/crontab_u.md

@@ -1,9 +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):
 
@@ -11,6 +13,11 @@ 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)
 
@@ -55,7 +62,7 @@ Examples:
       "variables": [
         {
           "name": "PATH",
-          "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin"
+          "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sb..."
         },
         {
           "name": "SHELL",
@@ -80,7 +87,7 @@ Examples:
             "*"
           ],
           "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily )"
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
         },
         {
           "minute": [
@@ -99,7 +106,7 @@ Examples:
             "7"
           ],
           "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly )"
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
         },
         {
           "minute": [
@@ -118,7 +125,7 @@ Examples:
             "*"
           ],
           "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )"
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
         }
       ]
     }
@@ -128,7 +135,7 @@ Examples:
       "variables": [
         {
           "name": "PATH",
-          "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin"
+          "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/..."
         },
         {
           "name": "SHELL",
@@ -143,7 +150,7 @@ Examples:
           "month": "*",
           "day_of_week": "*",
           "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily )"
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
         },
         {
           "minute": "47",
@@ -152,7 +159,7 @@ Examples:
           "month": "*",
           "day_of_week": "7",
           "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly )"
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
         },
         {
           "minute": "52",
@@ -161,7 +168,7 @@ Examples:
           "month": "*",
           "day_of_week": "*",
           "user": "root",
-          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )"
+          "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..."
         }
       ]
     }
@@ -183,7 +190,7 @@ 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:

docs/parsers/csv.md

@@ -3,7 +3,9 @@
 # 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):
 
@@ -11,12 +13,18 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('csv', csv_output)
+
+    or
+
     import jc.parsers.csv
     result = jc.parsers.csv.parse(csv_output)
 
 Schema:
 
-    csv file converted to a Dictionary: https://docs.python.org/3/library/csv.html
+    csv file converted to a Dictionary:
+    https://docs.python.org/3/library/csv.html
 
     [
       {
@@ -28,7 +36,7 @@ Schema:
 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
@@ -89,7 +97,7 @@ 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:

docs/parsers/csv_s.md

@@ -5,9 +5,12 @@ 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.
+The `csv` streaming parser will attempt to automatically detect the
+delimiter character. If the delimiter cannot be detected it will default
+to comma. The first row of the file must be a header row.
 
-Note: The first 100 rows are read into memory to enable delimiter detection, then the rest of the rows are loaded lazily.
+Note: The first 100 rows are read into memory to enable delimiter detection,
+then the rest of the rows are loaded lazily.
 
 Usage (cli):
 
@@ -15,21 +18,34 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    # result is an iterable object (generator)
+    result = jc.parse('csv_s', csv_output.splitlines())
+    for item in result:
+        # do something
+
+    or
+
     import jc.parsers.csv_s
-    result = jc.parsers.csv_s.parse(csv_output.splitlines())    # result is an iterable object
+    # 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
+    csv file converted to a Dictionary:
+    https://docs.python.org/3/library/csv.html
 
     {
       "column_name1":     string,
       "column_name2":     string,
-      "_jc_meta":                      # This object only exists if using -qq or ignore_exceptions=True
+
+      # below object only exists if using -qq or ignore_exceptions=True
+
+      "_jc_meta":
         {
-          "success":      boolean,     # true if successfully parsed, false if error
+          "success":      boolean,     # false if error parsing
           "error":        string,      # exists if "success" is false
           "line":         string       # exists if "success" is false
         }
@@ -38,16 +54,16 @@ Schema:
 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
     ...
 
     $ cat homes.csv | jc --csv-s
-    {"Sell":"142","List":"160","Living":"28","Rooms":"10","Beds":"5","Baths":"3","Age":"60","Acres":"0.28","Taxes":"3167"}
+    {"Sell":"142","List":"160","Living":"28","Rooms":"10","Beds":"5"...}
-    {"Sell":"175","List":"180","Living":"18","Rooms":"8","Beds":"4","Baths":"1","Age":"12","Acres":"0.43","Taxes":"4033"}
+    {"Sell":"175","List":"180","Living":"18","Rooms":"8","Beds":"4"...}
-    {"Sell":"129","List":"132","Living":"13","Rooms":"6","Beds":"3","Baths":"1","Age":"41","Acres":"0.33","Taxes":"1471"}
+    {"Sell":"129","List":"132","Living":"13","Rooms":"6","Beds":"3"...}
     ...
 
 
@@ -66,8 +82,10 @@ 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())
+    data:              (iterable)  line-based text data to parse
-    raw:               (boolean)   output preprocessed JSON if True
+                                   (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
 

docs/parsers/date.md

@@ -3,9 +3,11 @@
 # 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` 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.
+The `epoch_utc` calculated timestamp field is timezone-aware and is only
+available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -17,6 +19,11 @@ 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)
 
@@ -39,11 +46,15 @@ Schema:
       "day_of_year":        integer,
       "week_of_year":       integer,
       "iso":                string,
-      "epoch":              integer,      # naive timestamp
+      "epoch":              integer,     # [0]
-      "epoch_utc":          integer,      # timezone-aware timestamp. Only available if timezone field is UTC
+      "epoch_utc":          integer,     # [1]
-      "timezone_aware":     boolean       # if true, all fields are correctly based on UTC
+      "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
@@ -86,7 +97,7 @@ 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:

docs/parsers/df.md

@@ -13,6 +13,11 @@ 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)
 
@@ -112,7 +117,7 @@ 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:

docs/parsers/dig.md

@@ -4,12 +4,15 @@
 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.
+- `+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` 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.
+The `when_epoch_utc` calculated timestamp field is timezone-aware and is
+only available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -21,6 +24,11 @@ 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)
 
@@ -93,13 +101,16 @@ Schema:
         "query_time":           integer,   # in msec
         "server":               string,
         "when":                 string,
-        "when_epoch":           integer,   # naive timestamp if when field is parsable, else null
+        "when_epoch":           integer,   # [0]
-        "when_epoch_utc":       integer,   # timezone aware timestamp availabe for UTC, else null
+        "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 example.com | jc --dig -p
@@ -331,7 +342,7 @@ 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:

docs/parsers/dir.md

@@ -9,9 +9,11 @@ Options supported:
 - `/C, /-C`
 - `/S`
 
-The "Magic" syntax is not supported since the `dir` command is a shell builtin.
+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)
+The `epoch` calculated timestamp field is naive. (i.e. based on the local
+time of the system the parser is run on)
 
 Usage (cli):
 
@@ -19,6 +21,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('dir', dir_command_output)
+
+    or
+
     import jc.parsers.dir
     result = jc.parsers.dir.parse(dir_command_output)
 
@@ -133,7 +140,7 @@ 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:

docs/parsers/dmidecode.md

@@ -13,6 +13,11 @@ 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)
 
@@ -24,7 +29,7 @@ Schema:
         "type":                        integer,
         "bytes":                       integer,
         "description":                 string,
-        "values": {                               (null if empty)
+        "values": {                                 # null if empty
           "lowercase_no_spaces_keys":  string,
           "multiline_key_values": [
                                        string,
@@ -140,7 +145,7 @@ 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:

docs/parsers/dpkg_l.md

@@ -3,7 +3,8 @@
 # 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:
+Set the `COLUMNS` environment variable to a large value to avoid field
+truncation. For example:
 
     $ COLUMNS=500 dpkg -l | jc --dpkg-l
 
@@ -17,6 +18,11 @@ Usage (cli):
 
 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)
 
@@ -72,7 +78,7 @@ Examples:
         "name": "acpid",
         "version": "1:2.0.28-1ubuntu1",
         "architecture": "amd64",
-        "description": "Advanced Configuration and Power Interface event daemon",
+        "description": "Advanced Configuration and Power Interface...",
         "desired": "remove",
         "status": "half installed"
       },
@@ -116,7 +122,7 @@ Examples:
         "name": "acpid",
         "version": "1:2.0.28-1ubuntu1",
         "architecture": "amd64",
-        "description": "Advanced Configuration and Power Interface event daemon"
+        "description": "Advanced Configuration and Power Interface..."
       },
       {
         "codes": "pn",
@@ -145,7 +151,7 @@ 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:

docs/parsers/du.md

@@ -13,6 +13,11 @@ 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)
 
@@ -35,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/..."
       },
       ...
     ]
@@ -64,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/..."
       },
       ...
     ]
@@ -102,7 +107,7 @@ 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:

docs/parsers/env.md

@@ -3,7 +3,10 @@
 # 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):
 
@@ -15,6 +18,11 @@ 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)
 
@@ -84,7 +92,7 @@ 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:

docs/parsers/file.md

@@ -13,6 +13,11 @@ 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)
 
@@ -21,7 +26,7 @@ Schema:
     [
       {
         "filename":   string,
-        "type   ":    string
+        "type":       string
       }
     ]
 
@@ -51,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 ..."
       },
       ...
     ]
@@ -77,7 +82,7 @@ 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:

docs/parsers/finger.md

@@ -15,6 +15,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('finger', finger_command_output)
+
+    or
+
     import jc.parsers.finger
     result = jc.parsers.finger.parse(finger_command_output)
 
@@ -105,7 +110,7 @@ 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:

docs/parsers/free.md

@@ -13,6 +13,11 @@ 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)
 
@@ -87,7 +92,7 @@ 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:

docs/parsers/fstab.md

@@ -9,6 +9,11 @@ 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)
 
@@ -100,7 +105,7 @@ 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:

docs/parsers/group.md

@@ -9,6 +9,11 @@ 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)
 
@@ -124,7 +129,7 @@ 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:

docs/parsers/gshadow.md

@@ -9,6 +9,11 @@ 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)
 
@@ -92,7 +97,7 @@ 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:

docs/parsers/hash.md

@@ -9,6 +9,11 @@ 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)
 
@@ -52,7 +57,7 @@ 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:

docs/parsers/hashsum.md

@@ -23,6 +23,11 @@ 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)
 
@@ -83,7 +88,7 @@ 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:

docs/parsers/hciconfig.md

@@ -13,6 +13,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('hciconfig', hciconfig_command_output)
+
+    or
+
     import jc.parsers.hciconfig
     result = jc.parsers.hciconfig.parse(hciconfig_command_output)
 
@@ -332,7 +337,7 @@ 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:

docs/parsers/history.md

@@ -3,9 +3,13 @@
 # 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.
+The "Magic" syntax is not supported since the `history` command is a shell
+builtin.
 
 Usage (cli):
 
@@ -13,6 +17,11 @@ 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)
 
@@ -74,7 +83,7 @@ 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:

docs/parsers/hosts.md

@@ -9,6 +9,11 @@ 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)
 
@@ -89,7 +94,7 @@ 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:

docs/parsers/id.md

@@ -13,6 +13,11 @@ 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)
 
@@ -120,7 +125,7 @@ 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:

docs/parsers/ifconfig.md

@@ -15,6 +15,11 @@ 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)
 
@@ -201,7 +206,7 @@ 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:

docs/parsers/ini.md

@@ -3,9 +3,13 @@
 # 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):
 
@@ -13,16 +17,18 @@ 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)
 
 Schema:
 
-    ini or key/value document converted to a dictionary - see configparser standard
+    ini or key/value document converted to a dictionary - see the
-          library documentation for more details.
+    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.
 
     {
       "key1":       string,
@@ -80,7 +86,7 @@ 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:

docs/parsers/iostat.md

@@ -15,6 +15,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('iostat', iostat_command_output)
+
+    or
+
     import jc.parsers.iostat
     result = jc.parsers.iostat.parse(iostat_command_output)
 
@@ -174,7 +179,7 @@ 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:

docs/parsers/iostat_s.md

@@ -13,8 +13,17 @@ Usage (cli):
 
 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 = jc.parsers.iostat_s.parse(iostat_command_output.splitlines())    # result is an iterable object
+    # result is an iterable object (generator)
+    result = jc.parsers.iostat_s.parse(iostat_command_output.splitlines())
     for item in result:
         # do something
 
@@ -71,9 +80,12 @@ Schema:
       "percent_util":     float,
       "percent_rrqm":     float,
       "percent_wrqm":     float,
-      "_jc_meta":                      # This object only exists if using -qq or ignore_exceptions=True
+
+      # Below object only exists if using -qq or ignore_exceptions=True
+
+      "_jc_meta":
         {
-          "success":      boolean,     # true if successfully parsed, false if error
+          "success":      boolean,     # false if error parsing
           "error":        string,      # exists if "success" is false
           "line":         string       # exists if "success" is false
         }
@@ -82,13 +94,13 @@ Schema:
 Examples:
 
     $ iostat | jc --iostat-s
-    {"percent_user":0.14,"percent_nice":0.0,"percent_system":0.16,"percent_iowait":0.0,"percent_steal":0.0,"percent_idle":99.7,"type":"cpu"}
+    {"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,"kb_read":203305,"kb_wrtn":42368,"type":"device"}
+    {"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","percent_iowait":"0.00","percent_steal":"0.00","percent_idle":"99.70","type":"cpu"}
+    {"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","kb_read":"203305","kb_wrtn":"42368","type":"device"}
+    {"device":"sda","tps":"0.24","kb_read_s":"5.28","kb_wrtn_s":"1.10"...}
     ...
 
 
@@ -107,8 +119,10 @@ 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())
+    data:              (iterable)  line-based text data to parse
-    raw:               (boolean)   output preprocessed JSON if True
+                                   (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
 

docs/parsers/iptables.md

@@ -1,7 +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.
 
@@ -15,6 +15,11 @@ 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)
 
@@ -178,7 +183,7 @@ 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:

docs/parsers/iw_scan.md

@@ -3,7 +3,8 @@
 # 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.
+This parser is considered beta quality. Not all fields are parsed and there
+are not enough samples to test.
 
 Usage (cli):
 
@@ -15,8 +16,13 @@ Usage (cli):
 
 Usage (module):
 
-    import jc.parsers.iw-scan
+    import jc
-    result = jc.parsers.iw-scan.parse(iw-scan_command_output)
+    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:
 
@@ -135,7 +141,7 @@ 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:

docs/parsers/jar_manifest.md

@@ -9,6 +9,11 @@ Usage (cli):
 
 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)
 
@@ -24,15 +29,16 @@ Schema:
 Examples:
 
     $ cat MANIFEST.MF | jc --jar-manifest -p
-    $ unzip -c apache-log4j-2.16.0-bin/log4j-core-2.16.0.jar META-INF/MANIFEST.MF | jc --jar-manifest -p
+    $ unzip -c log4j-core-2.16.0.jar META-INF/MANIFEST.MF | \
-    $ unzip -c 'apache-log4j-2.16.0-bin/*.jar' META-INF/MANIFEST.MF | jc --jar-manifest -p
+      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;resolution:=optional,com.fasterxml.jackson.annotation;version="[2.12,3)";resolution:=optional,com.fasterxml.jackson.core;version="[2.12,3)";resolution:=optional,com.fasterxml.jackson.core.type;version="[2.12,3)";resolution:=optional,com.fasterxml.jackson.cor...",
+        "Import_Package": "com.conversantmedia.util.concurrent;resoluti...",
-        "Export_Package": "org.apache.logging.log4j.core;uses:="org.apache.logging.log4j,org.apache.logging.log4j.core.config,org.apache.logging.log4j.core.impl,org.apache.logging.log4j.core.layout,org.apache.logging.log4j.core.time,org.apache.logging.log4j.message,org.apache.logging.log4j.spi,org.apache.logging.log4j.status...",
+        "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",
@@ -45,28 +51,28 @@ Examples:
       }
     ]
 
-    $ unzip -c 'apache-log4j-2.16.0-bin/*.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
     [
       ...
       {
-        "Archive": "apache-log4j-2.16.0-bin/log4j-spring-boot-2.16.0-sources.jar",
+        "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-javadoc.jar",
+        "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-config-client.logging.log4j.core.util;version="[2.16,3)",org.springframework.boot.autoconfigure.condition,org.springframework.cloud.context.environment,org.springframework.context,org.springframework.stereotype",
+        "Bundle_SymbolicName": "org.apache.logging.log4j.spring-cloud-c...",
-        "Export_Package": "org.apache.logging.log4j.spring.cloud.config.controller;version="2.16.0"ient",
+        "Export_Package": "org.apache.logging.log4j.spring.cloud.config...",
-        "Archive": "apache-log4j-2.16.0-bin/log4j-spring-cloud-config-client-2.16.0.jar",
+        "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",
         ...
@@ -91,7 +97,7 @@ 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:

docs/parsers/jobs.md

@@ -5,7 +5,8 @@ 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.
+The "Magic" syntax is not supported since the `jobs` command is a shell
+builtin.
 
 Usage (cli):
 
@@ -13,6 +14,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('jobs', jobs_command_output)
+
+    or
+
     import jc.parsers.jobs
     result = jc.parsers.jobs.parse(jobs_command_output)
 
@@ -107,7 +113,7 @@ 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:

docs/parsers/kv.md

@@ -3,9 +3,13 @@
 # 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.
+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()`.
+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,18 @@ 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)
 
 Schema:
 
-    key/value document converted to a dictionary - see configparser standard library documentation for more details.
+    key/value document converted to a dictionary - see the
+    configparser standard library documentation for more details.
 
     {
       "key1":       string,
@@ -65,7 +75,7 @@ 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:

docs/parsers/last.md

@@ -5,7 +5,9 @@ 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.
+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):
 
@@ -17,6 +19,11 @@ 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)
 
@@ -30,9 +37,9 @@ Schema:
         "login":            string,
         "logout":           string,
         "duration":         string,
-        "login_epoch":      integer,   # (naive) available with last -F option
+        "login_epoch":      integer,  # (naive) available w/last -F option
-        "logout_epoch":     integer,   # (naive) available with last -F option
+        "logout_epoch":     integer,  # (naive) available w/last -F option
-        "duration_seconds": integer    # available with last -F option
+        "duration_seconds": integer   # available w/last -F option
       }
     ]
 
@@ -118,7 +125,7 @@ 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:

docs/parsers/ls.md

@@ -7,11 +7,17 @@ Options supported:
 - `lbaR1`
 - `--time-style=full-iso`
 
-Note: The `-1`, `-l`, or `-b` option of `ls` should be used to correctly parse filenames that include newline characters. Since `ls` does not encode newlines in filenames when outputting to a pipe it will cause `jc` to see multiple files instead of a single file if `-1`, `-l`, or `-b` is not used. Alternatively, `vdir` can be used, which is the same as running `ls -lb`.
+Note: The `-1`, `-l`, or `-b` option of `ls` should be used to correctly
+parse filenames that include newline characters. Since `ls` does not encode
+newlines in filenames when outputting to a pipe it will cause `jc` to see
+multiple files instead of a single file if `-1`, `-l`, or `-b` is not used.
+Alternatively, `vdir` can be used, which is the same as running `ls -lb`.
 
-The `epoch` calculated timestamp field is naive (i.e. based on the local time of the system the parser is run on)
+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.
+The `epoch_utc` calculated timestamp field is timezone-aware and is only
+available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -23,6 +29,11 @@ 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)
 
@@ -38,11 +49,15 @@ Schema:
         "group":        string,
         "size":         integer,
         "date":         string,
-        "epoch":        integer,     # naive timestamp if date field exists and can be converted
+        "epoch":        integer,     # [0]
-        "epoch_utc":    integer      # timezone aware timestamp if date field is in UTC and can be converted
+        "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:
 
     $ ls /usr/bin | jc --ls -p
@@ -121,7 +136,7 @@ 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:

docs/parsers/ls_s.md

@@ -1,17 +1,22 @@
 [Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.ls_s
-jc - JSON CLI output utility `ls` and `vdir` command output streaming parser
+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`.
+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 `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` 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.
+The `epoch_utc` calculated timestamp field is timezone-aware and is only
+available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -19,8 +24,17 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    # result is an iterable object (generator)
+    result = jc.parse('ls_s', ls_command_output.splitlines())
+    for item in result:
+        # do something
+
+    or
+
     import jc.parsers.ls_s
-    result = jc.parsers.ls_s.parse(ls_command_output.splitlines())    # result is an iterable object
+    # result is an iterable object (generator)
+    result = jc.parsers.ls_s.parse(ls_command_output.splitlines())
     for item in result:
         # do something
 
@@ -35,28 +49,35 @@ Schema:
       "group":          string,
       "size":           integer,
       "date":           string,
-      "epoch":          integer,     # naive timestamp if date field exists and can be converted
+      "epoch":          integer,     # [0]
-      "epoch_utc":      integer,     # timezone aware timestamp if date field is in UTC and can be converted
+      "epoch_utc":      integer,     # [1]
-      "_jc_meta":                    # This object only exists if using -qq or ignore_exceptions=True
+
+      # Below object only exists if using -qq or ignore_exceptions=True
+
+      "_jc_meta":
         {
-          "success":    boolean,     # true if successfully parsed, false if error
+          "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","group":"wheel","size":925,"date":"Feb 22 2019"}
+    {"filename":"2to3-","flags":"-rwxr-xr-x","links":4,"owner":"root","...}
-    {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/Python.framework/Versions/2.7/bin/2to3-2.7","flags":"lrwxr-xr-x","links":1,"owner":"root","group":"wheel","size":74,"date":"May 4 2019"}
+    {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/P...}
-    {"filename":"AssetCacheLocatorUtil","flags":"-rwxr-xr-x","links":1,"owner":"root","group":"wheel","size":55152,"date":"May 3 2019"}
+    {"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":"root","group":"wheel","size":"925","date":"Feb 22 2019"}
+    {"filename":"2to3-","flags":"-rwxr-xr-x","links":"4","owner":"roo"..."}
-    {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/Python.framework/Versions/2.7/bin/2to3-2.7","flags":"lrwxr-xr-x","links":"1","owner":"root","group":"wheel","size":"74","date":"May 4 2019"}
+    {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/P...}
-    {"filename":"AssetCacheLocatorUtil","flags":"-rwxr-xr-x","links":"1","owner":"root","group":"wheel","size":"55152","date":"May 3 2019"}
+    {"filename":"AssetCacheLocatorUtil","flags":"-rwxr-xr-x","links":"1...}
     ...
 
 
@@ -75,8 +96,10 @@ 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())
+    data:              (iterable)  line-based text data to parse
-    raw:               (boolean)   output preprocessed JSON if True
+                                   (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
 

docs/parsers/lsblk.md

@@ -13,6 +13,11 @@ 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)
 
@@ -88,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",
@@ -177,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",
@@ -283,7 +294,7 @@ 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:

docs/parsers/lsmod.md

@@ -13,6 +13,11 @@ 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)
 
@@ -140,7 +145,7 @@ 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:

docs/parsers/lsof.md

@@ -13,6 +13,11 @@ 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)
 
@@ -134,7 +139,7 @@ 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:

docs/parsers/lsusb.md

@@ -15,13 +15,19 @@ Usage (cli):
 
 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.
+    Note: <item> object keynames are assigned directly from the lsusb
-          If there are duplicate <item> names in a section, only the last one is converted.
+          output. If there are duplicate <item> names in a section, only the
+          last one is converted.
 
     [
       {
@@ -275,7 +281,7 @@ 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:

docs/parsers/mount.md

@@ -13,6 +13,11 @@ 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)
 
@@ -90,7 +95,7 @@ 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:

docs/parsers/netstat.md

@@ -5,7 +5,8 @@ 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):
 
@@ -17,6 +18,11 @@ 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)
 
@@ -369,7 +375,7 @@ 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:

docs/parsers/ntpq.md

@@ -13,6 +13,11 @@ 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)
 
@@ -221,7 +226,7 @@ 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:

docs/parsers/passwd.md

@@ -9,6 +9,11 @@ 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)
 
@@ -109,7 +114,7 @@ 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:

docs/parsers/ping.md

@@ -7,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
 
@@ -17,6 +18,11 @@ 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)
 
@@ -26,7 +32,7 @@ Schema:
       "source_ip":                   string,
       "destination_ip":              string,
       "data_bytes":                  integer,
-      "pattern":                     string,        # (null if not set)
+      "pattern":                     string,        # null if not set
       "destination":                 string,
       "packets_transmitted":         integer,
       "packets_received":            integer,
@@ -38,8 +44,8 @@ Schema:
       "round_trip_ms_stddev":        float,
       "responses": [
         {
-          "type":                    string,        # 'reply', 'timeout', 'unparsable_line', etc. See `_error_type.type_map` for all options
+          "type":                    string,        # [0]
-          "unparsed_line":           string,        # only if an 'unparsable_line' type
+          "unparsed_line":           string,        # [1]
           "timestamp":               float,
           "bytes":                   integer,
           "response_ip":             string,
@@ -47,21 +53,26 @@ Schema:
           "ttl":                     integer,
           "time_ms":                 float,
           "duplicate":               boolean,
-          "vr":                      integer,       # hex value converted to decimal
+          "vr":                      integer,       # [2]
-          "hl":                      integer,       # hex value converted to decimal
+          "hl":                      integer,       # [2]
-          "tos":                     integer,       # hex value converted to decimal
+          "tos":                     integer,       # [2]
-          "len":                     integer,       # hex value converted to decimal
+          "len":                     integer,       # [2]
-          "id":                      integer,       # hex value converted to decimal
+          "id":                      integer,       # [2]
-          "flg":                     integer,       # hex value converted to decimal
+          "flg":                     integer,       # [2]
-          "off":                     integer,       # hex value converted to decimal
+          "off":                     integer,       # [2]
-          "pro":                     integer,       # hex value converted to decimal
+          "pro":                     integer,       # [2]
-          "cks":                     ingeger,       # hex value converted to decimal
+          "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:
 
     $ ping -c 3 -p ff cnn.com | jc --ping -p
@@ -171,7 +182,7 @@ 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:

docs/parsers/ping_s.md

@@ -11,19 +11,33 @@ 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.
+> 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 = jc.parsers.ping_s.parse(ping_command_output.splitlines())    # result is an iterable object
+    # 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,        # 'reply', 'timeout', 'summary', etc. See `_error_type.type_map` for all options.
+      "type":                       string,   # [0]
       "source_ip":                  string,
       "destination_ip":             string,
       "sent_bytes":                 integer,
@@ -44,26 +58,32 @@ Schema:
       "round_trip_ms_avg":          float,
       "round_trip_ms_max":          float,
       "round_trip_ms_stddev":       float,
-      "_jc_meta":                                  # This object only exists if using -qq or ignore_exceptions=True
+
+      # Below object only exists if using -qq or ignore_exceptions=True
+
+      "_jc_meta":
         {
-          "success":                 boolean,      # true if successfully parsed, false if error
+          "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,"pattern":null,"response_bytes":64,"response_ip":"1.1.1.1","icmp_seq":0,"ttl":56,"time_ms":23.703}
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"patte...}
-    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"pattern":null,"response_bytes":64,"response_ip":"1.1.1.1","icmp_seq":1,"ttl":56,"time_ms":22.862}
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"patte...}
-    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"pattern":null,"response_bytes":64,"response_ip":"1.1.1.1","icmp_seq":2,"ttl":56,"time_ms":22.82}
+    {"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","pattern":null,"response_bytes":"64","response_ip":"1.1.1.1","icmp_seq":"0","ttl":"56","time_ms":"23.054"}
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","patte...}
-    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","pattern":null,"response_bytes":"64","response_ip":"1.1.1.1","icmp_seq":"1","ttl":"56","time_ms":"24.739"}
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","patte...}
-    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","pattern":null,"response_bytes":"64","response_ip":"1.1.1.1","icmp_seq":"2","ttl":"56","time_ms":"23.232"}
+    {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","patte...}
     ...
 
 
@@ -82,8 +102,10 @@ 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())
+    data:              (iterable)  line-based text data to parse
-    raw:               (boolean)   output preprocessed JSON if True
+                                   (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
 

docs/parsers/pip_list.md

@@ -13,6 +13,11 @@ 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)
 
@@ -62,7 +67,7 @@ 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:

docs/parsers/pip_show.md

@@ -13,6 +13,11 @@ 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)
 
@@ -80,7 +85,7 @@ 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:

docs/parsers/ps.md

@@ -17,6 +17,11 @@ 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)
 
@@ -56,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",
@@ -91,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",
@@ -129,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",
@@ -173,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",
@@ -221,7 +226,7 @@ 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:

docs/parsers/route.md

@@ -13,6 +13,11 @@ 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)
 
@@ -123,7 +128,7 @@ 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:

docs/parsers/rpm_qi.md

@@ -5,9 +5,11 @@ 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` 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.
+The `..._epoch_utc` calculated timestamp fields are timezone-aware and is
+only available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -19,6 +21,11 @@ Usage (cli):
 
 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)
 
@@ -32,16 +39,16 @@ Schema:
         "release":                  string,
         "architecture":             string,
         "install_date":             string,
-        "install_date_epoch":       integer,          # naive timestamp
+        "install_date_epoch":       integer,      # [0]
-        "install_date_epoch_utc":   integer,          # Aware timestamp if timezone is UTC
+        "install_date_epoch_utc":   integer,      # [1]
         "group":                    string,
         "size":                     integer,
         "license":                  string,
         "signature":                string,
         "source_rpm":               string,
         "build_date":               string,
-        "build_epoch":              integer,          # naive timestamp
+        "build_epoch":              integer,      # [0]
-        "build_epoch_utc":          integer,          # Aware timestamp if timezone is UTC
+        "build_epoch_utc":          integer,      # [1]
         "build_host":               string,
         "relocations":              string,
         "packager":                 string,
@@ -52,6 +59,9 @@ Schema:
       }
     ]
 
+    [0] naive timestamp
+    [1] Aware timestamp if timezone is UTC
+
 Examples:
 
     $ rpm -qia | jc --rpm-qi -p
@@ -66,7 +76,7 @@ Examples:
         "group": "Development/Tools",
         "size": 1160660,
         "license": "GPLv2+",
-        "signature": "RSA/SHA256, Thu 22 Aug 2019 02:34:59 PM PDT, Key ID 24c6a8a7f4a80eb5",
+        "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",
@@ -74,8 +84,8 @@ Examples:
         "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 users",
+        "summary": "A GNU tool which simplifies the build process for ...",
-        "description": "A GNU tool for controlling the generation of executables and other...",
+        "description": "A GNU tool for controlling the generation of ex...",
         "build_epoch": 1565311645,
         "build_epoch_utc": null,
         "install_date_epoch": 1571242902,
@@ -90,7 +100,7 @@ Examples:
         "group": "System Environment/Base",
         "size": 503608,
         "license": "GPLv2+",
-        "signature": "RSA/SHA256, Mon 12 Nov 2018 07:17:49 AM PST, Key ID 24c6a8a7f4a80eb5",
+        "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",
@@ -99,7 +109,7 @@ Examples:
         "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 for kbd package...",
+        "description": "The kbd-legacy package contains original keymap...",
         "build_epoch": 1540939200,
         "build_epoch_utc": null,
         "install_date_epoch": 1565891588,
@@ -120,7 +130,7 @@ Examples:
         "group": "Development/Tools",
         "size": "1160660",
         "license": "GPLv2+",
-        "signature": "RSA/SHA256, Thu 22 Aug 2019 02:34:59 PM PDT, Key ID 24c6a8a7f4a80eb5",
+        "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",
@@ -128,8 +138,8 @@ Examples:
         "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 users",
+        "summary": "A GNU tool which simplifies the build process for...",
-        "description": "A GNU tool for controlling the generation of executables and other..."
+        "description": "A GNU tool for controlling the generation of exe..."
       },
       {
         "name": "kbd-legacy",
@@ -140,7 +150,7 @@ Examples:
         "group": "System Environment/Base",
         "size": "503608",
         "license": "GPLv2+",
-        "signature": "RSA/SHA256, Mon 12 Nov 2018 07:17:49 AM PST, Key ID 24c6a8a7f4a80eb5",
+        "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",
@@ -149,7 +159,7 @@ Examples:
         "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 for kbd package..."
+        "description": "The kbd-legacy package contains original keymaps..."
       },
       ...
     ]
@@ -171,7 +181,7 @@ 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:

docs/parsers/sfdisk.md

@@ -22,6 +22,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('sfdisk', sfdisk_command_output)
+
+    or
+
     import jc.parsers.sfdisk
     result = jc.parsers.sfdisk.parse(sfdisk_command_output)
 
@@ -53,7 +58,7 @@ Schema:
             "boot":                 boolean,
             "start":                integer,
             "end":                  integer,
-            "size":                 string,    # Note: will be integer when using deprecated -d sfdisk option
+            "size":                 string,    # [0]
             "cyls":                 integer,
             "mib":                  integer,
             "blocks":               integer,
@@ -66,6 +71,8 @@ Schema:
       }
     ]
 
+    [0] will be integer when using deprecated -d sfdisk option
+
 Examples:
 
     # sfdisk -l | jc --sfdisk -p
@@ -75,7 +82,7 @@ Examples:
         "cylinders": 2610,
         "heads": 255,
         "sectors_per_track": 63,
-        "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, counting from 0",
+        "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, ...",
         "partitions": [
           {
             "device": "/dev/sda1",
@@ -140,7 +147,7 @@ Examples:
         "cylinders": "2610",
         "heads": "255",
         "sectors_per_track": "63",
-        "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, counting from 0",
+        "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, co...",
         "partitions": [
           {
             "device": "/dev/sda1",
@@ -215,7 +222,7 @@ 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:

docs/parsers/shadow.md

@@ -9,6 +9,11 @@ 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)
 
@@ -116,7 +121,7 @@ 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:

docs/parsers/ss.md

@@ -3,7 +3,8 @@
 # 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.
+Extended information options like -e and -p are not supported and may cause
+parsing irregularities.
 
 Usage (cli):
 
@@ -15,12 +16,18 @@ 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)
 
 Schema:
 
-    Information from https://www.cyberciti.biz/files/ss.html used to define field names
+    Information from https://www.cyberciti.biz/files/ss.html used to define
+    field names
 
     [
       {
@@ -293,7 +300,7 @@ 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:

docs/parsers/stat.md

@@ -3,9 +3,11 @@
 # 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` 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.
+The `xxx_epoch_utc` calculated timestamp fields are timezone-aware and are
+only available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -17,6 +19,11 @@ 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)
 
@@ -183,7 +190,7 @@ 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:

docs/parsers/stat_s.md

@@ -5,9 +5,11 @@ 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` 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.
+The `xxx_epoch_utc` calculated timestamp fields are timezone-aware and are
+only available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -15,8 +17,17 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    # result is an iterable object (generator)
+    result = jc.parse('stat_s', stat_command_output.splitlines())
+    for item in result:
+        # do something
+
+    or
+
     import jc.parsers.stat_s
-    result = jc.parsers.stat_s.parse(stat_command_output.splitlines())    # result is an iterable object
+    # result is an iterable object (generator)
+    result = jc.parsers.stat_s.parse(stat_command_output.splitlines())
     for item in result:
         # do something
 
@@ -54,9 +65,12 @@ Schema:
       "rdev":                     integer,
       "block_size":               integer,
       "unix_flags":               string,
-      "_jc_meta":                            # This object only exists if using -qq or ignore_exceptions=True
+
+      # Below object only exists if using -qq or ignore_exceptions=True
+
+      "_jc_meta":
         {
-          "success":              boolean,   # true if successfully parsed, false if error
+          "success":              boolean,   # false if error parsing
           "error":                string,    # exists if "success" is false
           "line":                 string     # exists if "success" is false
         }
@@ -65,10 +79,10 @@ Schema:
 Examples:
 
     $ stat | jc --stat-s
-    {"file":"(stdin)","unix_device":1027739696,"inode":1155,"flags":"crw--w----","links":1,"user":"kbrazil","group":"tty","rdev":268435456,"size":0,"access_time":"Jan  4 15:27:44 2022","modify_time":"Jan  4 15:27:44 2022","change_time":"Jan  4 15:27:44 2022","birth_time":"Dec 31 16:00:00 1969","block_size":131072,"blocks":0,"unix_flags":"0","access_time_epoch":1641338864,"access_time_epoch_utc":null,"modify_time_epoch":1641338864,"modify_time_epoch_utc":null,"change_time_epoch":1641338864,"change_time_epoch_utc":null,"birth_time_epoch":null,"birth_time_epoch_utc":null}
+    {"file":"(stdin)","unix_device":1027739696,"inode":1155,"flags":"cr...}
 
     $ stat | jc --stat-s -r
-    {"file":"(stdin)","unix_device":"1027739696","inode":"1155","flags":"crw--w----","links":"1","user":"kbrazil","group":"tty","rdev":"268435456","size":"0","access_time":"Jan  4 15:28:08 2022","modify_time":"Jan  4 15:28:08 2022","change_time":"Jan  4 15:28:08 2022","birth_time":"Dec 31 16:00:00 1969","block_size":"131072","blocks":"0","unix_flags":"0"}
+    {"file":"(stdin)","unix_device":"1027739696","inode":"1155","flag...}
 
 
 ## info
@@ -86,8 +100,10 @@ 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())
+    data:              (iterable)  line-based text data to parse
-    raw:               (boolean)   output preprocessed JSON if True
+                                   (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
 

docs/parsers/sysctl.md

@@ -3,7 +3,10 @@
 # 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):
 
@@ -15,6 +18,11 @@ 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)
 
@@ -69,7 +77,7 @@ 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:

docs/parsers/systemctl.md

@@ -13,6 +13,11 @@ 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)
 
@@ -37,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",
@@ -73,7 +78,7 @@ 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:

docs/parsers/systemctl_lj.md

@@ -13,6 +13,11 @@ 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)
 
@@ -90,7 +95,7 @@ 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:

docs/parsers/systemctl_ls.md

@@ -1,7 +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):
 
@@ -13,6 +14,11 @@ 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)
 
@@ -65,7 +71,7 @@ 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:

docs/parsers/systemctl_luf.md

@@ -1,7 +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):
 
@@ -13,6 +14,11 @@ 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)
 
@@ -61,7 +67,7 @@ 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:

docs/parsers/systeminfo.md

@@ -5,9 +5,13 @@ 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` 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.
+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):
 
@@ -15,6 +19,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('systeminfo', systeminfo_command_output)
+
+    or
+
     import jc.parsers.systeminfo
     result = jc.parsers.systeminfo.parse(systeminfo_command_output)
 
@@ -31,11 +40,11 @@ Schema:
       "registered_organization":                    string,
       "product_id":                                 string,
       "original_install_date":                      string,
-      "original_install_date_epoch":                integer,     # naive timestamp
+      "original_install_date_epoch":                integer,     # [0]
-      "original_install_date_epoch_utc":            integer,     # timezone-aware timestamp
+      "original_install_date_epoch_utc":            integer,     # [1]
       "system_boot_time":                           string,
-      "system_boot_time_epoch":                     integer,     # naive timestamp
+      "system_boot_time_epoch":                     integer,     # [0]
-      "system_boot_time_epoch_utc":                 integer,     # timezone-aware timestamp
+      "system_boot_time_epoch_utc":                 integer,     # [1]
       "system_manufacturer":                        string,
       "system_model":                               string,
       "system_type":                                string,
@@ -80,6 +89,9 @@ Schema:
       }
     }
 
+    [0] naive timestamp
+    [1] timezone-aware timestamp
+
 Examples:
 
     $ systeminfo | jc --systeminfo -p
@@ -219,7 +231,7 @@ 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:

docs/parsers/time.md

@@ -3,18 +3,27 @@
 # 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`.
+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.
+Alternatively, the output from `/usr/bin/time` can be redirected to `STDOUT`
+so `jc` can receive it.
 
-Note: `/usr/bin/time` is similar but different from the Bash builtin `time` command.
+Note: `/usr/bin/time` is similar but different from the Bash builtin
+      `time` command.
 
 Usage (cli):
 
-    $ /usr/bin/time -o timefile.out sleep 2.5; cat timefile.out | jc --time -p
+    $ /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)
 
@@ -39,8 +48,8 @@ Schema:
       "average_unshared_stack_size":        integer,
       "average_shared_memory_size":         integer,
       "maximum_resident_set_size":          integer,
-      "block_input_operations":             integer,   # aka File system inputs
+      "block_input_operations":             integer,   # [0]
-      "block_output_operations":            integer,   # aka File system outputs
+      "block_output_operations":            integer,   # [1]
       "major_pagefaults":                   integer,
       "minor_pagefaults":                   integer,
       "swaps":                              integer,
@@ -60,15 +69,19 @@ Schema:
       "exit_status":                        integer
     }
 
+    [0] aka File system inputs
+    [1] aka File system outputs
+
 Examples:
 
-    $ /usr/bin/time --verbose -o timefile.out sleep 2.5; cat timefile.out | jc --time -p
+    $ /usr/bin/time --verbose -o timefile.out sleep 2; cat timefile.out | \
+      jc --time -p
     {
-      "command_being_timed": "sleep 2.5",
+      "command_being_timed": "sleep 2",
       "user_time": 0.0,
       "system_time": 0.0,
       "cpu_percent": 0,
-      "elapsed_time": "0:02.50",
+      "elapsed_time": "0:02.00",
       "average_shared_text_size": 0,
       "average_unshared_data_size": 0,
       "average_stack_size": 0,
@@ -94,13 +107,14 @@ Examples:
       "elapsed_time_total_seconds": 2.5
     }
 
-    $ /usr/bin/time --verbose -o timefile.out sleep 2.5; cat timefile.out | jc --time -p -r
+    $ /usr/bin/time --verbose -o timefile.out sleep 2; cat timefile.out | \
+      jc --time -p -r
     {
-      "command_being_timed": ""sleep 2.5"",
+      "command_being_timed": ""sleep 2"",
       "user_time": "0.00",
       "system_time": "0.00",
       "cpu_percent": "0",
-      "elapsed_time": "0:02.50",
+      "elapsed_time": "0:02.00",
       "average_shared_text_size": "0",
       "average_unshared_data_size": "0",
       "average_stack_size": "0",
@@ -138,7 +152,7 @@ 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:

docs/parsers/timedatectl.md

@@ -3,7 +3,8 @@
 # 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.
+The `epoch_utc` calculated timestamp field is timezone-aware and is only
+available if the `universal_time` field is available.
 
 Usage (cli):
 
@@ -15,6 +16,11 @@ 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)
 
@@ -23,7 +29,7 @@ Schema:
     {
       "local_time":                        string,
       "universal_time":                    string,
-      "epoch_utc":                         integer,     # timezone-aware timestamp
+      "epoch_utc":                         integer,     # timezone-aware
       "rtc_time":                          string,
       "time_zone":                         string,
       "ntp_enabled":                       boolean,
@@ -78,7 +84,7 @@ 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:

docs/parsers/tracepath.md

@@ -15,6 +15,11 @@ 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)
 
@@ -146,7 +151,7 @@ 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:

docs/parsers/traceroute.md

@@ -5,9 +5,12 @@ 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):
 
@@ -19,6 +22,11 @@ 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)
 
@@ -132,7 +140,7 @@ 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:

docs/parsers/ufw.md

@@ -13,6 +13,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('ufw', ufw_command_output)
+
+    or
+
     import jc.parsers.ufw
     result = jc.parsers.ufw.parse(ufw_command_output)
 
@@ -43,7 +48,7 @@ Schema:
               "end":                integer
             }
           ],
-          "to_service":             string,     # null if any to ports or port_ranges are set
+          "to_service":             string,     # [0]
           "from_ip":                string,
           "from_ip_prefix":         integer,
           "from_interface":         string,
@@ -57,12 +62,15 @@ Schema:
               "end":                integer
             }
           ],
-          "from_service":           string,     # null if any from ports or port_ranges are set
+          "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
@@ -212,7 +220,7 @@ 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:

docs/parsers/ufw_appinfo.md

@@ -1,11 +1,15 @@
 [Home](https://kellyjonbrazil.github.io/jc/)
 
 # jc.parsers.ufw_appinfo
-jc - JSON CLI output utility `ufw app info [application]` command output parser
+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`.
+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.
+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):
 
@@ -17,6 +21,11 @@ Usage (cli):
 
 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)
 
@@ -32,7 +41,7 @@ Schema:
         ],
         "tcp_ranges": [
           {
-            "start":                integer,      # 'any' is converted to start/end: 0/65535
+            "start":                integer,      # [0]
             "end":                  integer
           }
         ],
@@ -41,31 +50,35 @@ Schema:
         ],
         "udp_ranges": [
           {
-            "start":                integer,      # 'any' is converted to start/end: 0/65535
+            "start":                integer,      # [0]
             "end":                  integer
           }
         ],
         "normalized_tcp_list": [
-                                    integers      # duplicates and overlapping are removed
+                                    integers      # [1]
         ],
         "normalized_tcp_ranges": [
           {
-            "start":                integer,      # 'any' is converted to start/end: 0/65535
+            "start":                integer,      # [0]
-            "end":                  integers      # overlapping are merged
+            "end":                  integers      # [2]
           }
         ],
         "normalized_udp_list": [
-                                    integers      # duplicates and overlapping are removed
+                                    integers      # [1]
         ],
         "normalized_udp_ranges": [
           {
-            "start":                integer,      # 'any' is converted to start/end: 0/65535
+            "start":                integer,      # [0]
-            "end":                  integers      # overlapping are merged
+            "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
@@ -145,7 +158,7 @@ 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:

docs/parsers/uname.md

@@ -15,6 +15,11 @@ 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)
 
@@ -62,7 +67,7 @@ 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:

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

@@ -3,9 +3,11 @@
 # 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` 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.
+The `updated_epoch_utc` calculated timestamp field is timezone-aware and is
+only available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -17,6 +19,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('upower', upower_command_output)
+
+    or
+
     import jc.parsers.upower
     result = jc.parsers.upower.parse(upower_command_output)
 
@@ -29,8 +36,8 @@ Schema:
         "native_path":                  string,
         "power_supply":                 boolean,
         "updated":                      string,
-        "updated_epoch":                integer,       # null if date-time conversion fails
+        "updated_epoch":                integer,       # [0]
-        "updated_epoch_utc":            integer,       # null if date-time conversion fails
+        "updated_epoch_utc":            integer,       # [0]
         "updated_seconds_ago":          integer,
         "has_history":                  boolean,
         "has_statistics":               boolean,
@@ -82,12 +89,14 @@ Schema:
       }
     ]
 
+    [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/power_supply/BAT0",
+        "native_path": "/sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/p...",
         "vendor": "NOTEBOOK",
         "model": "BAT",
         "serial": "0001",
@@ -146,7 +155,7 @@ Examples:
     $ upower -i /org/freedesktop/UPower/devices/battery | jc --upower -p -r
     [
       {
-        "native_path": "/sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/power_supply/BAT0",
+        "native_path": "/sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/p...",
         "vendor": "NOTEBOOK",
         "model": "BAT",
         "serial": "0001",
@@ -209,7 +218,7 @@ 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:

docs/parsers/uptime.md

@@ -13,6 +13,11 @@ 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)
 
@@ -80,7 +85,7 @@ 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:

docs/parsers/vmstat.md

@@ -5,9 +5,11 @@ 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` 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.
+The `epoch_utc` calculated timestamp field is timezone-aware and is only
+available if the timezone field is UTC.
 
 Usage (cli):
 
@@ -19,6 +21,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('vmstat', vmstat_command_output)
+
+    or
+
     import jc.parsers.vmstat
     result = jc.parsers.vmstat.parse(vmstat_command_output)
 
@@ -58,11 +65,14 @@ Schema:
         "io_seconds":                        integer,
         "timestamp":                         string,
         "timezone":                          string,
-        "epoch":                             integer,     # naive timestamp if -t flag is used
+        "epoch":                             integer,     # [0]
-        "epoch_utc":                         integer      # aware timestamp if -t flag is used and UTC TZ
+        "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
@@ -136,7 +146,7 @@ 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:

docs/parsers/vmstat_s.md

@@ -7,20 +7,36 @@ jc - JSON CLI output utility `vmstat` command output streaming 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` 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.
+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.
+> 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 = jc.parsers.vmstat_s.parse(vmstat_command_output.splitlines())    # result is an iterable object
+    # result is an iterable object (generator)
+    result = jc.parsers.vmstat_s.parse(vmstat_command_output.splitlines())
     for item in result:
         # do something
 
@@ -59,24 +75,32 @@ Schema:
       "io_seconds":                       integer,
       "timestamp":                        string,
       "timezone":                         string,
-      "epoch":                             integer,     # naive timestamp if -t flag is used
+      "epoch":                            integer,     # [0]
-      "epoch_utc":                         integer      # aware timestamp if -t flag is used and UTC TZ
+      "epoch_utc":                        integer      # [1]
-      "_jc_meta":                                       # This object only exists if using -qq or ignore_exceptions=True
+
+      # Below object only exists if using -qq or ignore_exceptions=True
+
+      "_jc_meta":
         {
-          "success":                       boolean,     # true if successfully parsed, false if error
+          "success":                      boolean,  # [2]
-          "error":                         string,      # exists if "success" is false
+          "error":                        string,   # [3]
-          "line":                          string       # exists if "success" is false
+          "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_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}
+    {"runnable_procs":2,"uninterruptible_sleeping_procs":0,"virtual_mem...}
     ...
 
     $ vmstat | jc --vmstat-s -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}
+    {"runnable_procs":"2","uninterruptible_sleeping_procs":"0","virtua...}
     ...
 
 
@@ -95,8 +119,10 @@ 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())
+    data:              (iterable)  line-based text data to parse
-    raw:               (boolean)   output preprocessed JSON if True
+                                   (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
 

docs/parsers/w.md

@@ -13,6 +13,11 @@ 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)
 
@@ -118,7 +123,7 @@ 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:

docs/parsers/wc.md

@@ -13,6 +13,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('wc', wc_command_output)
+
+    or
+
     import jc.parsers.wc
     result = jc.parsers.wc.parse(wc_command_output)
 
@@ -69,7 +74,7 @@ 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:

docs/parsers/who.md

@@ -5,7 +5,8 @@ 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)
+The `epoch` calculated timestamp field is naive. (i.e. based on the local
+time of the system the parser is run on)
 
 Usage (cli):
 
@@ -17,6 +18,11 @@ 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)
 
@@ -29,7 +35,7 @@ Schema:
         "writeable_tty":   string,
         "tty":             string,
         "time":            string,
-        "epoch":           integer,     # naive timestamp. null if time cannot be converted
+        "epoch":           integer,     # [0]
         "idle":            string,
         "pid":             integer,
         "from":            string,
@@ -37,6 +43,8 @@ Schema:
       }
     ]
 
+    [0] naive timestamp. null if time cannot be converted
+
 Examples:
 
     $ who -a | jc --who -p
@@ -147,7 +155,7 @@ 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:

docs/parsers/xml.md

@@ -9,6 +9,11 @@ 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)
 
@@ -85,7 +90,7 @@ 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:

docs/parsers/yaml.md

@@ -9,6 +9,11 @@ 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)
 
@@ -99,7 +104,7 @@ 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:

docs/parsers/zipinfo.md

@@ -18,6 +18,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('zipinfo', zipinfo_command_output)
+
+    or
+
     import jc.parsers.zipinfo
     result = jc.parsers.zipinfo.parse(zipinfo_command_output)
 
@@ -94,7 +99,7 @@ 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:

docs/readme.md

@@ -4,72 +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 the [documentation site](https://kellyjonbrazil.github.io/jc/).
+## Interactive Documentation
 
-CLI Example:
+    >>> help(jc)
+    >>> help(jc.lib)
+    >>> help(jc.util)
+    >>> jc.get_help('parser_module_name')
 
-    $ dig example.com | jc --dig -p
+## Online Documentation
-    [
-      {
-        "id": 2951,
-        "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": 39302,
-            "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:05:10 PDT 2021",
-        "rcvd": 56,
-        "when_epoch": 1618614310,
-        "when_epoch_utc": null
-      }
-    ]
 
-Module Example:
+### Latest:
 
-    >>> import jc.parsers.dig
+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
     >>>
+    >>> 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)
+    >>> cmd_output = subprocess.check_output(['dig', 'example.com'],
+                                             text=True)
     >>> data = jc.parsers.dig.parse(cmd_output)
-    >>>
     >>> data
-    [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', 'flags': ['qr', 'rd', 'ra'], 'query_num': 1, 'answer_num':
+    [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', ...}]
-    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.',
+## Available Functions
-    '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,
+Use `help(jc.lib)` for details:
-    'when_epoch': 1618614780, 'when_epoch_utc': None}]
+
+    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

@@ -7,9 +7,9 @@ jc - JSON CLI output utility utils
 warning_message(message_lines)
 ```
 
-Prints warning message for non-fatal issues. The first line is prepended with
+Prints warning message for non-fatal issues. The first line is
-'jc:  Warning - ' and subsequent lines are indented. Wraps text as needed based
+prepended with 'jc:  Warning - ' and subsequent lines are indented.
-on the terminal width.
+Wraps text as needed based on the terminal width.
 
 Parameters:
 
@@ -25,9 +25,9 @@ Returns:
 error_message(message_lines)
 ```
 
-Prints an error message for fatal issues. The first line is prepended with
+Prints an error message for fatal issues. The first line is
-'jc:  Error - ' and subsequent lines are indented. Wraps text as needed based
+prepended with 'jc:  Error - ' and subsequent lines are indented.
-on the terminal width.
+Wraps text as needed based on the terminal width.
 
 Parameters:
 
@@ -42,14 +42,16 @@ Returns:
 ```python
 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
 
-    compatible:     (list) sys.platform name(s) compatible with the parser
+    compatible:   (list) sys.platform name(s) compatible with
-                    compatible options:
+                  the parser. compatible options:
                   linux, darwin, cygwin, win32, aix, freebsd
 
     quiet:        (bool) supress compatibility message if True
@@ -64,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:
 
@@ -72,7 +75,8 @@ 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
@@ -80,7 +84,8 @@ Returns:
 convert_to_int(value)
 ```
 
-Converts string and float input to int. Strips all non-numeric characters from strings.
+Converts string and float input to int. Strips all non-numeric
+characters from strings.
 
 Parameters:
 
@@ -96,7 +101,8 @@ Returns:
 convert_to_float(value)
 ```
 
-Converts string and int input to float. Strips all non-numeric characters from strings.
+Converts string and int input to float. Strips all non-numeric
+characters from strings.
 
 Parameters:
 
@@ -112,7 +118,8 @@ Returns:
 convert_to_bool(value)
 ```
 
-Converts string, integer, or float input to boolean by checking for 'truthy' values
+Converts string, integer, or float input to boolean by checking
+for 'truthy' values.
 
 Parameters:
 
@@ -120,7 +127,8 @@ Parameters:
 
 Returns:
 
-    True/False      False unless a 'truthy' number or string is found ('y', 'yes', 'true', '1', 1, -1, etc.)
+    True/False      False unless a 'truthy' number or string is found
+                    ('y', 'yes', 'true', '1', 1, -1, etc.)
 
 
 ## stream_success
@@ -133,8 +141,9 @@ Add `_jc_meta` object to output line if `ignore_exceptions=True`
 ```python
 stream_error(e, ignore_exceptions, line)
 ```
-Reraise the stream exception with annotation or print an error `_jc_meta`
+
-field if `ignore_exceptions=True`
+Reraise the stream exception with annotation or print an error
+`_jc_meta` field if `ignore_exceptions=True`.
 
 
 ## input_type_check
@@ -160,16 +169,26 @@ Ensure each line is a string
 timestamp(datetime_string)
 ```
 
-Input a date-time text string of several formats and convert to a naive or timezone-aware epoch timestamp in UTC
+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
+    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
+    format            (int)   the format rule that was used to
-    utc                 (int)   aware timestamp only if UTC timezone detected in datetime string. None if conversion fails
+                              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,75 +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 the [documentation site](https://kellyjonbrazil.github.io/jc/).
+## Interactive Documentation
 
-CLI Example:
+    >>> help(jc)
+    >>> help(jc.lib)
+    >>> help(jc.util)
+    >>> jc.get_help('parser_module_name')
 
-    $ dig example.com | jc --dig -p
+## Online Documentation
-    [
-      {
-        "id": 2951,
-        "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": 39302,
-            "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:05:10 PDT 2021",
-        "rcvd": 56,
-        "when_epoch": 1618614310,
-        "when_epoch_utc": null
-      }
-    ]
 
-Module Example:
+### Latest:
 
-    >>> import jc.parsers.dig
+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
     >>>
+    >>> 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)
+    >>> cmd_output = subprocess.check_output(['dig', 'example.com'],
+                                             text=True)
     >>> data = jc.parsers.dig.parse(cmd_output)
-    >>>
     >>> data
-    [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', 'flags': ['qr', 'rd', 'ra'], 'query_num': 1, 'answer_num':
+    [{'id': 64612, 'opcode': 'QUERY', 'status': 'NOERROR', ...}]
-    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}]
-"""
 
-name = 'jc'
+## Available Functions
-__version__ = '1.17.7'
+
+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,19 +4,16 @@ JC cli module
 
 import sys
 import os
-import os.path
-import re
 import importlib
 import textwrap
 import signal
 import shlex
 import subprocess
 import json
-import jc
+from .lib import __version__, parsers, local_parsers
-from jc import appdirs
+from . import utils
-import jc.utils
+from . import tracebackplus
-import jc.tracebackplus
+from .exceptions import LibraryNotInstalled, ParseError
-from jc.exceptions import LibraryNotInstalled, ParseError
 
 # make pygments import optional
 try:
@@ -31,8 +28,11 @@ except Exception:
     PYGMENTS_INSTALLED = False
 
 
+JC_ERROR_EXIT = 100
+
+
 class info():
-    version = jc.__version__
+    version = __version__
     description = 'JSON CLI output utility'
     author = 'Kelly Brazil'
     author_email = 'kellyjonbrazil@gmail.com'
@@ -41,114 +41,6 @@ class info():
     license = 'MIT License'
 
 
-__version__ = info.version
-
-parsers = [
-    'acpi',
-    'airport',
-    'airport-s',
-    'arp',
-    'blkid',
-    'cksum',
-    'crontab',
-    'crontab-u',
-    'csv',
-    'csv-s',
-    'date',
-    'df',
-    'dig',
-    'dir',
-    'dmidecode',
-    'dpkg-l',
-    'du',
-    'env',
-    'file',
-    'finger',
-    'free',
-    'fstab',
-    'group',
-    'gshadow',
-    'hash',
-    'hashsum',
-    'hciconfig',
-    'history',
-    'hosts',
-    'id',
-    'ifconfig',
-    'ini',
-    'iostat',
-    'iostat-s',
-    'iptables',
-    'iw-scan',
-    'jar-manifest',
-    'jobs',
-    'kv',
-    'last',
-    'ls',
-    'ls-s',
-    'lsblk',
-    'lsmod',
-    'lsof',
-    'lsusb',
-    'mount',
-    'netstat',
-    'ntpq',
-    'passwd',
-    'ping',
-    'ping-s',
-    'pip-list',
-    'pip-show',
-    'ps',
-    'route',
-    'rpm-qi',
-    'sfdisk',
-    'shadow',
-    'ss',
-    'stat',
-    'stat-s',
-    'sysctl',
-    'systemctl',
-    'systemctl-lj',
-    'systemctl-ls',
-    'systemctl-luf',
-    'systeminfo',
-    'time',
-    'timedatectl',
-    'tracepath',
-    'traceroute',
-    'ufw',
-    'ufw-appinfo',
-    'uname',
-    'upower',
-    'uptime',
-    'vmstat',
-    'vmstat-s',
-    'w',
-    'wc',
-    'who',
-    'xml',
-    'yaml',
-    'zipinfo'
-]
-
-JC_ERROR_EXIT = 100
-
-
-# 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)
-
-
 # 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_INSTALLED:
@@ -226,7 +118,7 @@ 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:
-        jc.utils.warning_message(['Could not parse JC_COLORS environment variable'])
+        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
@@ -543,7 +435,7 @@ def main():
     version_info = 'v' in options
 
     if verbose_debug:
-        jc.tracebackplus.enable(context=11)
+        tracebackplus.enable(context=11)
 
     if not PYGMENTS_INSTALLED:
         mono = True
@@ -578,29 +470,23 @@ def main():
             if magic_stderr:
                 print(magic_stderr[:-1], file=sys.stderr)
 
-        except FileNotFoundError:
+        except OSError as e:
             if debug:
                 raise
 
-            jc.utils.error_message([f'"{run_command_str}" command could not be found. For details use the -d or -dd option.'])
+            error_msg = os.strerror(e.errno)
-            sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
+            utils.error_message([f'"{run_command_str}" command could not be run: {error_msg}. For details use the -d or -dd option.'])
-
-        except OSError:
-            if debug:
-                raise
-
-            jc.utils.error_message([f'"{run_command_str}" command could not be run due to too many open files. For details use the -d or -dd option.'])
             sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
 
         except Exception:
             if debug:
                 raise
 
-            jc.utils.error_message([f'"{run_command_str}" command could not be run. For details use the -d or -dd option.'])
+            utils.error_message([f'"{run_command_str}" command could not be run. For details use the -d or -dd option.'])
             sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
 
     elif run_command is not None:
-        jc.utils.error_message([f'"{run_command_str}" cannot be used with Magic syntax. Use "jc -h" for help.'])
+        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
@@ -619,16 +505,16 @@ def main():
                 break
 
         if not found:
-            jc.utils.error_message(['Missing or incorrect arguments. Use "jc -h" for help.'])
+            utils.error_message(['Missing or incorrect arguments. Use "jc -h" for help.'])
             sys.exit(combined_exit_code(magic_exit_code, JC_ERROR_EXIT))
 
     # check for input errors (pipe vs magic)
     if not sys.stdin.isatty() and magic_stdout:
-        jc.utils.error_message(['Piped data and Magic syntax used simultaneously. Use "jc -h" for help.'])
+        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))
 
     elif sys.stdin.isatty() and magic_stdout is None:
-        jc.utils.error_message(['Missing piped data. Use "jc -h" for help.'])
+        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
@@ -665,7 +551,7 @@ def main():
         if debug:
             raise
 
-        jc.utils.error_message([f'Parser issue with {parser_name}:',
+        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))
@@ -674,7 +560,7 @@ def main():
         if debug:
             raise
 
-        jc.utils.error_message(['There was an issue generating the JSON output.',
+        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))
 
@@ -686,7 +572,7 @@ def main():
         if getattr(parser.info, 'streaming', None):
             streaming_msg = 'Use the -qq option to ignore streaming parser errors.'
 
-        jc.utils.error_message([
+        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.'

jc/lib.py

@@ -0,0 +1,209 @@
+"""jc - JSON CLI output utility
+JC lib module
+"""
+
+import sys
+import os
+import re
+import importlib
+from jc import appdirs
+
+__version__ = '1.18.0'
+
+parsers = [
+    'acpi',
+    'airport',
+    'airport-s',
+    'arp',
+    'blkid',
+    'cksum',
+    'crontab',
+    'crontab-u',
+    'csv',
+    'csv-s',
+    'date',
+    'df',
+    'dig',
+    'dir',
+    'dmidecode',
+    'dpkg-l',
+    'du',
+    'env',
+    'file',
+    'finger',
+    'free',
+    'fstab',
+    'group',
+    'gshadow',
+    'hash',
+    'hashsum',
+    'hciconfig',
+    'history',
+    'hosts',
+    'id',
+    'ifconfig',
+    'ini',
+    'iostat',
+    'iostat-s',
+    'iptables',
+    'iw-scan',
+    'jar-manifest',
+    'jobs',
+    'kv',
+    'last',
+    'ls',
+    'ls-s',
+    'lsblk',
+    'lsmod',
+    'lsof',
+    'lsusb',
+    'mount',
+    'netstat',
+    'ntpq',
+    'passwd',
+    'ping',
+    'ping-s',
+    'pip-list',
+    'pip-show',
+    'ps',
+    'route',
+    'rpm-qi',
+    'sfdisk',
+    'shadow',
+    'ss',
+    'stat',
+    'stat-s',
+    'sysctl',
+    'systemctl',
+    'systemctl-lj',
+    'systemctl-ls',
+    'systemctl-luf',
+    'systeminfo',
+    'time',
+    'timedatectl',
+    'tracepath',
+    'traceroute',
+    'ufw',
+    'ufw-appinfo',
+    'uname',
+    'upower',
+    'uptime',
+    'vmstat',
+    'vmstat-s',
+    'w',
+    'wc',
+    'who',
+    'xml',
+    'yaml',
+    'zipinfo'
+]
+
+# Create the local_parsers list. This is a list of custom or
+# override parsers from <user_data_dir>/jc/jcparsers/*.py.
+# Once this list is created, extend the parsers list with it.
+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)
+    del name
+
+
+def _cliname_to_modname(parser_cli_name):
+    """Return real module name (dashes converted to underscores)"""
+    return parser_cli_name.replace('-', '_')
+
+def _modname_to_cliname(parser_mod_name):
+    """Return module's cli name (underscores converted to dashes)"""
+    return parser_mod_name.replace('_', '-')
+
+def _get_parser(parser_mod_name):
+    """Return the parser module object"""
+    parser_cli_name = _modname_to_cliname(parser_mod_name)
+    modpath = 'jcparsers.' if parser_cli_name in local_parsers else 'jc.parsers.'
+    return importlib.import_module(f'{modpath}{parser_mod_name}')
+
+def 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
+    """
+    jc_parser = _get_parser(parser_mod_name)
+
+    if ignore_exceptions is not None:
+        return jc_parser.parse(data, quiet=quiet, raw=raw,
+                               ignore_exceptions=ignore_exceptions, **kwargs)
+
+    return jc_parser.parse(data, quiet=quiet, raw=raw, **kwargs)
+
+def parser_mod_list():
+    """Returns a list of all available parser module names."""
+    return [_cliname_to_modname(p) for p in parsers]
+
+def plugin_parser_mod_list():
+    """
+    Returns a list of plugin parser module names. This function is a
+    subset of `parser_mod_list()`.
+    """
+    return [_cliname_to_modname(p) for p in local_parsers]
+
+def get_help(parser_mod_name):
+    """Show help screen for the selected parser."""
+    help(_get_parser(parser_mod_name))

jc/parsers/acpi.py

@@ -10,6 +10,11 @@ Usage (cli):
 
 Usage (module):
 
+    import jc
+    result = jc.parse('acpi', acpi_command_output)
+
+    or
+
     import jc.parsers.acpi
     result = jc.parsers.acpi.parse(acpi_command_output)
 
@@ -231,8 +236,6 @@ class info():
     description = '`acpi` command parser'
     author = 'Kelly Brazil'
     author_email = 'kellyjonbrazil@gmail.com'
-
-    # compatible options: linux, darwin, cygwin, win32, aix, freebsd
     compatible = ['linux']
     magic_commands = ['acpi']
 
@@ -252,7 +255,8 @@ def _process(proc_data):
 
         List of Dictionaries. Structured data to conform to the schema.
     """
-    int_list = ['id', 'charge_percent', 'design_capacity_mah', 'last_full_capacity', 'last_full_capacity_percent']
+    int_list = ['id', 'charge_percent', 'design_capacity_mah', 'last_full_capacity',
+                'last_full_capacity_percent']
     float_list = ['temperature']
 
     for entry in proc_data:
@@ -295,7 +299,7 @@ def parse(data, raw=False, quiet=False):
     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:

jc/parsers/airport.py

@@ -12,6 +12,11 @@ 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)
 
@@ -84,9 +89,6 @@ class info():
     description = '`airport -I` command parser'
     author = 'Kelly Brazil'
     author_email = 'kellyjonbrazil@gmail.com'
-    # details = 'enter any other details here'
-
-    # compatible options: linux, darwin, cygwin, win32, aix, freebsd
     compatible = ['darwin']
     magic_commands = ['airport -I']
 
@@ -123,7 +125,7 @@ def parse(data, raw=False, quiet=False):
     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:
@@ -139,7 +141,9 @@ def parse(data, raw=False, quiet=False):
 
         for line in filter(None, data.splitlines()):
             linedata = line.split(':', maxsplit=1)
-            raw_output[linedata[0].strip().lower().replace(' ', '_').replace('.', '_')] = linedata[1].strip()
+            key = linedata[0].strip().lower().replace(' ', '_').replace('.', '_')
+            value = linedata[1].strip()
+            raw_output[key] = value
 
     if raw:
         return raw_output

jc/parsers/airport_s.py

@@ -12,6 +12,11 @@ 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)
 
@@ -113,9 +118,6 @@ class info():
     description = '`airport -s` command parser'
     author = 'Kelly Brazil'
     author_email = 'kellyjonbrazil@gmail.com'
-    # details = 'enter any other details here'
-
-    # compatible options: linux, darwin, cygwin, win32, aix, freebsd
     compatible = ['darwin']
     magic_commands = ['airport -s']
 
@@ -159,7 +161,7 @@ def parse(data, raw=False, quiet=False):
     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:

jc/parsers/arp.py

@@ -12,6 +12,11 @@ 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)
 
@@ -122,8 +127,6 @@ class info():
     description = '`arp` command parser'
     author = 'Kelly Brazil'
     author_email = 'kellyjonbrazil@gmail.com'
-
-    # compatible options: linux, darwin, cygwin, win32, aix, freebsd
     compatible = ['linux', 'aix', 'freebsd', 'darwin']
     magic_commands = ['arp']
 
@@ -164,7 +167,7 @@ def parse(data, raw=False, quiet=False):
     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: