---
title: Command-line argument parsing
summary: Splits raw argument tokens into standardized key/value pairs using a configurable regex pattern.
status: draft
owner: <owner>
last_reviewed: 2026-09-15
library: SAIF.Framework.Windows
reference_type: package
operation_id: OP-WIN-004
trigger: Called from the argument container's constructor via its configured CommandLineParser.
---

# Command-line argument parsing

`PatternCommandLineParser.Parse(string[] args)` (used directly, or via its fixed-pattern subclass `SaifStandardCommandLineParser`) converts raw command-line tokens into a standardized `Dictionary<string,string>` that [argument resolution](resolve-arguments.md) then binds onto the argument container.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-WIN-004 |
| **Trigger** | Called from `ArgumentContainerBase<T>`'s constructor via the container's `CommandLineParser`. |
| **Inputs** | Raw command-line `string[] args`; the parser's configured `ParsePattern` regex. |
| **Outputs** | `Dictionary<string,string>` of standardized-key → value pairs. |
| **Primary components** | `PatternCommandLineParser.Parse`, `PatternCommandLineParser.StandardizeArgKey`, `SaifStandardCommandLineParser` |
| **Entry point** | `Console\SAIF.Console\Console\PatternCommandLineParser.cs` |

## Steps

1. For each arg token in `args`, split the token on `ParsePattern` into up to 3 regex parts.
2. If the split yields 2 parts (flag-only, e.g. `-verbose`): if the key isn't already present in the result dictionary, add it with value `"true"` ([BR-WIN-011](../business-rules.md#br-win-011-flag-only-arguments-default-to-true): boolean/flag-style arguments default to string `"true"`).
3. If the split yields 3 parts (`key:value`/`key=value`/`-key value` forms, depending on pattern): if the key isn't already present, add `key → value`.
4. Standardize each key via `StandardizeArgKey` before insertion:
   - `PatternCommandLineParser`'s default upper-cases the key.
   - `SaifStandardCommandLineParser` inherits this default unchanged, but fixes `ParsePattern` to `^-{1,2}|^/|:|=`.
5. Duplicate keys (the same standardized key appearing twice in `args`) are silently ignored — the first occurrence wins ([BR-WIN-012](../business-rules.md#br-win-012-first-occurrence-of-duplicate-argument-keys-wins)); no exception is thrown and no error is recorded for the duplicate.
6. Return the completed dictionary to the calling argument container.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Parse called with args]) --> Loop[For each token]
	Loop --> Split[Split on ParsePattern]
	Split --> Parts{Number of parts}
	Parts -->|2 parts, flag only| KeyExists1{Key already present?}
	Parts -->|3 parts, key/value| KeyExists2{Key already present?}
	KeyExists1 -->|No| AddTrue(["Add key -> #quot;true#quot;"])
	KeyExists1 -->|Yes| Skip1([Ignore duplicate])
	KeyExists2 -->|No| AddValue([Add key -> value])
	KeyExists2 -->|Yes| Skip2([Ignore duplicate])
	AddTrue --> Standardize[StandardizeArgKey]
	AddValue --> Standardize
	Standardize --> Loop
	Loop --> Done([Return dictionary])
```

## Failure and edge-case behavior
- Tokens that split into a number of parts other than 2 or 3 are not documented as producing a dictionary entry; behavior for such tokens depends on the configured `ParsePattern`.**
- Because standardization defaults to upper-casing, argument keys are effectively case-insensitive at the point of lookup in [argument resolution](resolve-arguments.md).

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

> **Note:** Statements marked with `**` could not be confirmed; treat as unknown until verified.

## Sources
- `Console\SAIF.Console\Console\PatternCommandLineParser.cs`
- `Console\SAIF.Console\Console\SaifStandardCommandLineParser.cs`
- `Console\SAIF.Console\Console\ICommandLineParser.cs`