obitools4/autodoc/docmd/pkg_obioptions.md

OBIOptions Package: Semantic Documentation

The obioptions package centralizes command-line interface (CLI) infrastructure for OBITools4, enabling consistent parsing of shared arguments and runtime configuration across tools. It standardizes logging, profiling controls, taxonomy integration, version reporting, and batch processing options—ensuring modularity, maintainability, and reproducibility.

Core CLI Infrastructure

Global Option Registration & Processing

• RegisterGlobalOptions(parser) injects shared flags into any argument parser, including:
  • Version (--version) and debug mode (--debug)
  • Resource control: --max-cpu, thread limits, memory/batch tuning (--batch-size, -size-max, --batch-mem)
  • Quality encoding toggle: --solexa
  • Warning suppression (--silent-warning)
• ProcessParsedOptions(parser) handles post-parsing logic:
  • Exits early on help/version requests
  • Loads taxonomy database via obiformats.LoadTaxonomy()
  • Sets log level (logrus.SetLevel)
  • Enables performance profiling via pprof:
    • Generic heap/goroutine dumps (/debug/pprof)
    • Mutex contention profiling (via --pprof-mutex + runtime.SetMutexProfileFraction())
    • Goroutine blocking profiling (via --pprof-goroutine + runtime.SetBlockProfileRate())

Parser Generation

• GenerateOptionParser(program, documentation) returns:
  • A reusable parser with bundled short options (-abc) and strict unknown-option rejection
  • Built-in --help support (via go-getoptions)
• Designed for reuse across commands with minimal boilerplate.

Taxonomy Handling

Option Set Registration

• LoadTaxonomyOptionSet(parser) adds taxonomy-specific flags:
  • Required/optional DB path: --taxonomy, -t
  • Alternative names lookup (--alternative-names)
  • Validation strictness: --fail-on-taxonomy
  • Auto-update taxonomic IDs (--update-taxid)
  • Raw output mode: --raw-taxid
  • Inclusion of leaf sequences (--with-leaves)
• Taxonomy loading is thread-safe (mutex-guarded) and lazy-loaded.

Runtime Accessors

• CLIIsDebugMode() → returns current debug state
• SeqAsTaxa() → indicates if sequence IDs should be treated as taxa (e.g., for --raw-taxid)
• SetDebugOn(), SetDebugOff() → programmatic toggling of debug mode

Subcommand-Aware Parsing

GenerateSubcommandParser(program, documentation, setup)

• Builds a hierarchical CLI:
  • Registers global options inherited by all subcommands
  • Invokes setup(parser) to define per-subcommand flags and commands
• Automatically adds a built-in help subcommand for command-level documentation
• Returns:
  • Root parser (*GetOpt) and an ArgumentParser function with signature:

    func([]string) (*GetOpt, []string)
    

  • Parses CLI args (skipping binary name), handles errors via ProcessParsedOptions, and returns parsed state + positional arguments

Versioning & Diagnostics

VersionString()

• Returns the current OBITools version as "Release X.Y.Z" (e.g., Release 4.4.29)
• Version is auto-populated from a build-time-generated version.txt (via Makefile)
  • Patch level increments per commit → precise tracking of development iterations
• Pure function: no side effects, safe for logging/diagnostics/compatibility checks
• Supports CI validation and runtime introspection (e.g., error reports, feature gates)

Design Principles

• Environment Variables: Configurable via OBIMAXCPU, OBIWARNING, etc.
• Error Handling: Parse errors → print help + exit gracefully
• Standard Tooling Integration:
  • logrus for structured logging
  • Go’s native pprof (HTTP servers, mutex/block profiles)
• Zero External Dependencies for versioning module