LIME (Lattice QCD Interchange Message Encapsulation) format implementation
This module provides reading and writing capabilities for LIME files, which are used by the SciDAC community for lattice QCD data interchange.
LIME format specification:
- Magic number: 0x456789AB (big-endian)
- Header: 144 bytes (18 x 64-bit words)
- Data payload with 8-byte alignment padding
Reference: https://usqcd-software.github.io/c-lime/
Types
LimeReader = ref object
LimeRecordHeader = object mbFlag*: bool ## Message Begin flag meFlag*: bool ## Message End flag limeType*: string ## LIME type identifier (max 128 chars) dataLength*: int64 ## Length of data payload in bytes
LimeStatus = enum lsSuccess = 0, lsErrParam, lsErrHeaderNext, lsErrWrite, lsEndOfRecord, lsEndOfFile, lsErrRead, lsErrSeek, lsErrMbMe, lsErrClose, lsErrMagic, lsErrVersion
LimeWriter = ref object
Consts
LimeHeaderSize = 144
LimeMagicNumber: uint32 = 0x456789AB'u32
LimeTypeMaxLen = 128
LimeVersion: uint16 = 1
Procs
proc bytesRemaining(reader: LimeReader): int64 {....raises: [], tags: [], forbids: [].}
- Get remaining unread bytes in current record
proc close(reader: LimeReader) {....raises: [IOError, OSError], tags: [WriteIOEffect], forbids: [].}
- Close the LIME reader
proc close(writer: LimeWriter): LimeStatus {....raises: [IOError, OSError], tags: [WriteIOEffect], forbids: [].}
- Close the LIME writer, finalizing the file
proc createHeader(mbFlag, meFlag: bool; limeType: string; dataLen: int64): LimeRecordHeader {. ...raises: [], tags: [], forbids: [].}
- Create a LIME record header
proc dataBytes(reader: LimeReader): int64 {....raises: [], tags: [], forbids: [].}
- Get the total data bytes in current record
proc dumpContents(filename: string) {....raises: [IOError, OSError], tags: [WriteIOEffect, ReadIOEffect], forbids: [].}
- Print contents of a LIME file (similar to lime_contents utility)
proc getPosition(reader: LimeReader): int64 {....raises: [IOError, OSError], tags: [], forbids: [].}
proc header(reader: LimeReader): LimeRecordHeader {....raises: [], tags: [], forbids: [].}
- Get the current record header
proc limeType(reader: LimeReader): string {....raises: [], tags: [], forbids: [].}
- Get the LIME type string of current record
proc mbFlag(reader: LimeReader): bool {....raises: [], tags: [], forbids: [].}
- Check if current record is message begin
proc meFlag(reader: LimeReader): bool {....raises: [], tags: [], forbids: [].}
- Check if current record is message end
proc newLimeReader(filename: string): LimeReader {....raises: [IOError], tags: [], forbids: [].}
- Create a new LIME reader from a file
proc newLimeReader(stream: Stream): LimeReader {....raises: [], tags: [], forbids: [].}
- Create a new LIME reader from an existing stream
proc newLimeWriter(filename: string): LimeWriter {....raises: [IOError], tags: [], forbids: [].}
- Create a new LIME writer to a file
proc newLimeWriter(stream: Stream): LimeWriter {....raises: [], tags: [], forbids: [].}
- Create a new LIME writer from an existing stream
proc nextRecord(reader: LimeReader): LimeStatus {....raises: [IOError, OSError], tags: [ReadIOEffect], forbids: [].}
- Advance to the next LIME record and read its header Returns lsSuccess on success, lsEndOfFile at end of file
proc readAllData(reader: LimeReader): seq[byte] {....raises: [IOError, OSError], tags: [ReadIOEffect], forbids: [].}
- Read all remaining data from current record
proc readData(reader: LimeReader; dest: pointer; nbytes: int): (int, LimeStatus) {. ...raises: [IOError, OSError], tags: [ReadIOEffect], forbids: [].}
- Read data from the current record Returns (bytes_read, status)
proc readString(reader: LimeReader): string {....raises: [IOError, OSError], tags: [ReadIOEffect], forbids: [].}
- Read record data as a string (for ASCII/XML records)
proc seek(reader: LimeReader; offset: int64; whence: int = 0): LimeStatus {. ...raises: [IOError, OSError], tags: [], forbids: [].}
- Seek within the current record payload whence: 0 = SEEK_SET (from start), 1 = SEEK_CUR (from current)
proc setPosition(reader: LimeReader; offset: int64): LimeStatus {....raises: [], tags: [], forbids: [].}
- Set absolute file position (must point to start of a record)
proc writeBytes(writer: LimeWriter; data: openArray[byte]): LimeStatus {. ...raises: [IOError, OSError], tags: [WriteIOEffect], forbids: [].}
- Write bytes as record data
proc writeData(writer: LimeWriter; source: pointer; nbytes: int): (int, LimeStatus) {....raises: [IOError, OSError], tags: [WriteIOEffect], forbids: [].}
- Write data to the current record
proc writeHeader(writer: LimeWriter; header: LimeRecordHeader): LimeStatus {. ...raises: [IOError, OSError], tags: [WriteIOEffect], forbids: [].}
- Write a LIME record header
proc writeRecord(writer: LimeWriter; limeType: string; data: openArray[byte]; mbFlag = true; meFlag = true): LimeStatus {. ...raises: [IOError, OSError], tags: [WriteIOEffect], forbids: [].}
- Write a complete record with binary data
proc writeRecord(writer: LimeWriter; limeType: string; data: string; mbFlag = true; meFlag = true): LimeStatus {. ...raises: [IOError, OSError], tags: [WriteIOEffect], forbids: [].}
- Write a complete record with string data
proc writeString(writer: LimeWriter; s: string): LimeStatus {. ...raises: [IOError, OSError], tags: [WriteIOEffect], forbids: [].}
- Write a string as record data
Iterators
iterator records(reader: LimeReader): LimeRecordHeader {. ...raises: [IOError, OSError], tags: [ReadIOEffect], forbids: [].}
- Iterate over all records in a LIME file