Skip to content

V7: Move structure check off the constructor, distinguish ArguException vs ArguParseException #326

Description

@dimension-zero

Spinning out of #306. Captures @bartelink's counter-proposal verbatim — the intent of #306 was a TryCreate returning Result<_, exn>, but the deeper observation is that the constructor / Create running structure validation eagerly is the wrong shape, and a TryCreate wrapper becomes obsolete-on-arrival once that is fixed.

Proposal

  1. Create never throws. No structure check at construction time.
  2. Lazy, cached structure check on first Parse. Any parse entry point runs the check once (memoised on the parser instance) before doing input parsing. Programmer errors (structure) and user errors (input) end up on the same code path the user is already prepared to handle.
  3. Opt-out escape hatch. Create(skipCheckStructure=true) for guaranteed non-throwing construction. XML doc spells out the contract: caller must have run ArgumentParser<T>.CheckStructure() in a test for that schema, otherwise behaviour is undefined.
  4. Exception taxonomy stays:
    • ArguException for structure failures (programmer error, raised by the lazy check unless skipCheckStructure=true).
    • ArguParseException for input failures (user error, raised by parsing).
    • Tutorial + samples updated to make the distinction explicit, including the recommended host pattern (try/with only around Parse*, not around Create).

Why now

Out of scope (follow-up)

Refs #306, #325.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions