P3051

schema/std_param-1.0.0.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://isocpp.org/release/schema/std_param-1.0.0.json",
+  "title": "Structured Parameters Version 1.0.0 JSON Schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema URI for the version of the structured parameters format.",
+      "type": "string",
+      "format": "uri"
+    },
+    "version": {
+      "description": "The Structured Parameters format version.",
+      "type": "string",
+      "$ref": "#/$defs/Version"
+    },
+    "arguments": {
+      "description": "Application direct arguments.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "options": {
+      "description": "Application structured options.",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$opt/Std.Param"
+        }
+      ],
+      "propertyName": {
+        "$ref": "#/$defs/Name"
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "required": [
+        "arguments"
+      ]
+    },
+    {
+      "required": [
+        "options"
+      ]
+    }
+  ],
+  "$defs": {
+    "Version": {
+      "type": "string",
+      "pattern": "^[0-9]+([.][0-9]+){0,2}$"
+    },
+    "Name": {
+      "type": "string",
+      "pattern": "^([a-z0-9_-]+[.])*([a-z0-9_-]+)$"
+    },
+    "StringOrArray": {
+      "type": [
+        "string",
+        "array"
+      ],
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "$opt": {
+    "Std.Param": {
+      "properties": {
+        "std.param": {
+          "description": "Recursive reference to one or more structured parameters files.",
+          "type": "object",
+          "properties": {
+            "pre": {
+              "$ref": "#/$defs/StringOrArray"
+            },
+            "post": {
+              "$ref": "#/$defs/StringOrArray"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "param": {
+        "$ref": "#/$opt/Std.Param/properties/std.param"
+      }
+    }
+  }
+}

src/eco_strctparam.tex

@@ -0,0 +1,258 @@
+%!TEX root = ecosystem.tex
+
+% strctparam
+\rSec0[strctparam]{Structured Parameters}
+
+
+% strctparam.pre
+\rSec1[strctparam.pre]{Preamble}
+
+\pnum
+This clause describes options, output, and formats that control the behavior of
+applications through the specification of arguments and options from
+\emph{structured parameters}.
+
+\pnum
+This clause specifies the \verb|std.strctparam| capability \iref{intspct.cap}
+version \verb|1.0.0|.
+
+\pnum
+An application can implement this capability.
+
+\pnum
+An application that implements the \verb|std.strctparam| capability shall
+include the \verb|std.strctparam| field and version value in the introspection
+JSON text output \iref{intspct.schema.cap}.
+
+% strctparam.overview
+\rSec1[strctparam.overview]{Overview}
+
+\pnum
+\begin{outputblock}
+@\emph{application}@ [ @\grammarterm{std-strctparam-input}@ [@\emph{file}@] ]
+\end{outputblock}
+
+\rSec1[strctparam.input]{Input Option}
+
+\pnum
+\grammarterm{std-strctparam-input}
+\begin{indented}
+	The pathname of a file to read the \emph{structured parameters} from. The
+	option is specified as \verb@--std-param=file@ or \verb@-std-param:file@. If
+	\emph{file} is ‘\verb@-@’, the standard input shall be used.
+\end{indented}
+
+\rSec1[strctparam.file]{Files}
+
+\pnum
+An application shall read a valid JSON text file that conforms to the
+\emph{structured parameters} schema \iref{strctparam.schema}.
+
+\pnum
+An application shall interpret the information in the file as if the options
+and arguments in the file occur in the same position as the
+\grammarterm{std-strctparam-input} parameter of the list of parameters given to
+the application. Given either directly as part of the application command line
+or as part of the arguments field \iref{strctparam.schema.args}.
+
+\pnum
+An application shall process arguments in the file in the order that they 
+appear.
+
+\pnum
+An application shall process options in the file as if the a new modified state
+replaces the current state.
+
+\rSec1[strctparam.schema]{Schema}
+
+\pnum
+A \emph{structured parameters} JSON text file shall contain one \emph{structured
+parameters} JSON object \iref{strctparam.schema.obj}.
+
+\rSec2[strctparam.schema.obj]{Structured Parameters Object}
+
+\pnum
+The \emph{structured parameters} object is the root JSON object of the 
+structured parameters JSON text.
+
+\pnum
+A \emph{structured parameters} object can have the following fields.
+
+\pnum
+A \emph{structured parameters} object shall have only one of the 
+\verb|arguments| and \verb|options| fields.
+
+\rSec2[strctparam.schema.schema]{JSON Schema Field}
+
+\begin{itemdescr}
+
+	\pnum \fldname \verb|$schema|
+
+	\pnum \fldtype \verb|string|
+
+	\pnum \fldval
+	The value shall be a reference to a JSON Schema specification.
+
+	\pnum \flddesc
+	A \emph{structured parameters} object can contain this field. If a
+	\emph{structured parameters} object does not contain this field the value 
+	shall be a reference to the JSON Schema corresponding to the current 
+	edition of this standard (strctparamjschm).
+
+\end{itemdescr}
+
+\rSec2[strctparam.schema.ver]{Version Field}
+
+\begin{itemdescr}
+
+	\pnum \fldname \verb|version|
+
+	\pnum \fldtype \verb|string|
+
+	\pnum \fldval
+	\verb|1| or \verb|1.0| or \verb|1.0.0|.
+
+	\pnum
+	\flddesc
+	The version field indicates the version of the \emph{structured parameters}
+	represented in the contents of the JSON text. If a \emph{Structured
+	parameters} object does not contain this field the value shall be
+	\verb|1.0.0|.
+
+\end{itemdescr}
+
+\rSec2[strctparam.schema.args]{Arguments Field}
+
+\begin{itemdescr}
+
+	\pnum \fldname \verb|arguments|
+
+	\pnum \fldtype \verb|array|
+
+	\pnum \fldval
+	The value shall be a JSON \verb|array|. The items in the \verb|array| shall
+	be of JSON \verb|string| types.
+
+	\pnum \flddesc
+	The arguments field specifies items to be interpreted directly as if they
+	occur in the command line of the program.
+
+\end{itemdescr}
+
+The application shall process the items as if they replace the
+\grammarterm{std-strctparam-input} argument.
+
+\rSec2[strctparam.schema.opts]{Options Field}
+
+\begin{itemdescr}
+
+	\pnum \fldname \verb|options|
+
+	\pnum \fldtype \verb|object|
+
+	\pnum \fldval
+	The value shall be a JSON \verb|object|.
+
+	\pnum \flddesc
+	A \emph{structured parameters} object can contain this \emph{structured
+	options} field.  The keys of items shall be name 
+	\iref{strctparam.schema.names} values.
+
+\end{itemdescr}
+
+\rSec3[strctparam.schema.names]{Names}
+
+\pnum
+\begin{ncbnf}
+
+\nontermdef{name}\br
+	\descr{one or more of:}\br
+	\ucode{0061} .. \ucode{007A} \uname{LATIN SMALL LETTER A .. Z}\br
+	\ucode{0030} .. \ucode{0039} \uname{DIGIT ZERO .. NINE}\br
+	\ucode{005F} \uname{LOW LINE} \ucode{002D} \uname{HYPHEN-MINUS}
+
+\nontermdef{scope}\br
+	name \opt{scope-designator}
+
+\nontermdef{scope-designator}\br
+	\ucode{002E} \uname{FULL STOP}
+
+\end{ncbnf}
+
+\pnum
+The \grammarterm{name} \verb|std| is reserved for \emph{structured options}
+defined in this standard.
+
+\pnum
+Applications can specify vendor designated \grammarterm{name} parts outside of
+this standard.
+
+\rSec2[strctparam.schema.opt.param]{Structured Option std.param}
+
+\pnum
+The \verb|std.param| structure option defines an option to refer to additional
+structured options \iref{strctparam} to process.
+
+\pnum
+An application shall implement this option.
+
+\pnum
+The \verb|std.param| option shall have the following fields.
+
+\vspace{\baselineskip}
+
+\begin{itemdescr}
+
+	\pnum \fldname \verb|pre|
+
+	\pnum \fldtype \verb|string| or \verb|array|
+
+	\pnum \fldval (for \verb|string|) A pathname to a file containing 
+	structured parameters \iref{strctparam}.
+
+	\pnum \fldval (for \verb|array|) A list of pathname \verb|string| items to 
+	files containing structured parameters \iref{strctparam}.
+
+	\pnum \flddesc
+	One or more references to files that include additional structured 
+	parameters \iref{strctparam}.
+
+\end{itemdescr}
+
+\vspace{\baselineskip}
+
+
+\begin{itemdescr}
+
+	\pnum \fldname \verb|post|
+
+	\pnum \fldtype \verb|string| or \verb|array|
+
+	\pnum \fldval (for \verb|string|) A pathname to a file containing 
+	structured parameters \iref{strctparam}.
+
+	\pnum \fldval (for \verb|array|) A list of pathname \verb|string| items to 
+	files containing structured parameters \iref{strctparam}.
+
+	\pnum \flddesc
+	One or more references to files that include additional structured 
+	parameters \iref{strctparam}.
+
+\end{itemdescr}
+
+A \verb|string| value in the \verb|pre| or \verb|post| field shall be as if the 
+value was given as an \verb|array| with the \verb|string| value as the only 
+value in the \verb|array|.
+
+An application shall process the structured parameters \iref{strctparam} in the 
+\verb|pre| field before processing the structured options where the 
+\verb|std.param| option is specified.
+
+An application shall process the structured parameters \iref{strctparam} in the 
+\verb|post| field after processing the structured options where the 
+\verb|std.param| option is specified.
+
+An application shall process the structured parameters \iref{strctparam} in the 
+\verb|pre| and \verb|post| field in the order given in the value applying 
+semantics as specified in the parameters or options of the structured 
+parameters \iref{strctparam}.