ard

package
v0.1.16 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 9, 2021 License: Apache-2.0 Imports: 11 Imported by: 0

README

Agnostic Raw Data (ARD)

What is "agnostic raw data"?

Agnostic?

Comprising primitives (string, integer, float, boolean, null) and structures (map, list). It's agnostic because it can be trivially represented in practically any language or platform, and also because it can be transmitted in a wide variety of formats.

Note that some formats present limitations:

YAML

YAML supports a rich set of primitive types, so ARD will survive a round trip to YAML.

One difference is that in YAML 1.1 maps can be ordered (!!omap vs. !!map) but ARD maps have arbitrary order (always !!map) for widest compatibility. A round trip from YAML to ARD would thus lose order. (YAML 1.2 does not include !!omap support by default.)

YAML allows 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 and more limitations than YAML (no integers, only floats; map keys can only be strings), ARD will lose some type information when translated into JSON.

We can overcome this challenge by extending JSON with some conventions for encoding extra types. See our conventions.

XML

XML does not have a type system. Arbitrary XML cannot be parsed into ARD.

However, with a proper schema and custom reader this could be implemented in the future.

Raw?

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

Documentation

Index

Constants

View Source 
const (
	FieldPathType = iota
	MapPathType
	ListPathType
	SequencedListPathType
)

Variables

View Source 
var CompatibleJSONBytesCode = "$ard.bytes"
View Source 
var CompatibleJSONIntegerCode = "$ard.integer"
View Source 
var CompatibleJSONMapCode = "$ard.map"
View Source 
var CompatibleJSONUIntegerCode = "$ard.uinteger"
View Source 
var NoNode = &Node{nil, nil, ""}
View Source 
var TypeValidators = map[TypeName]TypeValidator{
	TypeMap:       IsMap,
	TypeList:      IsList,
	TypeString:    IsString,
	TypeBoolean:   IsBoolean,
	TypeInteger:   IsInteger,
	TypeFloat:     IsFloat,
	TypeNull:      IsNull,
	TypeTimestamp: IsTimestamp,
}
View Source 
var TypeZeroes = map[TypeName]Value{
	TypeMap:       make(Map),
	TypeList:      List{},
	TypeString:    "",
	TypeBoolean:   false,
	TypeInteger:   int(0),
	TypeFloat:     float64(0.0),
	TypeNull:      nil,
	TypeTimestamp: time.Time{},
}

Functions

func DecodeCompatibleJSONBytes added in v0.1.15 

func DecodeCompatibleJSONBytes(code StringMap) ([]byte, bool)

func DecodeCompatibleJSONInteger added in v0.1.15 

func DecodeCompatibleJSONInteger(code StringMap) (int64, bool)

func DecodeCompatibleJSONUInteger added in v0.1.15 

func DecodeCompatibleJSONUInteger(code StringMap) (uint64, bool)

func Equals 

func Equals(a Value, b Value) bool

func FindYAMLNode 

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

func IsBoolean 

func IsBoolean(value Value) bool

bool

func IsFloat 

func IsFloat(value Value) bool

float64, float32

func IsInteger 

func IsInteger(value Value) bool

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

func IsList 

func IsList(value Value) bool

List = []interface{}

func IsMap 

func IsMap(value Value) bool

Map = map[interface{}]interface{}

func IsNull 

func IsNull(value Value) bool

func IsString 

func IsString(value Value) bool

string

func IsTimestamp 

func IsTimestamp(value Value) bool

time.Time

func MergeMaps 

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

func MergeStringMaps 

func MergeStringMaps(target StringMap, source StringMap, mergeLists bool)

func Read 

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

func ReadCompatibleJSON added in v0.1.16 

func ReadCompatibleJSON(reader io.Reader, 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

TODO: use Node instead

func ToYAMLDocumentNode 

func ToYAMLDocumentNode(value Value, verbose bool) *yaml.Node

func ToYAMLNode 

func ToYAMLNode(value Value, verbose bool) *yaml.Node

func ValueToString 

func ValueToString(data Value) string

Types

type CompatibleJSONBytes added in v0.1.15 

type CompatibleJSONBytes []byte

func (CompatibleJSONBytes) MarshalJSON added in v0.1.15 

func (self CompatibleJSONBytes) MarshalJSON() ([]byte, error)

json.Marshaler interface

type CompatibleJSONInteger added in v0.1.15 

type CompatibleJSONInteger int64

func (CompatibleJSONInteger) MarshalJSON added in v0.1.15 

func (self CompatibleJSONInteger) MarshalJSON() ([]byte, error)

json.Marshaler interface

type CompatibleJSONMap added in v0.1.15 

type CompatibleJSONMap Map

func (CompatibleJSONMap) MarshalJSON added in v0.1.15 

func (self CompatibleJSONMap) MarshalJSON() ([]byte, error)

json.Marshaler interface

type CompatibleJSONMapEntry added in v0.1.15 

type CompatibleJSONMapEntry struct {
	Key   Value `json:"key"`
	Value Value `json:"value"`
}

func DecodeCompatibleJSONMapEntry added in v0.1.15 

func DecodeCompatibleJSONMapEntry(entry Value) (*CompatibleJSONMapEntry, bool)

type CompatibleJSONUInteger added in v0.1.15 

type CompatibleJSONUInteger uint64

func (CompatibleJSONUInteger) MarshalJSON added in v0.1.15 

func (self CompatibleJSONUInteger) MarshalJSON() ([]byte, error)

json.Marshaler interface

type List 

type List = []Value

type Locator 

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

type Map 

type Map = map[Value]Value

func DecodeCompatibleJSONMap added in v0.1.15 

func DecodeCompatibleJSONMap(code StringMap) (Map, bool)

func EnsureMaps 

func EnsureMaps(map_ Value) Map

func ToMap 

func ToMap(stringMap StringMap) Map

type Node 

type Node struct {
	Data interface{}
	// contains filtered or unexported fields
}

func NewNode 

func NewNode(data interface{}) *Node

func (*Node) Append 

func (self *Node) Append(value interface{}) bool

func (*Node) Boolean 

func (self *Node) Boolean(allowNil bool) (bool, bool)

func (*Node) Float 

func (self *Node) Float(allowNil bool) (float64, bool)

func (*Node) Get 

func (self *Node) Get(key string) *Node

func (*Node) Integer 

func (self *Node) Integer(allowNil bool) (int64, bool)

func (*Node) List 

func (self *Node) List(allowNil bool) (List, bool)

func (*Node) Map 

func (self *Node) Map(allowNil bool) (Map, bool)

func (*Node) Put 

func (self *Node) Put(key string, value interface{}) bool

func (*Node) String 

func (self *Node) String(allowNil bool) (string, bool)

func (*Node) StringMap 

func (self *Node) StringMap(allowNil bool) (StringMap, bool)

func (*Node) UnsignedInteger 

func (self *Node) UnsignedInteger(allowNil bool) (uint64, bool)

type Path 

type Path []PathElement

func (Path) Append 

func (self Path) Append(element PathElement) Path

func (Path) AppendField 

func (self Path) AppendField(name string) Path

func (Path) AppendList 

func (self Path) AppendList(index int) Path

func (Path) AppendMap 

func (self Path) AppendMap(name string) Path

func (Path) AppendSequencedList 

func (self Path) AppendSequencedList(index int) Path

func (Path) String 

func (self Path) String() string

fmt.Stringer interface

type PathElement 

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

func NewFieldPathElement 

func NewFieldPathElement(name string) PathElement

func NewListPathElement 

func NewListPathElement(index int) PathElement

func NewMapPathElement 

func NewMapPathElement(name string) PathElement

func NewSequencedListPathElement 

func NewSequencedListPathElement(index int) PathElement

type PathElementType 

type PathElementType uint8

type StringMap 

type StringMap = map[string]Value

func EnsureStringMaps 

func EnsureStringMaps(map_ Value) StringMap

func ToStringMap 

func ToStringMap(map_ Map) StringMap

type TypeName 

type TypeName string
const (
	NoType TypeName = ""

	// Failsafe schema: https://yaml.org/spec/1.2/spec.html#id2802346
	TypeMap    TypeName = "ard.map"
	TypeList   TypeName = "ard.list"
	TypeString TypeName = "ard.string"

	// JSON schema: https://yaml.org/spec/1.2/spec.html#id2803231
	TypeBoolean TypeName = "ard.boolean"
	TypeInteger TypeName = "ard.integer"
	TypeFloat   TypeName = "ard.float"

	// Other schemas: https://yaml.org/spec/1.2/spec.html#id2805770
	TypeNull      TypeName = "ard.null"
	TypeTimestamp TypeName = "ard.timestamp"
)

func GetTypeName 

func GetTypeName(value Value) TypeName

type TypeValidator 

type TypeValidator = func(Value) bool

type Value 

type Value = interface{}

func Copy 

func Copy(value Value) Value

func FromCompatibleJSON added in v0.1.15 

func FromCompatibleJSON(value Value) Value

func ToCompatibleJSON added in v0.1.15 

func ToCompatibleJSON(value Value) Value

func ToMaps 

func ToMaps(value Value) (Value, bool)

func ToStringMaps 

func ToStringMaps(value Value) (Value, bool)

func TryFromCompatibleJSON added in v0.1.15 

func TryFromCompatibleJSON(value Value) (Value, bool)

func TryToCompatibleJSON added in v0.1.15 

func TryToCompatibleJSON(value Value) (Value, 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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.