add traceroute doc

docgen.sh

@@ -51,6 +51,7 @@ pydocmd simple jc.parsers.systemctl_lj+ > ../docs/parsers/systemctl_lj.md
 pydocmd simple jc.parsers.systemctl_ls+ > ../docs/parsers/systemctl_ls.md
 pydocmd simple jc.parsers.systemctl_luf+ > ../docs/parsers/systemctl_luf.md
 pydocmd simple jc.parsers.timedatectl+ > ../docs/parsers/timedatectl.md
+pydocmd simple jc.parsers.traceroute+ > ../docs/parsers/traceroute.md
 pydocmd simple jc.parsers.uname+ > ../docs/parsers/uname.md
 pydocmd simple jc.parsers.uptime+ > ../docs/parsers/uptime.md
 pydocmd simple jc.parsers.w+ > ../docs/parsers/w.md

docs/parsers/traceroute.md

@@ -0,0 +1,168 @@
+# jc.parsers.traceroute
+jc - JSON CLI output utility traceroute Parser
+
+Usage:
+
+    specify --traceroute as the first argument if the piped input is coming from traceroute
+
+    Note: on OSX and FreeBSD be sure to redirect STDERR to STDOUT since the header line is sent to STDERR
+          e.g. $ traceroute 8.8.8.8 2>&1 | jc --traceroute
+
+Compatibility:
+
+    'linux', 'darwin', 'freebsd'
+
+Examples:
+
+    $ traceroute google.com | jc --traceroute -p
+    {
+      "destination_ip": "216.58.194.46",
+      "destination_name": "google.com",
+      "hops": [
+        {
+          "hop": 1,
+          "probes": [
+            {
+              "annotation": null,
+              "asn": null,
+              "ip": "216.230.231.141",
+              "name": "216-230-231-141.static.houston.tx.oplink.net",
+              "rtt": 198.574
+            },
+            {
+              "annotation": null,
+              "asn": null,
+              "ip": "216.230.231.141",
+              "name": "216-230-231-141.static.houston.tx.oplink.net",
+              "rtt": null
+            },
+            {
+              "annotation": null,
+              "asn": null,
+              "ip": "216.230.231.141",
+              "name": "216-230-231-141.static.houston.tx.oplink.net",
+              "rtt": 198.65
+            }
+          ]
+        },
+        ...
+      ]
+    }
+
+    $ traceroute google.com  | jc --traceroute -p -r
+    {
+      "destination_ip": "216.58.194.46",
+      "destination_name": "google.com",
+      "hops": [
+        {
+          "hop": "1",
+          "probes": [
+            {
+              "annotation": null,
+              "asn": null,
+              "ip": "216.230.231.141",
+              "name": "216-230-231-141.static.houston.tx.oplink.net",
+              "rtt": "198.574"
+            },
+            {
+              "annotation": null,
+              "asn": null,
+              "ip": "216.230.231.141",
+              "name": "216-230-231-141.static.houston.tx.oplink.net",
+              "rtt": null
+            },
+            {
+              "annotation": null,
+              "asn": null,
+              "ip": "216.230.231.141",
+              "name": "216-230-231-141.static.houston.tx.oplink.net",
+              "rtt": "198.650"
+            }
+          ]
+        },
+        ...
+      ]
+    }
+
+## info
+```python
+info(self, /, *args, **kwargs)
+```
+
+## Traceroute
+```python
+Traceroute(self, dest_name, dest_ip)
+```
+
+Abstraction of a traceroute result.
+
+## Hop
+```python
+Hop(self, idx)
+```
+
+Abstraction of a hop in a traceroute.
+
+## Probe
+```python
+Probe(self, name=None, ip=None, asn=None, rtt=None, annotation=None)
+```
+
+Abstraction of a probe in a traceroute.
+
+## loads
+```python
+loads(data)
+```
+Parser entry point. Parses the output of a traceroute execution
+## process
+```python
+process(proc_data)
+```
+
+Final processing to conform to the schema.
+
+Parameters:
+
+    proc_data:   (dictionary) raw structured data to process
+
+Returns:
+
+    Dictionary. Structured data with the following schema:
+
+    {
+      "destination_ip":         string,
+      "destination_name":       string,
+      "hops": [
+        {
+          "hop":                integer,
+          "probes": [
+            {
+              "annotation":     string,
+              "asn":            integer,
+              "ip":             string,
+              "name":           string,
+              "rtt":            float
+            }
+          ]
+        }
+      ]
+    }
+
+## parse
+```python
+parse(data, raw=False, quiet=False)
+```
+
+Main text parsing function
+
+Parameters:
+
+    data:        (string)  text data to parse
+    raw:         (boolean) output preprocessed JSON if True
+    quiet:       (boolean) suppress warning messages if True
+
+Returns:
+
+    Dictionary. Raw or processed structured data.
+