From 73d4e2559fb69d798244e4ada3f1d52704e92d30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Wed, 30 Oct 2024 15:20:53 +0000 Subject: [PATCH] cue: improve docs around AnyIndex and AnyString MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When reading the rendered docs, it wasn't obvious to me how AnyIndex and AnyString were meant to be used. Only when I dug into the code did it seem apparent that they were Selectors that I could use with APIs taking selectors or paths like Value.LookupPath. Make that clear in the godocs, including a hint in LookupPath, as the old mechanism in Value.Elem is now hidden so the suggestion there to use LookupPath is not rendered in the docs page. While here, tweak other docs too to add links. Signed-off-by: Daniel Martí Change-Id: I2ab981293822c4ecebc8c3b2ed01c8e86461fb6f Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1203309 TryBot-Result: CUEcueckoo Reviewed-by: Matthew Sackman Unity-Result: CUE porcuepine --- cue/path.go | 6 +++--- cue/query.go | 4 ++++ cue/types.go | 15 +++++++-------- 3 files changed, 14 insertions(+), 11 deletions(-) diff --git a/cue/path.go b/cue/path.go index 42230f348d6..961699de5e9 100644 --- a/cue/path.go +++ b/cue/path.go @@ -212,18 +212,18 @@ func (sel Selector) Index() int { var ( - // AnyDefinition can be used to ask for any definition. + // AnyDefinition is a [Selector] which can be used to ask for any definition. // // In paths it is used to select constraints that apply to all elements. // AnyDefinition = anyDefinition anyDefinition = Selector{sel: anySelector(adt.AnyDefinition)} - // AnyIndex can be used to ask for any index. + // AnyIndex is a [Selector] which can be used to ask for any index. // // In paths it is used to select constraints that apply to all elements. AnyIndex = anyIndex anyIndex = Selector{sel: anySelector(adt.AnyIndex)} - // AnyString can be used to ask for any regular string field. + // AnyString is a [Selector] which can be used to ask for any regular string field. // // In paths it is used to select constraints that apply to all elements. AnyString = anyString diff --git a/cue/query.go b/cue/query.go index 4ef8f1cc075..f51a3923308 100644 --- a/cue/query.go +++ b/cue/query.go @@ -35,6 +35,10 @@ func getScopePrefix(v Value, p Path) Value { } // LookupPath reports the value for path p relative to v. +// +// Use [AnyString] and [AnyIndex] to find the value of undefined element types +// for structs and lists respectively, for example for the patterns in +// `{[string]: int}` and `[...string]`. func (v Value) LookupPath(p Path) Value { if v.v == nil { return Value{} diff --git a/cue/types.go b/cue/types.go index 87609d044b0..d23404c9880 100644 --- a/cue/types.go +++ b/cue/types.go @@ -934,8 +934,7 @@ func (v Value) Source() ast.Node { // If v exactly represents a package, BuildInstance returns // the build instance corresponding to the value; otherwise it returns nil. // -// The value returned by Value.ReferencePath will commonly represent -// a package. +// The value returned by [Value.ReferencePath] will commonly represent a package. func (v Value) BuildInstance() *build.Instance { if v.idx == nil { return nil @@ -953,7 +952,7 @@ func (v Value) Err() error { // Pos returns position information. // -// Use v.Expr to get positions for all conjuncts and disjuncts. +// Use [Value.Expr] to get positions for all conjuncts and disjuncts. func (v Value) Pos() token.Pos { if v.v == nil { return token.NoPos @@ -1143,7 +1142,7 @@ func (v Value) Len() Value { // Elem returns the value of undefined element types of lists and structs. // -// Deprecated: use [Value.LookupPath] in combination with "AnyString" or "AnyIndex". +// Deprecated: use [Value.LookupPath] in combination with [AnyString] or [AnyIndex]. func (v hiddenValue) Elem() (Value, bool) { sel := AnyString if v.v.IsList() { @@ -1550,7 +1549,7 @@ func (v hiddenValue) Fill(x interface{}, path ...string) Value { // FillPath creates a new value by unifying v with the value of x at the given // path. // -// If x is an cue/ast.Expr, it will be evaluated within the context of the +// If x is an [ast.Expr], it will be evaluated within the context of the // given path: identifiers that are not resolved within the expression are // resolved as if they were defined at the path position. // @@ -1558,7 +1557,7 @@ func (v hiddenValue) Fill(x interface{}, path ...string) Value { // from the same Runtime as v. // // Otherwise, the given Go value will be converted to CUE using the same rules -// as Context.Encode. +// as [Context.Encode]. // // Any reference in v referring to the value at the given path will resolve to x // in the newly created value. The resulting value is not validated. @@ -1753,7 +1752,7 @@ func (v Value) Unify(w Value) Value { return makeValue(v.idx, n, v.parent_) } -// UnifyAccept is as v.Unify(w), but will disregard the closedness rules for +// UnifyAccept is like [Value.Unify](w), but will disregard the closedness rules for // v and w, and will, instead, only allow fields that are present in accept. // // UnifyAccept is used to piecemeal unify individual conjuncts obtained from @@ -1831,7 +1830,7 @@ func (v hiddenValue) Reference() (inst *Instance, path []string) { } // ReferencePath returns the value and path referred to by this value such that -// value.LookupPath(path) resolves to the same value, or no path if this value +// [Value.LookupPath](path) resolves to the same value, or no path if this value // is not a reference. func (v Value) ReferencePath() (root Value, p Path) { // TODO: don't include references to hidden fields.