Documentation ¶
Index ¶
- Constants
- Variables
- type ErrNoSuchField
- type Kind
- type Maybe
- type StructField
- type StructRepresentation
- type StructRepresentation_Map
- type StructRepresentation_StringJoin
- type StructRepresentation_StringPairs
- type StructRepresentation_Tuple
- type Type
- type TypeBool
- type TypeBytes
- type TypeEnum
- type TypeFloat
- type TypeInt
- type TypeLink
- type TypeList
- type TypeMap
- type TypeName
- type TypeString
- type TypeStruct
- type TypeSystem
- type TypeUnion
- type TypedLinkNode
- type TypedNode
- type UnionStyle
Constants ¶
const ( Maybe_Value = Maybe(0) Maybe_Null = Maybe(1) Maybe_Absent = Maybe(2) )
Variables ¶
var ( UnionStyle_Kinded = UnionStyle{"kinded"} UnionStyle_Keyed = UnionStyle{"keyed"} UnionStyle_Envelope = UnionStyle{"envelope"} UnionStyle_Inline = UnionStyle{"inline"} )
Functions ¶
This section is empty.
Types ¶
type ErrNoSuchField ¶ added in v0.0.2
ErrNoSuchField may be returned from lookup functions on the Node interface when a field is requested which doesn't exist, or from Insert on a MapBuilder when a key doesn't match a field name in the structure.
func (ErrNoSuchField) Error ¶ added in v0.0.2
func (e ErrNoSuchField) Error() string
type Kind ¶
type Kind uint8
Kind is an enum of kind in the IPLD Schema system.
Note that schema.Kind is distinct from ipld.ReprKind! Schema kinds include concepts such as "struct" and "enum", which are concepts only introduced by the Schema layer, and not present in the Data Model layer.
func (Kind) ActsLike ¶
ActsLike returns a constant from the ipld.ReprKind enum describing what this schema.Kind acts like at the Data Model layer.
Things with similar names are generally conserved (e.g. "map" acts like "map"); concepts added by the schema layer have to be mapped onto something (e.g. "struct" acts like "map").
Note that this mapping describes how a typed Node will *act*, programmatically; it does not necessarily describe how it will be *serialized* (for example, a struct will always act like a map, even if it has a tuple representation strategy and thus becomes a list when serialized).
type StructField ¶
type StructField struct {
// contains filtered or unexported fields
}
func SpawnStructField ¶
func SpawnStructField(name string, typ Type, optional bool, nullable bool) StructField
func (StructField) IsNullable ¶
func (f StructField) IsNullable() bool
IsNullable returns true if the field value is allowed to be null.
If is Nullable is false, note that it's still possible that the field value will be absent if the field is Optional! Being nullable is unrelated to whether the field's presence is optional as a whole.
Note that a field may be both nullable and optional simultaneously, or either, or neither.
func (StructField) IsOptional ¶
func (f StructField) IsOptional() bool
IsOptional returns true if the field is allowed to be absent from the object. If IsOptional is false, the field may be absent from the serial representation of the object entirely.
Note being optional is different than saying the value is permitted to be null! A field may be both nullable and optional simultaneously, or either, or neither.
func (StructField) Name ¶
func (f StructField) Name() string
Name returns the string name of this field. The name is the string that will be used as a map key if the structure this field is a member of is serialized as a map representation.
func (StructField) Type ¶
func (f StructField) Type() Type
Type returns the Type of this field's value. Note the field may also be unset if it is either Optional or Nullable.
type StructRepresentation ¶
type StructRepresentation interface {
// contains filtered or unexported methods
}
type StructRepresentation_Map ¶
type StructRepresentation_Map struct {
// contains filtered or unexported fields
}
func (StructRepresentation_Map) GetFieldKey ¶ added in v0.0.2
func (r StructRepresentation_Map) GetFieldKey(field StructField) string
type StructRepresentation_StringJoin ¶
type StructRepresentation_StringJoin struct {
// contains filtered or unexported fields
}
type StructRepresentation_StringPairs ¶
type StructRepresentation_StringPairs struct {
// contains filtered or unexported fields
}
type StructRepresentation_Tuple ¶
type StructRepresentation_Tuple struct{}
type Type ¶
type Type interface { // Returns a pointer to the TypeSystem this Type is a member of. TypeSystem() *TypeSystem // Returns the string name of the Type. This name is unique within the // universe this type is a member of, *unless* this type is Anonymous, // in which case a string describing the type will still be returned, but // that string will not be required to be unique. Name() TypeName // Returns the Kind of this Type. // // The returned value is a 1:1 association with which of the concrete // "schema.Type*" structs this interface can be cast to. // // Note that a schema.Kind is a different enum than ipld.ReprKind; // and furthermore, there's no strict relationship between them. // schema.TypedNode values can be described by *two* distinct ReprKinds: // one which describes how the Node itself will act, // and another which describes how the Node presents for serialization. // For some combinations of Type and representation strategy, one or both // of the ReprKinds can be determined statically; but not always: // it can sometimes be necessary to inspect the value quite concretely // (e.g., `schema.TypedNode{}.Representation().ReprKind()`) in order to find // out exactly how a node will be serialized! This is because some types // can vary in representation kind based on their value (specifically, // kinded-representation unions have this property). Kind() Kind // contains filtered or unexported methods }
typesystem.Type is an union interface; each of the `Type*` concrete types in this package are one of its members.
Specifically,
TypeBool TypeString TypeBytes TypeInt TypeFloat TypeMap TypeList TypeLink TypeUnion TypeStruct TypeEnum
are all of the kinds of Type.
This is a closed union; you can switch upon the above members without including a default case. The membership is closed by the unexported '_Type' method; you may use the BurntSushi/go-sumtype tool to check your switches for completeness.
Many interesting properties of each Type are only defined for that specific type, so it's typical to use a type switch to handle each type of Type. (Your humble author is truly sorry for the word-mash that results from attempting to describe the types that describe the typesystem.Type.)
For example, to inspect the kind of fields in a struct: you might cast a `Type` interface into `TypeStruct`, and then the `Fields()` on that `TypeStruct` can be inspected. (`Fields()` isn't defined for any other kind of Type.)
type TypeBool ¶
type TypeBool struct {
// contains filtered or unexported fields
}
func (TypeBool) TypeSystem ¶
func (t TypeBool) TypeSystem() *TypeSystem
type TypeBytes ¶
type TypeBytes struct {
// contains filtered or unexported fields
}
func SpawnBytes ¶ added in v0.0.2
func (TypeBytes) TypeSystem ¶
func (t TypeBytes) TypeSystem() *TypeSystem
type TypeEnum ¶
type TypeEnum struct {
// contains filtered or unexported fields
}
func (TypeEnum) Members ¶
Members returns a slice the strings which are valid inhabitants of this enum.
func (TypeEnum) TypeSystem ¶
func (t TypeEnum) TypeSystem() *TypeSystem
type TypeFloat ¶
type TypeFloat struct {
// contains filtered or unexported fields
}
func (TypeFloat) TypeSystem ¶
func (t TypeFloat) TypeSystem() *TypeSystem
type TypeInt ¶
type TypeInt struct {
// contains filtered or unexported fields
}
func (TypeInt) TypeSystem ¶
func (t TypeInt) TypeSystem() *TypeSystem
type TypeLink ¶
type TypeLink struct {
// contains filtered or unexported fields
}
func SpawnLinkReference ¶ added in v0.0.2
func (TypeLink) HasReferencedType ¶ added in v0.0.2
HasReferencedType returns true if the link has a hint about the type it references false if it's generic
func (TypeLink) ReferencedType ¶ added in v0.0.2
ReferencedType returns the type hint for the node on the other side of the link
func (TypeLink) TypeSystem ¶
func (t TypeLink) TypeSystem() *TypeSystem
type TypeList ¶
type TypeList struct {
// contains filtered or unexported fields
}
func (TypeList) IsAnonymous ¶
IsAnonymous is returns true if the type was unnamed. Unnamed types will claim to have a Name property like `[Foo]`, and this is not guaranteed to be a unique string for all types in the universe.
func (TypeList) TypeSystem ¶
func (t TypeList) TypeSystem() *TypeSystem
func (TypeList) ValueIsNullable ¶
ValueIsNullable returns a bool describing if the list values are permitted to be null.
type TypeMap ¶
type TypeMap struct {
// contains filtered or unexported fields
}
func (TypeMap) IsAnonymous ¶
IsAnonymous is returns true if the type was unnamed. Unnamed types will claim to have a Name property like `{Foo:Bar}`, and this is not guaranteed to be a unique string for all types in the universe.
func (TypeMap) KeyType ¶
KeyType returns the Type of the map keys.
Note that map keys will must always be some type which is representable as a string in the IPLD Data Model (e.g. either TypeString or TypeEnum).
func (TypeMap) TypeSystem ¶
func (t TypeMap) TypeSystem() *TypeSystem
func (TypeMap) ValueIsNullable ¶
ValueIsNullable returns a bool describing if the map values are permitted to be null.
type TypeString ¶
type TypeString struct {
// contains filtered or unexported fields
}
func SpawnString ¶
func SpawnString(name TypeName) TypeString
func (TypeString) Kind ¶
func (TypeString) Kind() Kind
func (TypeString) TypeSystem ¶
func (t TypeString) TypeSystem() *TypeSystem
type TypeStruct ¶
type TypeStruct struct {
// contains filtered or unexported fields
}
func SpawnStruct ¶
func SpawnStruct(name TypeName, fields []StructField, repr StructRepresentation) TypeStruct
func (TypeStruct) Field ¶ added in v0.0.2
func (t TypeStruct) Field(name string) *StructField
Field looks up a StructField by name, or returns nil if no such field.
func (TypeStruct) Fields ¶
func (t TypeStruct) Fields() []StructField
Fields returns a slice of descriptions of the object's fields.
func (TypeStruct) Kind ¶
func (TypeStruct) Kind() Kind
func (TypeStruct) RepresentationStrategy ¶ added in v0.0.2
func (t TypeStruct) RepresentationStrategy() StructRepresentation
func (TypeStruct) TypeSystem ¶
func (t TypeStruct) TypeSystem() *TypeSystem
type TypeSystem ¶
type TypeSystem struct {
// contains filtered or unexported fields
}
type TypeUnion ¶
type TypeUnion struct {
// contains filtered or unexported fields
}
func (TypeUnion) TypeSystem ¶
func (t TypeUnion) TypeSystem() *TypeSystem
func (TypeUnion) UnionMembers ¶
UnionMembers returns a set of all the types that can inhabit this Union.
type TypedLinkNode ¶ added in v0.0.2
type TypedLinkNode interface {
LinkTargetNodeStyle() ipld.NodeStyle
}
schema.TypedLinkNode is a superset of the schema.TypedNode interface, and has one additional behavior.
A schema.TypedLinkNode contains a hint for the appropriate node builder to use for loading data on the other side of the link contained within the node, so that it can be assembled into a node representation and validated against the schema as quickly as possible
So, for example, if you wanted to support loading the other side of a link with a code-gen'd node builder while utilizing the automatic loading facilities of the traversal package, you could write a LinkNodeBuilderChooser as follows:
func LinkNodeBuilderChooser(lnk ipld.Link, lnkCtx ipld.LinkContext) ipld.NodeStyle { if tlnkNd, ok := lnkCtx.LinkNode.(schema.TypedLinkNode); ok { return tlnkNd.LinkTargetNodeStyle() } return basicnode.Style__Any{} }
type TypedNode ¶ added in v0.0.2
type TypedNode interface { // schema.TypedNode acts just like a regular Node for almost all purposes; // which ipld.ReprKind it acts as is determined by the TypeKind. // (Note that the representation strategy of the type does *not* affect // the ReprKind of schema.TypedNode -- rather, the representation strategy // affects the `.Representation().ReprKind()`.) // // For example: if the `.Type().Kind()` of this node is "struct", // it will act like ReprKind() == "map" // (even if Type().(Struct).ReprStrategy() is "tuple"). ipld.Node // Type returns a reference to the reified schema.Type value. Type() Type // Representation returns an ipld.Node which sees the data in this node // in its representation form. // // For example: if the `.Type().Kind()` of this node is "struct", // `.Representation().Kind()` may vary based on its representation strategy: // if the representation strategy is "map", then it will be ReprKind=="map"; // if the streatgy is "tuple", then it will be ReprKind=="list". Representation() ipld.Node }
schema.TypedNode is a superset of the ipld.Node interface, and has additional behaviors.
A schema.TypedNode can be inspected for its schema.Type and schema.Kind, which conveys much more and richer information than the Data Model layer ipld.ReprKind.
There are many different implementations of schema.TypedNode. One implementation can wrap any other existing ipld.Node (i.e., it's zero-copy) and promises that it has *already* been validated to match the typesystem.Type; another implementation similarly wraps any other existing ipld.Node, but defers to the typesystem validation checking to fields that are accessed; and when using code generation tools, all of the generated native Golang types produced by the codegen will each individually implement schema.TypedNode.
Typed nodes sometimes have slightly different behaviors than plain nodes: For example, when looking up fields on a typed node that's a struct, the error returned for a lookup with a key that's not a field name will be ErrNoSuchField (instead of ErrNotExists). These behaviors apply to the schema.TypedNode only and not their representations; continuing the example, the .Representation().LookupString() method on that same node for the same key as plain `.LookupString()` will still return ErrNotExists, because the representation isn't a schema.TypedNode!
type UnionStyle ¶
type UnionStyle struct {
// contains filtered or unexported fields
}
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
gen
|
|
The `schema/tests` package contains behavioral tests for type-constrained Node implementations -- meant to work with either codegenerated Nodes OR with the runtime schema.TypedNode wrappers, checking for the same behavior on each.
|
The `schema/tests` package contains behavioral tests for type-constrained Node implementations -- meant to work with either codegenerated Nodes OR with the runtime schema.TypedNode wrappers, checking for the same behavior on each. |