parse

package
v0.4.0-rc2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 21, 2023 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package parse provides generic functions to parse values from strings found from given sources interfaces. It essentially exists due to its use of generics, where its sibling package reader is not using generics.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrValueNotInRange = errors.New("value is not in range")
)

Functions

func BoolPtr 

func BoolPtr(sources []Source, key string, options ...Option) (
	boolPtr *bool, err error)

BoolPtr returns a pointer to a `bool` from the first value found at the given key in the given sources in order.

  • 'true' string values are: "enabled", "yes", "on", "true".
  • 'false' string values are: "disabled", "no", "off", "false".

The value is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

Otherwise, if the value is not one of the above, an error is returned with the key name and source name in its message.

func CSV 

func CSV(sources []Source, key string,
	options ...Option) (values []string)

CSV returns a slice of strings from the first comma separated value found from the given sources in order. The entire CSV string value may be modified depending on the parse default settings and the parse options given. The parse default settings are to:

  • Trim line endings suffixes \r\n and \n.
  • Trim spaces.
  • Trim quotes.
  • Force lowercase.

The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and its corresponding value is empty.

func CSVInt 

func CSVInt(sources []Source, key string,
	options ...Option) (values []int, err error)

CSVInt returns a slice of int from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid int string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVInt8 

func CSVInt8(sources []Source, key string,
	options ...Option) (values []int8, err error)

CSVInt8 returns a slice of int8 from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid int8 string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVInt16 

func CSVInt16(sources []Source, key string,
	options ...Option) (values []int16, err error)

CSVInt16 returns a slice of int16 from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid int16 string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVInt32 

func CSVInt32(sources []Source, key string,
	options ...Option) (values []int32, err error)

CSVInt32 returns a slice of int32 from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid int32 string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVInt64 

func CSVInt64(sources []Source, key string,
	options ...Option) (values []int64, err error)

CSVInt64 returns a slice of int64 from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid int64 string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVNetipAddresses 

func CSVNetipAddresses(sources []Source, key string,
	options ...Option) (prefixes []netip.Addr, err error)

CSVNetipAddresses returns a slice of netip.Addr from the first comma separated string value found at the given key from the given sources in order, and returns an error if any value is not a valid netip.Addr string.

The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and its corresponding value is empty.

The entire CSV string value may be modified depending on the parse default settings and the parse options given. The parse default settings are to:

  • Trim line endings suffixes \r\n and \n.
  • Trim spaces.
  • Trim quotes.
  • Force lowercase.

func CSVNetipPrefixes 

func CSVNetipPrefixes(sources []Source, key string,
	options ...Option) (prefixes []netip.Prefix, err error)

CSVNetipPrefixes returns a slice of netip.Prefix from the first comma separated string value found at the given key from the given sources in order, and returns an error if any value is not a valid netip.Prefix string.

The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and its corresponding value is empty.

The entire CSV string value may be modified depending on the parse default settings and the parse options given. The parse default settings are to:

  • Trim line endings suffixes \r\n and \n.
  • Trim spaces.
  • Trim quotes.
  • Force lowercase.

func CSVParse 

func CSVParse[T any](sources []Source, key string,
	parse ParseFunc[T], options ...Option) (values []T, err error)

CSVParse returns a slice of type T from the first comma separated string value found at the given key in the given sources in order. Each comma separated values is parsed using the provided `parse` function. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVUint 

func CSVUint(sources []Source, key string,
	options ...Option) (values []uint, err error)

CSVUint returns a slice of uint from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid uint string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVUint8 

func CSVUint8(sources []Source, key string,
	options ...Option) (values []uint8, err error)

CSVUint8 returns a slice of uint8 from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid uint8 string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVUint16 

func CSVUint16(sources []Source, key string,
	options ...Option) (values []uint16, err error)

CSVUint16 returns a slice of uint8 from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid uint8 string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVUint32 

func CSVUint32(sources []Source, key string,
	options ...Option) (values []uint32, err error)

CSVUint32 returns a slice of uint32 from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid uint32 string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func CSVUint64 

func CSVUint64(sources []Source, key string,
	options ...Option) (values []uint64, err error)

CSVUint64 returns a slice of uint64 from the first comma separated string value found at the given key in the given sources in order. It returns an error if any value is not a valid uint64 string. The slice is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set and the corresponding value is empty.

func Duration 

func Duration(sources []Source, key string,
	options ...Option) (duration time.Duration, err error)

Duration returns a `time.Duration` parsed from the first value found at the given key from the given sources in order. If the value is not a valid time.Duration string, an error is returned with the source name and key in its message. The value is returned as `0` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

func DurationPtr 

func DurationPtr(sources []Source, key string,
	options ...Option) (durationPtr *time.Duration, err error)

DurationPtr returns a pointer to a `time.Duration` from the first value found at the given key from the given sources in order. If the value is not a valid time.Duration string, an error is returned with the source name and key in its message. The value is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

func Float64 

func Float64(sources []Source, key string,
	options ...Option) (f float64, err error)

Float64 returns a `float64` from the first value found at the given key in the given sources in order. If the value is not a valid float64 string, an error is returned with the key name and the source name in its message. The value is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

func Get 

func Get(sources []Source, key string, options ...Option) (value *string)

Get returns the first value found at the given key from the given sources in order, as a string pointer.

The value is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set in one of the sources and its corresponding value is empty.

Otherwise, the value may be modified depending on the parse default settings and the parse options given.

The parse default settings are to:

  • Trim line endings suffixes \r\n and \n.
  • Trim spaces.
  • Trim quotes.
  • Force lowercase.

func GetParse 

func GetParse[T any](sources []Source, key string,
	parse ParseFunc[T], options ...Option) (value T, err error)

GetParse parses the first value found at the given key from the given sources in order, using the given parse function, and returns the typed parsed value with an eventual error containing the key name and the source name in its message.

The value is returned as the empty `T` value if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set in a source and its corresponding value is empty.

Note the value from the map may be modified depending on the parse default settings and the parse options given.

The parse default settings are to:

  • Trim line endings suffixes \r\n and \n.
  • Trim spaces.
  • Trim quotes.
  • Force lowercase.

func GetParsePtr 

func GetParsePtr[T any](sources []Source, key string,
	parse ParseFunc[T], options ...Option) (value *T, err error)

GetParsePtr parses the first value found at the given key from the given sources in order, using the given parse function, and returns the typed pointer to the parsed value with an eventual error which contains the key name and source name in its message.

The value is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AcceptEmpty option, if the key is set in the mapping and its corresponding value is empty.

Note the value from the map may be modified depending on the parse default settings and the parse options given.

The parse default settings are to:

  • Trim line endings suffixes \r\n and \n.
  • Trim spaces.
  • Trim quotes.
  • Force lowercase.

func Int 

func Int(sources []Source, key string,
	options ...Option) (n int, err error)

Int returns an `int` from the first value found at the given key in the given sources in order. If the value is not a valid integer string, an error is returned with the key name and the source name in its message. The value is returned as `0` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

func IntPtr 

func IntPtr(sources []Source, key string, options ...Option) (
	intPtr *int, err error)

IntPtr returns a pointer to an `int` from the first value found at the given key in the given sources in order. If the value is not a valid integer string, an error is returned with the key name and source name in its message. The value is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

func NetipAddr 

func NetipAddr(sources []Source, key string,
	options ...Option) (addr netip.Addr, err error)

NetipAddr returns a netip.Addr from the first value found at the given key from the given sources in order. If the value is not a valid netip.Addr string, an error is returned with the source and key in its message. The value is returned as the empty invalid `netip.Addr{}` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

func String 

func String(sources []Source, key string,
	options ...Option) (value string)

String returns the first string value found at the given key from the given sources in order. The value may be modified depending on the parse default settings and the parse options given. The parse default settings are to:

  • Trim line endings suffixes \r\n and \n.
  • Trim spaces.
  • Trim quotes.
  • Force lowercase.

If the key is not set in any of the sources, the empty string is returned.

func Uint8Ptr 

func Uint8Ptr(sources []Source, key string, options ...Option) (
	uint8Ptr *uint8, err error)

Uint8Ptr returns a pointer to an `uint8` from the first value found at the given key in the given sources in order. If the value is not a valid integer string between 0 and 255, an error is returned with the key name and source name in its message. The value is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

func Uint16Ptr 

func Uint16Ptr(sources []Source, key string, options ...Option) (
	uint16Ptr *uint16, err error)

Uint16Ptr returns a pointer to an `uint16` from the first value found at the given key in the given sources in order. If the value is not a valid integer string between 0 and 65535, an error is returned with the key name and source name in its message. The value is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

func Uint32Ptr 

func Uint32Ptr(sources []Source, key string, options ...Option) (
	uint32Ptr *uint32, err error)

Uint32Ptr returns a pointer to an `uint32` from the first value found at the given key in the given sources in order. If the value is not a valid integer string between 0 and 4294967295, an error is returned with the key name and source name in its message. The value is returned as `nil` if:

  • the key given is NOT set in any of the sources.
  • By default and unless changed by the AllowEmpty option, if the key is set and its corresponding value is empty.

Types

type Option 

type Option func(s *settings)

Option is an option to modify the behavior of the underlying `get` function which is called by all the other functions.

func AcceptEmpty 

func AcceptEmpty(accept bool) Option

AcceptEmpty, if set to true, makes the code distinguish between unset keys and empty values from a given source. By default, the code does not distinguish between the two cases.

func ForceLowercase 

func ForceLowercase(lowercase bool) Option

ForceLowercase forces the string values read from any source given to be lowercased or not, depending on the `lowercase` argument given.

func RetroKeys 

func RetroKeys(handleDeprecatedKey func(source, deprecateKey, currentKey string),
	deprecatedKeys ...string) Option

RetroKeys specifies a list of keys that are deprecated and replaced by the current key. The oldest deprecated key should be placed first in the list of deprecated keys, so it gets checked first, which is especially important if for example default variable values are set in the program or operating system matching more recent keys. The `handleDeprecatedKey` function is called when a deprecated key is used, with the source name, the deprecated key and the current key as arguments.

type ParseFunc 

type ParseFunc[T any] func(value string) (x T, err error)

ParseFunc is a function that parses a string into a value of type T and returns an error if the parsing failed.

type Source 

type Source interface {
	// String can return for example 'environment variable' or 'flag'
	String() string
	// Get returns the value of the key and whether it is set.
	Get(key string) (value string, isSet bool)
	// KeyTransform transforms a standardized key to a key specific to
	// the source. For example SERVER_ADDRESS becomes server-address for
	// the flags source.
	KeyTransform(key string) string
}

Source is a named key-value source.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.