Options Domain API Guidelines

Core Semantics

option = named flag, typed value, choice, or positional argument
option set = group of option definitions
module = named action-specific collection of option sets

Primary Types

Options // root definition for main option sets and modules
OptionManager // command-line parser and display orchestrator
OptionSet // reusable group of option definitions and parsing callbacks
OptionModule // command module with option sets and optional main function
Option // one named command-line definition

Definition Types

OptionEditor, OptionChoiceEditor // fluent option and choice definition editors
OptionSetManager // shared definition-owning interface of roots, sets, and modules
OptionChoice, OptionChoices // one accepted choice and its collection
OptionHelp // title, description, example, epilog, and visibility
OptionType, OptionFlag, OptionFlags // declared value kind and definition flags
OptionHelpVisibility // inherited or explicit help visibility
OptionParserFlag, OptionParserFlags // built-in parser behavior flags

Result Types

OptionResult // parse status, selected module, values, and error context
OptionValues // parsed lookup map
OptionValue // one parsed value with source definition and argument indexes
OptionValueStorage, OptionValueType // parsed storage and classification
OptionInteger // signed integer representation used by option values
OptionSensitiveTextLocation, OptionSensitiveTextLocations // protected source suffixes to mask
OptionResultStatus // success, display request, or error result

Callback and Error Types

OptionValidateFn // validation callback for one parsed value
PreOptionSetParsingFn, PreOptionModuleParsingFn // callbacks before definition parsing
PostParsingFn, ModuleMainFn // callbacks after parsing or for selected-module execution
OptionError // throwing parse or definition failure
OptionErrorContext, OptionErrorReason // structured failure context and reason

Pattern Definitions

Dp = OptionsPtr/OptionSetPtr/OptionModulePtr/OptionPtr // shared definition pointer
Vp = OptionValuesPtr/OptionValuePtr // shared parsed-value pointer

Definition Construction Patterns

T::create([primary, details]) -> Dp // create a shared root, set, module, or option definition
o.addOption(names) -> OptionEditor // add an option and return its fluent editor
o.editOption(name) -> OptionEditor // edit an existing option by lookup name
o.addSet(set)/addModule(module) // add an owned option set or module
o.optionSets()/optionModules()/options() -> T // inspect owned definitions
o.defaultOptionSet() -> OptionSetPtr // access the lazily created direct-addition set

Definition Name Patterns

T(names) // create an option or module and derive its identity
o.names() -> T // inspect accepted names
o.setNames(names)/addName(name) // replace or add accepted names
T::is❮NameForm❯(name) -> bool // classify long, short, option, or positional names
T::isValid❮NameForm❯(name) -> bool // validate a supported name form
o.has❮NameForm❯(name) -> bool // test a configured name or positional identity
o.hasConflictingOptionName(other) -> bool // test definition-name conflicts

Definition Property Patterns

o.❮property❯()/set❮Property❯(value) // get or set a definition property
o.set❮Property❯(value) -> OptionEditor& // fluently update an option definition
o.setFlag/clearFlag(flag) -> OptionEditor& // add or remove one definition flag
o.addChoice(text) -> OptionEditor& // add an accepted choice and select choice type
o.addChoice(text/choice) -> OptionChoiceEditor // append to OptionChoices and edit the accepted choice
o.setHelp❮Part❯(text) -> OptionChoiceEditor& // fluently update choice help metadata
o.clearDefaultValue() -> OptionEditor& // remove a configured default
o.isDisabled()/hasDefaultValue() -> bool // test common definition states
o.matchingChoiceText(text) -> text::String // resolve a case-insensitive accepted choice

Parsing Patterns

T([options]) // create a manager with a new or existing root definition
o.parse(arguments) -> OptionResult // parse, mask protected text, and return an explicit status
o.parseOrThrow(arguments) -> OptionValuesPtr // parse and mask or throw OptionError
T::convertCommandLineArguments(argc, argv) -> core::CommandLineArguments // convert the native process boundary
o.options() -> OptionsPtr // access the root definition
o.displayText()/setDisplayTextMap(map) // inspect or replace display wording

Display Patterns

o.helpDocument/versionDocument(module) -> text::TextDocument // build a neutral display document
o.detailedHelpDocument(module, name)/moduleOverviewDocument() -> text::TextDocument // build focused help
o.errorDocument(context) -> text::TextDocument // build a neutral error document
o.displayHelp/displayDetailedHelp/displayVersion(module) // render a built-in display request
o.displayModuleOverview() // render the reduced module-selection document
o.displayError(context) // render a structured option error
o.executablePath()/setExecutablePath(path) // retain argv zero and derive the usage name

Result Patterns

o.status()/values()/helpName()/errorContext() -> T // inspect the explicit parse outcome
o.moduleName()/module() -> T // inspect the selected module identity and definition
o.sensitiveTextLocations() -> OptionSensitiveTextLocations // inspect every suffix masked after parsing
o.value(name) -> OptionValuePtr // find a parsed value through any accepted name
o.valueCount(name) -> unit::ArgumentCount // count parsed values for a lookup name
o.argumentIndexes()/argumentIndex() -> T // inspect source command-line positions

Typed Value Access Patterns

o.getFlag([name, fallback]) -> bool // read a flag or fallback
o.getFlagCount(name[, fallback]) -> unit::ArgumentCount // read flag occurrence count
o.getBoolean/getInteger/getText([name, fallback]) -> T // read one typed value; sensitive text remains marked
o.getBooleanList/getIntegerList/getTextList([name, fallback]) -> T // read all typed values