settingo

package
v1.7.1 Latest Latest
Warning

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

 Go to latest Published: Feb 21, 2025 License: MIT Imports: 6 Imported by: 8

Documentation

Index

Constants

View Source 
const ITEM_DELIMITER = ";"

ITEM_DELIMITER is the delimiter used to separate key-value map items in a string representation.

When parsing a string into a map using `ParseLineToMap`, this delimiter is used to split the string into individual key-value pairs. For example, in the string "key1:value1,value2;key2:value3", the ITEM_DELIMITER is ";", separating "key1:value1,value2" and "key2:value3" as individual map items.

View Source 
const KEY_SEP = ":"

KEY_SEP is the separator used to separate keys from their values in a string representation of a map.

In `ParseLineToMap` and `ParseMapToLine`, this separator is used to split a key-value pair string into the key and the value string. For example, in "key:value1,value2", KEY_SEP is ":", separating "key" from "value1,value2".

View Source 
const VAL_SEP = ","

VAL_SEP is the separator used to delimit multiple values associated with a key in a string representation of a map.

In `ParseLineToMap` and `ParseMapToLine`, this separator is used to split a string of values into a slice of strings. For example, in "key:value1,value2", VAL_SEP is ",", separating "value1" and "value2".

Variables

View Source 
var SETTINGS = Settings{

	VarString:   make(map[string]string),
	VarInt:      make(map[string]int),
	VarMap:      make(map[string]map[string][]string),
	VarSlice:    make(map[string][]string),
	VarSliceSep: make(map[string]string),
	Parsers:     make(map[string]func(string) string),
	ParsersInt:  make(map[string]func(int) int),
	VarBool:     make(map[string]bool),
	// contains filtered or unexported fields
}

SETTINGS is the global instance of the Settings struct for the settingo package.

It provides a package-level access point to manage application settings. Use the package functions (e.g., settingo.Set, settingo.Get, settingo.Parse) to interact with this global settings registry.

Initialization: 

SETTINGS is initialized with empty maps for all setting types when the package is loaded.
Settings are registered and accessed through the package-level functions.

Example: 

package main

import "path/to/settingo"

func main() {
	settingo.SetString("outputDir", "/tmp", "Directory to write output files")
	settingo.Parse()
	outputDir := settingo.Get("outputDir")
	println("Output directory:", outputDir)
}

Functions

func FlattenMapStrSlice added in v1.2.0 

func FlattenMapStrSlice(ss map[string][]string) []string

FlattenMapStrSlice takes a map[string][]string and returns a flattened slice of unique string values.

It iterates through all values in the input map `ss` (which are slices of strings), and adds each individual string value to a set (using a map[string]bool for efficient uniqueness checking). Finally, it converts the set of unique string values into a slice of strings.

Args: 

ss: The map[string][]string to flatten.

Returns: 

A slice of strings containing all unique values from all string slices in the input map.
The order of items in the returned slice is not guaranteed to be consistent.

Example: 

inputMap := map[string][]string{
	"key1": {"val1", "val2", "val1"}, // "val1" is repeated
	"key2": {"val3", "val4"},
}
flattenedSlice := FlattenMapStrSlice(inputMap)
// flattenedSlice might be []string{"val1", "val2", "val3", "val4"} (order not guaranteed)

func Get added in v1.4.1 

func Get(x string) string

Get retrieves the current string value of a registered string setting from the global SETTINGS instance.

It's a package-level function that delegates to the Get method of the global SETTINGS variable.

Args: 

x: The name of the setting flag to retrieve.

Returns: 

The current string value of the setting from the global SETTINGS instance.

func GetBool added in v1.4.1 

func GetBool(flagName string) bool

GetBool retrieves the current boolean value of a registered boolean setting from the global SETTINGS instance.

It's a package-level function that delegates to the GetBool method of the global SETTINGS variable.

Args: 

flagName: The name of the setting flag to retrieve.

Returns: 

The current boolean value of the setting from the global SETTINGS instance.

func GetInt added in v1.4.1 

func GetInt(flagName string) int

GetInt retrieves the current integer value of a registered integer setting from the global SETTINGS instance.

It's a package-level function that delegates to the GetInt method of the global SETTINGS variable.

Args: 

flagName: The name of the setting flag to retrieve.

Returns: 

The current integer value of the setting from the global SETTINGS instance.

func GetMap added in v1.4.1 

func GetMap(flagName string) map[string][]string

GetMap retrieves the current map value of a registered map setting from the global SETTINGS instance.

It's a package-level function that delegates to the GetMap method of the global SETTINGS variable.

Args: 

flagName: The name of the setting flag to retrieve.

Returns: 

The current map value of the setting from the global SETTINGS instance.

func GetSlice added in v1.5.0 

func GetSlice(flagName string) []string

GetSlice retrieves the current slice value of a registered slice setting from the global SETTINGS instance.

It's a package-level function that delegates to the GetSlice method of the global SETTINGS variable.

Args: 

flagName: The name of the setting flag to retrieve.

Returns: 

The current slice value of the setting from the global SETTINGS instance.

func Parse added in v1.4.1 

func Parse()

Parse parses settings from both OS environment variables and command-line flags using the global SETTINGS instance.

It's a package-level function that delegates to the Parse method of the global SETTINGS variable.

It first calls HandleOSInput() to parse settings from environment variables, and then calls HandleCMDLineInput() to parse command-line flags.

This order ensures that command-line flags take precedence over environment variables if a setting is defined in both sources.

Call this function after registering all settings using the Set... functions to populate the global SETTINGS instance with values from the environment and command line.

func ParseLineToMap added in v1.2.0 

func ParseLineToMap(s string) map[string][]string

ParseLineToMap parses a line string into a map[string][]string.

It expects the input string `s` to be a series of key-value pairs separated by ITEM_DELIMITER (";"). Each key-value pair is expected to be in the format "key:value1,value2,...", as parsed by `parseKeyValue`.

If an item in the string cannot be parsed into a key-value pair (i.e., `parseKeyValue` returns an error), a message is printed to the console indicating the discarded item, and parsing continues with the next item.

Args: 

s: The line string to parse into a map.

Returns: 

A map[string][]string representing the parsed key-value pairs.
Keys are strings, and values are slices of strings.

Example: 

line := "key1:val1,val2;key2:val3;invalid-item"
parsedMap := ParseLineToMap(line)
// parsedMap will be:
// map[string][]string{
//    "key1": {"val1", "val2"},
//    "key2": {"val3"},
// }
// "Settingo: Unable to parse line, discarded: invalid-item" will be printed to console.

func ParseMapToLine added in v1.2.0 

func ParseMapToLine(m map[string][]string) string

ParseMapToLine converts a map[string][]string into a line string representation.

It iterates through the input map `m` and formats each key-value pair into a string "key:value1,value2,...", where values are joined by VAL_SEP (","). These key-value strings are then joined together using ITEM_DELIMITER (";") to form the final line string.

Args: 

m: The map[string][]string to convert to a line string.

Returns: 

A string representation of the map, in the format "key1:value1,value2;key2:value3;...".
Returns an empty string if the input map is empty.

Example: 

inputMap := map[string][]string{
	"key1": {"val1", "val2"},
	"key2": {"val3"},
}
line := ParseMapToLine(inputMap)
// line will be "key1:val1,val2;key2:val3" (order of keys might vary)

func ParseTo added in v1.6.0 

func ParseTo(to interface{})

ParseTo parses settings from environment variables and command-line flags for the global SETTINGS instance and then updates the fields of the provided struct with the parsed values.

It's a package-level function that delegates to the ParseTo method of the global SETTINGS variable.

It performs the following steps:

  1. LoadStruct(to): Registers settings based on the struct fields and "settingo" tags of the input struct 'to'. This effectively declares the settings to be parsed and associates them with struct fields.
  2. Parse(): Parses settings from OS environment variables and command-line flags, populating the global SETTINGS instance's internal storage.
  3. UpdateStruct(to): Updates the fields of the input struct 'to' with the parsed values from the global SETTINGS instance.

This function simplifies the process of configuring an application by directly mapping settings to struct fields.

Args: 

to: A pointer to a struct whose fields will be updated with parsed settings.
    The struct's fields must be exported and can be tagged with "settingo"
    to provide help messages (see LoadStruct for tag usage in Settings type).

func Set added in v1.4.1 

func Set(flagName, defaultVar, message string)

Set is a package-level function to register a string setting within the global SETTINGS instance.

It delegates to the Set method of the global SETTINGS variable. It associates a setting flag name with a default string value and a help message.

Args: 

flagName:   The name of the setting flag (e.g., "port", "output-dir").
defaultVar: The default string value for the setting.
message:    The help message describing the setting's purpose.

func SetBool added in v1.4.1 

func SetBool(flagName string, defaultVar bool, message string)

SetBool is a package-level function to register a boolean setting within the global SETTINGS instance.

It delegates to the SetBool method of the global SETTINGS variable. Registers a boolean setting that can be configured via environment variables or command-line flags.

When set via environment variables or command-line flags, the string values are interpreted as boolean using the truthiness function (see truthiness()).

Args: 

flagName:   The name of the setting flag (e.g., "verbose").
            Used for environment variable lookup and command-line flag parsing.
defaultVar: The default boolean value.
message:    The help message.

Example: 

	settingo.SetBool("verbose", false, "Enable verbose output")

 // Can be set via:
 // - Environment variable: VERBOSE=true or VERBOSE=y or VERBOSE=yes
 // - Command-line flag: --verbose=true or --verbose=y or --verbose=yes

func SetInt added in v1.4.1 

func SetInt(flagName string, defaultVar int, message string)

SetInt is a package-level function to register an integer setting within the global SETTINGS instance.

It delegates to the SetInt method of the global SETTINGS variable. Registers an integer setting that can be configured via environment variables or command-line flags.

Args: 

flagName:   The name of the setting flag (e.g., "port").
            Used for environment variable lookup and command-line flag parsing.
defaultVar: The default integer value.
message:    The help message.

Example: 

	settingo.SetInt("port", 8080, "Port to listen on")

 // Can be set via:
 // - Environment variable: PORT=8081
 // - Command-line flag: --port=8081

func SetMap added in v1.4.1 

func SetMap(flagName string, defaultVar map[string][]string, message string)

SetMap is a package-level function to register a map setting within the global SETTINGS instance.

It delegates to the SetMap method of the global SETTINGS variable. Registers a map setting with string keys and string slice values that can be configured via environment variables or command-line flags.

The map is parsed from a string representation in the format "key1:value1,value2;key2:value3". Keys and values are separated by colons, key-value pairs by semicolons, and values within a key by commas.

Args: 

flagName:   The name of the setting flag (e.g., "headers").
            Used for environment variable lookup and command-line flag parsing.
defaultVar: The default map value.
message:    The help message.

Example: 

	defaultHeaders := map[string][]string{"Content-Type": {"application/json"}, "Accept": {"application/json"}}
	settingo.SetMap("headers", defaultHeaders, "HTTP headers to include")

 // Can be set via:
 // - Environment variable: HEADERS="Content-Type:application/json,text/plain;Accept:application/json"
 // - Command-line flag: --headers="Content-Type:application/json,text/plain;Accept:application/json"

func SetParsed added in v1.4.1 

func SetParsed(flagName, defaultVar, message string, parserFunc func(string) string)

SetParsed is a package-level function to register a string setting with a custom parsing function within the global SETTINGS instance.

It delegates to the SetParsed method of the global SETTINGS variable. Registers a string setting with a custom parsing function.

This is useful when you need to perform custom validation or transformation on the string value obtained from environment variables or command-line flags before using it in your application.

Args: 

flagName:   The name of the setting flag.
defaultVar: The default string value.
message:    The help message.
parserFunc: A function that takes the raw string value (from env or flag)
            and returns a parsed string value. This function will be called
            after retrieving the value from the environment or command line.

Example: 

settingo.SetParsed("username", "default", "Username", func(s string) string {
	if s == "" {
		return "anonymous"
	}
	return strings.ToLower(s)
})

func SetParsedInt added in v1.4.1 

func SetParsedInt(flagName, defaultVar, message string, parserFunc func(int) int)

SetParsedInt is a package-level function to register an integer setting with a custom parsing function within the global SETTINGS instance.

It delegates to the SetParsedInt method of the global SETTINGS variable. Registers an integer setting with a custom parsing function.

This is useful for custom validation or transformation of integer settings. Note that while the setting is treated as an integer internally, the defaultVar is still a string for consistency with command-line flag handling, and the raw value from environment or flag parsing is initially a string.

Args: 

flagName:   The name of the setting flag.
defaultVar: The default string value (will be converted to int if possible).
message:    The help message.
parserFunc: A function that takes the raw integer value (after initial parsing from string)
            and returns a parsed integer value.  Note that the input to this function
            is an int, but the original input from environment/flag was a string.

Example: 

settingo.SetParsedInt("retries", "3", "Number of retries", func(i int) int {
	if i < 0 {
		return 0 // Ensure retries is not negative
	}
	return i
})

func SetSlice added in v1.5.0 

func SetSlice(flagName string, defaultVar []string, message string, sep string)

SetSlice is a package-level function to register a string slice setting within the global SETTINGS instance.

It delegates to the SetSlice method of the global SETTINGS variable. Registers a string slice setting that can be configured via environment variables or command-line flags.

The slice is parsed from a string by splitting it using the provided separator. If no separator is provided, it defaults to a comma ",".

Args: 

flagName:   The name of the setting flag (e.g., "hosts").
            Used for environment variable lookup and command-line flag parsing.
defaultVar: The default slice value.
message:    The help message.
sep:        The separator string used to split the environment variable or
            command-line flag value into a slice of strings. If empty, defaults to ",".

Example: 

	defaultHosts := []string{"localhost", "127.0.0.1"}
	settingo.SetSlice("hosts", defaultHosts, "List of hosts", ",")

 // Can be set via:
 // - Environment variable: HOSTS="host1,host2,host3"
 // - Command-line flag: --hosts="host1,host2,host3"
 // or using a different separator:
 // settingo.SetSlice("ports", []string{"80", "81"}, "Ports to listen on", ";")
 // - Environment variable: PORTS="80;81;82"
 // - Command-line flag: --ports="80;81;82"

func SetString added in v1.4.1 

func SetString(flagName, defaultVar, message string)

SetString is a package-level function to register a string setting within the global SETTINGS instance.

It delegates to the SetString method of the global SETTINGS variable. Registers a string setting that can be configured via environment variables or command-line flags.

Args: 

flagName:   The name of the setting flag (e.g., "output-format").
            This name will be used for both environment variable lookup
            (case-sensitive, typically uppercase) and command-line flag parsing
            (lowercase with hyphens).
defaultVar: The default string value if no environment variable or
            command-line flag is provided.
message:    The help message describing the setting's purpose, shown in
            command-line help output.

Example: 

	settingo.SetString("outputFormat", "json", "Format for output (json|xml)")

 // Can be set via:
 // - Environment variable: OUTPUTFORMAT=xml
 // - Command-line flag: --output-format=xml

Types

type Settings 

type Settings struct {
	VarString   map[string]string
	VarInt      map[string]int
	VarBool     map[string]bool
	VarMap      map[string]map[string][]string
	VarSlice    map[string][]string
	VarSliceSep map[string]string
	Parsers     map[string]func(string) string
	ParsersInt  map[string]func(int) int
	// contains filtered or unexported fields
}

func (Settings) Get 

func (s Settings) Get(flagName string) string

func (Settings) GetBool 

func (s Settings) GetBool(flagName string) bool

func (Settings) GetInt 

func (s Settings) GetInt(flagName string) int

func (Settings) GetMap added in v1.2.0 

func (s Settings) GetMap(flagName string) map[string][]string

func (Settings) GetSlice added in v1.5.0 

func (s Settings) GetSlice(flagName string) []string

func (*Settings) HandleCMDLineInput 

func (s *Settings) HandleCMDLineInput()

func (*Settings) HandleOSInput 

func (s *Settings) HandleOSInput()

func (*Settings) LoadStruct added in v1.6.0 

func (s *Settings) LoadStruct(cfg interface{})

LoadStruct registers a struct's fields with SETTINGS

func (*Settings) Parse 

func (s *Settings) Parse()

func (*Settings) ParseTo added in v1.6.0 

func (s *Settings) ParseTo(to interface{})

func (*Settings) Set 

func (s *Settings) Set(flagName, defaultVar, message string)

func (*Settings) SetBool 

func (s *Settings) SetBool(flagName string, defaultVar bool, message string)

func (*Settings) SetInt 

func (s *Settings) SetInt(flagName string, defaultVar int, message string)

func (*Settings) SetMap added in v1.2.0 

func (s *Settings) SetMap(flagName string, defaultVar map[string][]string, message string)

func (*Settings) SetParsed 

func (s *Settings) SetParsed(flagName, defaultVar, message string, parserFunc func(string) string)

func (*Settings) SetParsedInt 

func (s *Settings) SetParsedInt(flagName, defaultVar, message string, parserFunc func(int) int)

func (*Settings) SetSlice added in v1.5.0 

func (s *Settings) SetSlice(flagName string, defaultVar []string, message string, sep string)

func (*Settings) SetString 

func (s *Settings) SetString(flagName, defaultVar, message string)

func (*Settings) UpdateStruct added in v1.6.0 

func (s *Settings) UpdateStruct(cfg interface{})

UpdateStruct updates a struct with values from SETTINGS after Parse()

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.