Clarify result value lookup semantics
This commit is contained in:
@@ -75,7 +75,15 @@ unsupported-navigation behavior must remain unchanged.
|
|||||||
|
|
||||||
## 2. The exported Value documentation omits essential settled semantics
|
## 2. The exported Value documentation omits essential settled semantics
|
||||||
|
|
||||||
**Priority:** P3. **Status:** Open. **Plan stage:** 9.
|
**Priority:** P3. **Status:** Complete. **Plan stage:** 9.
|
||||||
|
|
||||||
|
**Completion:** expanded Value's declaration documentation for root selection,
|
||||||
|
manual results, presence versus availability, intermediate navigation, present
|
||||||
|
nil interfaces and typed nil values, preserved terminal types, scalar leaves,
|
||||||
|
no conversion/revalidation or codec calls, and ordinary assignment ownership.
|
||||||
|
Referenced the shared schema binding contract and Path semantics. Reviewed
|
||||||
|
`go doc Result.Value`; formatting and whitespace checks passed. No runtime
|
||||||
|
behavior changed in this unit.
|
||||||
|
|
||||||
**Relevant documentation:** the declaration comment in
|
**Relevant documentation:** the declaration comment in
|
||||||
[result_value.go](../../result_value.go), with the existing
|
[result_value.go](../../result_value.go), with the existing
|
||||||
|
|||||||
@@ -2,11 +2,27 @@ package configkit
|
|||||||
|
|
||||||
import "go.maximumdirect.net/configkit/internal/engine"
|
import "go.maximumdirect.net/configkit/internal/engine"
|
||||||
|
|
||||||
// Value returns the current Config value at path, including values absent from
|
// Value returns the current Config value at path. The root [Path] selects Config.
|
||||||
// input. It returns false for a nil result, invalid path, or missing value.
|
// A non-nil result supports lookup even when constructed manually without load
|
||||||
// Values are trusted application data and may include resolved secrets. Ordinary
|
// or inspection state. Success means value availability, not input presence or
|
||||||
// Go assignment applies: maps, slices, and pointers can alias Config. Inspection
|
// validation; use Metadata to inspect presence in the completed load.
|
||||||
// methods continue to report the frozen completed load, not later mutations.
|
//
|
||||||
|
// Navigation follows the shared YAML field names, inline bindings and supported
|
||||||
|
// shapes described in docs/config.md#application-schema-binding, with [Path]'s
|
||||||
|
// key/index rules. It follows non-nil intermediate pointers and interfaces,
|
||||||
|
// checks map membership and sequence bounds, and never allocates missing values.
|
||||||
|
// Scalars, including text-codec types and Secret, remain leaves.
|
||||||
|
// A nil receiver, invalid path, missing value, or unavailable traversal returns
|
||||||
|
// (nil, false). A present nil succeeds: a nil interface returns (nil, true), while
|
||||||
|
// typed nil pointers, maps and slices retain their types in the returned any.
|
||||||
|
//
|
||||||
|
// The terminal retains its actual Go type, including named types and pointers;
|
||||||
|
// terminal pointers are not dereferenced. Lookup performs no conversion or
|
||||||
|
// revalidation of the terminal and does not invoke codecs or resolve secrets.
|
||||||
|
// Values are trusted application data and may include resolved Secret values.
|
||||||
|
// Ordinary Go assignment applies: structs and arrays are copied, while maps,
|
||||||
|
// slices and pointers can alias Config. Inspection methods continue to report
|
||||||
|
// the frozen completed load, not later caller mutations.
|
||||||
func (r *Result[T]) Value(path Path) (any, bool) {
|
func (r *Result[T]) Value(path Path) (any, bool) {
|
||||||
if r == nil {
|
if r == nil {
|
||||||
return nil, false
|
return nil, false
|
||||||
|
|||||||
Reference in New Issue
Block a user