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) 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"
	JSONL    Encoding = "jsonl"
	Text     Encoding = "text"
	Protobuf Encoding = "proto"

	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           map[string]string `json:"tags,omitempty"` // code=go

	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 inclduded 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

	// 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

	// Scope is another instance that may be used to resolve any unresolved
	// reference of this instance. For instance, tool and test instances
	// may refer to top-level fields in their package scope.
	Scope *Instance

	// 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

	// Incomplete reports whether any dependencies had an error.
	Incomplete bool

	// ImportComment is the path in the import comment on the package statement.
	ImportComment string

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

	// Dir is the package directory. Note that a package may also include files
	// from ancestor directories, up to the module file.
	Dir 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)

	// AllTags are the build tags that can influence file selection in this
	// directory.
	AllTags []string

	Standard bool // Is a builtin package
	User     bool // True if package was created from individual files.

	// Deprecated: use BuildFiles
	CUEFiles []string // .cue source files
	// Deprecated: use BuildFiles and OrphanedFiles
	DataFiles []string // recognized data files (.json, .yaml, etc.)

	// The intent is to also deprecate the following fields in favor of
	// IgnoredFiles and UnknownFiles.
	TestCUEFiles    []string // .cue test files (_test.cue)
	ToolCUEFiles    []string // .cue tool files (_tool.cue)
	IgnoredCUEFiles []string // .cue source files ignored for this build
	InvalidCUEFiles []string // .cue source files with detected problems (parse error, wrong package name, and so on)

	// Dependencies
	ImportPaths []string
	ImportPos   map[string][]token.Pos // line information for Imports

	Deps       []string
	DepsErrors []error
	Match      []string
	// 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.

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

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 ParseFile is nil, the loader will uses 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.