Merge pull request #249 from kellyjonbrazil/dev

Dev v1.20.0

CHANGELOG

@@ -1,41 +1,50 @@
 jc changelog
 
+20220531 v1.20.0
+- Add YAML output option with `-y`
+- Add `top -b` standard and streaming parsers tested on linux
+- Add `plugin_parser_count`, `standard_parser_count`, and `streaming_parser_count`
+  keys to `jc -a` output
+- Add `is_compatible` function to the `utils` module
+- Fix `pip-show` parser for packages with a multi-line license field
+- Fix ASCII Table parser for cases where centered headers cause mis-aligned fields
+
 20220513 v1.19.0
-- Add chage --list command parser tested on linux
-- Add git log command streaming parser
-- Fix git log standard parser for coner-cases where hash values are in messages
-- Fix df command parser for rare instances when a newline is found at the end
+- Add `chage --list` command parser tested on linux
+- Add `git log` command streaming parser
+- Fix `git log` standard parser for corner-cases where hash values are in messages
+- Fix `df` command parser for rare instances when a newline is found at the end
 - Allow jc to pip install on unsupported python version 3.6
-- Fix asciitable-m parser to skip some rows that contain column separator
-  characters in cell data. A warning message will be printed to STDOUT
+- Fix `asciitable-m` parser to skip some rows that contain column separator
+  characters in cell data. A warning message will be printed to STDERR
   unless `-q` or `quiet=True` is used.
 
 20220427 v1.18.8
-- Fix update-alternatives --query parser for cases where `slaves` are not present
+- Fix `update-alternatives --query` parser for cases where `slaves` are not present
 - Fix UnicodeEncodeError on some systems where LANG=C is set and unicode
   characters are in the output
-- Update history parser: do not drop non-ASCII characters if the system
+- Update `history` parser: do not drop non-ASCII characters if the system
   is configured for UTF-8 encoding
 - Enhance "magic syntax" to always use UTF-8 encoding
 
 20220425 v1.18.7
-- Add git log command parser
-- Add update-alternatives --query parser
-- Add update-alternatives --get-selections parser
+- Add `git log` command parser
+- Add `update-alternatives --query` parser
+- Add `update-alternatives --get-selections` parser
 - Fix key/value and ini parsers to allow duplicate keys
 - Fix yaml file parser for files including timestamp objects
-- Update xrandr parser: add a 'rotation' field
+- Update `xrandr` parser: add a 'rotation' field
 - Fix failing tests by moving template files
 - Add python interpreter version and path to -v and -a output
 
 20220325 v1.18.6
-- Add pidstat command parser tested on linux
-- Add pidstat command streaming parser tested on linux
-- Add mpstat command parser tested on linux
-- Add mpstat command streaming parser tested on linux
+- Add `pidstat` command parser tested on linux
+- Add `pidstat` command streaming parser tested on linux
+- Add `mpstat` command parser tested on linux
+- Add `mpstat` command streaming parser tested on linux
 - Add single-line ASCII and Unicode table parser
 - Add multi-line ASCII and Unicode table parser
-- Add documentation option to parser_info() and all_parser_info()
+- Add documentation option to `parser_info()` and `all_parser_info()`
 
 20220305 v1.18.5
 - Fix date parser to ensure AM/PM period string is always uppercase

docs/parsers/asciitable.md

@@ -8,7 +8,12 @@ jc - JSON Convert `asciitable` parser
 This parser converts ASCII and Unicode text tables with single-line rows.
 
 Column headers must be at least two spaces apart from each other and must
-be unique.
+be unique. For best results, column headers should be left-justified. If
+column separators are present, then non-left-justified headers will be fixed
+automatically.
+
+Row separators are optional and are ignored. Each non-row-separator line is
+considered a separate row in the table.
 
 For example:
 
@@ -136,4 +141,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
 
-Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/asciitable_m.md

@@ -30,9 +30,10 @@ headers are joined with an underscore. All values are returned as strings,
 except empty strings, which are converted to None/null.
 
 > Note: table column separator characters (e.g. `|`) cannot be present
-  inside the cell data. If detected, a warning message will be printed to
-  STDERR and the line will be skipped. The warning message can be suppressed
-  by using the `-q` command option or by setting `quiet=True` in `parse()`.
+> inside the cell data. If detected, a warning message will be printed to
+> `STDERR` and the line will be skipped. The warning message can be
+> suppressed by using the `-q` command option or by setting `quiet=True` in
+> `parse()`.
 
 Usage (cli):
 

docs/parsers/csv_s.md

@@ -6,14 +6,14 @@
 jc - JSON Convert `csv` file streaming parser
 
 > This streaming parser outputs JSON Lines (cli) or returns an Iterable of
-  Dictionaries (module)
+> Dictionaries (module)
 
 The `csv` streaming parser will attempt to automatically detect the
 delimiter character. If the delimiter cannot be detected it will default
 to comma. The first row of the file must be a header row.
 
-Note: The first 100 rows are read into memory to enable delimiter detection,
-then the rest of the rows are loaded lazily.
+> Note: The first 100 rows are read into memory to enable delimiter
+> detection, then the rest of the rows are loaded lazily.
 
 Usage (cli):
 

docs/parsers/dir.md

@@ -19,7 +19,7 @@ time of the system the parser is run on)
 
 Usage (cli):
 
-    C:> dir | jc --dir
+    C:\> dir | jc --dir
 
 Usage (module):
 
@@ -42,7 +42,7 @@ Schema:
 
 Examples:
 
-    C:> dir | jc --dir -p
+    C:\> dir | jc --dir -p
     [
       {
         "date": "03/24/2021",
@@ -83,7 +83,7 @@ Examples:
       ...
     ]
 
-    C:> dir | jc --dir -p -r
+    C:\> dir | jc --dir -p -r
     [
       {
         "date": "03/24/2021",

docs/parsers/git_log.md

@@ -43,8 +43,8 @@ Schema:
         "author":               string,
         "author_email":         string,
         "date":                 string,
-        "epoch":                integer, [0]
-        "epoch_utc":            integer, [1]
+        "epoch":                integer,  # [0]
+        "epoch_utc":            integer,  # [1]
         "commit_by":            string,
         "commit_by_email":      string,
         "commit_by_date":       string,

docs/parsers/git_log_s.md

@@ -6,7 +6,7 @@
 jc - JSON Convert `git log` command output streaming parser
 
 > This streaming parser outputs JSON Lines (cli) or returns an Iterable of
-  Dictionaries (module)
+> Dictionaries (module)
 
 Can be used with the following format options:
 - `oneline`
@@ -44,8 +44,8 @@ Schema:
       "author":               string,
       "author_email":         string,
       "date":                 string,
-      "epoch":                integer, [0]
-      "epoch_utc":            integer, [1]
+      "epoch":                integer,  # [0]
+      "epoch_utc":            integer,  # [1]
       "commit_by":            string,
       "commit_by_email":      string,
       "commit_by_date":       string,

docs/parsers/ifconfig.md

@@ -5,7 +5,7 @@
 
 jc - JSON Convert `ifconfig` command output parser
 
-Note: No `ifconfig` options are supported.
+> Note: No `ifconfig` options are supported.
 
 Usage (cli):
 

docs/parsers/ini.md

@@ -12,8 +12,8 @@ Parses standard `INI` files and files containing simple key/value pairs.
 - If duplicate keys are found, only the last value will be used.
 
 > Note: Values starting and ending with quotation marks will have the marks
-        removed. If you would like to keep the quotation marks, use the `-r`
-        command-line argument or the `raw=True` argument in `parse()`.
+> 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):
 
@@ -26,8 +26,8 @@ Usage (module):
 
 Schema:
 
-    ini or key/value document converted to a dictionary - see the
-    configparser standard library documentation for more details.
+ini or key/value document converted to a dictionary - see the configparser
+standard library documentation for more details.
 
     {
       "key1":       string,

docs/parsers/iostat.md

@@ -5,7 +5,7 @@
 
 jc - JSON Convert `iostat` command output parser
 
-Note: `iostat` version 11 and higher include a JSON output option
+> Note: `iostat` version 11 and higher include a JSON output option
 
 Usage (cli):
 

docs/parsers/iostat_s.md

@@ -6,20 +6,20 @@
 jc - JSON Convert `iostat` command output streaming parser
 
 > This streaming parser outputs JSON Lines (cli) or returns an Iterable of
-  Dictionaries (module)
+> Dictionaries (module)
 
-Note: `iostat` version 11 and higher include a JSON output option
+> Note: `iostat` version 11 and higher include a JSON output option
 
 Usage (cli):
 
     $ iostat | jc --iostat-s
 
 > Note: When piping `jc` converted `iostat` output to other processes it may
-  appear the output is hanging due to the OS pipe buffers. This is because
-  `iostat` output is too small to quickly fill up the buffer. Use the `-u`
-  option to unbuffer the `jc` output if you would like immediate output. See
-  the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output)
-  for more information.
+> appear the output is hanging due to the OS pipe buffers. This is because
+> `iostat` output is too small to quickly fill up the buffer. Use the `-u`
+> option to unbuffer the `jc` output if you would like immediate output. See
+> the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output)
+> for more information.
 
 Usage (module):
 

docs/parsers/kv.md

@@ -12,8 +12,8 @@ Supports files containing simple key/value pairs.
 - If duplicate keys are found, only the last value will be used.
 
 > Note: Values starting and ending with quotation marks will have the marks
-        removed. If you would like to keep the quotation marks, use the `-r`
-        command-line argument or the `raw=True` argument in `parse()`.
+> 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):
 
@@ -26,8 +26,8 @@ Usage (module):
 
 Schema:
 
-    key/value document converted to a dictionary - see the
-    configparser standard library documentation for more details.
+key/value document converted to a dictionary - see the configparser standard
+library documentation for more details.
 
     {
       "key1":       string,

docs/parsers/ls.md

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

docs/parsers/ls_s.md

@@ -6,7 +6,7 @@
 jc - JSON Convert `ls` and `vdir` command output streaming parser
 
 > This streaming parser outputs JSON Lines (cli) or returns an Iterable of
-  Dictionaries (module)
+> Dictionaries (module)
 
 Requires the `-l` option to be used on `ls`. If there are newline characters
 in the filename, then make sure to use the `-b` option on `ls`.

docs/parsers/lsusb.md

@@ -22,9 +22,9 @@ Usage (module):
 
 Schema:
 
-    Note: <item> object keynames are assigned directly from the lsusb
-          output. If there are duplicate <item> names in a section, only the
-          last one is converted.
+> Note: <item> object keynames are assigned directly from the lsusb
+> output. If there are duplicate <item> names in a section, only the
+> last one is converted.
 
     [
       {

docs/parsers/mpstat.md

@@ -5,7 +5,7 @@
 
 jc - JSON Convert `mpstat` command output parser
 
-Note: Latest versions of `mpstat` support JSON output (v11.5.1+)
+> Note: Latest versions of `mpstat` support JSON output (v11.5.1+)
 
 Usage (cli):
 

docs/parsers/mpstat_s.md

@@ -6,9 +6,9 @@
 jc - JSON Convert `mpstat` command output streaming parser
 
 > This streaming parser outputs JSON Lines (cli) or returns an Iterable of
-  Dictionaries (module)
+> Dictionaries (module)
 
-Note: Latest versions of `mpstat` support JSON output (v11.5.1+)
+> Note: Latest versions of `mpstat` support JSON output (v11.5.1+)
 
 Usage (cli):
 

docs/parsers/nmcli.md

@@ -29,18 +29,18 @@ Usage (module):
 
 Schema:
 
-    Because there are so many options, the schema is not strictly defined.
-    Integer and Float value conversions are attempted and the original
-    values are kept if they fail. If you don't want automatic conversion,
-    then use the -r or raw=True option to disable it.
+Because there are so many options, the schema is not strictly defined.
+Integer and Float value conversions are attempted and the original
+values are kept if they fail. If you don't want automatic conversion,
+then use the `-r` or `raw=True` option to disable it.
 
-    The structure is flat, for the most part, but there are a couple of
-    "well-known" keys that are further parsed into objects for convenience.
-    These are documented below.
+The structure is flat, for the most part, but there are a couple of
+"well-known" keys that are further parsed into objects for convenience.
+These are documented below.
 
     [
       {
-        "<key>":                  string/integer/float,  [0]
+        "<key>":                  string/integer/float,   # [0]
         "dhcp4_option_x": {
           "name":                 string,
           "value":                string/integer/float,

docs/parsers/pidstat.md

@@ -3,7 +3,7 @@
 
 # jc.parsers.pidstat
 
-jc - JSON Convert `pidstat` command output parser
+jc - JSON Convert `pidstat -h` command output parser
 
 Must use the `-h` option in `pidstat`. All other `pidstat` options are
 supported in combination with `-h`.

docs/parsers/pidstat_s.md

@@ -3,10 +3,10 @@
 
 # jc.parsers.pidstat\_s
 
-jc - JSON Convert `pidstat` command output streaming parser
+jc - JSON Convert `pidstat -h` command output streaming parser
 
 > This streaming parser outputs JSON Lines (cli) or returns an Iterable of
-  Dictionaries (module)
+> Dictionaries (module)
 
 Must use the `-h` option in `pidstat`. All other `pidstat` options are
 supported in combination with `-h`.
@@ -16,11 +16,11 @@ Usage (cli):
     $ pidstat | jc --pidstat-s
 
 > Note: When piping `jc` converted `pidstat` output to other processes it
-  may appear the output is hanging due to the OS pipe buffers. This is
-  because `pidstat` output is too small to quickly fill up the buffer. Use
-  the `-u` option to unbuffer the `jc` output if you would like immediate
-  output. See the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output)
-  for more information.
+> may appear the output is hanging due to the OS pipe buffers. This is
+> because `pidstat` output is too small to quickly fill up the buffer. Use
+> the `-u` option to unbuffer the `jc` output if you would like immediate
+> output. See the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output)
+> for more information.
 
 Usage (module):