build

Documentation

Overview

Package build defines data types and utilities for defining CUE configuration instances.

This package enforces the rules regarding packages and instances as defined in the spec, but it leaves any other details, as well as handling of modules, up to the implementation.

A full implementation of instance loading can be found in the loader package.

WARNING: this packages may change. It is fine to use load and cue, who both use this package.

Package build defines collections of CUE files to build an instance.

Index

• func IsLocalImport(path string) bool
• type Context
  • func NewContext(opts ...Option) *Context
  • func (c *Context) NewInstance(dir string, f LoadFunc) *Instance
• type Encoding
• type File
• type Form
• type Instance
  • func (inst *Instance) Abs(path string) string
  • func (inst *Instance) AddFile(filename string, src interface{}) error
  • func (inst *Instance) AddSyntax(file *ast.File) errors.Error
  • func (inst *Instance) Complete() error
  • func (inst *Instance) Context() *Context
  • func (inst *Instance) Dependencies() []*Instance
  • func (inst *Instance) ID() string
  • func (inst *Instance) LookupImport(path string) *Instance
  • func (inst *Instance) RelPath(f *File) string
  • func (inst *Instance) ReportError(err errors.Error)
• type Interpretation
• type LoadFunc
• type Option
  • func Loader(f LoadFunc) Option
  • func ParseFile(f func(filename string, src interface{}) (*ast.File, error)) Option

Functions

func IsLocalImport

func IsLocalImport(path string) bool

IsLocalImport reports whether the import path is a local import path, like ".", "..", "./foo", or "../foo".

Types

type Context

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

A Context keeps track of state of building instances and caches work.

func NewContext

func NewContext(opts ...Option) *Context

NewContext creates a new build context.

All instances must be created with a context.

func (*Context) NewInstance

func (c *Context) NewInstance(dir string, f LoadFunc) *Instance

NewInstance creates an instance for this Context.

type Encoding

type Encoding string

A Encoding indicates a file format for representing a program.

const (
	CUE         Encoding = "cue"
	JSON        Encoding = "json"
	YAML        Encoding = "yaml"
	TOML        Encoding = "toml"
	JSONL       Encoding = "jsonl"
	Text        Encoding = "text"
	Binary      Encoding = "binary"
	Protobuf    Encoding = "proto"
	TextProto   Encoding = "textproto"
	BinaryProto Encoding = "pb"

	Code Encoding = "code" // Programming languages
)

type File

type File struct {
	Filename string `json:"filename"`

	Encoding       Encoding       `json:"encoding,omitempty"`
	Interpretation Interpretation `json:"interpretation,omitempty"`
	Form           Form           `json:"form,omitempty"`
	// Tags holds key-value pairs relating to the encoding
	// conventions to use for the file.
	Tags map[string]string `json:"tags,omitempty"` // e.g. code+lang=go

	// BoolTags holds boolean-valued tags relating to the
	// encoding conventions to use for the file.
	BoolTags map[string]bool `json:"boolTags,omitempty"`

	ExcludeReason errors.Error `json:"-"`
	Source        interface{}  `json:"-"` // TODO: swap out with concrete type.
}

A File represents a file that is part of the build process.

type Form

type Form string

A Form specifies the form in which a program should be represented.

const (
	Full   Form = "full"
	Schema Form = "schema"
	Struct Form = "struct"
	Final  Form = "final" // picking default values, may be non-concrete
	Graph  Form = "graph" // Data only, but allow references
	DAG    Form = "dag"   // Like graph, but don't allow cycles
	Data   Form = "data"  // always final
)

type Instance

type Instance struct {
	BuildFiles    []*File // files to be included in the build
	IgnoredFiles  []*File // files excluded for this build
	OrphanedFiles []*File // recognized file formats not part of any build
	InvalidFiles  []*File // could not parse these files
	UnknownFiles  []*File // unknown file types

	User bool // True if package was created from individual files.

	// Files contains the AST for all files part of this instance.
	// TODO: the intent is to deprecate this in favor of BuildFiles.
	Files []*ast.File

	// PkgName is the name specified in the package clause.
	PkgName string

	// ImportPath returns the unique path to identify an imported instance.
	//
	// Instances created with NewInstance do not have an import path.
	ImportPath string

	// Imports lists the instances of all direct imports of this instance.
	Imports []*Instance

	// The Err for loading this package or nil on success. This does not
	// include any errors of dependencies. Incomplete will be set if there
	// were any errors in dependencies.
	Err errors.Error

	// DisplayPath is a user-friendly version of the package or import path.
	DisplayPath string

	// Module defines the module name of a package. It must be defined if
	// the packages within the directory structure of the module are to be
	// imported by other packages, including those within the module.
	Module string

	// Root is the root of the directory hierarchy, it may be "" if this an
	// instance has no imports.
	// If Module != "", this corresponds to the module root.
	// Root/pkg is the directory that holds third-party packages.
	Root string // root directory of hierarchy ("" if unknown)

	// Dir is the package directory. A package may also include files from
	// ancestor directories, up to the module file.
	Dir string

	// Incomplete reports whether any dependencies had an error.
	Incomplete bool `api:"alpha"`

	// Dependencies
	// ImportPaths gives the transitive dependencies of all imports.
	ImportPaths []string               `api:"alpha"`
	ImportPos   map[string][]token.Pos `api:"alpha"` // line information for Imports

	Deps       []string `api:"alpha"`
	DepsErrors []error  `api:"alpha"`
	Match      []string `api:"alpha"`
	// contains filtered or unexported fields
}

An Instance describes the collection of files, and its imports, necessary to build a CUE instance.

A typical way to create an Instance is to use the cue/load package.

func (*Instance) Abs

func (inst *Instance) Abs(path string) string

Abs converts relative path used in the one of the file fields to an absolute one.

func (*Instance) AddFile

func (inst *Instance) AddFile(filename string, src interface{}) error

AddFile adds the file with the given name to the list of files for this instance. The file may be loaded from the cache of the instance's context. It does not process the file's imports. The package name of the file must match the package name of the instance.

Deprecated: use AddSyntax or wait for this to be renamed using a new signature.

func (*Instance) AddSyntax

func (inst *Instance) AddSyntax(file *ast.File) errors.Error

AddSyntax adds the given file to list of files for this instance. The package name of the file must match the package name of the instance.

func (*Instance) Complete

func (inst *Instance) Complete() error

Complete finishes the initialization of an instance. All files must have been added with AddFile before this call.

func (*Instance) Context

func (inst *Instance) Context() *Context

Context defines the build context for this instance. All files defined in Syntax as well as all imported instances must be created using the same build context.

func (*Instance) Dependencies

func (inst *Instance) Dependencies() []*Instance

Dependencies reports all Instances on which this instance depends.

func (*Instance) ID

func (inst *Instance) ID() string

ID returns the package ID unique for this module.

func (*Instance) LookupImport

func (inst *Instance) LookupImport(path string) *Instance

LookupImport defines a mapping from an ImportSpec's ImportPath to Instance.

func (*Instance) RelPath

func (inst *Instance) RelPath(f *File) string

RelPath reports the path of f relative to the root of the instance's module directory. The full path is returned if a relative path could not be found.

func (*Instance) ReportError

func (inst *Instance) ReportError(err errors.Error)

ReportError reports an error processing this instance.

type Interpretation

type Interpretation string

An Interpretation determines how a certain program should be interpreted. For instance, data may be interpreted as describing a schema, which itself can be converted to a CUE schema.

const (
	// Auto interprets the underlying data file as data, JSON Schema or OpenAPI,
	// depending on the existence of certain marker fields.
	//
	// JSON Schema is identified by a top-level "$schema" field with a URL
	// of the form "https?://json-schema.org/.*schema#?".
	//
	// OpenAPI is identified by the existence of a top-level field "openapi"
	// with a major semantic version of 3, as well as the existence of
	// the info.title and info.version fields.
	//
	// In all other cases, the underlying data is interpreted as is.
	Auto         Interpretation = "auto"
	JSONSchema   Interpretation = "jsonschema"
	OpenAPI      Interpretation = "openapi"
	ProtobufJSON Interpretation = "pb"
)

type LoadFunc

type LoadFunc func(pos token.Pos, path string) *Instance

type Option

type Option func(c *Context)

Option define build options.

func Loader

func Loader(f LoadFunc) Option

Loader sets parsing options.

func ParseFile

func ParseFile(f func(filename string, src interface{}) (*ast.File, error)) Option

ParseFile is called to read and parse each file when building syntax tree. It must be safe to call ParseFile simultaneously from multiple goroutines. If f is nil, the loader will use cuelang.org/go/cue/parser.ParseFile.

ParseFile should parse the source from src and use filename only for recording position information.

An application may supply a custom implementation of ParseFile to change the effective file contents or the behavior of the parser, or to modify the syntax tree. For example, changing the backwards compatibility.