Interface Decoder

docstore/driver/codec.go:324–369

TODO(jba): consider a fast path: if we are decoding into a struct, assume the same struct was used to encode. Then we can build a map from field names to functions, where each function avoids all the tests of Decode and contains just the code for setting the field. TODO(jba): provide a way to overr

// A Decoder decodes data that was produced by Encode back into Go values.
// Each Decoder instance is responsible for decoding one value.
type Decoder interface {
	// The AsXXX methods each report whether the value being decoded can be represented as
	// a particular Go type. If so, the method should return the value as that type, and true;
	// otherwise it should return the zero value and false.
	AsString() (string, bool)
	AsInt() (int64, bool)
	AsUint() (uint64, bool)
	AsFloat() (float64, bool)
	AsBytes() ([]byte, bool)
	AsBool() (bool, bool)
	AsNull() bool

	// ListLen should return the length of the value being decoded and true, if the
	// value can be decoded into a slice or array. Otherwise, ListLen should return
	// (0, false).
	ListLen() (int, bool)

	// If ListLen returned true, then DecodeList will be called. It should iterate
	// over the value being decoded in sequence from index 0, invoking the callback
	// for each element with the element's index and a Decoder for the element.
	// If the callback returns false, DecodeList should return immediately.
	DecodeList(func(int, Decoder) bool)

	// MapLen should return the number of fields of the value being decoded and true,
	// if the value can be decoded into a map or struct. Otherwise, it should return
	// (0, false).
	MapLen() (int, bool)

	// DecodeMap iterates over the fields of the value being decoded, invoke the
	// callback on each with field name, a Decoder for the field value, and a bool
	// to indicate whether or not to use exact match for the field names. It will
	// be called when MapLen returns true or decoding a struct. If the callback
	// returns false, DecodeMap should return immediately.
	DecodeMap(func(string, Decoder, bool) bool)

	// AsInterface should decode the value into the Go value that best represents it.
	AsInterface() (any, error)

	// If the decoder wants to decode a value in a special way it should do so here
	// and return true, the decoded value, and any error from the decoding.
	// Otherwise, it should return false.
	AsSpecial(reflect.Value) (bool, any, error)

	// String should return a human-readable representation of the Decoder, for error messages.
	String() string
}

// Decode decodes the value held in the Decoder d into v.
// Decode creates slices, maps and pointer elements as needed.