Documentation
¶
Index ¶
- type Optional
- func (o *Optional[T]) Get() *T
- func (o *Optional[T]) GetOrInsertDefault() *T
- func (o Optional[T]) HasValue() bool
- func (o Optional[T]) Marshal(conf *confmap.Conf) error
- func (o Optional[T]) MarshalScalar(scalarValue confmap.ScalarValue) error
- func (o *Optional[T]) Unmarshal(conf *confmap.Conf) error
- func (o *Optional[T]) UnmarshalScalar(scalarValue confmap.ScalarValue) error
- func (o *Optional[T]) Validate() error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Optional ¶
type Optional[T any] struct { // contains filtered or unexported fields }
Optional represents a value that may or may not be present. It supports two flavors for all types: Some(value) and None. It supports a third flavor for struct types: Default(defaultVal).
For struct types, it supports unmarshaling from a configuration source. For struct types, it supports an 'enabled' field to explicitly disable a section. The zero value of Optional is None.
func Default ¶
Default creates an Optional with a default value for unmarshaling.
It panics if T has a field with the mapstructure tag "enabled".
Example ¶
type Person struct {
Name string
Age int
}
opt := Default(Person{
Name: "John Doe",
Age: 42,
})
// A Default has no value.
fmt.Println(opt.HasValue())
fmt.Println(opt.Get())
// GetOrInsertDefault places the default value
// and returns it, allowing you to modify it.
opt.GetOrInsertDefault().Age = 38
fmt.Println(opt.HasValue())
fmt.Println(opt.Get())
Output: false <nil> true &{John Doe 38}
func None ¶
None has no value. It has the same behavior as a nil pointer when unmarshaling.
The zero value of Optional[T] is None[T]. Prefer using this constructor for validation.
It panics if T has a field with the mapstructure tag "enabled".
Example ¶
type Person struct {
Name string
Age int
}
opt := None[Person]()
// A None has no value.
fmt.Println(opt.HasValue())
fmt.Println(opt.Get())
// GetOrInsertDefault places the zero value
// and returns it, allowing you to modify it.
opt.GetOrInsertDefault().Name = "John Doe"
fmt.Println(opt.HasValue())
fmt.Println(opt.Get())
Output: false <nil> true &{John Doe 0}
func Some ¶
Some creates an Optional with a value and no factory.
It panics if T has a field with the mapstructure tag "enabled".
Example ¶
type Person struct {
Name string
Age int
}
opt := Some(Person{
Name: "John Doe",
Age: 42,
})
// A Some has a value.
fmt.Println(opt.HasValue())
fmt.Println(opt.Get())
// GetOrInsertDefault only returns a reference
// to the inner value without modifying it.
opt.GetOrInsertDefault().Name = "Jane Doe"
fmt.Println(opt.HasValue())
fmt.Println(opt.Get())
Output: true &{John Doe 42} true &{Jane Doe 42}
func (*Optional[T]) Get ¶
func (o *Optional[T]) Get() *T
Get returns the value of the Optional. If the value is not present, it returns nil.
func (*Optional[T]) GetOrInsertDefault ¶ added in v0.136.0
func (o *Optional[T]) GetOrInsertDefault() *T
GetOrInsertDefault makes the Optional into a Some(val) and returns val.
In particular, if it is Default(val) it turns it into Some(val) and if it is None[T]() it turns it into Some(zeroVal) where zeroVal is T's zero value. This method is useful for programmatic usage of an optional.
It panics if - T is not a struct OR - T has a field with the mapstructure tag "enabled".
func (Optional[T]) Marshal ¶ added in v0.129.0
Marshal the Optional value into the configuration. If the Optional is None or Default, it does not marshal anything. If the Optional is Some, it marshals the value into the configuration.
T must be dereferenceable to a type with struct kind. Scalar values are not supported, and will be handled by [MarshalScalar] instead. We do not need to check this since the hook for [ScalarMarshaler] will be called before the hook for [Marshaler].
func (Optional[T]) MarshalScalar ¶ added in v1.59.0
func (o Optional[T]) MarshalScalar(scalarValue confmap.ScalarValue) error
func (*Optional[T]) Unmarshal ¶
Unmarshal the configuration into the Optional value.
The behavior of this method depends on the state of the Optional:
- None[T]: does nothing if the configuration is nil, otherwise it unmarshals into the zero value of T.
- Some[T](val): equivalent to unmarshaling into a field of type T with value val.
- Default[T](val), equivalent to unmarshaling into a field of type T with base value val, using val without overrides from the configuration if the configuration is nil.
(Under the `configoptional.AddEnabledField` feature gate) If the configuration contains an 'enabled' field:
- if enabled is true: the Optional becomes Some after unmarshaling.
- if enabled is false: the Optional becomes None regardless of other configuration values.
T must be dereferenceable to a type with struct kind and not have an 'enabled' field. Scalar values are not supported, and will be handled by [UnmarshalScalar] instead. We do not need to check this since the hook for [ScalarUnmarshaler] will be called before the hook for [Unmarshaler].
func (*Optional[T]) UnmarshalScalar ¶ added in v1.59.0
func (o *Optional[T]) UnmarshalScalar(scalarValue confmap.ScalarValue) error
UnmarshalScalar unmarshals a scalar value into the Optional.
A `nil` value will set the Optional to None, disabling it as setting `enabled: false` for a struct-type Optional or `null` for a pointer field would.
func (*Optional[T]) Validate ¶ added in v0.133.0
Validate implements confmap.Validator. This is required because the private fields in confmap.Validator can't be seen by the reflection used by confmap.Validate, and therefore we have to continue the validation chain manually. This method isn't meant to be called directly, and should generally only be called by confmap.Validate.
Source Files