github.com/joomcode/cue@v0.4.4-0.20221111115225-539fe3512047/cue/build/context.go (about)

     1  // Copyright 2018 The CUE Authors
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package build defines data types and utilities for defining CUE configuration
    16  // instances.
    17  //
    18  // This package enforces the rules regarding packages and instances as defined
    19  // in the spec, but it leaves any other details, as well as handling of modules,
    20  // up to the implementation.
    21  //
    22  // A full implementation of instance loading can be found in the loader package.
    23  //
    24  // WARNING: this packages may change. It is fine to use load and cue, who both
    25  // use this package.
    26  package build
    27  
    28  import (
    29  	"context"
    30  
    31  	"github.com/joomcode/cue/cue/ast"
    32  	"github.com/joomcode/cue/cue/registry"
    33  )
    34  
    35  // A Context keeps track of state of building instances and caches work.
    36  type Context struct {
    37  	ctxt context.Context
    38  
    39  	loader    LoadFunc
    40  	parseFunc func(str string, src interface{}) (*ast.File, error)
    41  
    42  	initialized bool
    43  
    44  	imports map[string]*Instance
    45  	StarlarkRegistry *registry.Registry
    46  }
    47  
    48  // NewInstance creates an instance for this Context.
    49  func (c *Context) NewInstance(dir string, f LoadFunc) *Instance {
    50  	if c == nil {
    51  		c = &Context{}
    52  	}
    53  	if f == nil {
    54  		f = c.loader
    55  	}
    56  	return &Instance{
    57  		ctxt:     c,
    58  		loadFunc: f,
    59  		Dir:      dir,
    60  	}
    61  }
    62  
    63  // Complete finishes the initialization of an instance. All files must have
    64  // been added with AddFile before this call.
    65  func (inst *Instance) Complete() error {
    66  	if inst.done {
    67  		return inst.Err
    68  	}
    69  	inst.done = true
    70  
    71  	err := inst.complete()
    72  	if err != nil {
    73  		inst.ReportError(err)
    74  	}
    75  	if inst.Err != nil {
    76  		inst.Incomplete = true
    77  		return inst.Err
    78  	}
    79  	return nil
    80  }
    81  
    82  func (c *Context) init() {
    83  	if !c.initialized {
    84  		c.initialized = true
    85  		c.ctxt = context.Background()
    86  		c.imports = map[string]*Instance{}
    87  	}
    88  }
    89  
    90  // Options:
    91  // - certain parse modes
    92  // - parallellism
    93  // - error handler (allows cancelling the context)
    94  // - file set.
    95  
    96  // NewContext creates a new build context.
    97  //
    98  // All instances must be created with a context.
    99  func NewContext(opts ...Option) *Context {
   100  	c := &Context{}
   101  	for _, o := range opts {
   102  		o(c)
   103  	}
   104  	c.init()
   105  	return c
   106  }
   107  
   108  // Option define build options.
   109  type Option func(c *Context)
   110  
   111  // Loader sets parsing options.
   112  func Loader(f LoadFunc) Option {
   113  	return func(c *Context) { c.loader = f }
   114  }
   115  
   116  // ParseFile is called to read and parse each file
   117  // when building syntax tree.
   118  // It must be safe to call ParseFile simultaneously from multiple goroutines.
   119  // If ParseFile is nil, the loader will uses parser.ParseFile.
   120  //
   121  // ParseFile should parse the source from src and use filename only for
   122  // recording position information.
   123  //
   124  // An application may supply a custom implementation of ParseFile
   125  // to change the effective file contents or the behavior of the parser,
   126  // or to modify the syntax tree. For example, changing the backwards
   127  // compatibility.
   128  func ParseFile(f func(filename string, src interface{}) (*ast.File, error)) Option {
   129  	return func(c *Context) { c.parseFunc = f }
   130  }