Description
Format explicit option records and positional tokens into a literal argv vector using attached values and an end marker; not a shell command string.
An argv vector already consists of literal argument strings. Shell quoting and tokenization happen before this representation; joining argv elements with spaces does not reconstruct a safe command string. Option aliases, duplicates, arity and dependencies are application policies that these tools take explicitly.
Format explicit option records and positional tokens into a literal argv vector using attached values and an end marker; not a shell command string.
When to use this tool
Use this tool to format explicit option records and positional tokens into a literal argv vector using attached values and an end marker; not a shell command string.
How to use the tool and how it works
- Enter optionsJson, positionals using the input definitions below. Serialize the JSON text fields in the decoded shape shown below.
- Run the operation. Resolve malformed-input errors before interpreting the result.
- Read result.arguments. Interpret signs, units, ordering and null values using the rules below.
Validate restricted ASCII long-option names and null-or-string values. Format each as --name or --name=value, then append -- and supplied positionals only when any positionals exist.1
| Input field | Meaning and units | Accepted input |
|---|---|---|
| optionsJson | JSON array of {name,value} option records. name uses the restricted ASCII long-name grammar; value is null for a bare option or a string including an empty assignment. | Text, at most 8,192 UTF-16 code units; the stated grammar and narrower limits also apply. |
| positionals | Already-identified literal positional argument strings. | Dense list of at most 128 strings, each at most 8,192 UTF-16 code units. |
These decoded examples show the structure of the JSON text fields. Supply each as its corresponding serialized JSON string.
{
"optionsJson": [
{
"name": "x",
"value": "a b"
},
{
"name": "quiet",
"value": null
}
]
}| Output field | Interpretation |
|---|---|
| result | Object containing the fields below. |
| result.arguments | Formatted literal argv vector or token-local source-map records, as stated above. |
{
"input": {
"optionsJson": "[{\"name\":\"x\",\"value\":\"a b\"},{\"name\":\"quiet\",\"value\":null}]",
"positionals": [
"-file"
]
},
"output": {
"result": {
"arguments": [
"--x=a b",
"--quiet",
"--",
"-file"
]
}
}
}Limitations and assumptions
- The result is an argv vector with literal elements. It must not be joined into a shell command without separate platform-appropriate quoting.
- Inputs are literal tokens or explicit records. The restricted long-name grammar is [A-Za-z0-9][A-Za-z0-9-]* where required. No universal option syntax, shell semantics or process execution is inferred.
- Every declared top-level input is required and unknown fields are rejected. Ordinary strings are limited to 8,192 UTF-16 code units and lists to 128 entries, with tighter operation-specific bounds where stated. JSON text has bounded nesting and node counts.
- Numeric outputs must be finite and within the absolute safe-integer magnitude; exact larger integers use decimal text. Source positions are zero-based UTF-16 offsets and span ends are exclusive unless a different convention is explicitly stated.
Alternative or Complementary methods
Use the application’s option schema to choose arity, aliases and conflict policy. Pass a literal argv vector to the intended process interface; shell command construction requires separate quoting rules.
References
Similar or alternative tools
- Long Option Assignment Joiner
Format one literal long-option argv token under a restricted ASCII option-name grammar; returns one argument, not shell quoting.
- Long Option Assignment Splitter
Split one strict ASCII --long-name[=value] argv token at the first equals; no shell parsing or implicit next-token consumption.