rio

package
Version: v0.32.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 16, 2022 License: BSD-3-Clause Imports: 11 Imported by: 0

README

rio

GoDoc

rio is a Record-oriented I/O library, modeled after SIO (Serial I/O).

Installation

$ go get go-hep.org/x/hep/rio

Documentation

The documentation is browsable at godoc.org: https://godoc.org/go-hep.org/x/hep/rio

Example

package main

import (
	"fmt"
	"io"

	"go-hep.org/x/hep/rio"
)

type LCRunHeader struct {
	RunNbr   int32
	Detector string
	Descr    string
	SubDets  []string
}

func main() {
	fname := "c_sim.slcio"
	fmt.Printf(">>> opening [%s]\n", fname)

	f, err := rio.Open(fname)
	if err != nil {
		panic(err)
	}
	defer f.Close()

	var runhdr LCRunHeader
	runhdr.RunNbr = 42
	rec := f.Record("LCRunHeader")
	rec.SetUnpack(true)
	rec.Connect("RunHeader", &runhdr)

	fmt.Printf("::: [%s]\n", f.Name())
	fmt.Printf("::: [%s]\n", f.FileName())
	for {
		fmt.Printf("-----------------------------------------------\n")
		var rec *rio.Record

		rec, err = f.ReadRecord()
		fmt.Printf("***\n")
		if err != nil {
			if err == io.EOF {
				break
			}
			panic(err)
		}
		if rec == nil {
			fmt.Printf("** no record!\n")
			break
		}

		fmt.Printf(">> record: %s\n", rec.Name())
		if rec.Name() == "LCRunHeader" {
			fmt.Printf("runnbr: %d\n", runhdr.RunNbr)
			fmt.Printf("det:    %q\n", runhdr.Detector)
			dets := "["
			for i, det := range runhdr.SubDets {
				dets += fmt.Sprintf("%q", det)
				if i+1 != len(runhdr.SubDets) {
					dets += ", "
				}
			}
			dets += "]"
			fmt.Printf("dets:   %s\n", dets)
		}
	}
}

TODO

  • implement read/write pointers
  • implement buffered i/o
  • handle big files (ie: file offsets as int64)

Bibliography

Documentation

Overview

Package rio is a record-oriented persistency mechanism.

Index

Constants

View Source
const (

	// Name of the metadata record holding Metadata informations about the rio stream
	MetaRecord = ".rio.meta"
)

Variables

View Source
var (

	// Endian exposes the endianness of rio streams
	Endian = binary.LittleEndian
)

Functions

func RegisterCompressor

func RegisterCompressor(kind CompressorKind, x Xpressor)

RegisterCompressor registers a compressor/decompressor. It silently replaces the compressor/decompressor if one was already registered.

Types

type Block

type Block struct {
	// contains filtered or unexported fields
}

Block manages and desribes a block of data

func (*Block) Name

func (blk *Block) Name() string

Name returns the name of this block

func (*Block) Read

func (blk *Block) Read(data interface{}) error

Read reads data from the Reader, in the rio format

func (*Block) RioVersion

func (blk *Block) RioVersion() Version

RioVersion returns the rio-binary version of the block

func (*Block) Write

func (blk *Block) Write(data interface{}) error

Write writes data to the Writer, in the rio format

type BlockDesc

type BlockDesc struct {
	Name string
	Type string
}

BlockDesc provides high-level informations about a Block

type Compressor

type Compressor interface {
	io.WriteCloser

	// Reset clears the state of the Writer such that it is equivalent to its
	// initial state, but instead writing to w.
	Reset(w io.Writer) error

	// Flush flushes the Writer to its underlying io.Writer.
	Flush() error
}

A Compressor takes data written to it and writes the compressed form of that data to an underlying writer.

type CompressorKind

type CompressorKind uint16

CompressorKind names the various compressors

const (
	CompressDefault CompressorKind = iota
	CompressNone
	CompressFlate
	CompressZlib
	CompressGzip
	CompressLZA
	CompressLZO
	CompressSnappy

	CompressUser CompressorKind = 0xffff // keep last
)

builtin compressor types

func (CompressorKind) NewCompressor

func (ck CompressorKind) NewCompressor(w io.Writer, opts Options) (Compressor, error)

NewCompressor creates a Compressor writing to w, with compression level according to opts.

func (CompressorKind) NewDecompressor

func (ck CompressorKind) NewDecompressor(r io.Reader) (Decompressor, error)

NewDecompressor creates a Decompressor reading from r.

func (CompressorKind) String

func (ck CompressorKind) String() string

type Decompressor

type Decompressor interface {
	io.ReadCloser

	// Reset clears the state of the Reader such that it is equivalent to its
	// initial state, but instead reading from r.
	Reset(r io.Reader) error
}

A Decompressor reads data from the underlying io.Reader and decompresses it.

type File

type File struct {
	// contains filtered or unexported fields
}

File random-read-access to a rio stream

func Open

func Open(r io.ReadSeeker) (*File, error)

Open creates a new read-only File.

func (*File) Close

func (f *File) Close() error

Close closes access to the rio-file. It does not (and can not) close the underlying reader.

func (*File) Get

func (f *File) Get(name string, ptr interface{}) error

Get reads the value `name` into `ptr`

func (*File) Has

func (f *File) Has(name string) bool

Has returns whether a record `name` exists in this file.

func (*File) Keys

func (f *File) Keys() []RecordDesc

Keys returns the list of record names.

type Marshaler

type Marshaler interface {
	RioMarshal(w io.Writer) error
}

Marshaler is the interface implemented by an object that can marshal itself into a rio-binary form.

RioMarshal marshals the receiver into a rio-binary form, writes that binary form to the io.Writer and returns an error if any.

type Metadata

type Metadata struct {
	Records []RecordDesc
	Offsets map[string][]Span
}

Metadata stores metadata about a rio stream

type Options

type Options uint32

Options describes the various options attached to a rio stream such as: compression method, compression level, codec, ...

func NewOptions

func NewOptions(compr CompressorKind, lvl int, codec int) Options

NewOptions returns a new Options value carefully crafted from the CompressorKind and compression level

func (Options) CompressorCodec

func (o Options) CompressorCodec() int

CompressorCodec extracts the compression codec from the Options value

func (Options) CompressorKind

func (o Options) CompressorKind() CompressorKind

CompressorKind extracts the CompressorKind from the Options value

func (Options) CompressorLevel

func (o Options) CompressorLevel() int

CompressorLevel extracts the compression level from the Options value

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader is a rio read-only stream

func NewReader

func NewReader(r io.Reader) (*Reader, error)

NewReader returns a new read-only rio stream

func (*Reader) Close

func (r *Reader) Close() error

Close finishes reading the rio read-only stream. It does not (and can not) close the underlying reader.

func (*Reader) Record

func (r *Reader) Record(name string) *Record

Record adds a Record to the list of records to read or returns the Record with that name.

func (*Reader) Records

func (r *Reader) Records() []*Record

Records returns the list of connected Records

type Record

type Record struct {
	// contains filtered or unexported fields
}

Record manages and describes blocks of data

func (*Record) Block

func (rec *Record) Block(name string) *Block

Block returns the block named name for reading or writing Block returns nil if the block doesn't exist

func (*Record) Compress

func (rec *Record) Compress() bool

Compress returns the compression flag

func (*Record) Connect

func (rec *Record) Connect(name string, ptr interface{}) error

Connect connects a Block to this Record (for reading or writing)

func (*Record) Name

func (rec *Record) Name() string

Name returns the name of this record

func (*Record) Options

func (rec *Record) Options() Options

Options returns the options of this record.

func (*Record) Read

func (rec *Record) Read() error

Read reads data from the Reader, in the rio format

func (*Record) SetUnpack

func (rec *Record) SetUnpack(unpack bool)

SetUnpack sets whether to unpack incoming records

func (*Record) Unpack

func (rec *Record) Unpack() bool

Unpack returns whether to unpack incoming records

func (*Record) Write

func (rec *Record) Write() error

Write writes data to the Writer, in the rio format

type RecordDesc

type RecordDesc struct {
	Name   string
	Blocks []BlockDesc
}

RecordDesc provides high-level informations about a Record

type Scanner

type Scanner struct {
	// contains filtered or unexported fields
}

Scanner provides a convenient interface for reading records of a rio-stream.

func NewScanner

func NewScanner(r *Reader) *Scanner

NewScanner returns a new Scanner to read from r.

func (*Scanner) Err

func (s *Scanner) Err() error

Err returns the first non-EOF error encountered by the reader.

func (*Scanner) Record

func (s *Scanner) Record() *Record

Record returns the last Record read by the Scanner.

func (*Scanner) Scan

func (s *Scanner) Scan() bool

Scan scans the next Record until io.EOF

func (*Scanner) Select

func (s *Scanner) Select(selectors []Selector)

Select sets the records selection function.

type Selector

type Selector struct {
	Name   string // Record name
	Unpack bool   // Whether to unpack the Record
}

Selector selects Records based on their name

type Span

type Span struct {
	Pos int64
	Len int64
}

Span is a pair (position, length)

type Streamer

type Streamer interface {
	Marshaler
	Unmarshaler
	RioVersion() Version
}

Streamer is the interface implemented by an object that can marshal/unmarshal a rio-binary representation of itself to/from an io.Writer/io.Reader.

type Unmarshaler

type Unmarshaler interface {
	RioUnmarshal(r io.Reader) error
}

Unmarshalr is the interface implemented by an object that can unmarshal a rio-binary representation of itself.

RioUnmarshal must be able to unmarshal the form generated by RioMarshal.

type Version

type Version uint32

Version describes a rio on-disk version of a serialized block.

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer is a rio write-only stream

func NewWriter

func NewWriter(w io.Writer) (*Writer, error)

NewWriter returns a new write-only rio stream

func (*Writer) Close

func (w *Writer) Close() error

Close finishes writing the rio write-only stream. It does not (and can not) close the underlying writer.

func (*Writer) Record

func (w *Writer) Record(name string) *Record

Record adds a Record to the list of records to write or returns the Record with that name.

func (*Writer) SetCompressor

func (w *Writer) SetCompressor(compr CompressorKind, lvl int) error

SetCompressor enables compression and sets the compression method.

func (*Writer) WriteValue

func (w *Writer) WriteValue(name string, value interface{}) error

WriteValue writes a value to the stream. The value is written to a record named `name` with one block `name`.

type Xpressor

type Xpressor interface {
	Inflate(r io.Reader) (Decompressor, error)
	Deflate(w io.Writer, opts Options) (Compressor, error)
}

Xpressor provides compressor and decompressor functions

Directories

Path Synopsis
cmd
rio-ls-records
rio-ls-records displays the list of records stored in a given rio file.
rio-ls-records displays the list of records stored in a given rio file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL