fixup help, man, readme, about docs

README.md

@@ -225,6 +225,7 @@ option.
 | `     --pip-show` | `pip show` command parser                               | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/pip_show)       |
 | `        --plist` | PLIST file parser                                       | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/plist)          |
 | `     --postconf` | `postconf -M` command parser                            | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/postconf)       |
+| `         --proc` | `/proc/` file parser                                    | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/proc)           |
 | `           --ps` | `ps` command parser                                     | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/ps)             |
 | `        --route` | `route` command parser                                  | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/route)          |
 | `       --rpm-qi` | `rpm -qi` command parser                                | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/rpm_qi)         |
@@ -278,7 +279,7 @@ option.
 | `-a`  | `--about`       | About `jc`. Prints information about `jc` and the parsers (in JSON or YAML, of course!)                             |
 | `-C`  | `--force-color` | Force color output even when using pipes (overrides `-m` and the `NO_COLOR` env variable)                           |
 | `-d`  | `--debug`       | Debug mode. Prints trace messages if parsing issues are encountered (use`-dd` for verbose debugging)                |
-| `-h`  | `--help`        | Help. Use `jc -h --parser_name` for parser documentation                                                            |
+| `-h`  | `--help`        | Help. Use `jc -h --parser_name` for parser documentation. Use twice to show hidden parsers (e.g. `-hh`)             |
 | `-m`  | `--monochrome`  | Monochrome output                                                                                                   |
 | `-M`  | `--meta-out`    | Add metadata to output including timestamp, parser name, magic command, magic command exit code, etc.               |                                                                        |
 | `-p`  | `--pretty`      | Pretty format the JSON output                                                                                       |

completions/jc_bash_completion.sh

@@ -4,7 +4,7 @@ _jc()
           jc_about_options jc_about_mod_options jc_help_options jc_special_options
 
     jc_commands=(acpi airport arp blkid chage cksum crontab date df dig dmidecode dpkg du env file finger free git gpg hciconfig id ifconfig iostat iptables iw jobs last lastb ls lsblk lsmod lsof lsusb md5 md5sum mdadm mount mpstat netstat nmcli ntpq pidstat ping ping6 pip pip3 postconf printenv ps route rpm rsync sfdisk sha1sum sha224sum sha256sum sha384sum sha512sum shasum ss stat sum sysctl systemctl systeminfo timedatectl top tracepath tracepath6 traceroute traceroute6 ufw uname update-alternatives upower uptime vdir vmstat w wc who xrandr zipinfo)
-    jc_parsers=(--acpi --airport --airport-s --arp --asciitable --asciitable-m --blkid --cef --cef-s --chage --cksum --crontab --crontab-u --csv --csv-s --date --df --dig --dir --dmidecode --dpkg-l --du --email-address --env --file --finger --free --fstab --git-log --git-log-s --gpg --group --gshadow --hash --hashsum --hciconfig --history --hosts --id --ifconfig --ini --iostat --iostat-s --ip-address --iptables --iso-datetime --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lsusb --m3u --mdadm --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --plist --postconf --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --syslog --syslog-s --syslog-bsd --syslog-bsd-s --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --timestamp --top --top-s --tracepath --traceroute --ufw --ufw-appinfo --uname --update-alt-gs --update-alt-q --upower --uptime --url --vmstat --vmstat-s --w --wc --who --x509-cert --xml --xrandr --yaml --zipinfo)
+    jc_parsers=(--acpi --airport --airport-s --arp --asciitable --asciitable-m --blkid --cef --cef-s --chage --cksum --crontab --crontab-u --csv --csv-s --date --df --dig --dir --dmidecode --dpkg-l --du --email-address --env --file --finger --free --fstab --git-log --git-log-s --gpg --group --gshadow --hash --hashsum --hciconfig --history --hosts --id --ifconfig --ini --iostat --iostat-s --ip-address --iptables --iso-datetime --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lsusb --m3u --mdadm --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --plist --postconf --proc --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --syslog --syslog-s --syslog-bsd --syslog-bsd-s --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --timestamp --top --top-s --tracepath --traceroute --ufw --ufw-appinfo --uname --update-alt-gs --update-alt-q --upower --uptime --url --vmstat --vmstat-s --w --wc --who --x509-cert --xml --xrandr --yaml --zipinfo)
     jc_options=(--force-color -C --debug -d --monochrome -m --meta-out -M --pretty -p --quiet -q --raw -r --unbuffer -u --yaml-out -y)
     jc_about_options=(--about -a)
     jc_about_mod_options=(--pretty -p --yaml-out -y --monochrome -m --force-color -C)

completions/jc_zsh_completion.sh

@@ -95,7 +95,7 @@ _jc() {
         'xrandr:run "xrandr" command with magic syntax.'
         'zipinfo:run "zipinfo" command with magic syntax.'
     )
-    jc_parsers=(--acpi --airport --airport-s --arp --asciitable --asciitable-m --blkid --cef --cef-s --chage --cksum --crontab --crontab-u --csv --csv-s --date --df --dig --dir --dmidecode --dpkg-l --du --email-address --env --file --finger --free --fstab --git-log --git-log-s --gpg --group --gshadow --hash --hashsum --hciconfig --history --hosts --id --ifconfig --ini --iostat --iostat-s --ip-address --iptables --iso-datetime --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lsusb --m3u --mdadm --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --plist --postconf --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --syslog --syslog-s --syslog-bsd --syslog-bsd-s --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --timestamp --top --top-s --tracepath --traceroute --ufw --ufw-appinfo --uname --update-alt-gs --update-alt-q --upower --uptime --url --vmstat --vmstat-s --w --wc --who --x509-cert --xml --xrandr --yaml --zipinfo)
+    jc_parsers=(--acpi --airport --airport-s --arp --asciitable --asciitable-m --blkid --cef --cef-s --chage --cksum --crontab --crontab-u --csv --csv-s --date --df --dig --dir --dmidecode --dpkg-l --du --email-address --env --file --finger --free --fstab --git-log --git-log-s --gpg --group --gshadow --hash --hashsum --hciconfig --history --hosts --id --ifconfig --ini --iostat --iostat-s --ip-address --iptables --iso-datetime --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lsusb --m3u --mdadm --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --plist --postconf --proc --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --syslog --syslog-s --syslog-bsd --syslog-bsd-s --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --timestamp --top --top-s --tracepath --traceroute --ufw --ufw-appinfo --uname --update-alt-gs --update-alt-q --upower --uptime --url --vmstat --vmstat-s --w --wc --who --x509-cert --xml --xrandr --yaml --zipinfo)
     jc_parsers_describe=(
         '--acpi:`acpi` command parser'
         '--airport:`airport -I` command parser'
@@ -172,6 +172,7 @@ _jc() {
         '--pip-show:`pip show` command parser'
         '--plist:PLIST file parser'
         '--postconf:`postconf -M` command parser'
+        '--proc:`/proc/` file parser'
         '--ps:`ps` command parser'
         '--route:`route` command parser'
         '--rpm-qi:`rpm -qi` command parser'

docs/lib.md

@@ -162,7 +162,8 @@ Parameters:
 ### all\_parser\_info
 
 ```python
-def all_parser_info(documentation: bool = False) -> List[Dict]
+def all_parser_info(documentation: bool = False,
+                    show_hidden: bool = False) -> List[Dict]
 ```
 
 Returns a list of dictionaries that includes metadata for all parser
@@ -171,6 +172,8 @@ modules.
 Parameters:
 
     documentation:      (boolean)    include parser docstrings if True
+    show_hidden:        (boolean)    also show parsers marked as hidden
+                                     in their info metadata.
 
 <a id="jc.lib.get_help"></a>
 

docs/parsers/proc.md

@@ -0,0 +1,60 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.proc"></a>
+
+# jc.parsers.proc
+
+jc - JSON Convert Proc file output parser
+
+<<Short procfile description and caveats>>
+
+Usage (cli):
+
+    $ cat /proc/<file> | jc --procfile
+
+Usage (module):
+
+    import jc
+    result = jc.parse('procfile', proc_file)
+
+Schema:
+
+    [
+      {
+        "procfile":     string,
+        "bar":     boolean,
+        "baz":     integer
+      }
+    ]
+
+Examples:
+
+    $ procfile | jc --procfile -p
+    []
+
+    $ procfile | jc --procfile -p -r
+    []
+
+<a id="jc.parsers.proc.parse"></a>
+
+### parse
+
+```python
+def parse(data: str, raw: bool = False, quiet: bool = False) -> List[Dict]
+```
+
+Main text parsing function
+
+Parameters:
+
+    data:        (string)  text data to parse
+    raw:         (boolean) unprocessed output if True
+    quiet:       (boolean) suppress warning messages if True
+
+Returns:
+
+    List of Dictionaries. Raw or processed structured data.
+
+### Parser Information
+Compatibility:  linux
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/proc_meminfo.md

@@ -0,0 +1,58 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.proc_meminfo"></a>
+
+# jc.parsers.proc\_meminfo
+
+jc - JSON Convert `/proc/meminfo` file parser
+
+Usage (cli):
+
+    $ cat /proc/meminfo | jc --proc
+
+Usage (module):
+
+    import jc
+    result = jc.parse('proc_meminfo', proc_meminfo_file)
+
+Schema:
+
+    [
+      {
+        "foo":     string,
+        "bar":     boolean,
+        "baz":     integer
+      }
+    ]
+
+Examples:
+
+    $ foo | jc --foo -p
+    []
+
+    $ foo | jc --foo -p -r
+    []
+
+<a id="jc.parsers.proc_meminfo.parse"></a>
+
+### parse
+
+```python
+def parse(data: str, raw: bool = False, quiet: bool = False) -> Dict
+```
+
+Main text parsing function
+
+Parameters:
+
+    data:        (string)  text data to parse
+    raw:         (boolean) unprocessed output if True
+    quiet:       (boolean) suppress warning messages if True
+
+Returns:
+
+    Dictionary. Raw or processed structured data.
+
+### Parser Information
+Compatibility:  linux
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/proc_modules.md

@@ -0,0 +1,121 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.proc_modules"></a>
+
+# jc.parsers.proc\_modules
+
+jc - JSON Convert `/proc/modules` command output parser
+
+<<Short proc_modules description and caveats>>
+
+Usage (cli):
+
+    $ cat /proc/modules | jc --proc
+
+Usage (module):
+
+    import jc
+    result = jc.parse('proc_modules', proc_modules_file)
+
+Schema:
+
+    [
+      {
+        "module":                   string,
+        "size":                     integer,
+        "used":                     integer,
+        "used_by": [
+                                    string
+        ],
+        "status":                   string,
+        "location":                 string
+      }
+    ]
+
+Examples:
+
+    $ cat /proc/modules | jc --proc -p
+    [
+      {
+        "module": "binfmt_misc",
+        "size": 24576,
+        "used": 1,
+        "used_by": [],
+        "status": "Live",
+        "location": "0xffffffffc0ab4000"
+      },
+      {
+        "module": "vsock_loopback",
+        "size": 16384,
+        "used": 0,
+        "used_by": [],
+        "status": "Live",
+        "location": "0xffffffffc0a14000"
+      },
+      {
+        "module": "vmw_vsock_virtio_transport_common",
+        "size": 36864,
+        "used": 1,
+        "used_by": [
+          "vsock_loopback"
+        ],
+        "status": "Live",
+        "location": "0xffffffffc0a03000"
+      },
+      ...
+    ]
+
+    $ proc_modules | jc --proc_modules -p -r
+    [
+      {
+        "module": "binfmt_misc",
+        "size": "24576",
+        "used": "1",
+        "used_by": [],
+        "status": "Live",
+        "location": "0xffffffffc0ab4000"
+      },
+      {
+        "module": "vsock_loopback",
+        "size": "16384",
+        "used": "0",
+        "used_by": [],
+        "status": "Live",
+        "location": "0xffffffffc0a14000"
+      },
+      {
+        "module": "vmw_vsock_virtio_transport_common",
+        "size": "36864",
+        "used": "1",
+        "used_by": [
+          "vsock_loopback"
+        ],
+        "status": "Live",
+        "location": "0xffffffffc0a03000"
+      },
+      ...
+    ]
+
+<a id="jc.parsers.proc_modules.parse"></a>
+
+### parse
+
+```python
+def parse(data: str, raw: bool = False, quiet: bool = False) -> List[Dict]
+```
+
+Main text parsing function
+
+Parameters:
+
+    data:        (string)  text data to parse
+    raw:         (boolean) unprocessed output if True
+    quiet:       (boolean) suppress warning messages if True
+
+Returns:
+
+    List of Dictionaries. Raw or processed structured data.
+
+### Parser Information
+Compatibility:  linux
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

jc/cli.py

@@ -11,8 +11,9 @@ import signal
 import shlex
 import subprocess
 from .lib import (__version__, parser_info, all_parser_info, parsers,
-                  _get_parser, _parser_is_streaming, standard_parser_mod_list,
-                  plugin_parser_mod_list, streaming_parser_mod_list)
+                  _get_parser, _parser_is_streaming, parser_mod_list,
+                  standard_parser_mod_list, plugin_parser_mod_list,
+                  streaming_parser_mod_list)
 from . import utils
 from .cli_data import long_options_map, new_pygments_colors, old_pygments_colors
 from .shell_completions import bash_completion, zsh_completion
@@ -120,11 +121,11 @@ def parser_shortname(parser_arg):
     return parser_arg[2:]
 
 
-def parsers_text(indent=0, pad=0):
+def parsers_text(indent=0, pad=0, show_hidden=False):
     """Return the argument and description information from each parser"""
     ptext = ''
     padding_char = ' '
-    for p in all_parser_info():
+    for p in all_parser_info(show_hidden=show_hidden):
         parser_arg = p.get('argument', 'UNKNOWN')
         padding = pad - len(parser_arg)
         parser_desc = p.get('description', 'No description available.')
@@ -164,17 +165,17 @@ def about_jc():
         'license': info.license,
         'python_version': '.'.join((str(sys.version_info.major), str(sys.version_info.minor), str(sys.version_info.micro))),
         'python_path': sys.executable,
-        'parser_count': len(all_parser_info()),
+        'parser_count': len(parser_mod_list()),
         'standard_parser_count': len(standard_parser_mod_list()),
         'streaming_parser_count': len(streaming_parser_mod_list()),
         'plugin_parser_count': len(plugin_parser_mod_list()),
-        'parsers': all_parser_info()
+        'parsers': all_parser_info(show_hidden=True)
     }
 
 
-def helptext():
+def helptext(show_hidden=False):
     """Return the help text with the list of parsers"""
-    parsers_string = parsers_text(indent=4, pad=20)
+    parsers_string = parsers_text(indent=4, pad=20, show_hidden=show_hidden)
     options_string = options_text(indent=4, pad=20)
 
     helptext_string = f'''\
@@ -205,7 +206,7 @@ Examples:
     return helptext_string
 
 
-def help_doc(options):
+def help_doc(options, show_hidden=False):
     """
     Returns the parser documentation if a parser is found in the arguments,
     otherwise the general help text is returned.
@@ -228,7 +229,7 @@ def help_doc(options):
             utils._safe_pager(doc_text)
             return
 
-    utils._safe_print(helptext())
+    utils._safe_print(helptext(show_hidden=show_hidden))
     return
 
 
@@ -525,6 +526,7 @@ def main():
     force_color = 'C' in options
     mono = ('m' in options or bool(os.getenv('NO_COLOR'))) and not force_color
     help_me = 'h' in options
+    verbose_help = options.count('h') > 1
     pretty = 'p' in options
     quiet = 'q' in options
     ignore_exceptions = options.count('q') > 1
@@ -552,7 +554,7 @@ def main():
         sys.exit(0)
 
     if help_me:
-        help_doc(sys.argv)
+        help_doc(sys.argv, show_hidden=verbose_help)
         sys.exit(0)
 
     if version_info:

man/jc.1

@@ -1,4 +1,4 @@
-.TH jc 1 2022-08-29 1.21.2 "JSON Convert"
+.TH jc 1 2022-09-06 1.21.2 "JSON Convert"
 .SH NAME
 \fBjc\fP \- JSON Convert JSONifies the output of many CLI tools and file-types
 .SH SYNOPSIS
@@ -392,6 +392,21 @@ PLIST file parser
 \fB--postconf\fP
 `postconf -M` command parser
 
+.TP
+.B
+\fB--proc\fP
+`/proc/` file parser
+
+.TP
+.B
+\fB--proc-meminfo\fP
+`/proc/meminfo` command parser
+
+.TP
+.B
+\fB--proc-modules\fP
+`/proc/modules` command parser
+
 .TP
 .B
 \fB--ps\fP
@@ -639,7 +654,7 @@ Debug - show traceback (use \fB-dd\fP for verbose traceback)
 .TP
 .B
 \fB-h\fP, \fB--help\fP
-Help (\fB--help --parser_name\fP for parser documentation)
+Help (\fB--help --parser_name\fP for parser documentation). Use twice to show hidden parsers (e.g. \fB-hh\fP)
 .TP
 .B
 \fB-m\fP, \fB--monochrome\fP

readmegen.py

@@ -1,12 +1,15 @@
 #!/usr/bin/env python3
 # Genereate README.md from jc metadata using jinja2 templates
 import jc.cli
+import jc.lib
 from jinja2 import Environment, FileSystemLoader
 
 file_loader = FileSystemLoader('templates')
 env = Environment(loader=file_loader)
 template = env.get_template('readme_template')
-output = template.render(jc=jc.cli.about_jc())
+# output = template.render(jc=jc.cli.about_jc())
+output = template.render(parsers=jc.lib.all_parser_info(),
+                         info=jc.cli.about_jc())
 
 with open('README.md', 'w') as f:
     f.write(output)

templates/manpage_template

@@ -44,7 +44,7 @@ Debug - show traceback (use \fB-dd\fP for verbose traceback)
 .TP
 .B
 \fB-h\fP, \fB--help\fP
-Help (\fB--help --parser_name\fP for parser documentation)
+Help (\fB--help --parser_name\fP for parser documentation). Use twice to show hidden parsers (e.g. \fB-hh\fP)
 .TP
 .B
 \fB-m\fP, \fB--monochrome\fP

templates/readme_template

@@ -149,7 +149,7 @@ option.
 ### Parsers
 
 | Argument          | Command or Filetype                                     | Documentation                                                              |
-|-------------------|---------------------------------------------------------|----------------------------------------------------------------------------|{% for parser in jc.parsers %}
+|-------------------|---------------------------------------------------------|----------------------------------------------------------------------------|{% for parser in parsers %}
 | `{{ "{:>15}".format(parser.argument) }}` | {{ "{:<55}".format(parser.description) }} | {{ "{:<74}".format("[details](https://kellyjonbrazil.github.io/jc/docs/parsers/" + parser.name + ")") }} |{% endfor %}
 
 ### Options
@@ -159,7 +159,7 @@ option.
 | `-a`  | `--about`       | About `jc`. Prints information about `jc` and the parsers (in JSON or YAML, of course!)                             |
 | `-C`  | `--force-color` | Force color output even when using pipes (overrides `-m` and the `NO_COLOR` env variable)                           |
 | `-d`  | `--debug`       | Debug mode. Prints trace messages if parsing issues are encountered (use`-dd` for verbose debugging)                |
-| `-h`  | `--help`        | Help. Use `jc -h --parser_name` for parser documentation                                                            |
+| `-h`  | `--help`        | Help. Use `jc -h --parser_name` for parser documentation. Use twice to show hidden parsers (e.g. `-hh`)             |
 | `-m`  | `--monochrome`  | Monochrome output                                                                                                   |
 | `-M`  | `--meta-out`    | Add metadata to output including timestamp, parser name, magic command, magic command exit code, etc.               |                                                                        |
 | `-p`  | `--pretty`      | Pretty format the JSON output                                                                                       |
@@ -1104,4 +1104,4 @@ cat istio.yaml | jc --yaml -p
 ]
 ```
 
-{{ jc.copyright }}
+{{ info.copyright }}