schemahcl

package
v0.28.1 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2024 License: Apache-2.0 Imports: 30 Imported by: 16

Documentation

Index

Constants

View Source 
const (
	BlockData     = "data"
	BlockLocals   = "locals"
	BlockVariable = "variable"
	RefData       = "data"
	RefVar        = "var"
	RefLocal      = "local"
	AttrName      = "name"
)

Built-in blocks.

Variables

View Source 
var Marshal = MarshalerFunc(New().MarshalSpec)

Marshal returns the Atlas HCL encoding of v.

Functions

func MakeFileFunc added in v0.12.1 

func MakeFileFunc(base string) function.Function

MakeFileFunc returns a function that reads a file from the given base directory.

func MakeFileSetFunc added in v0.28.0 

func MakeFileSetFunc(base string) function.Function

MakeFileSetFunc returns a function that returns the names of all files matching pattern or nil if there is no matching file

func MakeGlobFunc added in v0.26.1 

func MakeGlobFunc(base string) function.Function

MakeGlobFunc returns a function that returns the names of all files matching pattern or nil if there is no matching file Deprecated: use fileset function instead.

func RawExprValue added in v0.8.2 

func RawExprValue(x *RawExpr) cty.Value

RawExprValue is a helper method for constructing a cty.Value that capsules a raw expression.

func RefValue added in v0.15.0 

func RefValue(v string) cty.Value

RefValue is a helper method for constructing a cty.Value that contains a Ref value.

func Register 

func Register(name string, ext any)

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 TypeValue added in v0.15.0 

func TypeValue(t *Type) cty.Value

TypeValue is a helper method for constructing a cty.Value that contains a Type value.

Types

type Attr 

type Attr struct {
	K string
	V cty.Value
	// contains filtered or unexported fields
}

Attr is an attribute of a Resource.

func BoolAttr added in v0.8.2 

func BoolAttr(k string, v bool) *Attr

BoolAttr is a helper method for constructing *schemahcl.Attr instances that contain a boolean value.

func Int64Attr added in v0.8.2 

func Int64Attr(k string, v int64) *Attr

Int64Attr is a helper method for constructing *schemahcl.Attr instances that contain int64 value.

func IntAttr added in v0.8.2 

func IntAttr(k string, v int) *Attr

IntAttr is a helper method for constructing *schemahcl.Attr instances that contain int64 value.

func RawAttr added in v0.8.2 

func RawAttr(k string, x string) *Attr

RawAttr is a helper method for constructing *schemahcl.Attr instances that contain RawExpr value.

func RefAttr added in v0.8.2 

func RefAttr(k string, v *Ref) *Attr

RefAttr is a helper method for constructing *schemahcl.Attr instances that contain a Ref value.

func RefsAttr added in v0.8.2 

func RefsAttr(k string, refs ...*Ref) *Attr

RefsAttr is a helper method for constructing *schemahcl.Attr instances that contain list references.

func StringAttr added in v0.8.2 

func StringAttr(k string, v string) *Attr

StringAttr is a helper method for constructing *schemahcl.Attr instances that contain string value.

func StringEnumsAttr added in v0.25.0 

func StringEnumsAttr(k string, elems ...*EnumString) *Attr

StringEnumsAttr is a helper method for constructing *schemahcl.Attr instances that contain list of elements that their values can be either enum or string.

func StringsAttr added in v0.8.2 

func StringsAttr(k string, vs ...string) *Attr

StringsAttr is a helper method for constructing *schemahcl.Attr instances that contain list strings.

func (*Attr) BigFloat added in v0.20.0 

func (a *Attr) BigFloat() (*big.Float, error)

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

func (*Attr) Bool 

func (a *Attr) Bool() (b bool, err 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() (vs []bool, err 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) Float64 added in v0.28.0 

func (a *Attr) Float64() (f float64, err error)

Float64 returns a float64 from the Value of the Attr. If The value is not a LiteralValue or the value cannot be converted to a float64 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() (i int64, err 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) IsRawExpr added in v0.8.2 

func (a *Attr) IsRawExpr() bool

IsRawExpr indicates if the attribute is a RawExpr type.

func (*Attr) IsRef added in v0.8.2 

func (a *Attr) IsRef() bool

IsRef indicates if the attribute is a reference type.

func (*Attr) IsType added in v0.8.2 

func (a *Attr) IsType() bool

IsType indicates if the attribute is a type spec.

func (*Attr) Range added in v0.24.0 

func (a *Attr) Range() *hcl.Range

Range returns the attribute range on the file, or nil if it is not set.

func (*Attr) RawExpr added in v0.8.2 

func (a *Attr) RawExpr() (*RawExpr, error)

RawExpr extracts the RawExpr from the Attr.

func (*Attr) Ref 

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

Ref extracts the reference from the Value of the Attr.

func (*Attr) Refs added in v0.6.5 

func (a *Attr) Refs() ([]*Ref, error)

Refs returns a slice of references.

func (*Attr) SetRange added in v0.24.0 

func (a *Attr) SetRange(p *hcl.Range)

SetRange sets the range of this attribute.

func (*Attr) String 

func (a *Attr) String() (s string, err 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() (vs []string, err 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.

func (*Attr) Type added in v0.8.2 

func (a *Attr) Type() (*Type, error)

Type extracts the Type from the Attr.

type BlockFunc added in v0.23.0 

type BlockFunc func(context.Context, *hcl.EvalContext, *hclsyntax.Block) (cty.Value, error)

BlockFunc is the function signature for evaluating a dynamic block.

type Config 

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

Config configures an unmarshaling.

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 EnumString added in v0.25.0 

type EnumString struct {
	E, S string // Enum or string value.
}

EnumString is a helper type that represents either an enum or a string value.

type EvalFunc 

type EvalFunc func(*hclparse.Parser, any, map[string]cty.Value) error

EvalFunc is an adapter that allows the use of an ordinary function as an Evaluator.

func (EvalFunc) Eval 

func (f EvalFunc) Eval(p *hclparse.Parser, i any, input map[string]cty.Value) error

Eval implements the Evaluator interface.

type Evaluator 

type Evaluator interface {
	// Eval evaluates parsed HCL files using input variables into a schema.Realm.
	Eval(*hclparse.Parser, any, map[string]cty.Value) error
}

Evaluator is the interface that wraps the Eval function.

type Marshaler 

type Marshaler interface {
	// MarshalSpec marshals the provided input into a valid Atlas HCL document.
	MarshalSpec(any) ([]byte, error)
}

Marshaler is the interface that wraps the MarshalSpec function.

type MarshalerFunc 

type MarshalerFunc func(any) ([]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 any) ([]byte, error)

MarshalSpec implements Marshaler.

type Option 

type Option func(*Config)

Option configures a Config.

func WithContext added in v0.23.0 

func WithContext(ctx context.Context) Option

WithContext allows passing a context to Eval stage. If provided, data source and type-block handlers will have access to this context.

func WithDataSource added in v0.8.0 

func WithDataSource(name string, h BlockFunc) Option

WithDataSource registers a data source name and its corresponding handler. e.g., the example below registers a data source named "text" that returns the string defined in the data source block. 

WithDataSource("text", func(ctx *hcl.EvalContext, b *hclsyntax.Block) (cty.Value, hcl.Diagnostics) {
	attrs, diags := b.Body.JustAttributes()
	if diags.HasErrors() {
		return cty.NilVal, diags
	}
	v, diags := attrs["value"].Expr.Value(ctx)
	if diags.HasErrors() {
		return cty.NilVal, diags
	}
	return cty.ObjectVal(map[string]cty.Value{"output": v}), nil
})

data "text" "hello" {
  value = "hello world"
}

func WithFunctions added in v0.12.0 

func WithFunctions(funcs map[string]function.Function) Option

WithFunctions registers a list of functions to be injected into the context.

func WithInitBlock added in v0.10.0 

func WithInitBlock(name string, h BlockFunc) Option

WithInitBlock registers a block that evaluates (first) to a cty.Value, has no labels, and can be defined only once. For example: 

WithInitBlock("atlas", func(ctx *hcl.EvalContext, b *hclsyntax.Block) (cty.Value, hcl.Diagnostics) {
	attrs, diags := b.Body.JustAttributes()
	if diags.HasErrors() {
		return cty.NilVal, diags
	}
	v, diags := attrs["modules"].Expr.Value(ctx)
	if diags.HasErrors() {
		return cty.NilVal, diags
	}
	return cty.ObjectVal(map[string]cty.Value{"modules": v}), nil
})

func WithPos added in v0.24.0 

func WithPos() Option

WithPos attaches parse positions to returned Resources and Attrs.

func WithSchemaValidator added in v0.13.0 

func WithSchemaValidator(v func() SchemaValidator) Option

WithSchemaValidator registers a schema validator to be used during unmarshaling.

func WithScopedEnums 

func WithScopedEnums[T interface{ ~string }](path string, enums ...T) Option

WithScopedEnums configured a list of allowed ENUMs to be used in the given context, block or attribute. For example, the following option allows setting HASH or BTREE to the "using" attribute in "index" block. 

WithScopedEnums("table.index.type", "HASH", "BTREE")

table "t" {
	...
	index "i" {
		type = HASH     // Allowed.
		type = INVALID  // Not Allowed.
	}
}

func WithTypeLabelBlock added in v0.16.0 

func WithTypeLabelBlock(name, label string, h BlockFunc) Option

WithTypeLabelBlock registers a type-block and its label along with the corresponding handler. e.g., the example below registers a typed block named "driver" with the label "remote" that returns the string defined in the token attribute. 

WithTypeLabelBlock("driver", "remote", func(ctx *hcl.EvalContext, b *hclsyntax.Block) (cty.Value, hcl.Diagnostics) {
	attrs, diags := b.Body.JustAttributes()
	if diags.HasErrors() {
		return cty.NilVal, diags
	}
	v, diags := attrs["token"].Expr.Value(ctx)
	if diags.HasErrors() {
		return cty.NilVal, diags
	}
	return cty.ObjectVal(map[string]cty.Value{"url": v}), nil
})

driver "remote" "hello" {
  token = "hello world"
}

func WithTypes 

func WithTypes(path string, typeSpecs []*TypeSpec) Option

WithTypes configures the given types as identifiers in the unmarshal context. The path controls where the usage of this type is allowed.

func WithVariables added in v0.9.1 

func WithVariables(vars map[string]cty.Value) Option

WithVariables registers a list of variables to be injected into the context.

type PathIndex added in v0.9.0 

type PathIndex struct {
	T string   // type
	V []string // identifiers
}

PathIndex represents an index in a reference path.

func (*PathIndex) Check added in v0.9.0 

func (p *PathIndex) Check() error

Check if the path index is valid.

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.

func BuildRef added in v0.9.0 

func BuildRef(path []PathIndex) *Ref

BuildRef from a path.

func (*Ref) ByType added in v0.9.0 

func (r *Ref) ByType(name string) ([]string, error)

ByType returns the path index for the given type.

func (*Ref) Path added in v0.9.0 

func (r *Ref) Path() (path []PathIndex, err error)

Path returns a parsed path including block types and their identifiers.

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
	// contains filtered or unexported fields
}

Resource is a generic container for resources described in configurations.

func (*Resource) As 

func (r *Resource) As(target any) 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) EmbedAttr added in v0.17.0 

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

EmbedAttr is like SetAttr but appends the attribute to an embedded resource, cause it to be marshaled after current blocks and attributes.

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) Range added in v0.24.0 

func (r *Resource) Range() *hcl.Range

Range returns the resource range on the file, or nil if it is not set.

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) Resources added in v0.22.0 

func (r *Resource) Resources(t string) []*Resource

Resources returns all child Resources by its type.

func (*Resource) Scan 

func (r *Resource) Scan(ext any) 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.

func (*Resource) SetRange added in v0.24.0 

func (r *Resource) SetRange(p *hcl.Range)

SetRange sets the range of this resource.

type SchemaValidator added in v0.13.0 

type SchemaValidator interface {
	Err() error
	ValidateBody(*hcl.EvalContext, *hclsyntax.Body) (func() error, error)
	ValidateBlock(*hcl.EvalContext, *hclsyntax.Block) (func() error, error)
	ValidateAttribute(*hcl.EvalContext, *hclsyntax.Attribute, cty.Value) error
}

SchemaValidator is the interface used for validating HCL documents.

type State 

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

State is used to evaluate and marshal Atlas HCL documents and stores a configuration for these operations.

func New 

func New(opts ...Option) *State

New returns a State configured with options.

func (*State) Eval 

func (s *State) Eval(parsed *hclparse.Parser, v any, input map[string]cty.Value) error

Eval evaluates the parsed HCL documents using the input variables and populates v using the result.

func (*State) EvalBytes 

func (s *State) EvalBytes(data []byte, v any, input map[string]cty.Value) error

EvalBytes evaluates the data byte-slice as an Atlas HCL document using the input variables and stores the result in v.

func (*State) EvalFiles 

func (s *State) EvalFiles(paths []string, v any, input map[string]cty.Value) error

EvalFiles evaluates the files in the provided paths using the input variables and populates v with the result.

func (*State) MarshalSpec 

func (s *State) MarshalSpec(v any) ([]byte, error)

MarshalSpec implements Marshaler for Atlas HCL documents.

type Type 

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

Type represents the type of the field in a schema.

func (*Type) IsRefTo added in v0.15.0 

func (t *Type) IsRefTo(n string) bool

IsRefTo indicates if the Type is a reference to specific schema type definition.

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.

func PrecisionTypeAttr added in v0.12.1 

func PrecisionTypeAttr() *TypeAttr

PrecisionTypeAttr returns a TypeAttr for a precision attribute.

func ScaleTypeAttr added in v0.12.1 

func ScaleTypeAttr() *TypeAttr

ScaleTypeAttr returns a TypeAttr for a scale attribute.

func SizeTypeAttr 

func SizeTypeAttr(required bool) *TypeAttr

SizeTypeAttr returns a TypeAttr for a size attribute.

type TypeRegistry 

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

TypeRegistry is a collection of *schemahcl.TypeSpec.

func NewRegistry 

func NewRegistry(opts ...TypeRegistryOption) *TypeRegistry

NewRegistry creates a new *TypeRegistry, registers the provided types and panics if an error occurs.

func (*TypeRegistry) Convert 

func (r *TypeRegistry) Convert(typ schema.Type) (*Type, error)

Convert converts the schema.Type to a *schemahcl.Type.

func (*TypeRegistry) PrintType 

func (r *TypeRegistry) PrintType(typ *Type) (string, error)

PrintType returns the string representation of a column type which can be parsed by the driver into a schema.Type.

func (*TypeRegistry) Register 

func (r *TypeRegistry) Register(specs ...*TypeSpec) error

Register adds one or more TypeSpec to the registry.

func (*TypeRegistry) Specs 

func (r *TypeRegistry) Specs() []*TypeSpec

Specs returns the TypeSpecs in the registry.

func (*TypeRegistry) Type 

func (r *TypeRegistry) Type(typ *Type, extra []*Attr) (schema.Type, error)

Type converts a *schemahcl.Type into a schema.Type.

type TypeRegistryOption 

type TypeRegistryOption func(*TypeRegistry) error

TypeRegistryOption configures a TypeRegistry.

func WithFormatter 

func WithFormatter(f func(schema.Type) (string, error)) TypeRegistryOption

WithFormatter configures the registry to use a formatting function for printing schema.Type as string.

func WithParser 

func WithParser(parser func(string) (schema.Type, error)) TypeRegistryOption

WithParser configures the registry to use a parsing function for converting a string to a schema.Type.

func WithSpecFunc 

func WithSpecFunc(spec func(schema.Type) (*Type, error)) TypeRegistryOption

WithSpecFunc configures the registry to use the given function for converting a schema.Type to schemahcl.Type

func WithSpecs 

func WithSpecs(specs ...*TypeSpec) TypeRegistryOption

WithSpecs configures the registry to register the given list of type specs.

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)

	// FromSpec is an optional function that can be attached
	// to the type spec and allows converting the schema spec
	// type to a schema type (from document to database).
	FromSpec func(*Type) (schema.Type, error)

	// ToSpec is an optional function that can be attached
	// to the type spec and allows converting the schema type
	// to a schema spec type (from database to document).
	ToSpec func(schema.Type) (*Type, error)
}

TypeSpec represents a specification for defining a Type.

func AliasTypeSpec 

func AliasTypeSpec(name, dbType string, opts ...TypeSpecOption) *TypeSpec

AliasTypeSpec returns a TypeSpec with the provided name.

func NewTypeSpec 

func NewTypeSpec(name string, opts ...TypeSpecOption) *TypeSpec

NewTypeSpec returns a TypeSpec with the provided name.

func (*TypeSpec) Attr 

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

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

type TypeSpecOption 

type TypeSpecOption func(*TypeSpec)

TypeSpecOption configures a schemahcl.TypeSpec.

func WithAttributes 

func WithAttributes(attrs ...*TypeAttr) TypeSpecOption

WithAttributes returns an attributes TypeSpecOption.

func WithFromSpec 

func WithFromSpec(f func(*Type) (schema.Type, error)) TypeSpecOption

WithFromSpec allows configuring the FromSpec convert function using functional options.

func WithToSpec 

func WithToSpec(f func(schema.Type) (*Type, error)) TypeSpecOption

WithToSpec allows configuring the ToSpec convert function using functional options.

func WithTypeFormatter 

func WithTypeFormatter(f func(*Type) (string, error)) TypeSpecOption

WithTypeFormatter allows overriding the Format function for the Type.

type Variables added in v0.12.0 

type Variables struct {
	Var, Local map[string]bool
	Data       map[string]map[string]bool
}

Variables represents the dynamic variables used in a body.

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.