schema

package
v0.0.4 Latest Latest
Warning

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

Go to latest
Published: Aug 28, 2021 License: MIT Imports: 2 Imported by: 3

Documentation

Index

Constants

View Source
const (
	Maybe_Absent = Maybe(0)
	Maybe_Null   = Maybe(1)
	Maybe_Value  = Maybe(2)
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ErrNoSuchField

type ErrNoSuchField struct {
	Type Type

	Field ld.PathSegment
}

ErrNoSuchField may be returned from lookup functions on the Node interface when a field is requested which doesn't exist, or from assigning data into on a MapAssembler for a struct when the key doesn't match a field name in the structure (or, when assigning data into a ListAssembler and the list size has reached out of bounds, in case of a struct with list-like representations!).

func (ErrNoSuchField) Error

func (e ErrNoSuchField) Error() string

type ErrNotUnionStructure

type ErrNotUnionStructure struct {
	TypeName string

	Detail string
}

ErrNotUnionStructure means data was fed into a union assembler that can't match the union.

This could have one of several reasons, which are explained in the detail text:

  • there are too many entries in the map;
  • the keys of critical entries aren't found;
  • keys are found that aren't any of the expected critical keys;
  • etc.

TypeName is currently a string... see comments at the top of this file for remarks on the issues we need to address about these identifiers in errors in general.

func (ErrNotUnionStructure) Error

func (e ErrNotUnionStructure) Error() string

type ImplicitValue

type ImplicitValue interface {
	// contains filtered or unexported methods
}

ImplicitValue is an sum type holding values that are implicits. It's not an 'Any' value because it can't be recursive (or to be slightly more specific, it can be one of the recursive kinds, but if so, only its empty value is valid here).

type ImplicitValue_EmptyList

type ImplicitValue_EmptyList struct{}

type ImplicitValue_EmptyMap

type ImplicitValue_EmptyMap struct{}

type ImplicitValue_Int

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

type ImplicitValue_String

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

type Maybe

type Maybe uint8

type StructField

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

func SpawnStructField

func SpawnStructField(name string, typ TypeName, optional bool, nullable bool) StructField

func (StructField) IsMaybe

func (f StructField) IsMaybe() bool

IsMaybe returns true if the field value is allowed to be either null or absent.

This is a simple "or" of the two properties, but this method is a shorthand that turns out useful often.

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) Parent

func (f StructField) Parent() *TypeStruct

Parent returns the type information that this field describes a part of.

While in many cases, you may know the parent already from context, there may still be situations where want to pass around a field and not need to continue passing down the parent type with it; this method helps your code be less redundant in such a situation. (You'll find this useful for looking up any rename directives, for example, when holding onto a field, since that requires looking up information from the representation strategy, which is a property of the type as a whole.)

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 SpawnStructRepresentationMap

func SpawnStructRepresentationMap(renames map[string]string) StructRepresentation_Map

func (StructRepresentation_Map) FieldHasRename

func (r StructRepresentation_Map) FieldHasRename(field StructField) bool

func (StructRepresentation_Map) GetFieldKey

func (r StructRepresentation_Map) GetFieldKey(field StructField) string

type StructRepresentation_StringPairs

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

type StructRepresentation_Stringjoin

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

func SpawnStructRepresentationStringjoin

func SpawnStructRepresentationStringjoin(delim string) StructRepresentation_Stringjoin

func (StructRepresentation_Stringjoin) GetDelim

type StructRepresentation_Tuple

type StructRepresentation_Tuple struct{}

func SpawnStructRepresentationTuple

func SpawnStructRepresentationTuple() StructRepresentation_Tuple

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 TypeKind 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.TypeKind is a different enum than ld.Kind;
	// and furthermore, there's no strict relationship between them.
	// schema.TypedNode values can be described by *two* distinct Kinds:
	// 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 Kinds can be determined statically; but not always:
	// it can sometimes be necessary to inspect the value quite concretely
	// (e.g., `schema.TypedNode{}.Representation().Kind()`) 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).
	TypeKind() TypeKind

	// RepresentationBehavior returns a description of how the representation
	// of this type will behave in terms of the LD Data Model.
	// This property varies based on the representation strategy of a type.
	//
	// In one case, the representation behavior cannot be known statically,
	// and varies based on the data: kinded unions have this trait.
	//
	// This property is used by kinded unions, which require that their members
	// all have distinct representation behavior.
	// (It follows that a kinded union cannot have another kinded union as a member.)
	//
	// You may also be interested in a related property that might have been called "TypeBehavior".
	// However, this method doesn't exist, because it's a deterministic property of `TypeKind()`!
	// You can use `TypeKind.ActsLike()` to get type-level behavioral information.
	RepresentationBehavior() ld.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 SpawnBool

func SpawnBool(name TypeName) *TypeBool

func (TypeBool) Name

func (t TypeBool) Name() TypeName

func (TypeBool) RepresentationBehavior

func (TypeBool) RepresentationBehavior() ld.Kind

func (TypeBool) TypeKind

func (TypeBool) TypeKind() TypeKind

func (TypeBool) TypeSystem

func (t TypeBool) TypeSystem() *TypeSystem

type TypeBytes

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

func SpawnBytes

func SpawnBytes(name TypeName) *TypeBytes

func (TypeBytes) Name

func (t TypeBytes) Name() TypeName

func (TypeBytes) RepresentationBehavior

func (TypeBytes) RepresentationBehavior() ld.Kind

func (TypeBytes) TypeKind

func (TypeBytes) TypeKind() TypeKind

func (TypeBytes) TypeSystem

func (t TypeBytes) TypeSystem() *TypeSystem

type TypeEnum

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

func (TypeEnum) Members

func (t TypeEnum) Members() []string

Members returns a slice the strings which are valid inhabitants of this enum.

func (TypeEnum) Name

func (t TypeEnum) Name() TypeName

func (TypeEnum) RepresentationBehavior

func (t TypeEnum) RepresentationBehavior() ld.Kind

func (TypeEnum) TypeKind

func (TypeEnum) TypeKind() TypeKind

func (TypeEnum) TypeSystem

func (t TypeEnum) TypeSystem() *TypeSystem

type TypeFloat

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

func SpawnFloat

func SpawnFloat(name TypeName) *TypeFloat

func (TypeFloat) Name

func (t TypeFloat) Name() TypeName

func (TypeFloat) RepresentationBehavior

func (TypeFloat) RepresentationBehavior() ld.Kind

func (TypeFloat) TypeKind

func (TypeFloat) TypeKind() TypeKind

func (TypeFloat) TypeSystem

func (t TypeFloat) TypeSystem() *TypeSystem

type TypeInt

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

func SpawnInt

func SpawnInt(name TypeName) *TypeInt

func (TypeInt) Name

func (t TypeInt) Name() TypeName

func (TypeInt) RepresentationBehavior

func (TypeInt) RepresentationBehavior() ld.Kind

func (TypeInt) TypeKind

func (TypeInt) TypeKind() TypeKind

func (TypeInt) TypeSystem

func (t TypeInt) TypeSystem() *TypeSystem

type TypeKind

type TypeKind uint8

TypeKind is an enum of kind in the LD Schema system.

Note that schema.TypeKind is distinct from ld.Kind! 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.

const (
	TypeKind_Invalid TypeKind = 0
	TypeKind_Map     TypeKind = '{'
	TypeKind_List    TypeKind = '['
	TypeKind_Unit    TypeKind = '1'
	TypeKind_Bool    TypeKind = 'b'
	TypeKind_Int     TypeKind = 'i'
	TypeKind_Float   TypeKind = 'f'
	TypeKind_String  TypeKind = 's'
	TypeKind_Bytes   TypeKind = 'x'
	TypeKind_Link    TypeKind = '/'
	TypeKind_Struct  TypeKind = '$'
	TypeKind_Union   TypeKind = '^'
	TypeKind_Enum    TypeKind = '%'
)

func (TypeKind) ActsLike

func (k TypeKind) ActsLike() ld.Kind

ActsLike returns a constant from the ld.Kind enum describing what this schema.TypeKind 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).

func (TypeKind) String

func (k TypeKind) String() string
type TypeLink struct {
	// contains filtered or unexported fields
}
func SpawnLink(name TypeName) *TypeLink

func SpawnLinkReference

func SpawnLinkReference(name TypeName, pointsTo TypeName) *TypeLink

func (TypeLink) HasReferencedType

func (t TypeLink) HasReferencedType() bool

HasReferencedType returns true if the link has a hint about the type it references false if it's generic

func (TypeLink) Name

func (t TypeLink) Name() TypeName

func (TypeLink) ReferencedType

func (t TypeLink) ReferencedType() Type

ReferencedType returns the type hint for the node on the other side of the link

func (TypeLink) RepresentationBehavior

func (TypeLink) RepresentationBehavior() ld.Kind

func (TypeLink) TypeKind

func (TypeLink) TypeKind() TypeKind

func (TypeLink) TypeSystem

func (t TypeLink) TypeSystem() *TypeSystem

type TypeList

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

func SpawnList

func SpawnList(name TypeName, valueType TypeName, nullable bool) *TypeList

func (TypeList) IsAnonymous

func (t TypeList) IsAnonymous() bool

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) Name

func (t TypeList) Name() TypeName

func (TypeList) RepresentationBehavior

func (TypeList) RepresentationBehavior() ld.Kind

func (TypeList) TypeKind

func (TypeList) TypeKind() TypeKind

func (TypeList) TypeSystem

func (t TypeList) TypeSystem() *TypeSystem

func (TypeList) ValueIsNullable

func (t TypeList) ValueIsNullable() bool

ValueIsNullable returns a bool describing if the list values are permitted to be null.

func (TypeList) ValueType

func (t TypeList) ValueType() Type

ValueType returns to the Type of the list values.

type TypeMap

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

func SpawnMap

func SpawnMap(name TypeName, keyType TypeName, valueType TypeName, nullable bool) *TypeMap

func (TypeMap) IsAnonymous

func (t TypeMap) IsAnonymous() bool

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

func (t TypeMap) KeyType() Type

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 LD Data Model (e.g. either TypeString or TypeEnum).

func (TypeMap) Name

func (t TypeMap) Name() TypeName

func (TypeMap) RepresentationBehavior

func (TypeMap) RepresentationBehavior() ld.Kind

func (TypeMap) TypeKind

func (TypeMap) TypeKind() TypeKind

func (TypeMap) TypeSystem

func (t TypeMap) TypeSystem() *TypeSystem

func (TypeMap) ValueIsNullable

func (t TypeMap) ValueIsNullable() bool

ValueIsNullable returns a bool describing if the map values are permitted to be null.

func (TypeMap) ValueType

func (t TypeMap) ValueType() Type

ValueType returns the Type of the map values.

type TypeName

type TypeName string // = ast.TypeName

func (TypeName) String

func (tn TypeName) String() string

type TypeString

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

func SpawnString

func SpawnString(name TypeName) *TypeString

func (TypeString) Name

func (t TypeString) Name() TypeName

func (TypeString) RepresentationBehavior

func (TypeString) RepresentationBehavior() ld.Kind

func (TypeString) TypeKind

func (TypeString) TypeKind() TypeKind

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

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) Name

func (t TypeStruct) Name() TypeName

func (TypeStruct) RepresentationBehavior

func (t TypeStruct) RepresentationBehavior() ld.Kind

func (TypeStruct) RepresentationStrategy

func (t TypeStruct) RepresentationStrategy() StructRepresentation

func (TypeStruct) TypeKind

func (TypeStruct) TypeKind() TypeKind

func (TypeStruct) TypeSystem

func (t TypeStruct) TypeSystem() *TypeSystem

type TypeSystem

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

func (*TypeSystem) Accumulate

func (ts *TypeSystem) Accumulate(typ Type)

func (TypeSystem) GetTypes

func (ts TypeSystem) GetTypes() map[TypeName]Type

func (*TypeSystem) Init

func (ts *TypeSystem) Init()

func (TypeSystem) TypeByName

func (ts TypeSystem) TypeByName(n string) Type

func (TypeSystem) ValidateGraph

func (ts TypeSystem) ValidateGraph() []error

ValidateGraph checks that all type names referenced are defined.

It does not do any other validations of individual type's sensibleness (that should've happened when they were created (although also note many of those validates are NYI, and are roadmapped for after we research self-hosting)).

type TypeUnion

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

func SpawnUnion

func SpawnUnion(name TypeName, members []TypeName, repr UnionRepresentation) *TypeUnion

func (TypeUnion) Members

func (t TypeUnion) Members() []Type

Members returns the list of all types that are possible inhabitants of this union.

func (TypeUnion) Name

func (t TypeUnion) Name() TypeName

func (TypeUnion) RepresentationBehavior

func (t TypeUnion) RepresentationBehavior() ld.Kind

func (TypeUnion) RepresentationStrategy

func (t TypeUnion) RepresentationStrategy() UnionRepresentation

func (TypeUnion) TypeKind

func (TypeUnion) TypeKind() TypeKind

func (TypeUnion) TypeSystem

func (t TypeUnion) TypeSystem() *TypeSystem

type TypedLinkNode

type TypedLinkNode interface {
	LinkTargetNodePrototype() ld.NodePrototype
}

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 ld.Link, lnkCtx ld.LinkContext) ld.NodePrototype {
	if tlnkNd, ok := lnkCtx.LinkNode.(schema.TypedLinkNode); ok {
		return tlnkNd.LinkTargetNodePrototype()
	}
	return basicnode.Prototype__Any{}
}

type TypedNode

type TypedNode interface {
	// schema.TypedNode acts just like a regular Node for almost all purposes;
	// which ld.Kind it acts as is determined by the TypeKind.
	// (Note that the representation strategy of the type does *not* affect
	// the Kind of schema.TypedNode -- rather, the representation strategy
	// affects the `.Representation().Kind()`.)
	//
	// For example: if the `.Type().TypeKind()` of this node is "struct",
	// it will act like Kind() == "map"
	// (even if Type().(Struct).ReprStrategy() is "tuple").
	ld.Node

	// Type returns a reference to the reified schema.Type value.
	Type() Type

	// Representation returns an ld.Node which sees the data in this node
	// in its representation form.
	//
	// For example: if the `.Type().TypeKind()` of this node is "struct",
	// `.Representation().TypeKind()` may vary based on its representation strategy:
	// if the representation strategy is "map", then it will be Kind=="map";
	// if the streatgy is "tuple", then it will be Kind=="list".
	Representation() ld.Node
}

schema.TypedNode is a superset of the ld.Node interface, and has additional behaviors.

A schema.TypedNode can be inspected for its schema.Type and schema.TypeKind, which conveys much more and richer information than the Data Model layer ld.Kind.

There are many different implementations of schema.TypedNode. One implementation can wrap any other existing ld.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 ld.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().LookupByString() method on that same node for the same key as plain `.LookupByString()` will still return ErrNotExists, because the representation isn't a schema.TypedNode!

type TypedPrototype

type TypedPrototype interface {
	ld.NodePrototype

	// Type returns a reference to the reified schema.Type value.
	Type() Type

	// Representation returns an ld.NodePrototype for the representation
	// form of the prototype.
	Representation() ld.NodePrototype
}

TypedPrototype is a superset of the ld.Nodeprototype interface, and has additional behaviors, much like TypedNode for ld.Node.

type UnionRepresentation

type UnionRepresentation interface {
	// contains filtered or unexported methods
}

type UnionRepresentation_Envelope

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

type UnionRepresentation_Inline

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

type UnionRepresentation_Keyed

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

func SpawnUnionRepresentationKeyed

func SpawnUnionRepresentationKeyed(table map[string]TypeName) UnionRepresentation_Keyed

func (UnionRepresentation_Keyed) GetDiscriminant

func (r UnionRepresentation_Keyed) GetDiscriminant(t Type) string

type UnionRepresentation_Kinded

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

func SpawnUnionRepresentationKinded

func SpawnUnionRepresentationKinded(table map[ld.Kind]TypeName) UnionRepresentation_Kinded

func (UnionRepresentation_Kinded) GetMember

func (r UnionRepresentation_Kinded) GetMember(k ld.Kind) TypeName

GetMember returns type info for the member matching the kind argument, or may return nil if that kind is not mapped to a member of this union.

type UnionRepresentation_Stringprefix

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

func SpawnUnionRepresentationStringprefix

func SpawnUnionRepresentationStringprefix(delim string, table map[string]TypeName) UnionRepresentation_Stringprefix

func (UnionRepresentation_Stringprefix) GetDelim

func (UnionRepresentation_Stringprefix) GetDiscriminant

func (r UnionRepresentation_Stringprefix) GetDiscriminant(t Type) string

Directories

Path Synopsis
gen
go

Jump to

Keyboard shortcuts

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