gohaystack

README

gohaystack

This is a toy library to play with Project Haystack in Go. It only relies on Go's standard library.

What is project-haystack?

As stated in the web site

"Project Haystack_ is an open-source initiative to streamline working with data from the Internet of Things. We standardize semantic data models and web services with the goal of making it easier to unlock value from the vast quantity of data being generated by the smart devices that permeate our homes, buildings, factories, and cities. Applications include automation, control, energy, HVAC, lighting, and other environmental systems."

-- Project-Haystack

What's included

This library is rather incomplete, as I am using it only for testing purpose (discovering haystack, building a sample server, and transform data from a format to another) This library has a Grid structure that can be (de)serialized to and from haystack format in JSON (no zinc yet). The Grid structure supports a couple of methods to add rows, and columns, and also a basic and inefficient search mechanism.

Please, see the API documentation for more information.

It also supports a special type TypedValue to make conversion easier from the Go'internal typed elements and haystack's typed elements.

Example

Basic example

Generate a grid and add values:

testGrid := NewGrid()
testGrid.AddColumn("col1", "la colonne 1 (string)")
testGrid.AddColumn("col2", "")
testGrid.AddColumn("col3", "array")
testGrid.AddColumn("col4", "")
err := testGrid.AddRow([]*TypedValue{
    NewTypedValue(HaystackTypeStr, "bla"),
    NewTypedValue(HaystackTypeStr, "blo"),
    NewTypedValue(HaystackTypeStr, "blu"),
    NewTypedValue(HaystackTypeStr, "bli"),
})

JSON

Generate a grid from a json payload:

gridDB := grid.NewGrid()
dec := json.NewDecoder(os.Stdin)
err := dec.Decode(&gridDB)
if err != nil {
    log.Fatal(err)
}

Complete example

the example/graph contains a CLI tool that reads a JSON encoded haystack grid from stdin and generates a dot compatible representation on stdout.

Caution

This is a toy project given without any warranty. I made it for my own need to discover haystack. If you want to take over the maintenance, feel free to contact me.

Documentation

Index

• type Grid
  • func NewGrid() *Grid
  • func (g *Grid) AddColumn(name, dis string)
  • func (g *Grid) AddRow(row []*TypedValue) error
  • func (g *Grid) CloneStruct() *Grid
  • func (g *Grid) GetCol(col string) ([]*TypedValue, bool)
  • func (g *Grid) GetRowsMatching(match map[string]*TypedValue) ([][]*TypedValue, error)
  • func (g *Grid) GobDecode(b []byte) error
  • func (g *Grid) GobEncode() ([]byte, error)
  • func (g *Grid) MarshalJSON() ([]byte, error)
  • func (g *Grid) NewRow() int
  • func (g *Grid) Set(row int, col string, value *TypedValue) error
  • func (g *Grid) UnmarshalJSON(b []byte) error
• type HaystackType
• type RowIterator
  • func NewRowIterator(g *Grid) *RowIterator
  • func (r *RowIterator) Len() int
  • func (r *RowIterator) Next() bool
  • func (r *RowIterator) Row() []*TypedValue
• type TypedValue
  • func NewTypedValue(typ HaystackType, value interface{}) *TypedValue
  • func (tv *TypedValue) Equal(tv2 *TypedValue) bool
  • func (tv *TypedValue) Hash() string

Types

type Grid

type Grid struct {
	Meta map[string]string

	Cols map[int]string // this is a reverse index string is the col name, and int its index
	// contains filtered or unexported fields
}

Grid is a simple database structure, column based

func NewGrid

func NewGrid() *Grid

NewGrid creates an empty grid

func (*Grid) AddColumn

func (g *Grid) AddColumn(name, dis string)

AddColumn with name and description. This column does not extend the existing rows and therefore is not safe for use after AddRow has been called. Column is added at the end of the stack, order of call to this function matters.

func (*Grid) AddRow

func (g *Grid) AddRow(row []*TypedValue) error

AddRow to the grid at the end of the existing row stack

func (*Grid) CloneStruct

func (g *Grid) CloneStruct() *Grid

CloneStruct ...

func (*Grid) GetCol

func (g *Grid) GetCol(col string) ([]*TypedValue, bool)

GetCol returns the column value and a boolean to false if the column does not exists

func (*Grid) GetRowsMatching

func (g *Grid) GetRowsMatching(match map[string]*TypedValue) ([][]*TypedValue, error)

GetRowsMatching returns rows matching the match hashmap. The key of match is the column name and *TypedValue a non nil value to be matched. The return value is a list of rows (the row is of length len(g.Cols)) This function returns an error if the key of match does not exist in the grid and if any of the pointer to TypedValue is nil in the request.

func (*Grid) GobDecode

func (g *Grid) GobDecode(b []byte) error

GobDecode ...

func (*Grid) GobEncode

func (g *Grid) GobEncode() ([]byte, error)

GobEncode the grid in a binary form for export

func (*Grid) MarshalJSON

func (g *Grid) MarshalJSON() ([]byte, error)

MarshalJSON encode the grid in a haystack compatible format

func (*Grid) NewRow

func (g *Grid) NewRow() int

NewRow empty row in the grid; returns the rowID

func (*Grid) Set

func (g *Grid) Set(row int, col string, value *TypedValue) error

Set the value in the grid; silently override any existing value. returns an error if col or row is out of range.

func (*Grid) UnmarshalJSON

func (g *Grid) UnmarshalJSON(b []byte) error

UnmarshalJSON implemented the json.Unmarshaler. Reads a haystack json payload and creates a grid.

type HaystackType

type HaystackType int

HaystackType represents a type handled by haystack

const (
	// HaystackTypeUndefined ...
	HaystackTypeUndefined HaystackType = iota
	// HaystackTypeGrid is a Grid object
	HaystackTypeGrid
	// HaystackTypeList Array
	HaystackTypeList
	// HaystackTypeDict Object
	HaystackTypeDict
	// HaystackTypenull null
	HaystackTypenull
	// HaystackTypeBool Boolean
	HaystackTypeBool
	// HaystackTypeMarker "m:"
	HaystackTypeMarker
	// HaystackTypeRemove "-:"
	HaystackTypeRemove
	// HaystackTypeNA "z:"
	HaystackTypeNA
	// HaystackTypeNumber "n:<float> [unit]" "n:45.5" "n:73.2 °F" "n:-INF"
	HaystackTypeNumber
	// HaystackTypeRef "r:<id> [dis]"  "r:abc-123" "r:abc-123 RTU #3"
	HaystackTypeRef
	// HaystackTypeStr "hello" "s:hello"
	HaystackTypeStr
	// HaystackTypeDate "d:2014-01-03"
	HaystackTypeDate
	// HaystackTypeTime "h:23:59"
	HaystackTypeTime
	// HaystackTypeDateTime "t:2015-06-08T15:47:41-04:00 New_York"
	HaystackTypeDateTime
	// HaystackTypeURI "u:http://project-haystack.org/"
	HaystackTypeURI
	// HaystackTypeCoord "c:<lat>,<lng>" "c:37.545,-77.449"
	HaystackTypeCoord
	//HaystackTypeXStr "x:Type:value"
	HaystackTypeXStr
	// HaystackLastType ...
	HaystackLastType
)

type RowIterator

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

RowIterator is a top level structure to get the row of a db

func NewRowIterator

func NewRowIterator(g *Grid) *RowIterator

NewRowIterator from a grid

func (*RowIterator) Len

func (r *RowIterator) Len() int

Len returns the remaining number of rows to be iterated over.

func (*RowIterator) Next

func (r *RowIterator) Next() bool

Next returns whether the next call of Row will return a valid row.

func (*RowIterator) Row

func (r *RowIterator) Row() []*TypedValue

Row returns the current row of the iterator. Next must have been called prior to a call to Row.

type TypedValue

type TypedValue struct {
	Type  HaystackType
	Value interface{}
}

TypedValue is any value that can be associated with a HaystackType

func NewTypedValue

func NewTypedValue(typ HaystackType, value interface{}) *TypedValue

NewTypedValue holding the haystack type (not tag). There is not check done to see if the interface{} underlying type is compatible with the haystack type.

func (*TypedValue) Equal

func (tv *TypedValue) Equal(tv2 *TypedValue) bool

Equal returns true if type and value are equal

func (*TypedValue) Hash

func (tv *TypedValue) Hash() string

Hash ...