Development

This section documents the internal structure of OptParse and the conventions that matter when extending it.

It is intended for:

• contributors adding a new parser family or value parser
• maintainers changing parser internals while preserving trimming and inference
• curious users who want to understand how the parser tree is executed

For the user-facing API, see:

• Overview
• Examples
• API Docstrings

Guide Structure

• Runtime Model
  • Parser{T,S,p,P}
  • parse vs complete
  • parser state
  • Context, Consumed, and parse results
  • structured errors
• Parser Semantics
  • primitive / constructor / modifier categories
  • parser priority
  • semantics of object, or, sequence, command, and multiple
• Extending OptParse
  • how to add a value parser
  • how to add a parser family
  • public API / docs / test checklist
• Inference And Trimming
  • wrapped unions
  • tight state signatures
  • common inference traps
  • JET / trimming notes

Short Contributor Summary

If you only need the shortest version:

• start from a parser-family-specific state alias
• keep parse and complete signatures tight
• interact with Context through the helper API
• add family-specific errors and a renderer
• add the family to the wrapped union
• keep public names, display output, docs, and tests in sync