Skip to content

Commit 2368d7a

Browse files
AttummAttumm
committed
Updated readme
1 parent be76bbe commit 2368d7a

File tree

1 file changed

+97
-55
lines changed

1 file changed

+97
-55
lines changed

‎README.md

+97-55
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,37 @@
11
# Settingo
2-
[![Go Reference](https://pkg.go.dev/badge/github.com/Attumm/settingo/settingo.svg)](https://pkg.go.dev/github.com/Attumm/settingo/settingo)
2+
[![GitHub release](https://img.shields.io/github/v/release/Attumm/settingo?sort=semver)](https://github.com/Attumm/settingo/releases/latest)
33
[![Go Report Card](https://goreportcard.com/badge/github.com/Attumm/settingo)](https://goreportcard.com/report/github.com/Attumm/settingo)
4+
[![CI](https://github.com/Attumm/settingo/actions/workflows/ci.yml/badge.svg)](https://github.com/Attumm/settingo/actions/workflows/ci.yml)
45
[![codecov](https://codecov.io/gh/Attumm/settingo/branch/main/graph/badge.svg)](https://codecov.io/gh/Attumm/settingo)
6+
[![Go Reference](https://pkg.go.dev/badge/github.com/Attumm/settingo/settingo.svg)](https://pkg.go.dev/github.com/Attumm/settingo/settingo)
57

68
## _Settings should be simple, and with settingo it is._
79

8-
Settings parses command line and environment variables on one line.
9-
And makes it available throughout the code base. Making using settings in your project as boring and unimportant as it should be.
10-
Settings vars is as simple as:
10+
Settingo parses command line and environment variables, all within one tool.
11+
Setting up settings is as simple as creating a struct with helpful messages for your project and --help on the CLI.
1112
```go
12-
settingo.Set("FOO", "default value", "help text")
13+
type Config struct {
14+
APIKey string `settingo:"API key for authentication"`
15+
}
16+
17+
func main() {
18+
config := Config{
19+
APIKey: "foo-bar",
20+
}
21+
settingo.ParseTo(config)
22+
}
1323
```
14-
Getting vars out has the same level of complexity as setting the value.
24+
25+
Now the struct will hold always hold value, either default, environment var, cli. based on the context making settings simple.
26+
Letting you focus on your project.
1527
```go
16-
settingo.Get("FOO")
28+
config.APIKey
1729
```
1830

1931
## Features
2032
- Simplicity: Set up settings within a single line of code.
2133
- Flexibility: Utilize command-line flags, environment variables, or defaults.
22-
- Typesafety: Seamlessly work with strings, integers, booleans, and maps.
34+
- Typesafety: Seamlessly work with strings, integers, slices, booleans, and maps.
2335
- Convenience: Global access with a singleton pattern.
2436
- User-friendly: Automatic --help flag generation for your applications.
2537
- Versatility: Works flawlessly in Linux, Docker, Kubernetes, and other environments.
@@ -34,48 +46,55 @@ import (
3446
"github.com/Attumm/settingo/settingo"
3547
)
3648

37-
// Define your configuration
49+
// Define your configuration with various types and help messages
3850
type Config struct {
39-
APIKey string `settingo:"API key for authentication"`
40-
UploadDir string `settingo:"Directory for file uploads"`
41-
Port string `settingo:"Port to run the server on"`
42-
Quality int `settingo:"WebP quality (0-100)"`
51+
APIKey string `settingo:"API key for authentication"`
52+
Port int `settingo:"Port to run the server on"`
53+
Verbose bool `settingo:"Enable verbose output"`
54+
Hosts []string `settingo:"List of allowed hosts (comma-separated)"`
55+
Items []string `settingo:"List of items (pipe-separated, sep=|)" settingo:"sep=|"`
56+
Headers map[string][]string `settingo:"HTTP headers to include (key:value1,value2;key2:value3 format)"`
4357
}
4458

4559
func main() {
46-
// Initialize with default values
60+
// Initialize config with default values
4761
config := &Config{
48-
APIKey: "foo-bar",
49-
UploadDir: "./uploads",
50-
Port: "8080",
51-
Quality: 85,
62+
APIKey: "foo-bar",
63+
Port: 8080,
64+
Verbose: true,
65+
Hosts: []string{"localhost", "127.0.0.1"},
66+
Items: []string{"alpha", "beta", "gamma"},
67+
Headers: map[string][]string{"Accept": {"application/json"}},
5268
}
5369

54-
// Parse command-line flags and environment variables into your config
70+
// Parse command-line flags and environment variables into config
5571
settingo.ParseTo(config)
5672

57-
// Now config fields will be updated according to:
58-
// 1. Command-line flags
59-
// 2. Environment variables
60-
// 3. Struct defaults
61-
fmt.Println("APIKey =", config.APIKey)
62-
fmt.Println("UploadDir=", config.UploadDir)
63-
fmt.Println("Port =", config.Port)
64-
fmt.Println("Quality =", config.Quality)
73+
// Print out the configuration values
74+
fmt.Println("Configuration:")
75+
fmt.Println("APIKey =", config.APIKey)
76+
fmt.Println("Port =", config.Port)
77+
fmt.Println("Verbose =", config.Verbose)
78+
fmt.Println("Headers =", config.Headers)
79+
fmt.Println("Hosts =", config.Hosts)
80+
fmt.Println("Items =", config.Items)
6581
}
66-
6782
```
6883
When you build your application (e.g., go build -o myapp) and run ./myapp --help, settingo automatically generates help text based on struct tags and default values:
6984
```bash
7085
Usage of ./myapp:
7186
-APIKEY string
7287
API key for authentication (default "foo-bar")
73-
-PORT string
74-
Port to run the server on (default "8080")
75-
-QUALITY int
76-
WebP quality (0-100) (default 85)
77-
-UPLOADDIR string
78-
Directory for file uploads (default "./uploads")
88+
-HEADERS string
89+
HTTP headers to include (key:value1,value2;key2:value3 format) (default "Accept:application/json")
90+
-HOSTS string
91+
List of allowed hosts (comma-separated) (default "localhost,127.0.0.1")
92+
-ITEMS string
93+
List of items (pipe-separated, sep=|) (default "alpha,beta,gamma")
94+
-PORT int
95+
Port to run the server on (default 8080)
96+
-VERBOSE string
97+
Enable verbose output (default "true")
7998
```
8099

81100
```go
@@ -129,26 +148,51 @@ The priority order is as follows
129148
2. Environment variables
130149
3. Default values
131150

132-
## Types
133-
Settingo supports different types.
151+
## Example: Custom Parsing for "Messy" Input with `SetParsed`
152+
153+
Sometimes, environment variables or command-line arguments might not be perfectly formatted. You might receive an empty string, mixed-case input, or data that needs transformation. `settingo`'s `SetParsed` is ideal for cleaning up and standardizing such "messy" input.
154+
155+
This example demonstrates handling a `RAW_USERNAME` environment variable, ensuring the `Username` setting is always a lowercase, non-empty string, defaulting to "anonymous" if the input is blank:
156+
134157
```go
135-
// string
136-
settingo.Set("FOO", "default", "help text")
137-
settingo.Get("FOO")
138-
139-
// integer
140-
settingo.SetInt("FOO", 42, "help text")
141-
settingo.GetInt("FOO")
142-
143-
// boolean
144-
settingo.SetBool("FOO", true, "help text")
145-
settingo.GetBool("FOO")
146-
147-
// map
148-
defaultMap := make(map[string][]string)
149-
defaultMap["foo"] = []string{"bar"}
150-
settingo.SetMap("FOO", defaultMap, "help text")
151-
settingo.GetMap("FOO")
158+
package main
159+
160+
import (
161+
"fmt"
162+
"github.com/Attumm/settingo/settingo"
163+
"strings"
164+
)
165+
166+
// Define your configuration with Parsed setting
167+
type Config struct {
168+
Username string `settingo:"USERNAME for application access"`
169+
}
170+
171+
func main() {
172+
config := &Config{
173+
Username: "default",
174+
}
175+
176+
// Use SetParsed to handle potentially messy Username input
177+
settingo.SetParsed("USERNAME", "default", "Username for application access", func(input string) string {
178+
if input == "" {
179+
return "anonymous" // Default to "anonymous" if empty input
180+
}
181+
return strings.ToLower(input) // Convert username to lowercase
182+
})
183+
184+
settingo.ParseTo(config)
185+
fmt.Println("Configured Username:", config.Username)
186+
}
187+
```
188+
189+
```bash
190+
$./example
191+
Configured Username: default
192+
$ ./example --USERNAME ''
193+
Configured Username: anonymous
194+
$ ./example --USERNAME FOOBAR
195+
Configured Username: foobar
152196
```
153197

154198
## installation
@@ -160,6 +204,4 @@ go get "github.com/Attumm/settingo/settingo"
160204
Handy [example_project](https://github.com/Attumm/settingo_example_project) as starting point.
161205

162206
## License
163-
164207
MIT
165-

0 commit comments

Comments
 (0)