go: cuelang.org/go/cue/build Index | Files

package build

import "cuelang.org/go/cue/build"

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.


Package Files

context.go doc.go file.go import.go instance.go

func IsLocalImport Uses

func IsLocalImport(path string) bool

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

type Context Uses

type Context struct {
    // contains filtered or unexported fields

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

func NewContext Uses

func NewContext(opts ...Option) *Context

NewContext creates a new build context.

All instances must be created with a context.

func (*Context) NewInstance Uses

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

NewInstance creates an instance for this Context.

type Encoding Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Dependencies reports all Instances on which this instance depends.

func (*Instance) ID Uses

func (inst *Instance) ID() string

ID returns the package ID unique for this module.

func (*Instance) LookupImport Uses

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

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

func (*Instance) ReportError Uses

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

ReportError reports an error processing this instance.

type Interpretation Uses

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 Uses

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

type Option Uses

type Option func(c *Context)

Option define build options.

func Loader Uses

func Loader(f LoadFunc) Option

Loader sets parsing options.

func ParseFile Uses

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.

Package build imports 14 packages (graph) and is imported by 20 packages. Updated 2021-01-26. Refresh now. Tools for package owners.