obitools4/autodoc/docmd/pkg_obitools_obiscript.md

obiscript Package: CLI Scriptable Processing Pipeline

The obiscript package provides a high-level, modular interface for embedding custom Lua scripts into OBITools4’s sequence processing pipelines. It enables users to define bioinformatics workflows using a lightweight, embeddable scripting language—without sacrificing performance or composability.

Public API Overview

CLIScriptPipeline() Pipeable

Returns a reusable, parallelized pipeline stage that executes user-provided Lua scripts on sequence data. Internally uses obilua.LuaScriptPipe() with parallelism enabled (default worker count from obidefault.ParallelWorkers). Accepts a script path via the pipeline configuration (typically set through CLIScriptFilename() in CLI usage). Designed to integrate seamlessly with other pipeable stages from the obiiter framework.

Script Lifecycle Hooks (Exposed via Lua API)

The embedded ObiLua runtime expects the user script to define three optional functions:

• begin()
  Called once before processing any sequences. Used for initialization (e.g., counters, file handles). Optional.

• worker(sequence)
  Invoked for each input sequence. Provides full access to metadata via sequence:attribute(name, value?), supports in-place modification of tags/IDs, and allows interaction with global context (obicontext) for cross-sequence state management.

• finish()
  Called after all sequences have been processed. Typically used to output summary statistics or cleanup resources.

CLI Integration

• --script FILE, -S FILE
  Specifies the Lua script to execute. The file must exist and be syntactically valid.

• --template
  Outputs a minimal, self-contained Lua script template to stdout. Includes stubs for begin(), worker(...), and finish() with inline documentation.

• Shared Options
  Reuses configuration sets from core OBITools4 modules:

  • obiconvert.DataIOOptionSet: input/output format, file paths.
  • obigrep.SequenceSelectionOptionSet: filtering/sorting logic.

Semantic Role

obiscript abstracts the complexity of embedding and orchestrating Lua scripts in a streaming, parallelizable context. It decouples workflow logic (Lua) from pipeline orchestration (Go), enabling:

• Rapid prototyping of NGS processing steps.
• Custom annotation, filtering, assembly, or reporting without recompilation.
• Consistent CLI behavior across OBITools4 tools.

Use Cases

Scenario	Example
Read filtering + renaming	Filter low-quality reads and prepend sample ID to sequence names
Annotation injection	Add UMI or barcode info from external metadata file per read
Summary reporting	Count reads passing filters, write stats to log at end

Designed for extensibility: users extend functionality by writing Lua, not Go.