cue: add Iterator.Selector

deprecates many existing Iterator methods.

Change-Id: Ic6ea17a003445ea1b6354413fc5622276cfc7c0b
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/9445
Reviewed-by: CUE cueckoo <cueckoo@gmail.com>
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>

cue/cue.go

@@ -12,6 +12,32 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package cue is a transition package for supporting the cue.Value API.
-// It aims to be plugin compatible with the old API.
+// Package cue is the main API for CUE evaluation.
+//
+// Value is the main type that represents CUE evaluations. Values are created
+// with a cue.Context. Only values created from the same Context can be
+// involved in the same operation.
+//
+// A Context defines the set of active packages, the translations of field
+// names to unique codes, as well as the set of builtins. Use
+//
+//     import "cuelang.org/go/cue/cuecontext"
+//
+//     ctx := cuecontext.New()
+//
+// to obtain a context.
+//
+//
+// Note that the following types are DEPRECATED and their usage should be
+// avoided if possible:
+//
+//    FieldInfo
+//    Instance
+//    Runtime
+//    Struct
+//
+// Many types also have deprecated methods. Code that already uses deprecated
+// methods can keep using them for at least some time. We aim to provide a
+// go or cue fix solution to automatically rewrite code using the new API.
+//
 package cue

cue/types.go

@@ -225,6 +225,8 @@ type Iterator struct {
 	isOpt bool
 }
 
+type hiddenIterator = Iterator
+
 type field struct {
 	arc        *adt.Vertex
 	isOptional bool
@@ -252,21 +254,27 @@ func (i *Iterator) Value() Value {
 	return i.cur
 }
 
-func (i *Iterator) Feature() adt.Feature {
-	return i.f
+// Selector reports the field label of this iteration.
+func (i *Iterator) Selector() Selector {
+	return featureToSel(i.f, i.idx)
 }
 
 // Label reports the label of the value if i iterates over struct fields and
 // "" otherwise.
-func (i *Iterator) Label() string {
+//
+// Deprecated: use i.Selector().String(). Note that this will give more accurate
+// string representations.
+func (i *hiddenIterator) Label() string {
 	if i.f == 0 {
 		return ""
 	}
 	return i.idx.LabelStr(i.f)
 }
 
 // IsHidden reports if a field is hidden from the data model.
-func (i *Iterator) IsHidden() bool {
+//
+// Deprecated: use i.Selector().PkgPath() != ""
+func (i *hiddenIterator) IsHidden() bool {
 	return i.f.IsHidden()
 }
 
@@ -276,7 +284,9 @@ func (i *Iterator) IsOptional() bool {
 }
 
 // IsDefinition reports if a field is a definition.
-func (i *Iterator) IsDefinition() bool {
+//
+// Deprecated: use i.Selector().IsDefinition()
+func (i *hiddenIterator) IsDefinition() bool {
 	return i.f.IsDef()
 }
 

cue/types_test.go

@@ -691,7 +691,7 @@ func TestFields(t *testing.T) {
 		res:   "{a:1,b:2,c:3,}",
 	}, {
 		value: `{a:1,"_b":2,c:3,_d:4}`,
-		res:   "{a:1,_b:2,c:3,}",
+		res:   `{a:1,"_b":2,c:3,}`,
 	}, {
 		value: `{_a:"a"}`,
 		res:   "{}",
@@ -715,7 +715,7 @@ func TestFields(t *testing.T) {
 
 			buf := []byte{'{'}
 			for iter.Next() {
-				buf = append(buf, iter.Label()...)
+				buf = append(buf, iter.Selector().String()...)
 				buf = append(buf, ':')
 				b, err := iter.Value().MarshalJSON()
 				checkFatal(t, err, tc.err, "Obj.At")