func IsLocalImport(path string) bool
IsLocalImport reports whether the import path is a local import path, like ".", "..", "./foo", or "../foo".
A Context keeps track of state of building instances and caches work.
type Context struct {
// contains filtered or unexported fields
}
func NewContext(opts ...Option) *Context
NewContext creates a new build context.
All instances must be created with a context.
func (c *Context) NewInstance(dir string, f LoadFunc) *Instance
NewInstance creates an instance for this Context.
A Encoding indicates a file format for representing a program.
type Encoding string
const (
CUE Encoding = "cue"
JSON Encoding = "json"
YAML Encoding = "yaml"
JSONL Encoding = "jsonl"
Text Encoding = "text"
Binary Encoding = "binary"
Protobuf Encoding = "proto"
TextProto Encoding = "textproto"
BinaryProto Encoding = "pb"
Code Encoding = "code" // Programming languages
)
A File represents a file that is part of the build process.
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
ExcludeReason errors.Error `json:"-"`
Source interface{} `json:"-"` // TODO: swap out with concrete type.
}
A Form specifies the form in which a program should be represented.
type Form string
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
)
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.
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
// ImportComment is the path in the import comment on the package statement.
ImportComment string `api:"alpha"`
// AllTags are the build tags that can influence file selection in this
// directory.
AllTags []string `api:"alpha"`
// 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
}
func (inst *Instance) Abs(path string) string
Abs converts relative path used in the one of the file fields to an absolute one.
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 (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 (inst *Instance) Complete() error
Complete finishes the initialization of an instance. All files must have been added with AddFile before this call.
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 (inst *Instance) Dependencies() []*Instance
Dependencies reports all Instances on which this instance depends.
func (inst *Instance) ID() string
ID returns the package ID unique for this module.
func (inst *Instance) LookupImport(path string) *Instance
LookupImport defines a mapping from an ImportSpec's ImportPath to Instance.
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 (inst *Instance) ReportError(err errors.Error)
ReportError reports an error processing this instance.
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.
type Interpretation string
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 func(pos token.Pos, path string) *Instance
Option define build options.
type Option func(c *Context)
func Loader(f LoadFunc) Option
Loader sets parsing options.
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.