mirror of
https://github.com/metabarcoding/obitools4.git
synced 2026-04-30 12:00:39 +00:00
Eric Coissac
8c7017a99d
- Update obioptions.Version from "Release 4.4.29" to "/v/ Release v5" - Update version.txt from 4.29 → .30 (automated by Makefile)
34 lines
1.9 KiB
Markdown
34 lines
1.9 KiB
Markdown
# Obilua: Lua-Based Sequence Processing Framework
|
||
|
||
The `obilua` package provides a bridge between Go and the Lua scripting language for high-performance, parallelizable biological sequence processing. It enables users to write custom analysis logic in Lua while leveraging Go’s concurrency and I/O capabilities.
|
||
|
||
## Core Features
|
||
|
||
- **Lua Interpreter Initialization**: `NewInterpreter()` creates an isolated Lua state preloaded with Obi-specific types (`BioSequence`, etc.).
|
||
- **Compilation Support**: `Compile()` and `CompileScript()` parse and compile Lua code into efficient function prototypes.
|
||
- **Worker Conversion**: `LuaWorker(proto)` wraps a compiled Lua script as a Go-compatible `SeqWorker`, allowing seamless integration into sequence pipelines.
|
||
- **Pipeline Integration**:
|
||
- `LuaProcessor()` executes a Lua script over an iterator of sequences using configurable parallelism.
|
||
- It supports optional `begin()` and `finish()` hook functions in Lua for initialization/cleanup.
|
||
- Errors can be handled either by halting (`breakOnError=true`) or logging warnings.
|
||
|
||
- **Pipeable Interface**:
|
||
- `LuaPipe()` and `LuaScriptPipe()` expose Lua scripts as reusable, chainable pipeline stages (`obiiter.Pipeable`), supporting both inline programs and external `.lua` files.
|
||
|
||
## Lua API Contract
|
||
|
||
Scripts must define a global `worker(sequence)` function returning either:
|
||
- A single `BioSequence`
|
||
- A list (`BioSequenceSlice`)
|
||
Or return nothing (interpreted as filtered out).
|
||
|
||
Optionally, `begin()` and `finish()` functions may be defined for lifecycle management.
|
||
|
||
## Parallel Execution
|
||
|
||
Uses Go routines to run multiple workers concurrently, with batched input and output management. Default worker count falls back to system-wide parallelism settings if `nworkers ≤ 0`.
|
||
|
||
## Logging & Error Handling
|
||
|
||
Uses Logrus for structured logging; fatal errors are logged during setup, while runtime issues respect the `breakOnError` flag.
|