jsonwall

Documentation

Overview

Package jsonwall provides an interface to work with database files in the simple "jsonwall" format, which consists of a text file with one JSON object per line, where both the individual JSON fields and the lines themselves are sorted to optimize for searching and iteration.

For example, the following content represents a valid jsonwall database:

{"jsonwall":"1.0","count":3}
{"kind":"app","name":"chisel","version":"1.0"}
{"kind":"app","name":"pebble","version":"1.2"}

The entries in this database might be manipulated with a type such as:

type AppEntry struct {
        Kind string    `json:"kind"`
        Name string    `json:"name,omitempty"`
        Version string `json:"version,omitempty"`
}

Such data types have two important characteristics: fields must be defined in the order that will be used when searching, and every optional field must be tagged with `omitempty`.

With that in place, the database may be accessed as:

app := AppEntry{Kind: "app", Name: "chisel"}
if db.Get(&app) == nil {
        fmt.Println(app.Name, "version:", app.Version)
}

Iteration works similarly:

app := AppEntry{Kind: "app"}
if iter, err := db.Iter(&app); err == nil {
        for iter.Next() {
                if iter.Get(&app) == nil {
                        fmt.Println(app.Name, "version:", app.Version)
                }
        }
}

Index

• Variables
• func SetDebug(debug bool)
• func SetLogger(logger log_Logger)
• type DB
  • func ReadDB(r io.Reader) (*DB, error)
  • func (db *DB) Get(value any) error
  • func (db *DB) Iterate(value any) (*Iterator, error)
  • func (db *DB) IteratePrefix(value any) (*Iterator, error)
  • func (db *DB) Schema() string
• type DBWriter
  • func NewDBWriter(options *DBWriterOptions) *DBWriter
  • func (dbw *DBWriter) Add(value any) error
  • func (dbw *DBWriter) WriteTo(w io.Writer) (n int64, err error)
• type DBWriterOptions
• type Iterator
  • func (iter *Iterator) Get(value any) error
  • func (iter *Iterator) Next() bool

Variables

var ErrNotFound = fmt.Errorf("value not found in database")

Functions

func SetDebug

func SetDebug(debug bool)

Enable the delivery of debug messages to the logger. Only meaningful if a logger is also set.

func SetLogger

func SetLogger(logger log_Logger)

Specify the *log.Logger object where log messages should be sent to.

Types

type DB

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

DB holds an in-memory read-only database ready for querying.

func ReadDB

func ReadDB(r io.Reader) (*DB, error)

ReadDB reads into memory the database from the provided r.

func (*DB) Get

func (db *DB) Get(value any) error

Get encodes the provided value as JSON, finds the first entry in the database with initial fields exactly matching that encoding, and then decodes the entry back into the provided value.

func (*DB) Iterate

func (db *DB) Iterate(value any) (*Iterator, error)

Iterate encodes the provided value as JSON and returns an iterator that will go over every entry in the database with initial fields that exactly match that encoding. An iterator is still returned even if no entries match the provided value.

func (*DB) IteratePrefix

func (db *DB) IteratePrefix(value any) (*Iterator, error)

IteratePrefix works similarly to Iterate, except that after encoding the provided value as JSON, its last encoded field must be a string that will be matched as a prefix of the respective database entry field, instead of being matched exactly.

func (*DB) Schema

func (db *DB) Schema() string

Schema returns the optional schema value that was provided when writing the database. This information is available to help with the decoding of the data, and is not internally interpreted in any way.

type DBWriter

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

DBWriter holds in memory the state of a database while it's being prepared for serialization and implements the WriterTo interface for assembling it.

func NewDBWriter

func NewDBWriter(options *DBWriterOptions) *DBWriter

NewDBWriter returns a database writer that can assemble new databases.

func (*DBWriter) Add

func (dbw *DBWriter) Add(value any) error

Add encodes the provided value as a JSON object and includes the resulting data into the database being created.

func (*DBWriter) WriteTo

func (dbw *DBWriter) WriteTo(w io.Writer) (n int64, err error)

WriteTo assembles the current database state and writes it to w.

type DBWriterOptions

type DBWriterOptions struct {
	// Schema is included in the database header to help the decoding
	// process. The value is made available when reading, and is not
	// internally interpreted.
	Schema string
}

type Iterator

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

func (*Iterator) Get

func (iter *Iterator) Get(value any) error

Get decodes the current entry into the provided value. The Next method must always be called first.

func (*Iterator) Next

func (iter *Iterator) Next() bool

Next positions the iterator on the next available entry for decoding and returns whether such an entry was found. Next must also be called for the first entry of the iteration as the result set might be empty.