mirror of
https://github.com/metabarcoding/obitools4.git
synced 2026-04-30 12:00:39 +00:00
38 lines
1.5 KiB
Markdown
38 lines
1.5 KiB
Markdown
|
# `obiutils` Package: File and Stream Writing Utilities
|
||
|
|
|
||
|
|
The `obiutils` package provides a unified abstraction for writing data to files or streams, with optional gzip compression and buffered I/O.
|
||
|
|
|
||
|
|
## Core Type: `Wfile`
|
||
|
|
|
||
|
|
- Encapsulates a write-ready output stream (`io.WriteCloser`).
|
||
|
|
- Supports both **compressed** (gzip) and uncompressed modes.
|
||
|
|
- Uses `bufio.Writer` for efficient buffered writes.
|
||
|
|
|
||
|
|
## Key Functions
|
||
|
|
|
||
|
|
### `OpenWritingFile(name string, compressed bool, append bool) (*Wfile, error)`
|
||
|
|
- Opens a file for writing.
|
||
|
|
- `compressed`: enables gzip compression via `pgzip`.
|
||
|
|
- `append`: if true, writes at end of file (`os.O_APPEND`).
|
||
|
|
- Returns a ready-to-use `*Wfile`.
|
||
|
|
|
||
|
|
### `CompressStream(out io.WriteCloser, compressed bool, close bool) (*Wfile, error)`
|
||
|
|
- Wraps an arbitrary `io.WriteCloser` (e.g., HTTP response, pipe) in buffered/compressed I/O.
|
||
|
|
- `close`: if true, the underlying writer is closed on `.Close()`.
|
||
|
|
|
||
|
|
## Methods
|
||
|
|
|
||
|
|
- **`Write(p []byte)` / `WriteString(s string)`**:
|
||
|
|
Buffered writes to the underlying stream (transparently compressed if enabled).
|
||
|
|
|
||
|
|
- **`Close()`**:
|
||
|
|
- Flushes the buffer.
|
||
|
|
- Closes gzip writer (if compressed).
|
||
|
|
- Closes underlying file/stream *only if* `close == true`.
|
||
|
|
|
||
|
|
## Design Highlights
|
||
|
|
|
||
|
|
- **Transparent compression**: Uses high-performance `pgzip` for parallel gzip.
|
||
|
|
- **Resource control**: Explicit flag (`close`) prevents premature closure of shared writers (e.g., in pipelines).
|
||
|
|
- **Efficiency**: Double buffering via `bufio.Writer` + gzip stream.
|