ard

README

Agnostic Raw Data (ARD)

What is "agnostic raw data"?

Agnostic

Comprising primitives (string, integer, float, boolean, null, etc.) and structures (map, list) that can be transmitted to practically any language or platform. It can also work with a wide variety of formats, though with some limitations.

YAML

YAML supports a rich set of primitive types, so ARD will survive a round trip to YAML. Indeed, the ARD type system should adhere to YAML's. However, note that YAML maps are ordered while ARD maps have arbitrary order. A round trip from YAML to ARD would thus lose order. Another YAML feature is allowing for maps with arbitrary keys. This is non-trivial to support in Go, and so we provide special functions (MapGet, MapPut, MapDelete, MapMerge) that replace the Go native functionality with additional support for detecting and handling complex keys. (This feature is provided as an independent library, yamlkeys.)

JSON

JSON can be read into ARD. However, because JSON has fewer types than YAML (no integers, only floats; map keys can only be string), ARD can be translated to JSON but some type information would be lost unless it were to be encoded within the data. This would effectively become an extended JSON format that would also have to be parsed and generated in a particular way.

XML

XML is more complicated: with a proper schema, ARD can survive a round trip. However, XML would have to be created specifically for that schema. Arbitrary XML cannot be parsed into ARD.

Raw

The data is untreated and not validated. There's no schema.

Documentation

Index

• Constants
• Variables
• func Copy(value interface{}) interface{}
• func FindYAMLNode(node *yaml.Node, path ...PathElement) *yaml.Node
• func IsBool(value interface{}) bool
• func IsFloat(value interface{}) bool
• func IsInteger(value interface{}) bool
• func IsList(value interface{}) bool
• func IsMap(value interface{}) bool
• func IsString(value interface{}) bool
• func IsTime(value interface{}) bool
• func MergeMaps(target Map, source Map, mergeLists bool)
• func Read(reader io.Reader, format string, locate bool) (Map, Locator, error)
• func ReadFromURL(url urlpkg.URL, locate bool) (Map, Locator, error)
• func ReadJSON(reader io.Reader, locate bool) (Map, Locator, error)
• func ReadYAML(reader io.Reader, locate bool) (Map, Locator, error)
• func StringMapPutNested(map_ StringMap, key string, value string) error
• func ToMaps(value interface{}) (interface{}, bool)
• func ToStringMaps(value interface{}) (interface{}, bool)
• func ToYAMLDocumentNode(value interface{}, verbose bool) *yaml.Node
• func ToYAMLNode(value interface{}, verbose bool) *yaml.Node
• func TypeName(value interface{}) string
• type List
• type Locator
• type Map
  • func EnsureMaps(map_ interface{}) Map
  • func ToMap(stringMap StringMap) Map
• type Path
  • func (self Path) String() string
• type PathElement
  • func NewFieldPathElement(name string) PathElement
  • func NewListPathElement(index int) PathElement
  • func NewMapPathElement(name string) PathElement
• type StringMap
  • func EnsureStringMaps(map_ interface{}) StringMap
  • func ToStringMap(map_ Map) StringMap
• type TypeValidator
• type YAMLLocator
  • func NewYAMLLocator(rootNode *yaml.Node) *YAMLLocator
  • func (self *YAMLLocator) Locate(path ...PathElement) (int, int, bool)

Constants

const (
	FieldPathType = iota
	MapPathType   = iota
	ListPathType  = iota
)

Variables

var TypeValidators = map[string]TypeValidator{

	"!!map": IsMap,
	"!!seq": IsList,
	"!!str": IsString,

	"!!bool":  IsBool,
	"!!int":   IsInteger,
	"!!float": IsFloat,

	"!!timestamp": IsTime,
}

var TypeZeroes = map[string]interface{}{
	"!!map":       make(Map),
	"!!seq":       List{},
	"!!str":       "",
	"!!bool":      false,
	"!!int":       int(0),
	"!!float":     float64(0.0),
	"!!timestamp": time.Time{},
}

Functions

func Copy

func Copy(value interface{}) interface{}

func FindYAMLNode

func FindYAMLNode(node *yaml.Node, path ...PathElement) *yaml.Node

func IsBool

func IsBool(value interface{}) bool

bool

func IsFloat

func IsFloat(value interface{}) bool

float64, float32

func IsInteger

func IsInteger(value interface{}) bool

int64, int32, int16, int8, int, uint64, uint32, uint16, uint8, uint

func IsList

func IsList(value interface{}) bool

List = []interface{}

func IsMap

func IsMap(value interface{}) bool

Map = map[interface{}]interface{}

func IsString

func IsString(value interface{}) bool

string

func IsTime

func IsTime(value interface{}) bool

time.Time

func MergeMaps

func MergeMaps(target Map, source Map, mergeLists bool)

func Read

func Read(reader io.Reader, format string, locate bool) (Map, Locator, error)

func ReadFromURL

func ReadFromURL(url urlpkg.URL, locate bool) (Map, Locator, error)

func ReadJSON

func ReadJSON(reader io.Reader, locate bool) (Map, Locator, error)

func ReadYAML

func ReadYAML(reader io.Reader, locate bool) (Map, Locator, error)

func StringMapPutNested

func StringMapPutNested(map_ StringMap, key string, value string) error

func ToMaps

func ToMaps(value interface{}) (interface{}, bool)

func ToStringMaps

func ToStringMaps(value interface{}) (interface{}, bool)

func ToYAMLDocumentNode

func ToYAMLDocumentNode(value interface{}, verbose bool) *yaml.Node

func ToYAMLNode

func ToYAMLNode(value interface{}, verbose bool) *yaml.Node

func TypeName

func TypeName(value interface{}) string

Types

type List

type List = []interface{}

Note: This is just a convenient alias, *not* a type. An extra type would ensure more strictness but would make life more complicated than it needs to be. That said, if we *do* want to make this into a type, we need to make sure not to add any methods to the type, otherwise the goja JavaScript engine will treat it as a host object instead of a regular JavaScript dict object.

type Locator

type Locator interface {
	Locate(path ...PathElement) (int, int, bool)
}

type Map

type Map = map[interface{}]interface{}

Note: This is just a convenient alias, *not* a type. An extra type would ensure more strictness but would make life more complicated than it needs to be. That said, if we *do* want to make this into a type, we need to make sure not to add any methods to the type, otherwise the goja JavaScript engine will treat it as a host object instead of a regular JavaScript dict object.

func EnsureMaps

func EnsureMaps(map_ interface{}) Map

func ToMap

func ToMap(stringMap StringMap) Map

type Path

type Path []PathElement

func (Path) String

func (self Path) String() string

fmt.Stringer interface

type PathElement

type PathElement struct {
	Type  int
	Value interface{} // string for FieldPathType and MapPathType, int for ListPathType
}

func NewFieldPathElement

func NewFieldPathElement(name string) PathElement

func NewListPathElement

func NewListPathElement(index int) PathElement

func NewMapPathElement

func NewMapPathElement(name string) PathElement

type StringMap

type StringMap = map[string]interface{}

func EnsureStringMaps

func EnsureStringMaps(map_ interface{}) StringMap

func ToStringMap

func ToStringMap(map_ Map) StringMap

type TypeValidator

type TypeValidator = func(interface{}) bool

type YAMLLocator

type YAMLLocator struct {
	RootNode *yaml.Node
}

func NewYAMLLocator

func NewYAMLLocator(rootNode *yaml.Node) *YAMLLocator

func (*YAMLLocator) Locate

func (self *YAMLLocator) Locate(path ...PathElement) (int, int, bool)

Locator interface