versioned

Documentation

Overview

Example

type DataV1 struct {
	FullName string `json:"name"`
}

type DataV2 struct {
	FirstName string `json:"first_name"`
	LastName  string `json:"last_name"`
}

//latest := MustParse("1.2.0")
// 1- Open file contains data
bits := `{"name": "John Smith"}`

buf := bytes.NewBufferString(bits)
// 2- create versioned reader
reader, err := NewReader(buf)
if IsNotVersioned(err) {
	reader = NewVersionedReader(MustParse("1.0.0"), bytes.NewBufferString(bits))
} else if err != nil {
	panic(err)
}

dec := json.NewDecoder(reader)
var data DataV2 // final object
var resave bool
if reader.Version().EQ(MustParse("1.0.0")) { //V1 object
	// data migration from v1 to v2
	var d1 DataV1
	if err := dec.Decode(&d1); err != nil {
		panic(err)
	}
	parts := strings.SplitN(d1.FullName, " ", 2)
	data = DataV2{
		FirstName: parts[0],
		LastName:  parts[1],
	}
	resave = true
} else if reader.Version().EQ(MustParse("2.0.0")) { //V2 (current) version
	if err := dec.Decode(&data); err != nil {
		panic(err)
	}
} else {
	panic("unknown version")
}

if resave {
	var buf bytes.Buffer
	writer, _ := NewWriter(&buf, MustParse("2.0.0"))
	enc := json.NewEncoder(writer)
	if err := enc.Encode(data); err != nil {
		panic(err)
	}

	fmt.Println(buf.String())
}

Output:

"2.0.0"{"first_name":"John","last_name":"Smith"}

Index

• Variables
• func IsNotVersioned(err error) bool
• func NewWriter(w io.Writer, version Version) (io.Writer, error)
• func WriteFile(filename string, version Version, data []byte, perm os.FileMode) error
• type Range
  • func MustParseRange(s string) Range
  • func ParseRange(s string) (Range, error)
• type Reader
  • func NewReader(r io.Reader) (*Reader, error)
  • func NewVersionedReader(version Version, r io.Reader) *Reader
  • func (r *Reader) Version() Version
• type Version
  • func MustParse(s string) Version
  • func Parse(s string) (Version, error)
  • func ReadFile(path string) (Version, []byte, error)

Examples

• Package
• NewReader

Variables

var (
	// ErrNotVersioned error is raised if the underlying reader has no version
	ErrNotVersioned = fmt.Errorf("no version information")
)

Functions

func IsNotVersioned

func IsNotVersioned(err error) bool

IsNotVersioned checks if error is caused by a 'not versioned' stream

func NewWriter

func NewWriter(w io.Writer, version Version) (io.Writer, error)

NewWriter creates a versioned writer that marks data with the Provided version.

func WriteFile

func WriteFile(filename string, version Version, data []byte, perm os.FileMode) error

WriteFile versioned data to file

Types

type Range

type Range = semver.Range

Range type

func MustParseRange

func MustParseRange(s string) Range

MustParseRange parses range

func ParseRange

func ParseRange(s string) (Range, error)

ParseRange parses a range

type Reader

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

Reader is a versioned reader The Versioned Reader is a reader that can load the version of the data from a stream without assuming anything regarding the underlying encoding of your data object

func NewReader

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

NewReader creates a new versioned reader from a stream. It fails if the reader can not read the version from the stream. On success, the reader will have a version, and then can be used to load the data.

Example

latest := MustParse("1.2.0")
// 1- Open file contains data
buf := bytes.NewBufferString(`"1.0.1" "my data goes here"`)

// 2- create versioned reader
reader, err := NewReader(buf)
if err != nil {
	// no version in data, take another action!
	panic(err)
}

fmt.Println("data version is:", reader.Version())
dec := json.NewDecoder(reader)

if reader.Version().Compare(latest) <= 0 {
	//data version is older than or equal latest
	var data string
	if err := dec.Decode(&data); err != nil {
		panic(err)
	}
	fmt.Println("data is:", "my data goes here")
}

Output:

data version is: 1.0.1
data is: my data goes here

func NewVersionedReader

func NewVersionedReader(version Version, r io.Reader) *Reader

NewVersionedReader creates a versioned reader from an un-versioned reader. It's usually used to unify the data migration work flow in case the older data file didn't have a version stamp example:

 reader, err := NewReader(file)
 if IsNotVersioned(err) {
     file.Seek(0, 0) // this is important to make u reading from start
     reader = NewVersionedReader(MustParse("0.0.0"), file)
 } else err != nil {
   // probably io error
}

func (*Reader) Version

func (r *Reader) Version() Version

Version return the version of the data

type Version

type Version = semver.Version

Version type

func MustParse

func MustParse(s string) Version

MustParse version

func Parse

func Parse(s string) (Version, error)

Parse version string

func ReadFile

func ReadFile(path string) (Version, []byte, error)

ReadFile content