Parse command-line arguments with a flag and option spec

Provide the tokens and a compact specification that names each boolean flag or value-taking option. The parser resolves aliases to canonical names, preserves positional arguments, identifies unknown flags, supports long options with an equals sign, and stops option parsing after the conventional double-dash marker. Malformed specifications, duplicate arguments, and options without required values produce clear input errors.

Describe the command-line interface as data

Start with the argument tokens exactly as a runtime supplies them after removing the executable and script names. Then define each accepted argument in the spec. Every entry has a canonical name, one or more aliases, and a kind. Use flag for a switch whose presence means true, such as <code>--verbose</code>. Use option when the spelling must be followed by a value, such as <code>--output result.json</code>. Aliases let short and long spellings populate the same canonical property, so <code>-o</code> and <code>--output</code> can both produce <code>output</code>. Canonical names use lowercase letters, digits, and underscores, making the returned object safe to consume without another renaming pass. Alias spellings must begin with one or two hyphens. The parser rejects duplicate canonical names and duplicate aliases because either collision would make the result depend on declaration order. Set <code>multiple</code> only when repeating an argument is intentionally part of the interface; repeated values are then returned in encounter order.

Understand token parsing and output

The result separates three concerns: recognized values, positional tokens, and unknown flags. Recognized flags become true under their canonical names, while options store their following token. A long option can also carry its value in the same token, as in <code>--format=json</code>. An exact token match is required; short-flag bundles such as <code>-abc</code> are not expanded unless that entire spelling appears as an alias. Any unrecognized token beginning with a hyphen is appended to <code>unknown_flags</code>, allowing callers to reject it, display a warning, or forward it deliberately. Other unrecognized tokens are positional values. A standalone <code>--</code> ends option processing, and every later token is positional even if it begins with a hyphen. This conventional escape makes filenames such as <code>-draft.txt</code> unambiguous. The parser does not invent defaults or coerce strings into numbers, because those policies belong to the application and can otherwise hide user mistakes. Its output is deterministic and preserves the order of positional and unknown items.

Handle missing values and repeated arguments safely

Every entry whose kind is option requires a non-empty value whenever its alias appears. If the alias is the final token, is followed by the end-of-options marker, or is followed by another flag-shaped token, parsing fails with an invalid-input error that names the offending alias. The same rule applies to an empty attached form such as <code>--output=</code>. This strict behavior prevents a later switch from being silently consumed as data and addresses the most damaging command-line parsing failure directly. A lone hyphen may still be used as an option value, which is useful for programs that treat standard input or standard output as <code>-</code>. By default, presenting the same recognized argument twice is also an error. Declare <code>multiple: true</code> when repetition is valid, such as multiple include paths or labels; the output will then always contain an array for that canonical name. Unknown flags are merely reported rather than causing failure, so the caller retains control over compatibility and forwarding policy.