Documentation
¶
Overview ¶
Package ffval provides common flag value types and helpers.
Value represents a single instance of any type T that can be parsed from a string. The package defines a set of values for common types, like Bool, String, Duration, etc.
List and UniqueList represent a sequence of values of type T, where each call to set adds a value to the end of the list. Enum represents one of a specific set of values of type T.
Index ¶
- Variables
- func DefaultStringFunc[T any](vals []T) string
- func NewValueReflect(ptr any, def string) (flag.Value, error)
- type Bool
- type Complex128
- type Complex64
- type Duration
- type Enum
- type Float32
- type Float64
- type Int
- type Int16
- type Int32
- type Int64
- type Int8
- type List
- type String
- type StringList
- type StringSet
- type Uint
- type Uint16
- type Uint32
- type Uint64
- type Uint8
- type UniqueList
- type Value
- type ValueType
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidValue = errors.New("invalid value")
ErrInvalidValue is returned when a value is set with invalid input.
Functions ¶
func DefaultStringFunc ¶
DefaultStringFunc is used by List and UniqueList if no StringFunc is explicitly provided. Each value is rendered to a string via fmt.Sprint, and the strings are joined via strings.Join with a separator of ", ".
func NewValueReflect ¶
NewValueReflect produces a simple flag.Value which updates ptr when set. ptr must be a pointer to a supported ValueType. If def is non-empty, the flag will be set to that default string before being returned. Otherwise, the default value of the flag will be the zero value of the type.
This is a fairly low-level function, which exists mainly to support parsing struct tags. Most consumers should not need to use it.
Types ¶
type Bool ¶
Bool is a flag value representing a bool. Values are parsed by strconv.ParseBool.
type Complex128 ¶
type Complex128 = Value[complex128]
Complex128 is a flag value representing a complex128. Values are parsed by strconv.ParseComplex.
type Complex64 ¶
Complex64 is a flag value representing a complex64. Values are parsed by strconv.ParseComplex.
type Duration ¶
Duration is a flag value representing a time.Duration. Values are parsed by time.ParseDuration.
type Enum ¶
type Enum[T comparable] struct { // ParseFunc parses a string to the type T. If no ParseFunc is provided, and // T is a supported [ValueType], then a default ParseFunc will be assigned // lazily. If no ParseFunc is provided, and T is not a supported // [ValueType], then most method calls will panic. ParseFunc func(string) (T, error) // Valid is the set of acceptable values. An enum with no valid values is // itself invalid, and all methods will panic. Valid []T // Pointer is the actual instance of the type T which is managed and updated // by the value. If no Pointer is provided, a new T is allocated lazily. For // this reason, callers should generally access the pointer via GetPointer, // rather than reading the field directly. Pointer *T // Default value of the enum. If the default value isn't valid, it will be // set to the first valid value lazily. For this reason, callers should // generally access the default via GetDefault, rather than reading the // field directly. Default T // contains filtered or unexported fields }
Enum is a generic flag.Value that represents one of a fixed set of possible values of any comparable type T. An enum must have at least one valid value, or it is itself invalid. For this reason, the zero value of an enum is not useful, and calling most methods on a zero-value enum will panic.
func NewEnum ¶
NewEnum returns an enum of ValueType T, updating the given pointer ptr when set, and which will accept only the provided valid values. At least one valid value is required, or else the function will panic.
func NewEnumParser ¶
func NewEnumParser[T comparable](parseFunc func(string) (T, error), valid ...T) *Enum[T]
NewEnumParser returns an enum of any comparable type T that can be parsed from a string, and which will accept only the provided valid values. At least one valid value is required, or else the function will panic.
This constructor is intended as a convenience function for tests; consumers who want to provide a parser are probably better served by constructing an enum directly, so that they can also provide other fields in a single motion.
func (*Enum[T]) GetPointer ¶
func (v *Enum[T]) GetPointer() *T
GetPointer returns a pointer to the underlying value.
type Float32 ¶
Float32 is a flag value representing a float32. Values are parsed by strconv.ParseFloat.
type Float64 ¶
Float64 is a flag value representing a float64. Values are parsed by strconv.ParseFloat.
type Int ¶
Int is a flag value representing an int. Values are parsed by strconv.Atoi.
type Int16 ¶
Int16 is a flag value representing an int16. Values are parsed by strconv.ParseInt.
type Int32 ¶
Int32 is a flag value representing an int32. Values are parsed by strconv.ParseInt.
type Int64 ¶
Int64 is a flag value representing an int64. Values are parsed by strconv.ParseInt.
type Int8 ¶
Int8 is a flag value representing an int8. Values are parsed by strconv.ParseInt.
type List ¶
type List[T any] struct { // ParseFunc parses a string to the type T. If no ParseFunc is provided, and // T is a supported [ValueType], then a default ParseFunc will be assigned // lazily. If no ParseFunc is provided, and T is not a supported // [ValueType], then most method calls will panic. ParseFunc func(string) (T, error) // Pointer is the actual slice of type T which is managed and updated by the // list. If no Pointer is provided, a new slice is allocated lazily. For // this reason, callers should generally access the pointer via GetPointer, // rather than reading the field directly. Pointer *[]T // StringFunc is used by the String method to transform the underlying slice // of T to a string. If no StringFunc is provided, [DefaultStringFunc] is // used. StringFunc func([]T) string // contains filtered or unexported fields }
List is a generic flag.Value that represents an ordered list of values. Every call to Set adds the successfully parsed value to the end of the list. To prevent duplicate values, see UniqueList.
func NewList ¶
NewList returns a list of underlying ValueType T, which updates the given pointer ptr when set.
func NewListParser ¶
NewListParser returns a list of any type T that can be parsed from a string.
This constructor is intended as a convenience function for tests; consumers who want to provide a parser are probably better served by constructing a list directly, so that they can also provide other fields in a single motion.
func (*List[T]) GetPointer ¶
func (v *List[T]) GetPointer() *[]T
GetPointer returns a pointer to the underlying slice of T.
type StringList ¶
StringList is a flag value representing a sequence of strings.
type StringSet ¶
type StringSet = UniqueList[string]
StringSet is a flag value representing a unique set of strings.
type Uint ¶
Uint is a flag value representing a uint. Values are parsed by strconv.ParseUint.
type Uint16 ¶
Uint16 is a flag value representing a uint16. Values are parsed by strconv.ParseUint.
type Uint32 ¶
Uint32 is a flag value representing a uint32. Values are parsed by strconv.ParseUint.
type Uint64 ¶
Uint64 is a flag value representing a uint64. Values are parsed by strconv.ParseUint.
type Uint8 ¶
Uint8 is a flag value representing a uint8. Values are parsed by strconv.ParseUint.
type UniqueList ¶
type UniqueList[T comparable] struct { // ParseFunc parses a string to the type T. If no ParseFunc is provided, and // T is a supported [ValueType], then a default ParseFunc will be assigned // lazily. If no ParseFunc is provided, and T is not a supported // [ValueType], then most method calls will panic. ParseFunc func(string) (T, error) // Pointer is the actual slice of type T which is managed and updated by the // list. If no Pointer is provided, a new slice is allocated lazily. Pointer *[]T // StringFunc is used by the String method to transform the underlying slice // of T to a string. If no StringFunc is provided, [DefaultStringFunc] is // used. StringFunc func([]T) string // ErrDuplicate is returned by Set when it detects a duplicate value. By // default, ErrDuplicate is nil, so duplicate values are silently dropped. ErrDuplicate error // contains filtered or unexported fields }
UniqueList is a List that doesn't allow duplicate values.
func NewUniqueList ¶
func NewUniqueList[T ValueType](ptr *[]T) *UniqueList[T]
NewUniqueList returns a unique list of underlying ValueType T, which updates the given pointer ptr when set.
func NewUniqueListParser ¶
func NewUniqueListParser[T comparable](parseFunc func(string) (T, error)) *UniqueList[T]
NewUniqueListParser returns a unique list of any comparable type T that can be parsed from a string.
This constructor is intended as a convenience function for tests; consumers who want to provide a parser are probably better served by constructing a unique list directly, so that they can also provide other fields in a single motion.
func (*UniqueList[T]) GetPointer ¶
func (v *UniqueList[T]) GetPointer() *[]T
GetPointer returns a pointer to the underlying slice of T.
func (*UniqueList[T]) IsSet ¶
func (v *UniqueList[T]) IsSet() bool
IsSet returns true if the list has been explicitly set.
func (*UniqueList[T]) Reset ¶
func (v *UniqueList[T]) Reset() error
Reset the list of values to its default (empty) state.
func (*UniqueList[T]) Set ¶
func (v *UniqueList[T]) Set(s string) error
Set parses the given string, and appends the successfully parsed value to the list. If the value already exists in the list, Set returns the UniqueList's ErrDuplicate field, which is nil by default.
func (*UniqueList[T]) String ¶
func (v *UniqueList[T]) String() string
String returns a string representation of the list of values.
type Value ¶
type Value[T any] struct { // ParseFunc parses a string to the type T. If no ParseFunc is provided, and // T is a supported [ValueType], then a default ParseFunc will be assigned // lazily. If no ParseFunc is provided, and T is not a supported // [ValueType], then most method calls will panic. ParseFunc func(string) (T, error) // Pointer is the actual instance of the type T which is managed and updated // by the value. If no Pointer is provided, a new T is allocated lazily. For // this reason, callers should generally access the pointer via GetPointer, // rather than reading the field directly. Pointer *T // Default value, which is the zero value of the type T by default. Default T // contains filtered or unexported fields }
Value is a generic flag.Value that can be set from a string.
Most consumers should probably not need to use a value directly, and can instead use one of the specific value types defined by this package, like String or Duration.
func NewValue ¶
NewValue returns a Value of underlying ValueType T, which updates the given pointer ptr when set, and which has a default value of the zero value of the type T.
func NewValueDefault ¶
NewValueDefault returns a value of underlying ValueType T, which updates the given pointer ptr when set, and which has the given default value def.
func NewValueParser ¶
NewValueParser returns a value for any type T that can be parsed from a string.
This constructor is intended as a convenience function for tests; consumers who want to provide a parser are probably better served by constructing a value directly, so that they can also provide other fields in a single motion.
func (*Value[T]) GetPointer ¶
func (v *Value[T]) GetPointer() *T
GetPointer returns a pointer to the underlying instance of type T which is managed by this value.
func (Value[T]) IsBoolFlag ¶
IsBoolFlag returns true if the underlying type T is bool.
type ValueType ¶
type ValueType interface {
bool | int | int8 | int16 | int32 | int64 | uint | uint8 | uint16 | uint32 | uint64 | float32 | float64 | string | complex64 | complex128 | time.Duration
}
ValueType is a generic type constraint for a specific set of primitive types that are natively supported by this package. Each of them has a default parser, which will be used if a parser is not explicitly provided by the user. This permits the zero value of corresponding generic types to be useful, which in turn allows this package to provide common and useful types like Bool, Duration, StringSet, etc.
Source Files