cuelang.org/go@v0.13.0/cue/cuecontext/cuecontext.go (about)

     1  // Copyright 2021 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 cuecontext
    16  
    17  import (
    18  	"fmt"
    19  
    20  	"cuelang.org/go/cue"
    21  	"cuelang.org/go/internal"
    22  	"cuelang.org/go/internal/core/runtime"
    23  	"cuelang.org/go/internal/cuedebug"
    24  	"cuelang.org/go/internal/envflag"
    25  
    26  	_ "cuelang.org/go/pkg"
    27  )
    28  
    29  // Option controls a build context.
    30  type Option struct {
    31  	apply func(r *runtime.Runtime)
    32  }
    33  
    34  // New creates a new [*cue.Context].
    35  //
    36  // The environment variables CUE_EXPERIMENT and CUE_DEBUG are followed to configure
    37  // the evaluator, just like the cue tool documents via [cue help environment].
    38  // You can override these settings via options like [EvaluatorVersion] and [CUE_DEBUG].
    39  //
    40  // [cue help environment]: https://cuelang.org/docs/reference/command/cue-help-environment/
    41  func New(options ...Option) *cue.Context {
    42  	r := runtime.New()
    43  	for _, o := range options {
    44  		o.apply(r)
    45  	}
    46  	return (*cue.Context)(r)
    47  }
    48  
    49  // An ExternInterpreter creates a compiler that can produce implementations of
    50  // functions written in a language other than CUE. It is currently for internal
    51  // use only.
    52  type ExternInterpreter = runtime.Interpreter
    53  
    54  // Interpreter associates an interpreter for external code with this context.
    55  func Interpreter(i ExternInterpreter) Option {
    56  	return Option{func(r *runtime.Runtime) {
    57  		r.SetInterpreter(i)
    58  	}}
    59  }
    60  
    61  type EvalVersion = internal.EvaluatorVersion
    62  
    63  const (
    64  	// EvalDefault is the default version of the evaluator, which is selected based on
    65  	// the CUE_EXPERIMENT environment variable described in [cue help environment].
    66  	//
    67  	// [cue help environment]: https://cuelang.org/docs/reference/command/cue-help-environment/
    68  	EvalDefault EvalVersion = internal.DefaultVersion
    69  
    70  	// EvalDefault is the latest stable version of the evaluator, currently [EvalV3].
    71  	EvalStable EvalVersion = internal.StableVersion
    72  
    73  	// EvalExperiment refers to the latest in-development version of the evaluator,
    74  	// currently [EvalV3]. Note that this version may change without notice.
    75  	EvalExperiment EvalVersion = internal.DevVersion
    76  
    77  	// EvalV2 is the previous version of the evaluator. It was introduced in CUE
    78  	// version 0.3 and is being maintained until 2024.
    79  	EvalV2 EvalVersion = internal.EvalV2
    80  
    81  	// EvalV3 is the current version of the evaluator. It was introduced in 2024
    82  	// and brought a new disjunction algorithm, a new closedness algorithm, a
    83  	// new core scheduler, and adds performance enhancements like structure sharing.
    84  	EvalV3 EvalVersion = internal.EvalV3
    85  )
    86  
    87  // EvaluatorVersion indicates which version of the evaluator to use. Currently
    88  // only experimental versions can be selected as an alternative.
    89  func EvaluatorVersion(v EvalVersion) Option {
    90  	return Option{func(r *runtime.Runtime) {
    91  		r.SetVersion(v)
    92  	}}
    93  }
    94  
    95  // CUE_DEBUG takes a string with the same contents as CUE_DEBUG and configures
    96  // the context with the relevant debug options. It panics for unknown or
    97  // malformed options.
    98  func CUE_DEBUG(s string) Option {
    99  	var c cuedebug.Config
   100  	if err := envflag.Parse(&c, s); err != nil {
   101  		panic(fmt.Errorf("cuecontext.CUE_DEBUG: %v", err))
   102  	}
   103  
   104  	return Option{func(r *runtime.Runtime) {
   105  		r.SetDebugOptions(&c)
   106  	}}
   107  }