doc update

2025-06-17 00:07:37 +02:00 · 2022-07-20 17:09:09 -07:00
parent 956ad75168
commit c4fc5409e3
6 changed files with 164 additions and 8 deletions
--- a/README.md
+++ b/README.md
@ -190,6 +190,7 @@ option.
 | `       --iostat` | `iostat` command parser                                 | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/iostat)         |
 | `     --iostat-s` | `iostat` command streaming parser                       | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/iostat_s)       |
 | `     --iptables` | `iptables` command parser                               | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/iptables)       |
+| ` --iso-datetime` | ISO 8601 Datetime string parser                         | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/iso_datetime)   |
 | `      --iw-scan` | `iw dev [device] scan` command parser                   | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/iw_scan)        |
 | ` --jar-manifest` | MANIFEST.MF file parser                                 | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/jar_manifest)   |
 | `         --jobs` | `jobs` command parser                                   | [details](https://kellyjonbrazil.github.io/jc/docs/parsers/jobs)           |
--- a/completions/jc_bash_completion.sh
+++ b/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 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 --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 --iptables --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lsusb --m3u --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --postconf --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --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 --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 --iptables --iso-datetime --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lsusb --m3u --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --postconf --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --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 --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)
--- a/completions/jc_zsh_completion.sh
+++ b/completions/jc_zsh_completion.sh
@ -94,7 +94,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 --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 --iptables --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lsusb --m3u --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --postconf --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --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 --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 --iptables --iso-datetime --iw-scan --jar-manifest --jobs --jwt --kv --last --ls --ls-s --lsblk --lsmod --lsof --lsusb --m3u --mount --mpstat --mpstat-s --netstat --nmcli --ntpq --passwd --pidstat --pidstat-s --ping --ping-s --pip-list --pip-show --postconf --ps --route --rpm-qi --rsync --rsync-s --sfdisk --shadow --ss --stat --stat-s --sysctl --systemctl --systemctl-lj --systemctl-ls --systemctl-luf --systeminfo --time --timedatectl --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'
@ -138,6 +138,7 @@ _jc() {
        '--iostat:`iostat` command parser'
        '--iostat-s:`iostat` command streaming parser'
        '--iptables:`iptables` command parser'
+        '--iso-datetime:ISO 8601 Datetime string parser'
        '--iw-scan:`iw dev [device] scan` command parser'
        '--jar-manifest:MANIFEST.MF file parser'
        '--jobs:`jobs` command parser'
--- a/docs/parsers/iso_datetime.md
+++ b/docs/parsers/iso_datetime.md
@ -0,0 +1,87 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.iso_datetime"></a>
+
+# jc.parsers.iso\_datetime
+
+jc - JSON Convert ISO 8601 Datetime string parser
+
+This parser supports standard ISO 8601 strings that include both date and
+time. If no timezone or offset information is available in the sring, then
+UTC timezone is used.
+
+Usage (cli):
+
+    $ echo "2022-07-20T14:52:45Z" | jc --iso-datetime
+
+Usage (module):
+
+    import jc
+    result = jc.parse('iso_datetime', iso_8601_output)
+
+Schema:
+
+    {
+      "year":               integer,
+      "month":              string,
+      "month_num":          integer,
+      "day":                integer,
+      "weekday":            string,
+      "weekday_num":        integer,
+      "hour":               integer,
+      "hour_24":            integer,
+      "minute":             integer,
+      "second":             integer,
+      "period":             string,
+      "utc_offset":         string,
+      "day_of_year":        integer,
+      "week_of_year":       integer,
+      "iso":                string,
+      "timestamp":          integer
+    }
+
+Examples:
+
+    $ echo "2022-07-20T14:52:45Z" | jc --iso-datetime -p
+    {
+      "year": 2022,
+      "month": "Jul",
+      "month_num": 7,
+      "day": 20,
+      "weekday": "Wed",
+      "weekday_num": 3,
+      "hour": 2,
+      "hour_24": 14,
+      "minute": 52,
+      "second": 45,
+      "period": "PM",
+      "utc_offset": "+0000",
+      "day_of_year": 201,
+      "week_of_year": 29,
+      "iso": "2022-07-20T14:52:45+00:00",
+      "timestamp": 1658328765
+    }
+
+<a id="jc.parsers.iso_datetime.parse"></a>
+
+### parse
+
+```python
+def parse(data, raw=False, quiet=False)
+```
+
+Main text parsing function
+
+Parameters:
+
+    data:        (string)  text data to parse
+    raw:         (boolean) unprocessed output if True
+    quiet:       (boolean) suppress warning messages if True
+
+Returns:
+
+    Dictionary. Raw or processed structured data.
+
+### Parser Information
+Compatibility:  linux, aix, freebsd, darwin, win32, cygwin
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)
--- a/docs/parsers/url.md
+++ b/docs/parsers/url.md
@ -5,6 +5,18 @@

 jc - JSON Convert URL string parser

+This parser will work with naked and wrapped URL strings:
+
+- `scheme://host/path`
+- `URL:scheme://host/path`
+- `<scheme://host/path>`
+- `<URL:scheme://host/path>`
+
+Two query representations are available and documented in the schema.
+
+Normalized quoted and unquoted versions of the original URL are also
+included.
+
 Usage (cli):

    $ echo "http://example.com/test/path?q1=foo&q2=bar#frag" | jc --url
@ -17,12 +29,25 @@ Usage (module):
 Schema:

    {
+      "quoted":               string,
+      'unquoted":             string,
      "scheme":               string,
      "netloc":               string,
      "path":                 string or null,
-      "query": {              object or null,
-        <query-key>:          string
+      "path_list": [          array or null
+                              string
+      ],
+      "query": {              object or null
+        <query-key>: [        array or null
+          <query-value>       string             # [0]
+        ]
      },
+      "query_list": [         array or null
+        [
+          <query-key>         string,            # [1]
+          <query-value>       string
+        ]
+      ],
      "fragment":             string or null,
      "username":             string or null,
      "password":             string or null,
@ -30,17 +55,48 @@ Schema:
      "port":                 integer or null
    }

+    [0] Duplicate query-keys will have their values consolidated into the
+        array of query-values
+    [1] The first array value is the query-key and the second value is the
+        query-value
+
 Examples:

-    $ echo "http://example.com/test/path?q1=foo&q2=bar#frag" | jc --url -p
+    % echo "http://example.com/test/path?q1=foo&q1=bar&q2=baz#frag" \\
+           | jc --url -p
    {
+      "quoted": "http://example.com/test/path?q1%3Dfoo%26q1%3Dbar%26q2%3Dbaz#frag",
+      "unquoted": "http://example.com/test/path?q1=foo&q1=bar&q2=baz#frag",
      "scheme": "http",
      "netloc": "example.com",
      "path": "/test/path",
+      "path_list": [
+        "test",
+        "path"
+      ],
      "query": {
-        "q1": "foo",
-        "q2": "bar"
+        "q1": [
+          "foo",
+          "bar"
+        ],
+        "q2": [
+          "baz"
+        ]
      },
+      "query_list": [
+        [
+          "q1",
+          "foo"
+        ],
+        [
+          "q1",
+          "bar"
+        ],
+        [
+          "q2",
+          "baz"
+        ]
+      ],
      "fragment": "frag",
      "username": null,
      "password": null,
@ -50,10 +106,16 @@ Examples:

    $ echo "ftp://localhost/filepath" | jc --url -p
    {
+      "quoted": "ftp://localhost/filepath",
+      "unquoted": "ftp://localhost/filepath",
      "scheme": "ftp",
      "netloc": "localhost",
      "path": "/filepath",
+      "path_list": [
+        "filepath"
+      ],
      "query": null,
+      "query_list": null,
      "fragment": null,
      "username": null,
      "password": null,
--- a/man/jc.1
+++ b/man/jc.1
@ -1,4 +1,4 @@
-.TH jc 1 2022-07-19 1.20.3 "JSON Convert"
+.TH jc 1 2022-07-20 1.20.3 "JSON Convert"
 .SH NAME
 \fBjc\fP \- JSON Convert JSONifies the output of many CLI tools and file-types
 .SH SYNOPSIS
@ -227,6 +227,11 @@ INI file parser
 \fB--iptables\fP
 `iptables` command parser

+.TP
+.B
+\fB--iso-datetime\fP
+ISO 8601 Datetime string parser
+
 .TP
 .B
 \fB--iw-scan\fP