Tag release v1.0.0
This release adds much more detailed errors, support for the `toml.Marshaler`
interface, and several fixes.
There is no special meaning in the jump to v1.0; the 0.x releases were always
treated as if they're 1.x with regards to compatibility; the versioning scheme
for this library predates the release of modules.
New features
------------
- Error reporting is much improved; the reported position of errors should now
always be correct and the library can print more detailed errors (#299, #332)
Decode always return a `toml.ParseError`, which has three methods:
- `Error()` behaves as before and shows a single concise line with the error.
- `ErrorWithLocation()` shows the same error, but also shows the line the
error occurred at, similar to e.g. clang or the Rust compiler.
- `ErrorWithUsage()` is the same as `ErrorWithPosition()`, but may also show a
longer usage guidance message. This isn't always present (in which case it
behaves identical to `ErrorWithPosition()`), but it should be present for
most common mistakes and sources of confusion.
Which error the correct one to use is depends on your application and
preferences; in general I would recommend using at least `ErrorWithPosition()`
for user-facing errors, as it's much more helpful for users of any skill
level. If your users are likely to be non-technical then `ErrorWithUsage()` is
probably a good idea; I did my best to avoid technical jargon such as
"newline" and phrase things in a way that's understandable by most people not
intimately familiar with these sort of things.
Additionally, the TOML key that fialed should now always be reported in all
errors.
- Add `toml.Marshaler` interface. This can be used if you want full control over
how something is marshalled as TOML, similar to `json.Marshaler` etc. This
takes precedence over `encoding.TextMarshaler`. (#327)
- Allow TOML integers to be decoded to a Go float (#325)
Previously `int = 42` could only be decoded to an `int*` type; now this can
also be decoded in a `float` type as long as it can be represented without
loss of data.
Fixes
-----
- Key.String() is now quoted when needed (#333)
- Fix decoding of nested structs on 32bit platforms (#314)
- Empty slices are now always `[]T{}` rather than nil, which was the behaviour
in v0.3.1 and before. While they are identical for most purposes,
encoding/json encodes them different (`[]` vs. `null`), making it an
(accidentally) incompatible change (#339)