From 1e2c053f442c0ac99df1f5b56bae3feab98caa4f Mon Sep 17 00:00:00 2001 From: Martin Tournoij Date: Thu, 23 May 2024 13:37:56 +0100 Subject: [PATCH] Undeprecate PrimitiveDecode and MetaData.PrimitiveDecode() Updates #404 --- .github/workflows/test.yml | 2 +- README.md | 2 +- _example/example.toml | 2 +- decode.go | 32 ++++++++++++++++++++++++++++++++ deprecated.go | 38 -------------------------------------- 5 files changed, 35 insertions(+), 41 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index e0695d0c..4bff0cc6 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -5,7 +5,7 @@ "test": { "strategy": { "matrix": { - "go-version": ["1.18.x", "1.21.x"], + "go-version": ["1.18.x", "1.22.x"], "os": ["ubuntu-latest", "macos-latest", "windows-latest"] } }, diff --git a/README.md b/README.md index 3651cfa9..639e6c39 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ See the [releases page](https://github.com/BurntSushi/toml/releases) for a changelog; this information is also in the git tag annotations (e.g. `git show v0.4.0`). -This library requires Go 1.13 or newer; add it to your go.mod with: +This library requires Go 1.18 or newer; add it to your go.mod with: % go get github.com/BurntSushi/toml@latest diff --git a/_example/example.toml b/_example/example.toml index b89c504b..199e54c1 100644 --- a/_example/example.toml +++ b/_example/example.toml @@ -23,7 +23,7 @@ times = [ # Durations. duration = ["4m49s", "8m03s", "1231h15m55s"] -# Table with inline tables. +# Array with inline tables. distros = [ {name = "Arch Linux", packages = "pacman"}, {name = "Void Linux", packages = "xbps"}, diff --git a/decode.go b/decode.go index 7987f4fc..7aaf462c 100644 --- a/decode.go +++ b/decode.go @@ -57,6 +57,22 @@ func DecodeFS(fsys fs.FS, path string, v any) (MetaData, error) { return NewDecoder(fp).Decode(v) } +// Primitive is a TOML value that hasn't been decoded into a Go value. +// +// This type can be used for any value, which will cause decoding to be delayed. +// You can use [PrimitiveDecode] to "manually" decode these values. +// +// NOTE: The underlying representation of a `Primitive` value is subject to +// change. Do not rely on it. +// +// NOTE: Primitive values are still parsed, so using them will only avoid the +// overhead of reflection. They can be useful when you don't know the exact type +// of TOML data until runtime. +type Primitive struct { + undecoded any + context Key +} + // The significand precision for float32 and float64 is 24 and 53 bits; this is // the range a natural number can be stored in a float without loss of data. const ( @@ -164,6 +180,22 @@ func (dec *Decoder) Decode(v any) (MetaData, error) { return md, md.unify(p.mapping, rv) } +// PrimitiveDecode is just like the other Decode* functions, except it decodes a +// TOML value that has already been parsed. Valid primitive values can *only* be +// obtained from values filled by the decoder functions, including this method. +// (i.e., v may contain more [Primitive] values.) +// +// Meta data for primitive values is included in the meta data returned by the +// Decode* functions with one exception: keys returned by the Undecoded method +// will only reflect keys that were decoded. Namely, any keys hidden behind a +// Primitive will be considered undecoded. Executing this method will update the +// undecoded keys in the meta data. (See the example.) +func (md *MetaData) PrimitiveDecode(primValue Primitive, v any) error { + md.context = primValue.context + defer func() { md.context = nil }() + return md.unify(primValue.undecoded, rvalue(v)) +} + // unify performs a sort of type unification based on the structure of `rv`, // which is the client representation. // diff --git a/deprecated.go b/deprecated.go index ce8c7e25..155709a8 100644 --- a/deprecated.go +++ b/deprecated.go @@ -27,41 +27,3 @@ func PrimitiveDecode(primValue Primitive, v any) error { md := MetaData{decoded: make(map[string]struct{})} return md.unify(primValue.undecoded, rvalue(v)) } - -// Primitive is a TOML value that hasn't been decoded into a Go value. -// -// This type can be used for any value, which will cause decoding to be delayed. -// You can use [PrimitiveDecode] to "manually" decode these values. -// -// NOTE: The underlying representation of a `Primitive` value is subject to -// change. Do not rely on it. -// -// NOTE: Primitive values are still parsed, so using them will only avoid the -// overhead of reflection. They can be useful when you don't know the exact type -// of TOML data until runtime. -// -// Deprecated: use Marshaler interface for customer decoding. Or "any" -// parameters for varying types. -type Primitive struct { - undecoded any - context Key -} - -// PrimitiveDecode is just like the other Decode* functions, except it decodes a -// TOML value that has already been parsed. Valid primitive values can *only* be -// obtained from values filled by the decoder functions, including this method. -// (i.e., v may contain more [Primitive] values.) -// -// Meta data for primitive values is included in the meta data returned by the -// Decode* functions with one exception: keys returned by the Undecoded method -// will only reflect keys that were decoded. Namely, any keys hidden behind a -// Primitive will be considered undecoded. Executing this method will update the -// undecoded keys in the meta data. (See the example.) -// -// Deprecated: use Marshaler interface for customer decoding. Or "any" -// parameters for varying types. -func (md *MetaData) PrimitiveDecode(primValue Primitive, v any) error { - md.context = primValue.context - defer func() { md.context = nil }() - return md.unify(primValue.undecoded, rvalue(v)) -}