Debian Codegraph @

providers/posflag/posflag.go

raw
1 // Package posflag implements a koanf.Provider that reads commandline
2 // parameters as conf maps using spf13/pflag, a POSIX compliant
3 // alternative to Go's stdlib flag package.
4 package posflag
5
6 import (
7 "errors"
8
9 "github.com/knadh/koanf/maps"
10 "github.com/spf13/pflag"
11 )
12
13 // KoanfIntf is an interface that represents a small subset of methods
14 // used by this package from Koanf{}. When using this package, a live
15 // instance of Koanf{} should be passed.
16 type KoanfIntf interface {
17 Exists(string) bool
18 }
19
20 // Posflag implements a pflag command line provider.
21 type Posflag struct {
22 delim string
23 flagset *pflag.FlagSet
24 ko KoanfIntf
25 cb func(key string, value string) (string, any)
26 flagCB func(f *pflag.Flag) (string, any)
27 }
28
29 // Provider returns a commandline flags provider that returns
30 // a nested map[string]any of environment variable where the
31 // nesting hierarchy of keys are defined by delim. For instance, the
32 // delim "." will convert the key `parent.child.key: 1`
33 // to `{parent: {child: {key: 1}}}`.
34 //
35 // It takes an optional (but recommended) Koanf instance to see if
36 // the flags defined have been set from other providers, for instance,
37 // a config file. If they are not, then the default values of the flags
38 // are merged. If they do exist, the flag values are not merged but only
39 // the values that have been explicitly set in the command line are merged.
40 func Provider(f *pflag.FlagSet, delim string, ko KoanfIntf) *Posflag {
41 return &Posflag{
42 flagset: f,
43 delim: delim,
44 ko: ko,
45 }
46 }
47
48 // ProviderWithValue works exactly the same as Provider except the callback
49 // takes a (key, value) with the variable name and value and allows their modification.
50 // This is useful for cases where complex types like slices separated by
51 // custom separators.
52 // Returning "" for the key causes the particular flag to be disregarded.
53 func ProviderWithValue(f *pflag.FlagSet, delim string, ko KoanfIntf, cb func(key string, value string) (string, any)) *Posflag {
54 return &Posflag{
55 flagset: f,
56 delim: delim,
57 ko: ko,
58 cb: cb,
59 }
60 }
61
62 // ProviderWithFlag takes pflag.FlagSet and a callback that takes *pflag.Flag
63 // and applies the callback to all items in the flagset. It does not parse
64 // pflag.Flag values and expects the callback to process the keys and values
65 // from *pflag.Flag however. FlagVal() can be used in the callback to avoid
66 // repeating the type-switch block for parsing values.
67 // Returning "" for the key causes the particular flag to be disregarded.
68 //
69 // Example:
70 //
71 // p := posflag.ProviderWithFlag(flagset, ".", ko, func(f *pflag.Flag) (string, any) {
72 // // Transform the key in whatever manner.
73 // key := f.Name
74 //
75 // // Use FlagVal() and then transform the value, or don't use it at all
76 // // and add custom logic to parse the value.
77 // val := posflag.FlagVal(flagset, f)
78 //
79 // return key, val
80 // })
81 func ProviderWithFlag(f *pflag.FlagSet, delim string, ko KoanfIntf, cb func(f *pflag.Flag) (string, any)) *Posflag {
82 return &Posflag{
83 flagset: f,
84 delim: delim,
85 ko: ko,
86 flagCB: cb,
87 }
88 }
89
90 // Read reads the flag variables and returns a nested conf map.
91 func (p *Posflag) Read() (map[string]any, error) {
92 mp := make(map[string]any)
93 p.flagset.VisitAll(func(f *pflag.Flag) {
94 var (
95 key = f.Name
96 val any
97 )
98
99 // If there is a (key, value) callback set, pass the key and string
100 // value from the flagset to it and use the results.
101 if p.cb != nil {
102 key, val = p.cb(key, f.Value.String())
103 } else if p.flagCB != nil {
104 // If there is a pflag.Flag callback set, pass the flag as-is
105 // to it and use the results from the callback.
106 key, val = p.flagCB(f)
107 } else {
108 // There are no callbacks set. Use the in-built flag value parser.
109 val = FlagVal(p.flagset, f)
110 }
111
112 if key == "" {
113 return
114 }
115
116 // If the default value of the flag was never changed by the user,
117 // it should not override the value in the conf map (if it exists in the first place).
118 if !f.Changed {
119 if p.ko != nil {
120 if p.ko.Exists(key) {
121 return
122 }
123 } else {
124 return
125 }
126 }
127
128 // No callback. Use the key and value as-is.
129 mp[key] = val
130 })
131
132 return maps.Unflatten(mp, p.delim), nil
133 }
134
135 // ReadBytes is not supported by the pflag provider.
136 func (p *Posflag) ReadBytes() ([]byte, error) {
137 return nil, errors.New("pflag provider does not support this method")
138 }
139
140 // Watch is not supported.
141 func (p *Posflag) Watch(cb func(event any, err error)) error {
142 return errors.New("posflag provider does not support this method")
143 }
144
145 // FlagVal examines a pflag.Flag and returns a typed value as an any
146 // from the types that pflag supports. If it is of a type that isn't known
147 // for any reason, the value is returned as a string.
148 func FlagVal(fs *pflag.FlagSet, f *pflag.Flag) any {
149 var (
150 key = f.Name
151 val any
152 )
153
154 switch f.Value.Type() {
155 case "int":
156 val, _ = fs.GetInt(key)
157 case "uint":
158 val, _ = fs.GetUint(key)
159 case "int8":
160 val, _ = fs.GetInt8(key)
161 case "uint8":
162 val, _ = fs.GetUint8(key)
163 case "int16":
164 val, _ = fs.GetInt16(key)
165 case "uint16":
166 val, _ = fs.GetUint16(key)
167 case "int32":
168 val, _ = fs.GetInt32(key)
169 case "uint32":
170 val, _ = fs.GetUint32(key)
171 case "int64":
172 val, _ = fs.GetInt64(key)
173 case "uint64":
174 val, _ = fs.GetUint64(key)
175 case "float":
176 val, _ = fs.GetFloat64(key)
177 case "float32":
178 val, _ = fs.GetFloat32(key)
179 case "float64":
180 val, _ = fs.GetFloat64(key)
181 case "bool":
182 val, _ = fs.GetBool(key)
183 case "duration":
184 val, _ = fs.GetDuration(key)
185 case "ip":
186 val, _ = fs.GetIP(key)
187 case "ipMask":
188 val, _ = fs.GetIPv4Mask(key)
189 case "ipNet":
190 val, _ = fs.GetIPNet(key)
191 case "count":
192 val, _ = fs.GetCount(key)
193 case "bytesHex":
194 val, _ = fs.GetBytesHex(key)
195 case "bytesBase64":
196 val, _ = fs.GetBytesBase64(key)
197 case "string":
198 val, _ = fs.GetString(key)
199 case "stringSlice":
200 val, _ = fs.GetStringSlice(key)
201 case "intSlice":
202 val, _ = fs.GetIntSlice(key)
203 case "uintSlice":
204 val, _ = fs.GetUintSlice(key)
205 case "int32Slice":
206 val, _ = fs.GetInt32Slice(key)
207 case "int64Slice":
208 val, _ = fs.GetInt64Slice(key)
209 case "float32Slice":
210 val, _ = fs.GetFloat32Slice(key)
211 case "float64Slice":
212 val, _ = fs.GetFloat64Slice(key)
213 case "boolSlice":
214 val, _ = fs.GetBoolSlice(key)
215 case "durationSlice":
216 val, _ = fs.GetDurationSlice(key)
217 case "ipSlice":
218 val, _ = fs.GetIPSlice(key)
219 case "stringArray":
220 val, _ = fs.GetStringArray(key)
221 case "stringToString":
222 val, _ = fs.GetStringToString(key)
223 case "stringToInt":
224 val, _ = fs.GetStringToInt(key)
225 case "stringToInt64":
226 val, _ = fs.GetStringToInt64(key)
227 default:
228 val = f.Value.String()
229 }
230
231 return val
232 }