Skip to content

Commit 0f12a9e

Browse files
AttummAttumm
committed
Added initial code docs
1 parent 444bbd0 commit 0f12a9e

File tree

2 files changed

+410
-4
lines changed

2 files changed

+410
-4
lines changed

‎settingo/settingo.go

+294
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,28 @@
11
package settingo
22

3+
// SETTINGS is the global instance of the Settings struct for the settingo package.
4+
//
5+
// It provides a package-level access point to manage application settings.
6+
// Use the package functions (e.g., settingo.Set, settingo.Get, settingo.Parse)
7+
// to interact with this global settings registry.
8+
//
9+
// Initialization:
10+
//
11+
// SETTINGS is initialized with empty maps for all setting types when the package is loaded.
12+
// Settings are registered and accessed through the package-level functions.
13+
//
14+
// Example:
15+
//
16+
// package main
17+
//
18+
// import "path/to/settingo"
19+
//
20+
// func main() {
21+
// settingo.SetString("outputDir", "/tmp", "Directory to write output files")
22+
// settingo.Parse()
23+
// outputDir := settingo.Get("outputDir")
24+
// println("Output directory:", outputDir)
25+
// }
326
var SETTINGS = Settings{
427
msg: make(map[string]string),
528
VarString: make(map[string]string),
@@ -11,60 +34,331 @@ var SETTINGS = Settings{
1134
VarBool: make(map[string]bool),
1235
}
1336

37+
// Get retrieves the current string value of a registered string setting from the global SETTINGS instance.
38+
//
39+
// It's a package-level function that delegates to the Get method of the global SETTINGS variable.
40+
//
41+
// Args:
42+
//
43+
// x: The name of the setting flag to retrieve.
44+
//
45+
// Returns:
46+
//
47+
// The current string value of the setting from the global SETTINGS instance.
1448
func Get(x string) string {
1549
return SETTINGS.Get(x)
1650
}
51+
52+
// Set is a package-level function to register a string setting within the global SETTINGS instance.
53+
//
54+
// It delegates to the Set method of the global SETTINGS variable.
55+
// It associates a setting flag name with a default string value and a help message.
56+
//
57+
// Args:
58+
//
59+
// flagName: The name of the setting flag (e.g., "port", "output-dir").
60+
// defaultVar: The default string value for the setting.
61+
// message: The help message describing the setting's purpose.
1762
func Set(flagName, defaultVar, message string) {
1863
SETTINGS.Set(flagName, defaultVar, message)
1964
}
2065

66+
// SetString is a package-level function to register a string setting within the global SETTINGS instance.
67+
//
68+
// It delegates to the SetString method of the global SETTINGS variable.
69+
// Registers a string setting that can be configured via environment variables or command-line flags.
70+
//
71+
// Args:
72+
//
73+
// flagName: The name of the setting flag (e.g., "output-format").
74+
// This name will be used for both environment variable lookup
75+
// (case-sensitive, typically uppercase) and command-line flag parsing
76+
// (lowercase with hyphens).
77+
// defaultVar: The default string value if no environment variable or
78+
// command-line flag is provided.
79+
// message: The help message describing the setting's purpose, shown in
80+
// command-line help output.
81+
//
82+
// Example:
83+
//
84+
// settingo.SetString("outputFormat", "json", "Format for output (json|xml)")
85+
//
86+
// // Can be set via:
87+
// // - Environment variable: OUTPUTFORMAT=xml
88+
// // - Command-line flag: --output-format=xml
2189
func SetString(flagName, defaultVar, message string) {
2290
SETTINGS.Set(flagName, defaultVar, message)
2391
}
2492

93+
// SetInt is a package-level function to register an integer setting within the global SETTINGS instance.
94+
//
95+
// It delegates to the SetInt method of the global SETTINGS variable.
96+
// Registers an integer setting that can be configured via environment variables or command-line flags.
97+
//
98+
// Args:
99+
//
100+
// flagName: The name of the setting flag (e.g., "port").
101+
// Used for environment variable lookup and command-line flag parsing.
102+
// defaultVar: The default integer value.
103+
// message: The help message.
104+
//
105+
// Example:
106+
//
107+
// settingo.SetInt("port", 8080, "Port to listen on")
108+
//
109+
// // Can be set via:
110+
// // - Environment variable: PORT=8081
111+
// // - Command-line flag: --port=8081
25112
func SetInt(flagName string, defaultVar int, message string) {
26113
SETTINGS.SetInt(flagName, defaultVar, message)
27114
}
28115

116+
// SetBool is a package-level function to register a boolean setting within the global SETTINGS instance.
117+
//
118+
// It delegates to the SetBool method of the global SETTINGS variable.
119+
// Registers a boolean setting that can be configured via environment variables or command-line flags.
120+
//
121+
// When set via environment variables or command-line flags, the string values
122+
// are interpreted as boolean using the truthiness function (see truthiness()).
123+
//
124+
// Args:
125+
//
126+
// flagName: The name of the setting flag (e.g., "verbose").
127+
// Used for environment variable lookup and command-line flag parsing.
128+
// defaultVar: The default boolean value.
129+
// message: The help message.
130+
//
131+
// Example:
132+
//
133+
// settingo.SetBool("verbose", false, "Enable verbose output")
134+
//
135+
// // Can be set via:
136+
// // - Environment variable: VERBOSE=true or VERBOSE=y or VERBOSE=yes
137+
// // - Command-line flag: --verbose=true or --verbose=y or --verbose=yes
29138
func SetBool(flagName string, defaultVar bool, message string) {
30139
SETTINGS.SetBool(flagName, defaultVar, message)
31140
}
32141

142+
// SetMap is a package-level function to register a map setting within the global SETTINGS instance.
143+
//
144+
// It delegates to the SetMap method of the global SETTINGS variable.
145+
// Registers a map setting with string keys and string slice values
146+
// that can be configured via environment variables or command-line flags.
147+
//
148+
// The map is parsed from a string representation in the format "key1:value1,value2;key2:value3".
149+
// Keys and values are separated by colons, key-value pairs by semicolons, and values within a key by commas.
150+
//
151+
// Args:
152+
//
153+
// flagName: The name of the setting flag (e.g., "headers").
154+
// Used for environment variable lookup and command-line flag parsing.
155+
// defaultVar: The default map value.
156+
// message: The help message.
157+
//
158+
// Example:
159+
//
160+
// defaultHeaders := map[string][]string{"Content-Type": {"application/json"}, "Accept": {"application/json"}}
161+
// settingo.SetMap("headers", defaultHeaders, "HTTP headers to include")
162+
//
163+
// // Can be set via:
164+
// // - Environment variable: HEADERS="Content-Type:application/json,text/plain;Accept:application/json"
165+
// // - Command-line flag: --headers="Content-Type:application/json,text/plain;Accept:application/json"
33166
func SetMap(flagName string, defaultVar map[string][]string, message string) {
34167
SETTINGS.SetMap(flagName, defaultVar, message)
35168
}
36169

170+
// SetSlice is a package-level function to register a string slice setting within the global SETTINGS instance.
171+
//
172+
// It delegates to the SetSlice method of the global SETTINGS variable.
173+
// Registers a string slice setting that can be configured via environment variables or command-line flags.
174+
//
175+
// The slice is parsed from a string by splitting it using the provided separator.
176+
// If no separator is provided, it defaults to a comma ",".
177+
//
178+
// Args:
179+
//
180+
// flagName: The name of the setting flag (e.g., "hosts").
181+
// Used for environment variable lookup and command-line flag parsing.
182+
// defaultVar: The default slice value.
183+
// message: The help message.
184+
// sep: The separator string used to split the environment variable or
185+
// command-line flag value into a slice of strings. If empty, defaults to ",".
186+
//
187+
// Example:
188+
//
189+
// defaultHosts := []string{"localhost", "127.0.0.1"}
190+
// settingo.SetSlice("hosts", defaultHosts, "List of hosts", ",")
191+
//
192+
// // Can be set via:
193+
// // - Environment variable: HOSTS="host1,host2,host3"
194+
// // - Command-line flag: --hosts="host1,host2,host3"
195+
// // or using a different separator:
196+
// // settingo.SetSlice("ports", []string{"80", "81"}, "Ports to listen on", ";")
197+
// // - Environment variable: PORTS="80;81;82"
198+
// // - Command-line flag: --ports="80;81;82"
37199
func SetSlice(flagName string, defaultVar []string, message string, sep string) {
38200
SETTINGS.SetSlice(flagName, defaultVar, message, sep)
39201
}
40202

203+
// SetParsed is a package-level function to register a string setting with a custom parsing function within the global SETTINGS instance.
204+
//
205+
// It delegates to the SetParsed method of the global SETTINGS variable.
206+
// Registers a string setting with a custom parsing function.
207+
//
208+
// This is useful when you need to perform custom validation or transformation
209+
// on the string value obtained from environment variables or command-line flags
210+
// before using it in your application.
211+
//
212+
// Args:
213+
//
214+
// flagName: The name of the setting flag.
215+
// defaultVar: The default string value.
216+
// message: The help message.
217+
// parserFunc: A function that takes the raw string value (from env or flag)
218+
// and returns a parsed string value. This function will be called
219+
// after retrieving the value from the environment or command line.
220+
//
221+
// Example:
222+
//
223+
// settingo.SetParsed("username", "default", "Username", func(s string) string {
224+
// if s == "" {
225+
// return "anonymous"
226+
// }
227+
// return strings.ToLower(s)
228+
// })
41229
func SetParsed(flagName, defaultVar, message string, parserFunc func(string) string) {
42230
SETTINGS.SetParsed(flagName, defaultVar, message, parserFunc)
43231
}
44232

233+
// SetParsedInt is a package-level function to register an integer setting with a custom parsing function within the global SETTINGS instance.
234+
//
235+
// It delegates to the SetParsedInt method of the global SETTINGS variable.
236+
// Registers an integer setting with a custom parsing function.
237+
//
238+
// This is useful for custom validation or transformation of integer settings.
239+
// Note that while the setting is treated as an integer internally, the defaultVar
240+
// is still a string for consistency with command-line flag handling, and the
241+
// raw value from environment or flag parsing is initially a string.
242+
//
243+
// Args:
244+
//
245+
// flagName: The name of the setting flag.
246+
// defaultVar: The default string value (will be converted to int if possible).
247+
// message: The help message.
248+
// parserFunc: A function that takes the raw integer value (after initial parsing from string)
249+
// and returns a parsed integer value. Note that the input to this function
250+
// is an int, but the original input from environment/flag was a string.
251+
//
252+
// Example:
253+
//
254+
// settingo.SetParsedInt("retries", "3", "Number of retries", func(i int) int {
255+
// if i < 0 {
256+
// return 0 // Ensure retries is not negative
257+
// }
258+
// return i
259+
// })
45260
func SetParsedInt(flagName, defaultVar, message string, parserFunc func(int) int) {
46261
SETTINGS.SetParsedInt(flagName, defaultVar, message, parserFunc)
47262
}
48263

264+
// GetInt retrieves the current integer value of a registered integer setting from the global SETTINGS instance.
265+
//
266+
// It's a package-level function that delegates to the GetInt method of the global SETTINGS variable.
267+
//
268+
// Args:
269+
//
270+
// flagName: The name of the setting flag to retrieve.
271+
//
272+
// Returns:
273+
//
274+
// The current integer value of the setting from the global SETTINGS instance.
49275
func GetInt(flagName string) int {
50276
return SETTINGS.GetInt(flagName)
51277
}
52278

279+
// GetBool retrieves the current boolean value of a registered boolean setting from the global SETTINGS instance.
280+
//
281+
// It's a package-level function that delegates to the GetBool method of the global SETTINGS variable.
282+
//
283+
// Args:
284+
//
285+
// flagName: The name of the setting flag to retrieve.
286+
//
287+
// Returns:
288+
//
289+
// The current boolean value of the setting from the global SETTINGS instance.
53290
func GetBool(flagName string) bool {
54291
return SETTINGS.GetBool(flagName)
55292
}
56293

294+
// GetMap retrieves the current map value of a registered map setting from the global SETTINGS instance.
295+
//
296+
// It's a package-level function that delegates to the GetMap method of the global SETTINGS variable.
297+
//
298+
// Args:
299+
//
300+
// flagName: The name of the setting flag to retrieve.
301+
//
302+
// Returns:
303+
//
304+
// The current map value of the setting from the global SETTINGS instance.
57305
func GetMap(flagName string) map[string][]string {
58306
return SETTINGS.GetMap(flagName)
59307
}
60308

309+
// GetSlice retrieves the current slice value of a registered slice setting from the global SETTINGS instance.
310+
//
311+
// It's a package-level function that delegates to the GetSlice method of the global SETTINGS variable.
312+
//
313+
// Args:
314+
//
315+
// flagName: The name of the setting flag to retrieve.
316+
//
317+
// Returns:
318+
//
319+
// The current slice value of the setting from the global SETTINGS instance.
61320
func GetSlice(flagName string) []string {
62321
return SETTINGS.GetSlice(flagName)
63322
}
64323

324+
// Parse parses settings from both OS environment variables and command-line flags using the global SETTINGS instance.
325+
//
326+
// It's a package-level function that delegates to the Parse method of the global SETTINGS variable.
327+
//
328+
// It first calls HandleOSInput() to parse settings from environment variables,
329+
// and then calls HandleCMDLineInput() to parse command-line flags.
330+
//
331+
// This order ensures that command-line flags take precedence over environment
332+
// variables if a setting is defined in both sources.
333+
//
334+
// Call this function after registering all settings using the Set... functions
335+
// to populate the global SETTINGS instance with values from the environment and command line.
65336
func Parse() {
66337
SETTINGS.Parse()
67338
}
339+
340+
// ParseTo parses settings from environment variables and command-line flags for the global SETTINGS instance
341+
// and then updates the fields of the provided struct with the parsed values.
342+
//
343+
// It's a package-level function that delegates to the ParseTo method of the global SETTINGS variable.
344+
//
345+
// It performs the following steps:
346+
// 1. LoadStruct(to): Registers settings based on the struct fields and "settingo" tags
347+
// of the input struct 'to'. This effectively declares the settings to be parsed
348+
// and associates them with struct fields.
349+
// 2. Parse(): Parses settings from OS environment variables and command-line flags,
350+
// populating the global SETTINGS instance's internal storage.
351+
// 3. UpdateStruct(to): Updates the fields of the input struct 'to' with the parsed
352+
// values from the global SETTINGS instance.
353+
//
354+
// This function simplifies the process of configuring an application by directly
355+
// mapping settings to struct fields.
356+
//
357+
// Args:
358+
//
359+
// to: A pointer to a struct whose fields will be updated with parsed settings.
360+
// The struct's fields must be exported and can be tagged with "settingo"
361+
// to provide help messages (see LoadStruct for tag usage in Settings type).
68362
func ParseTo(to interface{}) {
69363
SETTINGS.ParseTo(to)
70364
}

0 commit comments

Comments
 (0)