Description
Overlay two explicit environment occurrence lists with last-wins shadow provenance; case-sensitive portable names, no process environment mutation.
Environment assignments pair names with literal string values. Repeated names need an explicit first/last policy, and missing values differ from present empty strings. A dotenv file and a shell program can use different quoting and expansion rules; these tools implement their stated literal subsets using supplied data.
Overlay two explicit environment occurrence lists with last-wins shadow provenance; case-sensitive portable names, no process environment mutation.
When to use this tool
Use this tool to overlay two explicit environment occurrence lists with last-wins shadow provenance; case-sensitive portable names, no process environment mutation.
How to use the tool and how it works
- Enter baseJson, overlayJson 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.assignments. Interpret signs, units, ordering and null values using the rules below.
Concatenate base then overlay occurrences, group exact names in first-appearance order, and retain each group’s final occurrence. Return its side, side-local sourceIndex and all shadowed indexes in the combined list.1
| Input field | Meaning and units | Accepted input |
|---|---|---|
| baseJson | JSON array of base {name,value} assignments; names are portable ASCII and values are NUL-free strings. | Text, at most 8,192 UTF-16 code units; the stated grammar and narrower limits also apply. |
| overlayJson | JSON array of overlay {name,value} assignments, processed after base. | Text, at most 8,192 UTF-16 code units; the stated grammar and narrower limits also apply. |
These decoded examples show the structure of the JSON text fields. Supply each as its corresponding serialized JSON string.
{
"baseJson": [
{
"name": "A",
"value": "1"
}
],
"overlayJson": [
{
"name": "A",
"value": "2"
}
]
}| Output field | Interpretation |
|---|---|
| result | Object containing the fields below. |
| result.assignments | Selected assignment records with source indexes or overlay/shadow provenance as stated above. |
{
"input": {
"baseJson": "[{\"name\":\"A\",\"value\":\"1\"}]",
"overlayJson": "[{\"name\":\"A\",\"value\":\"2\"}]"
},
"output": {
"result": {
"assignments": [
{
"name": "A",
"value": "2",
"side": "overlay",
"sourceIndex": 0,
"shadowed": [
0
]
}
]
}
}
}Limitations and assumptions
- The policy is case-sensitive last-wins, including duplicate names within either side; nothing is applied to the process environment.
- Portable assignment records require names matching [A-Za-z_][A-Za-z0-9_]* and NUL-free values. Name matching is case-sensitive. Reference scanners and quoted-value helpers follow only their own stated grammar and do not read the process environment.
- 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
Select the consuming application’s dotenv dialect explicitly. Keep literal substitution separate from recursive expansion and shell execution, and retain occurrence provenance when resolving duplicate assignments.
References
Similar or alternative tools
- Environment Empty Value Audit
Distinguish empty from nonempty whitespace-only portable environment values, retaining source occurrences; does not conflate missing variables with present empty values.
- Environment Assignment First Wins
Resolve explicit case-sensitive portable environment assignment occurrences under first-wins policy with source indexes; no shell execution or expansion.