Skip to content

Commit

Permalink
Undeprecate PrimitiveDecode and MetaData.PrimitiveDecode()
Browse files Browse the repository at this point in the history
Updates #404
  • Loading branch information
arp242 committed May 23, 2024
1 parent f8f7e48 commit 1e2c053
Show file tree
Hide file tree
Showing 5 changed files with 35 additions and 41 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
}
},
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion _example/example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"},
Expand Down
32 changes: 32 additions & 0 deletions decode.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
Expand Down Expand Up @@ -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.
//
Expand Down
38 changes: 0 additions & 38 deletions deprecated.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
}

0 comments on commit 1e2c053

Please sign in to comment.