schemaspec

Documentation

Overview

Package schemaspec provides types designed to capture atlas schema elements, and create type-safe extensions to the configuration language. This package is designed to provide an intermediate representation between a serialized configuration language representation (Atlas HCL, JSON, YAML, etc.) and concrete representations that are created and handled by a specific driver.

The basic type that is handled in this package is schemaspec.Resource which is a generic container for resources described in Atlas configurations. A resource has a set of "Attr" instances associated with it, as well a a list of children schemaspec.Resource instances that can be associated with it.

Users of Atlas applications are expected to interface with this package via a configuration language package. For example, via the `schemahcl` package:

  schemahcl.Unmarshal([]byte(`
		table "users" {
			column "id" {
				type = "int"
			}
		}
 `), &someStruct{})

Applications working with the Atlas DDL are expected to extend the Atlas language by defining their own type structs that objects can be handled in a type-safe way. Resource objects provide the `As` method to read a resource into an extension struct, as well as a `Scan` method to read an extension struct back into a Resource.

The mapping between the extension struct fields and a Resource is done by placing tags on the extension struct field using the `spec` key in the tag. To specify that a field should be mapped to the corresponding Resource's `Name` specify ",name" to the tag value. For example,

type Point struct {
    ID string `spec:",name"`
    X  int    `spec:"x"
    Y  int    `spec:"y"
}

Would be able to capture a Resource defined in Atlas HCL as:

point "origin" {
	x = 100
	y = 200
}

Extension structs may implement the Remainer interface if they wish to store any attributes and children that are not matched by their tagged fields. As a convenience the package exports a DefaultExtension type that can be embedded to support this behavior.

Index

• func BoolVal(v Value) (bool, error)
• func Register(name string, ext interface{})
• func StrVal(v Value) (string, error)
• type Attr
  • func (a *Attr) Bool() (bool, error)
  • func (a *Attr) Bools() ([]bool, error)
  • func (a *Attr) Int() (int, error)
  • func (a *Attr) Int64() (int64, error)
  • func (a *Attr) Ref() (string, error)
  • func (a *Attr) String() (string, error)
  • func (a *Attr) Strings() ([]string, error)
• type DefaultExtension
  • func (d *DefaultExtension) Attr(name string) (*Attr, bool)
  • func (d *DefaultExtension) Remain() *Resource
• type ListValue
• type LiteralValue
• type Marshaler
• type MarshalerFunc
  • func (f MarshalerFunc) MarshalSpec(v interface{}) ([]byte, error)
• type RawExpr
• type Ref
• type Remainer
• type Resource
  • func (r *Resource) As(target interface{}) error
  • func (r *Resource) Attr(name string) (*Attr, bool)
  • func (r *Resource) FinalName() (string, error)
  • func (r *Resource) Resource(t string) (*Resource, bool)
  • func (r *Resource) Scan(ext interface{}) error
  • func (r *Resource) SetAttr(attr *Attr)
• type Type
• type TypeAttr
• type TypeSpec
  • func (s *TypeSpec) Attr(name string) (*TypeAttr, bool)
• type Unmarshaler
• type UnmarshalerFunc
  • func (f UnmarshalerFunc) UnmarshalSpec(data []byte, v interface{}) error
• type Value

Functions

func BoolVal

func BoolVal(v Value) (bool, error)

BoolVal returns the bool representation of v. If v is not a *LiteralValue it returns an error. If the raw string representation of v cannot be read as a bool, an error is returned as well.

func Register

func Register(name string, ext interface{})

Register records the type of ext in the global extension registry. If Register is called twice with the same name or if ext is nil, it panics.

func StrVal

func StrVal(v Value) (string, error)

StrVal returns the raw string representation of v. If v is not a *LiteralValue it returns an error. If the raw string representation of v cannot be read as a string by unquoting it, an error is returned as well.

Types

type Attr

type Attr struct {
	K string
	V Value
}

Attr is an attribute of a Resource.

func (*Attr) Bool

func (a *Attr) Bool() (bool, error)

Bool returns a boolean from the Value of the Attr. If The value is not a LiteralValue or the value cannot be converted to a boolean an error is returned.

func (*Attr) Bools

func (a *Attr) Bools() ([]bool, error)

Bools returns a slice of bools from the Value of the Attr. If The value is not a ListValue or its values cannot be converted to bools an error is returned.

func (*Attr) Int

func (a *Attr) Int() (int, error)

Int returns an int from the Value of the Attr. If The value is not a LiteralValue or the value cannot be converted to an integer an error is returned.

func (*Attr) Int64

func (a *Attr) Int64() (int64, error)

Int64 returns an int64 from the Value of the Attr. If The value is not a LiteralValue or the value cannot be converted to an integer an error is returned.

func (*Attr) Ref

func (a *Attr) Ref() (string, error)

Ref returns the string representation of the Attr. If the value is not a Ref or the value an error is returned.

func (*Attr) String

func (a *Attr) String() (string, error)

String returns a string from the Value of the Attr. If The value is not a LiteralValue an error is returned. String values are expected to be quoted. If the value is not properly quoted an error is returned.

func (*Attr) Strings

func (a *Attr) Strings() ([]string, error)

Strings returns a slice of strings from the Value of the Attr. If The value is not a ListValue or its values cannot be converted to strings an error is returned.

type DefaultExtension

type DefaultExtension struct {
	Extra Resource
}

DefaultExtension can be embedded in structs that need basic default behavior. For instance, DefaultExtension implements Remainer, and has a private *Resource field that can store additional attributes and children that do not match the structs fields.

func (*DefaultExtension) Attr

func (d *DefaultExtension) Attr(name string) (*Attr, bool)

Attr returns the Attr by the provided name and reports whether it was found.

func (*DefaultExtension) Remain

func (d *DefaultExtension) Remain() *Resource

Remain implements the Remainer interface.

type ListValue

type ListValue struct {
	V []Value
}

ListValue implements Value and represents a list of Values.

type LiteralValue

type LiteralValue struct {
	V string
}

LiteralValue implements Value and represents a literal value (string, number, etc.)

type Marshaler

type Marshaler interface {
	MarshalSpec(interface{}) ([]byte, error)
}

Marshaler is the interface implemented by types that can marshal objects into a valid Atlas DDL representation.

type MarshalerFunc

type MarshalerFunc func(interface{}) ([]byte, error)

MarshalerFunc is the function type that is implemented by the MarshalSpec method of the Marshaler interface.

func (MarshalerFunc) MarshalSpec

func (f MarshalerFunc) MarshalSpec(v interface{}) ([]byte, error)

MarshalSpec implements Marshaler.

type RawExpr

type RawExpr struct {
	X string
}

RawExpr implements Value and represents any raw expression.

type Ref

type Ref struct {
	V string
}

Ref implements Value and represents a reference to another Resource. The path to a Resource under the root Resource is expressed as "$<type>.<name>..." recursively. For example, a resource of type "table" that is named "users" and is a direct child of the root Resource's address shall be "$table.users". A child resource of that table of type "column" and named "id", shall be referenced as "$table.users.$column.id", and so on.

type Remainer

type Remainer interface {
	// Remain returns a resource representing any extra children and attributes
	// that are related to the struct but were not mapped to any of its fields.
	Remain() *Resource
}

Remainer is the interface that is implemented by types that can store additional attributes and children resources.

type Resource

type Resource struct {
	Name      string
	Qualifier string
	Type      string
	Attrs     []*Attr
	Children  []*Resource
}

Resource is a generic container for resources described in configurations.

func (*Resource) As

func (r *Resource) As(target interface{}) error

As reads the attributes and children resources of the resource into the target struct.

func (*Resource) Attr

func (r *Resource) Attr(name string) (*Attr, bool)

Attr returns the Attr by the provided name and reports whether it was found.

func (*Resource) FinalName

func (r *Resource) FinalName() (string, error)

FinalName returns the final name for the resource by examining the struct tags for the extension of the Resource's type. If no such extension is registered or the extension struct does not have a name field, an error is returned.

func (*Resource) Resource

func (r *Resource) Resource(t string) (*Resource, bool)

Resource returns the first child Resource by its type and reports whether it was found.

func (*Resource) Scan

func (r *Resource) Scan(ext interface{}) error

Scan reads the Extension into the Resource. Scan will override the Resource name or type if they are set for the extension.

func (*Resource) SetAttr

func (r *Resource) SetAttr(attr *Attr)

SetAttr sets the Attr on the Resource. If r is nil, a zero value Resource is initialized. If an Attr with the same key exists, it is replaced by attr.

type Type

type Type struct {
	T     string
	Attrs []*Attr
	IsRef bool
}

Type represents the type of the field in a schema.

type TypeAttr

type TypeAttr struct {
	// Name should be a snake_case of related the schema.Type struct field.
	Name     string
	Kind     reflect.Kind
	Required bool
}

TypeAttr describes an attribute of a TypeSpec, for example `varchar` fields can have a `size` attribute.

type TypeSpec

type TypeSpec struct {
	// Name is the identifier for the type in an Atlas DDL document.
	Name string

	// T is the database identifier for the type.
	T          string
	Attributes []*TypeAttr

	// RType is the reflect.Type of the schema.Type used to describe the TypeSpec.
	// This field is optional and used to determine the TypeSpec in cases where the
	// schema.Type does not have a `T` field.
	RType reflect.Type

	// Format is an optional formatting function.
	// If exists, it will be used instead the registry one.
	Format func(*Type) (string, error)
}

TypeSpec represents a specification for defining a Type.

func (*TypeSpec) Attr

func (s *TypeSpec) Attr(name string) (*TypeAttr, bool)

Attr returns a TypeAttr by name and reports if one was found.

type Unmarshaler

type Unmarshaler interface {
	UnmarshalSpec([]byte, interface{}) error
}

Unmarshaler is the interface implemented by types that can unmarshal an Atlas DDL representation into an object.

type UnmarshalerFunc

type UnmarshalerFunc func([]byte, interface{}) error

UnmarshalerFunc is the function type that is implemented by the UnmarshalSpec method of the Unmarshaler interface.

func (UnmarshalerFunc) UnmarshalSpec

func (f UnmarshalerFunc) UnmarshalSpec(data []byte, v interface{}) error

UnmarshalSpec implements Unmarshaler.

type Value

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

Value represents the value of an Attr.