ndb: aqwari.net/exp/ndb Index | Files

package ndb

import "aqwari.net/exp/ndb"

Package ndb decodes and encodes simple strings of attribute=value pairs. The accepted format is based on Plan 9's ndb(6) format found at http://plan9.bell-labs.com/magic/man2html/6/ndb, with additional rules for quoting values containing white space.

Attributes are UTF-8 encoded strings of any printable non-whitespace character, except for the equals sign ('='). Value strings may contain any printable character except for a new line. Values containing white space must be enclosed in single quotes. Single quotes can be escaped by doubling them, like so:

* {"example1": "Let's go shopping"} is encoded as
  example1='Let''s go shopping'
* {"example2": "Escape ' marks by doubling like this: ''"}
  example2='Escape '' marks by doubling like this: '''''
* {"example3": "can't"}
  example3=can''t

Tuples must be separated by at least one whitespace character. The same attribute may appear multiple times in an ndb string. When decoding an ndb string with repeated attributes, the destination type must be a slice.

Index

Package Files

ndb.go read.go write.go

func Marshal Uses

func Marshal(v interface{}) ([]byte, error)

Marshal encodes a value into an ndb string. Marshal will use the String method of each struct field or map entry to produce ndb output. If v is a slice or array, multiple ndb lines will be output, one for each element. For structs, attribute names will be the name of the struct field, or the fields ndb annotation if it exists. Ndb attributes may not contain white space. Ndb values may contain white space but may not contain new lines. If Marshal cannot produce valid ndb strings, an error is returned. No guarantee is made about the order of the tuples.

func Unmarshal Uses

func Unmarshal(data []byte, v interface{}) error

The Unmarshal function reads an entire ndb string and unmarshals it into the Go value v. Value v must be a pointer. Unmarshal will behave differently depending on the type of value v points to.

If v is a slice, Unmarshal will decode all lines from the ndb input into slice elements. Otherwise, Unmarshal will decode only the first line.

If v is a map, Unmarshal will populate v with key/value pairs, where value is decoded according to the concrete types of the map.

If v is a struct, Unmarshal will populate struct fields whose names match the ndb attribute. Struct fields may be annotated with a tag of the form `ndb:"name"`, where name matches the attribute string in the ndb input.

Struct fields or map keys that do not match the ndb input are left unmodified. Ndb attributes that do not match any struct fields are silently dropped. If an ndb string cannot be converted to the destination value or a syntax error occurs, an error is returned and v is left unmodified. Unmarshal can only store to exported (capitalized) fields of a struct.

type Decoder Uses

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

A decoder wraps an io.Reader and decodes successive ndb strings into Go values using the Decode() function.

func NewDecoder Uses

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a Decoder with its input pulled from an io.Reader

func (*Decoder) Decode Uses

func (d *Decoder) Decode(v interface{}) error

The Decode method follows the same parsing rules as Unmarshal(), but reads its input from the Decoder's input stream.

type Encoder Uses

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

An Encoder wraps an io.Writer and serializes Go values into ndb strings. Successive calls to the Encode() method append lines to the io.Writer.

func NewEncoder Uses

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns an Encoder that writes ndb output to an io.Writer

func (*Encoder) Encode Uses

func (e *Encoder) Encode(v interface{}) error

The Encode method will write the ndb encoding of the Go value v to its backend io.Writer. Unlike Decode(), slice or array values are valid, and will cause multiple ndb lines to be written. If the value cannot be fully encoded, an error is returned and no data will be written to the io.Writer.

type SyntaxError Uses

type SyntaxError struct {
    Data    []byte
    Offset  int64
    Message string
}

A SyntaxError occurs when malformed input, such as an unterminated quoted string, is received. It contains the UTF-8 encoded line that was being read and the position of the first byte that caused the syntax error. Data may only be valid until the next call to the Decode() method

func (*SyntaxError) Error Uses

func (e *SyntaxError) Error() string

type TypeError Uses

type TypeError struct {
    Type reflect.Type
}

A TypeError occurs when a Go value is incompatible with the ndb string it must store or create.

func (*TypeError) Error Uses

func (e *TypeError) Error() string

Package ndb imports 10 packages (graph). Updated 2018-05-15. Refresh now. Tools for package owners.