README
¶
toml
import "github.com/kitsunium/sdk/pkg/v1/data/codec/toml"
Package toml registers the TOML codec with the SDK's codec registry — and no other codec — when it is imported (ADR 0134):
import _ "github.com/kitsunium/sdk/pkg/v1/data/codec/toml"
Everything that dispatches through the registry by format name then reads and writes TOML: config.FileSource and config.FSSource, i18n.LoadFS, and the codec package's Marshal and Unmarshal. Importing github.com/kitsunium/sdk/pkg/v1/data/codec instead registers every format the SDK ships — BSON, CBOR, MessagePack and the rest — which a program that only reads TOML does not need to link. This package links the TOML codec, which the SDK implements with the standard library alone, and no module outside the SDK.
The codec reads TOML v1.0.0 (https://toml.io/en/v1.0.0), refusing what the specification refuses — a key or a table defined twice, an integer outside int64, bytes that are not UTF-8 — and accepts the four TOML v1.1.0 relaxations: newlines, comments and a trailing comma in an inline table, the \e and \xHH escapes, and a time without seconds. It writes TOML v1.0.0. A refusal never quotes the document; it names the problem, the line and the column.
A document decoded into map[string]any or any holds map[string]any, []any, string, int64, float64, bool, time.Time for an offset date-time, and LocalDateTime, LocalDate and LocalTime for the three kinds of TOML value that carry no time zone. Decoded into a time.Time instead, a local value is placed in time.Local.
Importing both packages is harmless: a format is registered by the package that implements it, which Go initialises once however many packages import it.
Errors
Failures carry the range 0.3.5.*; match them with errs.HasCode, or the sentinels with errors.Is:
CodeMarshalFailed 0.3.5.1 a Go value TOML cannot represent, or a writer that failed
CodeUnmarshalFailed 0.3.5.2 a document that is not TOML, past a bound, or a value its target cannot hold
Index
Constants
const CodeMarshalFailed errs.Code = 197889
CodeMarshalFailed identifies a Go value TOML cannot represent (0.3.5.1).
Initialised with github.com/kitsunium/sdk/internal/core/data/codec/toml.CodeTOMLMarshalFailed.
Code 0.3.5.1
const CodeUnmarshalFailed errs.Code = 197890
CodeUnmarshalFailed identifies a document the decoder cannot read, or a value its target cannot hold (0.3.5.2).
Initialised with github.com/kitsunium/sdk/internal/core/data/codec/toml.CodeTOMLUnmarshalFailed.
Code 0.3.5.2
const Format = "toml"
Format is the name TOML is registered under. It is an untyped constant, so it goes wherever a format name is taken — config.FSSource's string, i18n.LoadFS's codec.Format — without a conversion.
Variables
var MarshalFailed *errs.Error
MarshalFailed is the sentinel of CodeMarshalFailed.
Initialised with github.com/kitsunium/sdk/internal/core/data/codec/toml.MarshalFailed.
Code 0.3.5.1 · reason MARSHAL_FAILED · public "TOML encoding failed"
var UnmarshalFailed *errs.Error
UnmarshalFailed is the sentinel of CodeUnmarshalFailed.
Initialised with github.com/kitsunium/sdk/internal/core/data/codec/toml.UnmarshalFailed.
Code 0.3.5.2 · reason UNMARSHAL_FAILED · public "TOML decoding failed"
type LocalDate
LocalDate is a calendar day in no time zone: what a TOML local date such as 1979-05-27 decodes to in an untyped target. It writes and reads itself as YYYY-MM-DD, through String, MarshalText and UnmarshalText, and AsTime places it at midnight in a zone.
type LocalDate = toml.LocalDate
LocalDate is an alias of github.com/kitsunium/sdk/internal/service/data/codec/toml.LocalDate, declared as:
type LocalDate struct {
// Year is the calendar year.
Year int
// Month is 1 to 12.
Month int
// Day is 1 to 31.
Day int
}
func (LocalDate) AsTime
func (LocalDate) AsTime(zone *time.Location) time.Time
AsTime returns the day at midnight in zone.
func (LocalDate) MarshalText
func (LocalDate) MarshalText() ([]byte, error)
MarshalText returns the day as String writes it.
func (LocalDate) String
func (LocalDate) String() string
String returns the day as RFC 3339 writes it, YYYY-MM-DD.
func (LocalDate) UnmarshalText
func (*LocalDate) UnmarshalText(text []byte) error
UnmarshalText reads a day written YYYY-MM-DD, refusing a day the month does not have.
type LocalDateTime
LocalDateTime is a date and a time of day in no time zone: what a TOML local date-time such as 1979-05-27T07:32:00 decodes to in an untyped target. AsTime places it in a zone.
type LocalDateTime = toml.LocalDateTime
LocalDateTime is an alias of github.com/kitsunium/sdk/internal/service/data/codec/toml.LocalDateTime, declared as:
type LocalDateTime struct {
LocalDate
LocalTime
}
func (LocalDateTime) AsTime
func (LocalDateTime) AsTime(zone *time.Location) time.Time
AsTime returns the date-time in zone.
func (LocalDateTime) MarshalText
func (LocalDateTime) MarshalText() ([]byte, error)
MarshalText returns the date-time as String writes it.
func (LocalDateTime) String
func (LocalDateTime) String() string
String returns the date-time as RFC 3339 writes it, with a T between the date and the time.
func (LocalDateTime) UnmarshalText
func (*LocalDateTime) UnmarshalText(text []byte) error
UnmarshalText reads a date-time written YYYY-MM-DDTHH:MM:SS with an optional fraction; a space or a t may stand for the T.
type LocalTime
LocalTime is a time of day in no time zone: what a TOML local time such as 07:32:00.999 decodes to in an untyped target. Precision is the number of fractional digits the document wrote, which String writes back.
type LocalTime = toml.LocalTime
LocalTime is an alias of github.com/kitsunium/sdk/internal/service/data/codec/toml.LocalTime, declared as:
type LocalTime struct {
// Hour is 0 to 23.
Hour int
// Minute is 0 to 59.
Minute int
// Second is 0 to 59.
Second int
// Nanosecond is 0 to 999 999 999.
Nanosecond int
// Precision is how many fractional digits String writes: as many as the
// document had, up to nine. Zero writes the fewest that keep
// Nanosecond.
Precision int
}
func (LocalTime) MarshalText
func (LocalTime) MarshalText() ([]byte, error)
MarshalText returns the time as String writes it.
func (LocalTime) String
func (LocalTime) String() string
String returns the time as RFC 3339 writes it, HH:MM:SS, with Precision fractional digits, or the fewest that keep Nanosecond when Precision is 0.
func (LocalTime) UnmarshalText
func (*LocalTime) UnmarshalText(text []byte) error
UnmarshalText reads a time written HH:MM:SS with an optional fraction.
Generated from docs/api by tools/genindex.
Documentation
¶
Overview ¶
Package toml registers the TOML codec with the SDK's codec registry — and no other codec — when it is imported (ADR 0134):
import _ "github.com/kitsunium/sdk/pkg/v1/data/codec/toml"
Everything that dispatches through the registry by format name then reads and writes TOML: config.FileSource and config.FSSource, i18n.LoadFS, and the codec package's Marshal and Unmarshal. Importing github.com/kitsunium/sdk/pkg/v1/data/codec instead registers every format the SDK ships — BSON, CBOR, MessagePack and the rest — which a program that only reads TOML does not need to link. This package links the TOML codec, which the SDK implements with the standard library alone, and no module outside the SDK.
The codec reads TOML v1.0.0 (https://toml.io/en/v1.0.0), refusing what the specification refuses — a key or a table defined twice, an integer outside int64, bytes that are not UTF-8 — and accepts the four TOML v1.1.0 relaxations: newlines, comments and a trailing comma in an inline table, the \e and \xHH escapes, and a time without seconds. It writes TOML v1.0.0. A refusal never quotes the document; it names the problem, the line and the column.
A document decoded into map[string]any or any holds map[string]any, []any, string, int64, float64, bool, time.Time for an offset date-time, and LocalDateTime, LocalDate and LocalTime for the three kinds of TOML value that carry no time zone. Decoded into a time.Time instead, a local value is placed in time.Local.
Importing both packages is harmless: a format is registered by the package that implements it, which Go initialises once however many packages import it.
Errors ¶
Failures carry the range 0.3.5.*; match them with errs.HasCode, or the sentinels with errors.Is:
CodeMarshalFailed 0.3.5.1 a Go value TOML cannot represent, or a writer that failed CodeUnmarshalFailed 0.3.5.2 a document that is not TOML, past a bound, or a value its target cannot hold
Index ¶
Constants ¶
const ( // CodeMarshalFailed identifies a Go value TOML cannot represent (0.3.5.1). CodeMarshalFailed errs.Code = coretoml.CodeTOMLMarshalFailed // CodeUnmarshalFailed identifies a document the decoder cannot read, or a // value its target cannot hold (0.3.5.2). CodeUnmarshalFailed errs.Code = coretoml.CodeTOMLUnmarshalFailed )
The error codes, range 0.3.5.*, declared in the core (ADR 0160).
const Format = "toml"
Format is the name TOML is registered under. It is an untyped constant, so it goes wherever a format name is taken — config.FSSource's string, i18n.LoadFS's codec.Format — without a conversion.
Variables ¶
var ( // MarshalFailed is the sentinel of [CodeMarshalFailed]. MarshalFailed = coretoml.MarshalFailed // UnmarshalFailed is the sentinel of [CodeUnmarshalFailed]. UnmarshalFailed = coretoml.UnmarshalFailed )
The sentinels, for errors.Is: each carries the code of the same name.
Functions ¶
This section is empty.
Types ¶
type LocalDate ¶
LocalDate is a calendar day in no time zone: what a TOML local date such as 1979-05-27 decodes to in an untyped target. It writes and reads itself as YYYY-MM-DD, through String, MarshalText and UnmarshalText, and AsTime places it at midnight in a zone.
type LocalDateTime ¶
type LocalDateTime = toml.LocalDateTime
LocalDateTime is a date and a time of day in no time zone: what a TOML local date-time such as 1979-05-27T07:32:00 decodes to in an untyped target. AsTime places it in a zone.
Source Files