obitools4/autodoc/docmd/pkg/obitax/iterator.md

Semantic Description of obitax Package Functionalities

The obitax package provides a robust iterator-based API for traversing taxonomic data structures in Go. Its core component is the ITaxon interface, which implements a lazy, concurrent-safe iterator over taxon instances (*Taxon). Key features include:

• Iterator Creation: ITaxon can be instantiated via NewITaxon() or derived from collections:

  • TaxonSet.Iterator(), TaxonSlice.Iterator() (sorted), and Taxonomy.nodes.Iterator()
  • Goroutines feed taxa into a channel, enabling non-blocking iteration.

• Control Methods:

  • Next() advances to the next taxon, returning success/failure.
  • Get() retrieves the current taxon (must follow a successful Next).
  • Finished() checks if iteration is complete.

• Channel Management:

  • Push(taxon) sends a taxon into the iterator’s channel.
  • Close() terminates iteration by closing the source channel.

• Iterator Composition:

  • Split(): creates a new iterator sharing the same source and termination status (useful for parallel consumption).
  • Concat(...): merges multiple iterators sequentially into one.

• Metadata Enrichment:

  • AddMetadata(name, value) wraps the iterator to inject metadata into each taxon via SetMetadata.

• Subtree Traversal:

  • ISubTaxonomy() (on *Taxon or via Taxonomy.ITaxon(taxid)) performs a breadth-first traversal of descendant taxa, starting from the current taxon or given ID. It uses parent-child adjacency logic to expand the subtree incrementally.

• Consumption Utility:

  • Consume() exhausts an iterator without processing (e.g., for side-effect-only pipelines).

All iterators are designed to be composable, memory-efficient (via channels), and safe for concurrent use. The package integrates with obiutils to manage pipeline registration/unregistration during subtree expansion.