cue: hide deprecated methods from docs
Change-Id: I4e7cdc00b54a88bb17a1c1e77441224257e09e54
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/9426
Reviewed-by: CUE cueckoo <cueckoo@gmail.com>
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>
diff --git a/cue/build.go b/cue/build.go
index 44730dd..9c603af 100644
--- a/cue/build.go
+++ b/cue/build.go
@@ -33,14 +33,16 @@
// Deprecated: use Context.
type Runtime runtime.Runtime
-func (r *Runtime) index() *runtime.Runtime {
+func (r *Runtime) runtime() *runtime.Runtime {
rt := (*runtime.Runtime)(r)
rt.Init()
return rt
}
+type hiddenRuntime = Runtime
+
func (r *Runtime) complete(p *build.Instance, v *adt.Vertex) (*Instance, error) {
- idx := r.index()
+ idx := r.runtime()
inst := getImportFromBuild(idx, p, v)
inst.ImportPath = p.ImportPath
if inst.Err != nil {
@@ -55,9 +57,9 @@
// Build to allow importing non-builtin packages.
//
// Deprecated: use Parse or ParseBytes. The use of Instance is being phased out.
-func (r *Runtime) Compile(filename string, source interface{}) (*Instance, error) {
+func (r *hiddenRuntime) Compile(filename string, source interface{}) (*Instance, error) {
cfg := &runtime.Config{Filename: filename}
- v, p := r.index().Compile(cfg, source)
+ v, p := r.runtime().Compile(cfg, source)
return r.complete(p, v)
}
@@ -65,8 +67,8 @@
// import builtin packages. Use Build to allow importing non-builtin packages.
//
// Deprecated: use BuildFile. The use of Instance is being phased out.
-func (r *Runtime) CompileFile(file *ast.File) (*Instance, error) {
- v, p := r.index().CompileFile(nil, file)
+func (r *hiddenRuntime) CompileFile(file *ast.File) (*Instance, error) {
+ v, p := r.runtime().CompileFile(nil, file)
return r.complete(p, v)
}
@@ -75,8 +77,8 @@
// packages.
//
// Deprecated: use BuildExpr. The use of Instance is being phased out.
-func (r *Runtime) CompileExpr(expr ast.Expr) (*Instance, error) {
- v, p, err := r.index().CompileExpr(nil, expr)
+func (r *hiddenRuntime) CompileExpr(expr ast.Expr) (*Instance, error) {
+ v, p, err := r.runtime().CompileExpr(nil, expr)
if err != nil {
return nil, err
}
@@ -89,17 +91,17 @@
//
// Deprecated: use ParseString or ParseBytes. The use of Instance is being
// phased out.
-func (r *Runtime) Parse(name string, source interface{}) (*Instance, error) {
+func (r *hiddenRuntime) Parse(name string, source interface{}) (*Instance, error) {
return r.Compile(name, source)
}
// Build creates an Instance from the given build.Instance. A returned Instance
// may be incomplete, in which case its Err field is set.
//
-// Deprecated: use Runtime.BuildInstance. The use of Instance is being phased
+// Deprecated: use Context.BuildInstance. The use of Instance is being phased
// out.
-func (r *Runtime) Build(p *build.Instance) (*Instance, error) {
- v, _ := r.index().Build(nil, p)
+func (r *hiddenRuntime) Build(p *build.Instance) (*Instance, error) {
+ v, _ := r.runtime().Build(nil, p)
return r.complete(p, v)
}
@@ -109,7 +111,7 @@
// Example:
// inst := cue.Build(load.Instances(args))
//
-// Deprecated: use Runtime.BuildInstances. The use of Instance is being phased
+// Deprecated: use Context.BuildInstances. The use of Instance is being phased
// out.
func Build(instances []*build.Instance) []*Instance {
if len(instances) == 0 {
@@ -120,8 +122,8 @@
return a
}
-func (r *Runtime) build(instances []*build.Instance) ([]*Instance, error) {
- index := r.index()
+func (r *hiddenRuntime) build(instances []*build.Instance) ([]*Instance, error) {
+ index := r.runtime()
loaded := []*Instance{}
@@ -142,7 +144,7 @@
// Any references must be resolved beforehand.
//
// Deprecated: use CompileExpr
-func (r *Runtime) FromExpr(expr ast.Expr) (*Instance, error) {
+func (r *hiddenRuntime) FromExpr(expr ast.Expr) (*Instance, error) {
return r.CompileFile(&ast.File{
Decls: []ast.Decl{&ast.EmbedDecl{Expr: expr}},
})
diff --git a/cue/context.go b/cue/context.go
index 1ff8163..63eaa13 100644
--- a/cue/context.go
+++ b/cue/context.go
@@ -38,13 +38,13 @@
// to create a new Context.
type Context runtime.Runtime
-func (c *Context) index() *runtime.Runtime {
+func (c *Context) runtime() *runtime.Runtime {
rt := (*runtime.Runtime)(c)
return rt
}
func (c *Context) ctx() *adt.OpContext {
- return newContext(c.index())
+ return newContext(c.runtime())
}
// Context reports the Context with which this value was created.
@@ -92,7 +92,7 @@
// error occurred.
func (c *Context) BuildInstance(i *build.Instance, options ...BuildOption) Value {
cfg := c.parseOptions(options)
- v, err := c.index().Build(&cfg, i)
+ v, err := c.runtime().Build(&cfg, i)
if err != nil {
return c.makeError(err)
}
@@ -113,7 +113,7 @@
var errs errors.Error
var a []Value
for _, b := range instances {
- v, err := c.index().Build(nil, b)
+ v, err := c.runtime().Build(nil, b)
if err != nil {
errs = errors.Append(errs, err)
}
@@ -128,7 +128,7 @@
// error occurred.
func (c *Context) BuildFile(f *ast.File, options ...BuildOption) Value {
cfg := c.parseOptions(options)
- return c.compile(c.index().CompileFile(&cfg, f))
+ return c.compile(c.runtime().CompileFile(&cfg, f))
}
func (c *Context) compile(v *adt.Vertex, p *build.Instance) Value {
@@ -144,7 +144,7 @@
// error occurred.
func (c *Context) BuildExpr(x ast.Expr, options ...BuildOption) Value {
cfg := c.parseOptions(options)
- v, p, err := c.index().CompileExpr(&cfg, x)
+ v, p, err := c.runtime().CompileExpr(&cfg, x)
if err != nil {
return c.makeError(p.Err)
}
@@ -157,7 +157,7 @@
// error occurred.
func (c *Context) CompileString(src string, options ...BuildOption) Value {
cfg := c.parseOptions(options)
- return c.compile(c.index().Compile(&cfg, src))
+ return c.compile(c.runtime().Compile(&cfg, src))
}
// ParseString parses and build a Value from the given source bytes.
@@ -166,7 +166,7 @@
// error occurred.
func (c *Context) CompileBytes(b []byte, options ...BuildOption) Value {
cfg := c.parseOptions(options)
- return c.compile(c.index().Compile(&cfg, b))
+ return c.compile(c.runtime().Compile(&cfg, b))
}
// TODO: fs.FS or custom wrapper?
@@ -183,7 +183,7 @@
// }
func (c *Context) make(v *adt.Vertex) Value {
- return newValueRoot(c.index(), newContext(c.index()), v)
+ return newValueRoot(c.runtime(), newContext(c.runtime()), v)
}
// An EncodeOption defines options for the various encoding-related methods of
@@ -214,7 +214,7 @@
func (c *Context) Encode(x interface{}, option ...EncodeOption) Value {
switch v := x.(type) {
case adt.Value:
- return newValueRoot(c.index(), c.ctx(), v)
+ return newValueRoot(c.runtime(), c.ctx(), v)
}
var options encodeOptions
options.process(option)
diff --git a/cue/instance.go b/cue/instance.go
index 02dc82a..df01f0a 100644
--- a/cue/instance.go
+++ b/cue/instance.go
@@ -61,6 +61,8 @@
// complete bool // for cycle detection
}
+type hiddenInstance = Instance
+
func addInst(x *runtime.Runtime, p *Instance) *Instance {
if p.inst == nil {
p.inst = &build.Instance{
@@ -260,7 +262,7 @@
// Doc returns the package comments for this instance.
//
// Deprecated: use inst.Value().Doc()
-func (inst *Instance) Doc() []*ast.CommentGroup {
+func (inst *hiddenInstance) Doc() []*ast.CommentGroup {
return inst.Value().Doc()
}
@@ -276,7 +278,7 @@
// Eval evaluates an expression within an existing instance.
//
// Expressions may refer to builtin packages if they can be uniquely identified.
-func (inst *Instance) Eval(expr ast.Expr) Value {
+func (inst *hiddenInstance) Eval(expr ast.Expr) Value {
ctx := newContext(inst.index)
v := inst.root
v.Finalize(ctx)
@@ -311,7 +313,9 @@
// Build creates a new instance from the build instances, allowing unbound
// identifier to bind to the top-level field in inst. The top-level fields in
// inst take precedence over predeclared identifier and builtin functions.
-func (inst *Instance) Build(p *build.Instance) *Instance {
+//
+// Deprecated: use Context.Build
+func (inst *hiddenInstance) Build(p *build.Instance) *Instance {
p.Complete()
idx := inst.index
@@ -350,14 +354,18 @@
// exist. The Err method reports if any error occurred during evaluation. The
// empty path returns the top-level configuration struct. Use LookupDef for definitions or LookupField for
// any kind of field.
-func (inst *Instance) Lookup(path ...string) Value {
+//
+// Deprecated: use Value.LookupPath
+func (inst *hiddenInstance) Lookup(path ...string) Value {
return inst.value().Lookup(path...)
}
// LookupDef reports the definition with the given name within struct v. The
// Exists method of the returned value will report false if the definition did
// not exist. The Err method reports if any error occurred during evaluation.
-func (inst *Instance) LookupDef(path string) Value {
+//
+// Deprecated: use Value.LookupPath
+func (inst *hiddenInstance) LookupDef(path string) Value {
return inst.value().LookupDef(path)
}
@@ -368,7 +376,9 @@
//
// Deprecated: this API does not work with new-style definitions. Use
// FieldByName defined on inst.Value().
-func (inst *Instance) LookupField(path ...string) (f FieldInfo, err error) {
+//
+// Deprecated: use Value.LookupPath
+func (inst *hiddenInstance) LookupField(path ...string) (f FieldInfo, err error) {
v := inst.value()
for _, k := range path {
s, err := v.Struct()
@@ -396,7 +406,7 @@
// Runtime.
//
// Deprecated: use Value.FillPath()
-func (inst *Instance) Fill(x interface{}, path ...string) (*Instance, error) {
+func (inst *hiddenInstance) Fill(x interface{}, path ...string) (*Instance, error) {
v := inst.Value().Fill(x, path...)
inst = addInst(inst.index, &Instance{
diff --git a/cue/marshal.go b/cue/marshal.go
index f877b77..43ca6d4 100644
--- a/cue/marshal.go
+++ b/cue/marshal.go
@@ -140,7 +140,7 @@
return p
}
// TODO: support exporting instance
- file, _ := export.Def(r.index(), i.inst.ID(), i.root)
+ file, _ := export.Def(r.runtime(), i.inst.ID(), i.root)
imports := []string{}
file.VisitImports(func(i *ast.ImportDecl) {
for _, spec := range i.Specs {
@@ -190,7 +190,7 @@
p := len(staged) - 1
for _, imp := range imports {
- i := getImportFromPath(r.index(), imp)
+ i := getImportFromPath(r.runtime(), imp)
if i == nil || !strings.Contains(imp, ".") {
continue // a builtin package.
}
diff --git a/cue/types.go b/cue/types.go
index 86ac88e..e06cef0 100644
--- a/cue/types.go
+++ b/cue/types.go
@@ -94,8 +94,10 @@
features []adt.Feature
}
+type hiddenStructValue = structValue
+
// Len reports the number of fields in this struct.
-func (o *structValue) Len() int {
+func (o *hiddenStructValue) Len() int {
if o.obj == nil {
return 0
}
@@ -103,12 +105,12 @@
}
// At reports the key and value of the ith field, i < o.Len().
-func (o *structValue) At(i int) (key string, v Value) {
+func (o *hiddenStructValue) At(i int) (key string, v Value) {
f := o.features[i]
return o.v.idx.LabelStr(f), newChildValue(o, i)
}
-func (o *structValue) at(i int) (v *adt.Vertex, isOpt bool) {
+func (o *hiddenStructValue) at(i int) (v *adt.Vertex, isOpt bool) {
f := o.features[i]
arc := o.obj.Lookup(f)
if arc == nil {
@@ -125,7 +127,7 @@
// Lookup reports the field for the given key. The returned Value is invalid
// if it does not exist.
-func (o *structValue) Lookup(key string) Value {
+func (o *hiddenStructValue) Lookup(key string) Value {
f := o.v.idx.StrLabel(key)
i := 0
len := o.Len()
@@ -336,7 +338,7 @@
// Decimal is for internal use only. The Decimal type that is returned is
// subject to change.
-func (v Value) Decimal() (d *internal.Decimal, err error) {
+func (v hiddenValue) Decimal() (d *internal.Decimal, err error) {
n, err := v.getNum(adt.NumKind)
if err != nil {
return nil, err
@@ -827,7 +829,7 @@
//
// TODO: get rid of this somehow. Probably by including a FieldInfo struct
// or the like.
-func (v Value) Label() (string, bool) {
+func (v hiddenValue) Label() (string, bool) {
if v.v == nil || v.v.Label == 0 {
return "", false
}
@@ -1037,7 +1039,7 @@
// Source returns a non-nil value.
//
// Deprecated: use Expr.
-func (v Value) Split() []Value {
+func (v hiddenValue) Split() []Value {
if v.v == nil {
return nil
}
@@ -1085,7 +1087,7 @@
// when the value is not a list or struct.
//
// Deprecated: use Allows and Kind/IncompleteKind.
-func (v Value) IsClosed() bool {
+func (v hiddenValue) IsClosed() bool {
if v.v == nil {
return false
}
@@ -1207,7 +1209,7 @@
// Elem returns the value of undefined element types of lists and structs.
//
// Deprecated: use LookupPath in combination with "AnyString" or "AnyIndex".
-func (v Value) Elem() (Value, bool) {
+func (v hiddenValue) Elem() (Value, bool) {
sel := AnyString
if v.v.IsList() {
sel = AnyIndex
@@ -1283,7 +1285,7 @@
// Reader returns a new Reader if v is a string or bytes type and an error
// otherwise.
-func (v Value) Reader() (io.Reader, error) {
+func (v hiddenValue) Reader() (io.Reader, error) {
v, _ = v.Default()
ctx := v.ctx()
switch x := v.eval(ctx).(type) {
@@ -1358,7 +1360,7 @@
// Struct returns the underlying struct of a value or an error if the value
// is not a struct.
-func (v Value) Struct() (*Struct, error) {
+func (v hiddenValue) Struct() (*Struct, error) {
// TODO: deprecate
ctx := v.ctx()
obj, err := v.structValOpts(ctx, options{})
@@ -1383,6 +1385,8 @@
structValue
}
+type hiddenStruct = Struct
+
// FieldInfo contains information about a struct field.
type FieldInfo struct {
Selector string
@@ -1395,12 +1399,12 @@
IsHidden bool
}
-func (s *Struct) Len() int {
+func (s *hiddenStruct) Len() int {
return s.structValue.Len()
}
// field reports information about the ith field, i < o.Len().
-func (s *Struct) Field(i int) FieldInfo {
+func (s *hiddenStruct) Field(i int) FieldInfo {
a, opt := s.at(i)
ctx := s.v.ctx()
@@ -1413,7 +1417,7 @@
// FieldByName looks up a field for the given name. If isIdent is true, it will
// look up a definition or hidden field (starting with `_` or `_#`). Otherwise
// it interprets name as an arbitrary string for a regular field.
-func (s *Struct) FieldByName(name string, isIdent bool) (FieldInfo, error) {
+func (s *hiddenStruct) FieldByName(name string, isIdent bool) (FieldInfo, error) {
f := s.v.idx.Label(name, isIdent)
for i, a := range s.features {
if a == f {
@@ -1424,7 +1428,7 @@
}
// Fields creates an iterator over the Struct's fields.
-func (s *Struct) Fields(opts ...Option) *Iterator {
+func (s *hiddenStruct) Fields(opts ...Option) *Iterator {
iter, _ := s.v.Fields(opts...)
return iter
}
@@ -1456,7 +1460,7 @@
//
// Deprecated: use LookupPath. At some point before v1.0.0, this method will
// be removed to be reused eventually for looking up a selector.
-func (v Value) Lookup(path ...string) Value {
+func (v hiddenValue) Lookup(path ...string) Value {
ctx := v.ctx()
for _, k := range path {
// TODO(eval) TODO(error): always search in full data and change error
@@ -1500,7 +1504,7 @@
// LookupDef is equal to LookupPath(MakePath(Def(name))).
//
// Deprecated: use LookupPath.
-func (v Value) LookupDef(name string) Value {
+func (v hiddenValue) LookupDef(name string) Value {
return v.LookupPath(MakePath(Def(name)))
}
@@ -1511,7 +1515,7 @@
// it interprets name as an arbitrary string for a regular field.
//
// Deprecated: use LookupPath.
-func (v Value) FieldByName(name string, isIdent bool) (f FieldInfo, err error) {
+func (v hiddenValue) FieldByName(name string, isIdent bool) (f FieldInfo, err error) {
s, err := v.Struct()
if err != nil {
return f, err
@@ -1522,7 +1526,7 @@
// LookupField reports information about a field of v.
//
// Deprecated: use LookupPath
-func (v Value) LookupField(name string) (FieldInfo, error) {
+func (v hiddenValue) LookupField(name string) (FieldInfo, error) {
s, err := v.Struct()
if err != nil {
// TODO: return a Value at the same location and a new error?
@@ -1560,7 +1564,7 @@
// to x in the newly created value. The resulting value is not validated.
//
// Deprecated: use FillPath.
-func (v Value) Fill(x interface{}, path ...string) Value {
+func (v hiddenValue) Fill(x interface{}, path ...string) Value {
if v.v == nil {
return v
}
@@ -1634,7 +1638,7 @@
// given its name.
//
// Deprecated: use LookupPath in combination with using optional selectors.
-func (v Value) Template() func(label string) Value {
+func (v hiddenValue) Template() func(label string) Value {
if v.v == nil {
return nil
}
@@ -1690,7 +1694,7 @@
// By default, Subsumes tests whether two values are compatible
// Value v and w must be obtained from the same build.
// TODO: remove this requirement.
-func (v Value) Subsumes(w Value) bool {
+func (v hiddenValue) Subsumes(w Value) bool {
ctx := v.ctx()
p := subsume.Profile{Defaults: true}
return p.Check(ctx, v.v, w.v)
@@ -1840,7 +1844,7 @@
// only return a reference if the index resolves to a concrete value.
//
// Deprecated: use ReferencePath
-func (v Value) Reference() (inst *Instance, path []string) {
+func (v hiddenValue) Reference() (inst *Instance, path []string) {
root, p := v.ReferencePath()
if !root.Exists() {
return nil, nil
@@ -2032,8 +2036,6 @@
}
// Hidden indicates that definitions and hidden fields should be included.
-//
-// Deprecated: Hidden fields are deprecated.
func Hidden(include bool) Option {
return func(p *options) {
p.hasHidden = true
diff --git a/encoding/json/json.go b/encoding/json/json.go
index a319222..5289b39 100644
--- a/encoding/json/json.go
+++ b/encoding/json/json.go
@@ -55,6 +55,8 @@
// Decode parses JSON-encoded data to a CUE value, using path for position
// information.
+//
+// Deprecated: use Extract and build using cue.Context.BuildExpr.
func Decode(r *cue.Runtime, path string, data []byte) (*cue.Instance, error) {
expr, err := extract(path, data)
if err != nil {
@@ -80,6 +82,8 @@
// NewDecoder configures a JSON decoder. The path is used to associate position
// information with each node. The runtime may be nil if the decoder
// is only used to extract to CUE ast objects.
+//
+// The runtime may be nil if Decode isn't used.
func NewDecoder(r *cue.Runtime, path string, src io.Reader) *Decoder {
return &Decoder{
r: r,
@@ -129,6 +133,8 @@
// Decode converts the current JSON value to a CUE instance. It returns io.EOF
// if the input has been exhausted.
+//
+// Deprecated: use Extract and build with cue.Context.BuildExpr.
func (d *Decoder) Decode() (*cue.Instance, error) {
expr, err := d.Extract()
if err != nil {
diff --git a/encoding/yaml/yaml.go b/encoding/yaml/yaml.go
index 0787077..1e356e0 100644
--- a/encoding/yaml/yaml.go
+++ b/encoding/yaml/yaml.go
@@ -66,6 +66,8 @@
// Decode converts a YAML file to a CUE value. Streams are returned as a list
// of the streamed values.
+//
+// Deprecate: use Extract and build the File with cue.Context.BuildFile.
func Decode(r *cue.Runtime, filename string, src interface{}) (*cue.Instance, error) {
file, err := Extract(filename, src)
if err != nil {
