feat: honour TextMarshaler and TextUnmarshaler by default

Assisted-by: DeepSeek V4.1 Flash

interpres.go

@@ -123,6 +123,11 @@ func ParseContext(ctx context.Context, data []byte) (map[string]any, error) {
 // case-insensitive match on the field name when no tag is present. A tag of
 // "-" skips the field.
 //
+// A destination implementing Unmarshaler receives the parsed value as it is,
+// a TOML string fills a destination implementing encoding.TextUnmarshaler, and
+// a time.Duration destination takes a duration literal such as `1h30m` or a
+// bare integer as its nanosecond count.
+//
 // Unmarshal is equivalent to UnmarshalContext with context.Background.
 func Unmarshal(data []byte, v any) error {
 	return UnmarshalContext(context.Background(), data, v)
@@ -177,6 +182,10 @@ func (d *Decoder) DecodeContext(ctx context.Context, data []byte, v any) error {
 // then encodes as if the returned value had been passed in its place, which
 // is useful for emitting a Go type as a different TOML shape (for example, a
 // struct as an inline table or a primitive alias as a richer value).
+//
+// MarshalTOML wins over encoding.TextMarshaler when a type implements both.
+// A type that implements only encoding.TextMarshaler is encoded as a TOML
+// string holding its text, and needs no method here.
 type Marshaler interface {
 	MarshalTOML() (any, error)
 }
@@ -194,6 +203,10 @@ type Marshaler interface {
 // UnmarshalTOML is invoked from (*Decoder).Decode / Unmarshal when the
 // destination type implements the interface. The decoder does not need to
 // consult the concrete return value; whatever the receiver stores is kept.
+//
+// UnmarshalTOML wins over encoding.TextUnmarshaler when a type implements
+// both. A type that implements only encoding.TextUnmarshaler is filled from a
+// TOML string holding its text, and needs no method here.
 type Unmarshaler interface {
 	UnmarshalTOML(data any) error
 }
@@ -222,6 +235,9 @@ type Unmarshaler interface {
 //     variants).
 //   - Values implementing Marshaler are encoded by calling MarshalTOML and
 //     using its result.
+//   - Values implementing encoding.TextMarshaler, and not one of the
+//     date-time types, encode as a TOML string holding the text the method
+//     returns. time.Duration is written in its canonical Go form, `1h30m0s`.
 //   - nil pointer fields are omitted.
 //
 // Marshal cannot encode cyclic data structures; passing one will loop until