ard

package

v0.1.4 Latest Latest Go to latest Published: Oct 26, 2020 License: Apache-2.0 Imports: 10 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/tliron/kutil

Links

Open Source Insights

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 YAML 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 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 string), ARD will lose some type information when translated into JSON.

This could be fixed if we extend JSON with some conventions for encoding extra types. See MongoDB Extended JSON for an example. Also, maps with complex keys could be encoded as key-value pair lists.

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
Variables
func Equals(a Value, b Value) bool
func FindYAMLNode(node *yaml.Node, path ...PathElement) *yaml.Node
func IsBoolean(value Value) bool
func IsFloat(value Value) bool
func IsInteger(value Value) bool
func IsList(value Value) bool
func IsMap(value Value) bool
func IsNull(value Value) bool
func IsString(value Value) bool
func IsTimestamp(value Value) bool
func MergeMaps(target Map, source Map, mergeLists bool)
func MergeStringMaps(target StringMap, source StringMap, mergeLists bool)
func Read(reader io.Reader, format string, 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 ToYAMLDocumentNode(value Value, verbose bool) *yaml.Node
func ToYAMLNode(value Value, verbose bool) *yaml.Node
func ValueToString(data Value) string
type List
type Locator
type Map
- func EnsureMaps(map_ Value) Map
- func ToMap(stringMap StringMap) Map
type Node
- func NewNode(data interface{}) *Node
- func (self *Node) Append(value interface{}) bool
- func (self *Node) Boolean(allowNil bool) (bool, bool)
- func (self *Node) Float(allowNil bool) (float64, bool)
- func (self *Node) Get(key string) *Node
- func (self *Node) Integer(allowNil bool) (int64, bool)
- func (self *Node) List(allowNil bool) (List, bool)
- func (self *Node) Map(allowNil bool) (Map, bool)
- func (self *Node) Put(key string, value interface{}) bool
- func (self *Node) String(allowNil bool) (string, bool)
- func (self *Node) StringMap(allowNil bool) (StringMap, bool)
- func (self *Node) UnsignedInteger(allowNil bool) (uint64, bool)
type Path
- func (self Path) Append(element PathElement) Path
- func (self Path) AppendField(name string) Path
- func (self Path) AppendList(index int) Path
- func (self Path) AppendMap(name string) Path
- func (self Path) AppendSequencedList(index int) Path
- func (self Path) String() string
type PathElement
- func NewFieldPathElement(name string) PathElement
- func NewListPathElement(index int) PathElement
- func NewMapPathElement(name string) PathElement
- func NewSequencedListPathElement(index int) PathElement
type PathElementType
type StringMap
- func EnsureStringMaps(map_ Value) StringMap
- func ToStringMap(map_ Map) StringMap
type TypeName
- func GetTypeName(value Value) TypeName
type TypeValidator
type Value
- func Copy(value Value) Value
- func ToMaps(value Value) (Value, bool)
- func ToStringMaps(value Value) (Value, bool)
type YAMLLocator
- func NewYAMLLocator(rootNode *yaml.Node) *YAMLLocator
- func (self *YAMLLocator) Locate(path ...PathElement) (int, int, bool)

Constants ¶

View Source

const (
	FieldPathType = iota
	MapPathType
	ListPathType
	SequencedListPathType
)

Variables ¶

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 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 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 List ¶

type List = []Value

type Locator ¶

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

type Map ¶

type Map = map[Value]Value

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 ToMaps ¶

func ToMaps(value Value) (Value, bool)

func ToStringMaps ¶

func ToStringMaps(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

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL