Add support for --stdout-format to pkg-status command

1 files changed, 76 insertions, 0 deletions

diff --git a/bpkg/common.cli b/bpkg/common.cli
index dd0417d..cccf1d3 100644
--- a/bpkg/common.cli
+++ b/bpkg/common.cli
@@ -80,6 +80,14 @@ namespace bpkg
        \li|Even more detailed information.||"
     }
 
+    bpkg::stdout_format --stdout-format = bpkg::stdout_format::lines
+    {
+      "<format>",
+      "Representation format to use for printing to \cb{stdout}. Valid values
+       for this option are \cb{lines} (default) and \cb{json}. See the JSON
+       OUTPUT section below for details on the \cb{json} format."
+    }
+
     size_t --jobs|-j
     {
       "<num>",
@@ -409,4 +417,72 @@ namespace bpkg
       "Don't load default options files."
     }
   };
+
+  {
+    "",
+    "
+    \h|JSON OUTPUT|
+
+    Commands that support the JSON output specify their formats as a
+    serialized representation of a C++ \cb{struct} or an array thereof. For
+    example:
+
+    \
+    struct package
+    {
+      string name;
+    };
+
+    struct configuration
+    {
+      uint64_t         id;
+      string           path;
+      optional<string> name;
+      bool             default;
+      vector<package>  packages;
+    };
+    \
+
+    An example of the serialized JSON representation of \cb{struct}
+    \cb{configuration}:
+
+    \
+    {
+      \"id\": 1,
+      \"path\": \"/tmp/hello-gcc\",
+      \"name\": \"gcc\",
+      \"default\": true,
+      \"packages\": [
+        {
+          \"name\": \"hello\"
+        }
+      ]
+    }
+    \
+
+    This sections provides details on the overall properties of such formats
+    and the semantics of the \cb{struct} serialization.
+
+    The order of members in a JSON object is fixed as specified in the
+    corresponding \cb{struct}. While new members may be added in the
+    future (and should be ignored by older consumers), the semantics of the
+    existing members (including whether the top-level entry is an object or
+    array) may not change.
+
+    An object member is required unless its type is \cb{optional<>},
+    \cb{bool}, or \cb{vector<>} (array). For \cb{bool} members absent means
+    \cb{false}. For \cb{vector<>} members absent means empty. An empty
+    top-level array is always present.
+
+    For example, the following JSON text is a possible serialization of
+    the above \cb{struct} \cb{configuration}:
+
+    \
+    {
+      \"id\": 1,
+      \"path\": \"/tmp/hello-gcc\"
+    }
+    \
+    "
+  }
 }