Documentation
¶
Overview ¶
Package toml adds support to marshal and unmarshal types not in the official TOML spec.
Index ¶
- Constants
- Variables
- func ApplyEnvOverrides(getenv GetenvFunc, prefix string, val interface{}) ([]string, error)
- func UnmatchedEnvVars(environ []string, prefix string, applied []string) []string
- func VerifyConfigType(cfg interface{}) error
- type Defaulter
- type Duration
- type FileMode
- type GetenvFunc
- type Group
- type SSize
- type SSizeV1
- type SSizeV2
- type Size
- type SizeV1
- type SizeV2
Constants ¶
const MaxEnvSliceGrowth = 64
MaxEnvSliceGrowth limits how many elements can be appended to a slice via environment variable overrides, preventing unbounded memory allocation. This is to prevent unbounded growth by environment variables, a potential security issue, as well as unintentionally unbounded growth due to errors in management scripts.
Variables ¶
var ErrSizeOutOfRange = errors.New("size value out of range for target type")
ErrSizeOutOfRange is returned by the ToInt / ToInt64 / ToUint64 conversion helpers when the stored size cannot be represented in the target type.
Functions ¶
func ApplyEnvOverrides ¶
func ApplyEnvOverrides(getenv GetenvFunc, prefix string, val interface{}) ([]string, error)
ApplyEnvOverrides applies environment variable overrides to the given configuration value. It returns the list of all environment variable names that were applied and any error encountered.
func UnmatchedEnvVars ¶ added in v2.9.0
UnmatchedEnvVars returns the names of environment variables in environ that match the prefix namespace (start with prefix+"_") but are not present in applied. The applied list is typically the result of ApplyEnvOverrides.
This is useful for detecting typos in user-set environment variable names: any var that the user set with the configured prefix but that didn't match a config field will appear in the result. Callers can log the result at startup to give operators feedback about config they thought they were setting but weren't.
environ should be in the format returned by os.Environ() — each entry is "KEY=VALUE". Entries without an "=" are ignored. The returned slice is sorted and deduplicated. If prefix is empty, UnmatchedEnvVars returns nil.
func VerifyConfigType ¶ added in v2.9.0
func VerifyConfigType(cfg interface{}) error
VerifyConfigType walks the type tree of cfg and reports an error if the type cannot serve as a valid configuration root. It currently checks:
- slice element types that would be appended via indexed env var overrides must implement Defaulter
- the type graph must not contain cycles, which cannot be expressed in TOML or via the environment variable override scheme in this package
cfg may be a value or a pointer; the type tree is walked from its (dereferenced) type. Element types that implement encoding.TextUnmarshaler are exempt from the Defaulter check: they are treated as leaves by ApplyEnvOverrides and have no fields to default. Primitive element types (string, int, etc.) are also exempt for the same reason. Fields tagged `toml:"-"` and unexported fields are skipped because ApplyEnvOverrides skips them too.
VerifyConfigType is intended to be called from a test in the package that owns the config root, as a CI safety net for the conventions that a config type must satisfy.
Types ¶
type Defaulter ¶ added in v2.9.0
type Defaulter interface {
ApplyDefaults()
}
Defaulter is implemented by config types that can populate themselves with default values. Slice element types reachable from a configuration root passed to ApplyEnvOverrides must implement Defaulter so that elements appended via indexed environment variables are seeded with defaults before overrides are applied. This avoids producing partially-configured elements with zero values for unset fields. NewConfig-style constructors should delegate to ApplyDefaults so the same defaults are produced regardless of construction path.
type Duration ¶
Duration is a TOML wrapper type for time.Duration.
func (Duration) MarshalText ¶
MarshalText converts a duration to a string for encoding toml
func (*Duration) Set ¶
Set parses s into the receiver. It satisfies pflag.Value so Duration can be used as a command-line flag via pflag.Var. Unlike UnmarshalText, Set rejects the empty string — an explicit `--flag=""` on the command line is almost always a user mistake, and surfacing it as an error matches pflag.DurationVar's native behavior. The error text mirrors what time.ParseDuration("") returns so callers see a consistent message.
func (*Duration) UnmarshalText ¶
UnmarshalText parses a TOML value into a duration value.
type FileMode ¶
type FileMode uint32
FileMode is a TOML wrapper around os.FileMode. Values are parsed as octal (matching chmod convention), so "755" means 0o755.
An empty value is treated as "unset" and leaves the receiver at its zero value. An explicit "0" (or any other zero octal literal) is rejected — an explicit zero mode is almost always a configuration mistake.
func (FileMode) MarshalText ¶
func (*FileMode) UnmarshalText ¶
type GetenvFunc ¶ added in v2.9.0
GetenvFunc is a function that matches os.Getenv.
type Group ¶
type Group int
func (*Group) UnmarshalTOML ¶
func (*Group) UnmarshalText ¶ added in v2.9.0
type SSize ¶ added in v2.9.0
type SSize = SSizeV2
Size and SSize are aliases for the branch-appropriate size-parser implementation. On the 1.x branch they point at SizeV1/SSizeV1, which preserve the historical binary meaning of bare 'k'/'m'/'g' suffixes on top of the richer humanize vocabulary. On the 2.x branch they point at SizeV2/SSizeV2, which use humanize's native SI-decimal interpretation of bare letters.
This file is the only intentional point of divergence between the 1.x and 2.x branches in the toml package — everything else in the package is shared. Do NOT cherry-pick this file across branches.
type SSizeV1 ¶ added in v2.9.0
type SSizeV1 int64
SSizeV1 is like SizeV1 but uses a signed int64, allowing negative values. Callers should reference this type as SSize via the alias in size_alias.go.
func (SSizeV1) MarshalText ¶ added in v2.9.0
MarshalText emits the compact form ("-512m"/"1g") — same backward-compat rationale as SizeV1.
func (SSizeV1) ToInt ¶ added in v2.9.0
ToInt returns the value as an int, or an error wrapping ErrSizeOutOfRange if it does not fit. SSize is int64 so on 32-bit platforms values outside the int32 range cannot be represented as int.
func (SSizeV1) ToUint64 ¶ added in v2.9.0
ToUint64 returns the value as a uint64, or an error wrapping ErrSizeOutOfRange if it is negative.
func (*SSizeV1) UnmarshalText ¶ added in v2.9.0
UnmarshalText parses a signed byte size. Any input matching 1.x's exact accept pattern (optional sign + digits + optional bare k/K/m/M/g/G) goes through strconv + integer multiplication for bit-exact parity with 1.x. Everything else falls through to humanize via parseBytesSigned.
type SSizeV2 ¶ added in v2.9.0
type SSizeV2 int64
SSizeV2 is like SizeV2 but uses a signed int64, allowing negative values.
func (SSizeV2) String ¶ added in v2.9.0
SSizeV2, like SizeV2, deliberately does NOT implement encoding.TextMarshaler. See the comment above SizeV2.String for the full rationale; the short version is that BurntSushi/toml's default int64 encoding preserves exact values, while humanize.IBytes would silently drift non-power-of-2 values across a marshal/unmarshal cycle.
String is humanize-formatted with a sign prepended for negatives. Used for human display only, same as SizeV2.String.
func (*SSizeV2) UnmarshalText ¶ added in v2.9.0
UnmarshalText parses a signed byte size using pure humanize semantics. Negative sign is handled outside humanize (which is unsigned-only).
type Size ¶
type Size = SizeV2
Size and SSize are aliases for the branch-appropriate size-parser implementation. On the 1.x branch they point at SizeV1/SSizeV1, which preserve the historical binary meaning of bare 'k'/'m'/'g' suffixes on top of the richer humanize vocabulary. On the 2.x branch they point at SizeV2/SSizeV2, which use humanize's native SI-decimal interpretation of bare letters.
This file is the only intentional point of divergence between the 1.x and 2.x branches in the toml package — everything else in the package is shared. Do NOT cherry-pick this file across branches.
type SizeV1 ¶ added in v2.9.0
type SizeV1 uint64
SizeV1 represents a TOML-parseable file size using the historical 1.x bare-letter binary suffixes ('k'/'K' = KiB, 'm'/'M' = MiB, 'g'/'G' = GiB) on top of the richer vocabulary from github.com/dustin/go-humanize ("kib", "kb", "tib", "1.5g", etc.). A 1.x bare-letter suffix is detected and rewritten to its explicit IEC form ("1k" → "1 kib") before the string is handed to humanize.
Callers should reference this type as Size via the alias in size_alias.go — SizeV1 is the implementation name so that the 2.x branch can alias Size to SizeV2 (pure humanize) without changing any shared source.
func (SizeV1) MarshalText ¶ added in v2.9.0
MarshalText emits the compact form ("1g"/"512m") that older 1.x influxd releases can still parse. Changing this would break backward compatibility of config files regenerated by `influxd config`.
func (SizeV1) String ¶ added in v2.9.0
String returns the same compact format as MarshalText so pflag help text and written config values stay consistent.
func (SizeV1) ToInt ¶ added in v2.9.0
ToInt returns the value as an int, or an error wrapping ErrSizeOutOfRange if it does not fit. Size is uint64 so it may exceed the representable range of int on any platform (and routinely does on 32-bit platforms). Callers passing a Size to APIs that take int should go through ToInt rather than a bare cast.
func (SizeV1) ToInt64 ¶ added in v2.9.0
ToInt64 returns the value as an int64, or an error wrapping ErrSizeOutOfRange if it does not fit. Size is uint64 so values above math.MaxInt64 silently wrap to negative when cast directly. ToInt64 rejects those instead.
func (SizeV1) Type ¶ added in v2.9.0
Type satisfies pflag.Value. Returns "Size" (not "SizeV1") so pflag help output doesn't leak the branch-specific implementation name.
func (*SizeV1) UnmarshalText ¶ added in v2.9.0
UnmarshalText parses a byte size. Any input matching 1.x's exact accept pattern (digits + optional bare k/K/m/M/g/G) is routed through strconv + integer multiplication for bit-exact parity with 1.x. Everything else falls through to humanize; bare 1.x suffixes reached via whitespace or mixed forms are rewritten to humanize's explicit IEC form ("1k " → "1 kib") before parsing.
type SizeV2 ¶ added in v2.9.0
type SizeV2 uint64
SizeV2 represents a TOML-parseable file size using github.com/dustin/go-humanize as the only parser. Bare 'k'/'m'/'g' mean SI decimal (KB = 1000, MB = 10^6, GB = 10^9); IEC binary units must be spelled explicitly ("kib", "mib", "gib"). See the doc block on String for how the type serializes to TOML.
SizeV2 is defined for both 1.x and 2.x branches so the source stays identical, but is only selected as the active Size alias on the 2.x branch (see size_alias.go).
func (SizeV2) String ¶ added in v2.9.0
SizeV2 deliberately does NOT implement encoding.TextMarshaler. BurntSushi/toml falls back to the underlying uint64 encoding when no TextMarshaler is present, which emits a raw integer (e.g. `cache-max-memory-size = 1073741824`). That matches the wire format used by v2.8.0 and earlier byte-for-byte and, crucially, round-trips exactly: a value like 25_000_000 (the default [http] max-body-size) survives a marshal → unmarshal cycle unchanged.
Emitting a humanized form via humanize.IBytes (e.g. "1.0 GiB") looks nicer but is lossy — humanize.IBytes formats non-power-of-2 values with limited precision, so 25_000_000 would become "24 MiB" and read back as 25_165_824, silently altering the operator's configured limit across an upgrade.
String uses humanize.IBytes, matching v2.8.0's Size.String. It is only used in human-facing contexts (pflag help, log lines); BurntSushi/toml consults TextMarshaler rather than Stringer when encoding, so the lossy conversion in String never reaches the on-disk config.
func (*SizeV2) UnmarshalText ¶ added in v2.9.0
UnmarshalText parses a byte size with pure humanize semantics: bare 'k'/'m'/'g' mean SI decimal (1000-based), IEC binary requires explicit "kib"/"mib"/"gib".
Source Files