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.