From fdec4f08c02e96a1be513c1619ee02fe68007b65 Mon Sep 17 00:00:00 2001
From: Kelly Brazil <kellyjonbrazil@gmail.com>
Date: Fri, 21 Oct 2022 11:50:06 -0700
Subject: [PATCH] add schema docs for pci-ids

---
 docs/parsers/pci_ids.md | 57 +++++++++++++++++++++++++++++++++--------
 jc/parsers/pci_ids.py   | 57 +++++++++++++++++++++++++++++++++--------
 man/jc.1                |  2 +-
 3 files changed, 95 insertions(+), 21 deletions(-)

diff --git a/docs/parsers/pci_ids.md b/docs/parsers/pci_ids.md
index 88a160eb..97ab68a5 100644
--- a/docs/parsers/pci_ids.md
+++ b/docs/parsers/pci_ids.md
@@ -9,6 +9,28 @@ This parser converts the pci.ids database file.
 
 https://raw.githubusercontent.com/pciutils/pciids/master/pci.ids
 
+A nested schema allows straightforward queries with tools like `jq`. Hex id
+numbers are prefixed with an underscore (`_`) so bracket notation is not
+necessary when referencing. For example:
+
+    $ cat pci.ids | jc --pci-ids | jq '.vendors._9005._0053._9005._ffff.subsystem_name'
+    "AIC-7896 SCSI Controller mainboard implementation"
+
+Here are the vendor and class mappings:
+
+    jq '.vendors._001c._0001._001c._0005.subsystem_name'
+                  |     |     |     |
+                  |     |     |     subdevice
+                  |     |     subvendor
+                  |     device
+                  vendor
+
+    jq '.classes._0c._03._40'
+                  |   |   |
+                  |   |   prog_if
+                  |   subclass
+                  class
+
 Usage (cli):
 
     $ cat pci.ids | jc --pci-ids
@@ -20,21 +42,36 @@ Usage (module):
 
 Schema:
 
-    [
-      {
-        "pci-id":     string,
-        "bar":     boolean,
-        "baz":     integer
+    {
+      "vendors": {
+        "_<vendor_id>": {
+          "vendor_name":                 string,
+          "_<device_id>": {
+            "device_name":               string,
+            "_<subvendor_id>": {
+              "_<subdevice_id":          string
+            }
+          }
+        }
+      },
+      "classes": {
+        "_<class_id>": {
+          "class_name":                  string,
+          "_<subclass_id>": {
+            "subclass_name":             string,
+            "_<prog_if>":                string
+          }
+        }
       }
-    ]
+    }
 
 Examples:
 
-    $ cat pci.ids | jc --pci-id -p
-    []
+    $ cat pci.ids | jc --pci-ids | jq '.vendors._001c._0001._001c._0005.subsystem_name'
+    "2 Channel CAN Bus SJC1000 (Optically Isolated)"
 
-    $ cat pci.ids | jc --pci-id -p -r
-    []
+    $ cat pci.ids | jc --pci-ids | jq '.classes._0c._03._40'
+    "USB4 Host Interface"
 
 <a id="jc.parsers.pci_ids.parse"></a>
 
diff --git a/jc/parsers/pci_ids.py b/jc/parsers/pci_ids.py
index da232273..4419fd82 100644
--- a/jc/parsers/pci_ids.py
+++ b/jc/parsers/pci_ids.py
@@ -4,6 +4,28 @@ This parser converts the pci.ids database file.
 
 https://raw.githubusercontent.com/pciutils/pciids/master/pci.ids
 
+A nested schema allows straightforward queries with tools like `jq`. Hex id
+numbers are prefixed with an underscore (`_`) so bracket notation is not
+necessary when referencing. For example:
+
+    $ cat pci.ids | jc --pci-ids | jq '.vendors._9005._0053._9005._ffff.subsystem_name'
+    "AIC-7896 SCSI Controller mainboard implementation"
+
+Here are the vendor and class mappings:
+
+    jq '.vendors._001c._0001._001c._0005.subsystem_name'
+                  |     |     |     |
+                  |     |     |     subdevice
+                  |     |     subvendor
+                  |     device
+                  vendor
+
+    jq '.classes._0c._03._40'
+                  |   |   |
+                  |   |   prog_if
+                  |   subclass
+                  class
+
 Usage (cli):
 
     $ cat pci.ids | jc --pci-ids
@@ -15,21 +37,36 @@ Usage (module):
 
 Schema:
 
-    [
-      {
-        "pci-id":     string,
-        "bar":     boolean,
-        "baz":     integer
+    {
+      "vendors": {
+        "_<vendor_id>": {
+          "vendor_name":                 string,
+          "_<device_id>": {
+            "device_name":               string,
+            "_<subvendor_id>": {
+              "_<subdevice_id":          string
+            }
+          }
+        }
+      },
+      "classes": {
+        "_<class_id>": {
+          "class_name":                  string,
+          "_<subclass_id>": {
+            "subclass_name":             string,
+            "_<prog_if>":                string
+          }
+        }
       }
-    ]
+    }
 
 Examples:
 
-    $ cat pci.ids | jc --pci-id -p
-    []
+    $ cat pci.ids | jc --pci-ids | jq '.vendors._001c._0001._001c._0005.subsystem_name'
+    "2 Channel CAN Bus SJC1000 (Optically Isolated)"
 
-    $ cat pci.ids | jc --pci-id -p -r
-    []
+    $ cat pci.ids | jc --pci-ids | jq '.classes._0c._03._40'
+    "USB4 Host Interface"
 """
 import re
 from typing import Dict
diff --git a/man/jc.1 b/man/jc.1
index 05a57fb7..fad13c4c 100644
--- a/man/jc.1
+++ b/man/jc.1
@@ -1,4 +1,4 @@
-.TH jc 1 2022-10-19 1.22.1 "JSON Convert"
+.TH jc 1 2022-10-21 1.22.1 "JSON Convert"
 .SH NAME
 \fBjc\fP \- JSON Convert JSONifies the output of many CLI tools, file-types, and strings
 .SH SYNOPSIS