introduce New() and Flag()/FlagSet() to split definition of dynamic var from assignent to a flag

Author: ldemailly

README.md

@@ -32,7 +32,7 @@ All of this can be done simultaneously across a whole shard of your services.
 ## Features
 
  * compatible with standard go `flag` package
- * dynamic `flag` that are thread-safe and efficient:
+ * dynamic `flag` that are thread-safe and efficient, now also `Dyn[T]` generic:
    - `DynBool`
    - `DynInt64`
    - `DynFloat64`
@@ -88,6 +88,14 @@ func MyHandler(resp http.ResponseWriter, req *http.Request) {
 ```
 
 All access to `featuresFlag`, which is a `[]string` flag, is synchronized across go-routines using `atomic` pointer swaps.
+## Library versus caller style
+
+```golang
+// In the library "libfoo" package
+var MyConfig = dflag.New("default value", "explanation of what that is for").WithValidator(MyValidator)
+// In the caller/users, bind to an actual flag:
+dflag.Flag("foocfg", libfoo.MyConfig) // defines -foocfg flag
+```
 
 ## Complete example
 

dynbool.go

@@ -12,17 +12,34 @@ import (
 // type DynBoolValue = DynValue[bool]
 // but that doesn't work with IsBoolFlag
 // https://github.com/golang/go/issues/53473
+// only fixed in go 1.20
 // so we extend this type as special, the only one with that method.
 
-// DynBool creates a `Flag` that represents `bool` which is safe to change dynamically at runtime.
-func DynBool(flagSet *flag.FlagSet, name string, value bool, usage string) *DynBoolValue {
+func NewBool(value bool, usage string) *DynBoolValue {
 	dynValue := DynBoolValue{}
-	dynInit(&dynValue.DynValue, flagSet, name, value, usage)
-	flagSet.Var(&dynValue, name, usage)
-	flagSet.Lookup(name).DefValue = fmt.Sprintf("%v", value)
+	dynInit(&dynValue.DynValue, value, usage)
 	return &dynValue
 }
 
+func FlagBool(name string, o *DynBoolValue) *DynBoolValue {
+	return FlagSetBool(flag.CommandLine, name, o)
+}
+
+func FlagSetBool(flagSet *flag.FlagSet, name string, dynValue *DynBoolValue) *DynBoolValue {
+	// we inline/repeat code of FlagSet(flagSet, name, &dynValue.DynValue)
+	// because we need to set this specific type for the IsBoolFlag to work
+	dynValue.flagSet = flagSet
+	dynValue.flagName = name
+	flagSet.Var(dynValue, name, dynValue.usage)
+	flagSet.Lookup(name).DefValue = fmt.Sprintf("%v", dynValue.av.Load())
+	return dynValue
+}
+
+// DynBool creates a `Flag` that represents `bool` which is safe to change dynamically at runtime.
+func DynBool(flagSet *flag.FlagSet, name string, value bool, usage string) *DynBoolValue {
+	return FlagSetBool(flagSet, name, NewBool(value, usage))
+}
+
 // DynStringSetValue implements a dynamic set of strings.
 type DynBoolValue struct {
 	DynamicBoolValueTag

dyngeneric.go

@@ -92,17 +92,44 @@ type DynValue[T any] struct {
 	usage        string
 }
 
-func Dyn[T DynValueTypes](flagSet *flag.FlagSet, name string, value T, usage string) *DynValue[T] {
+// New allows to define a dynamic flag in 2 steps. With the default value and other
+// options like validation in the first step (in a library code). And later
+// re-assigning using Flag()/FlagSet() to bind to an actual flag name and value.
+func New[T DynValueTypes](value T, usage string) *DynValue[T] {
 	dynValue := DynValue[T]{}
-	dynInit(&dynValue, flagSet, name, value, usage)
-	flagSet.Var(&dynValue, name, usage)
-	flagSet.Lookup(name).DefValue = fmt.Sprintf("%v", value)
+	dynInit(&dynValue, value, usage)
 	return &dynValue
 }
 
-func dynInit[T any](dynValue *DynValue[T], flagSet *flag.FlagSet, name string, value T, usage string) {
-	dynValue.flagName = name
+// Flag assigns a dynamic value to a command line flag.
+// e.g. in a library:
+//
+//	var Value1 = dflag.New("default value", "explanation for value1's usage")
+//
+// in a main/where the library is used:
+//
+//	dflag.Flag("flag1", library.Value1) // assigns to -flag1
+func Flag[T DynValueTypes](name string, o *DynValue[T]) *DynValue[T] {
+	return FlagSet(flag.CommandLine, name, o)
+}
+
+// FlagSet is like Flag but allows to specify the flagset to use.
+// also backward compatible with earlier versions of dflag.
+func FlagSet[T DynValueTypes](flagSet *flag.FlagSet, name string, dynValue *DynValue[T]) *DynValue[T] {
 	dynValue.flagSet = flagSet
+	dynValue.flagName = name
+	flagSet.Var(dynValue, name, dynValue.usage)
+	flagSet.Lookup(name).DefValue = fmt.Sprintf("%v", dynValue.av.Load())
+	return dynValue
+}
+
+// Dyn[type] is the all in one function to create a dynamic flag for a flagset.
+// For library prefer splitting into New() in library and Flag() in callers.
+func Dyn[T DynValueTypes](flagSet *flag.FlagSet, name string, value T, usage string) *DynValue[T] {
+	return FlagSet(flagSet, name, New(value, usage))
+}
+
+func dynInit[T any](dynValue *DynValue[T], value T, usage string) {
 	dynValue.av.Store(value)
 	dynValue.inpMutator = strings.TrimSpace // default so parsing of numbers etc works well
 	dynValue.usage = usage
@@ -111,6 +138,7 @@ func dynInit[T any](dynValue *DynValue[T], flagSet *flag.FlagSet, name string, v
 
 // Unfortunately IsBoolFlag isn't called, just presence is needed
 // https://github.com/golang/go/issues/53473
+// fixed in 1.20 only
 
 /*
 // lets the flag parsing know that -flagname is enough to turn to true.

dynjson.go

@@ -24,7 +24,9 @@ func DynJSON(flagSet *flag.FlagSet, name string, value interface{}, usage string
 		panic("DynJSON value must be a pointer to a struct or to a slice")
 	}
 	dynValue := DynJSONValue{}
-	dynInit(&dynValue.DynValue, flagSet, name, value, usage)
+	dynInit(&dynValue.DynValue, value, usage)
+	dynValue.flagSet = flagSet
+	dynValue.flagName = name
 	dynValue.structType = reflectVal.Type().Elem()
 	flagSet.Var(&dynValue, name, usage) // use our Set()
 	flagSet.Lookup(name).DefValue = dynValue.usageString()

examples/server_kube/http.go

@@ -25,12 +25,15 @@ var (
 	staticInt = flag.Int("example_my_static_int", 1337, "Something integery here.")
 
 	// With generics typing
-	dynStr   = dflag.Dyn(flag.CommandLine, "example_my_dynamic_string", "initial_value", "Something interesting here.")
-	dynInt   = dflag.Dyn(flag.CommandLine, "example_my_dynamic_int", int64(1337), "Something integery here.")
+	dynStr = dflag.Dyn(flag.CommandLine, "example_my_dynamic_string", "initial_value", "Something interesting here.")
+	dynInt = dflag.Dyn(flag.CommandLine, "example_my_dynamic_int", int64(1337), "Something `int`egery here.")
+	// This shows the wrong help until 1.20 and https://github.com/golang/go/issues/53473 workaround is removed
 	dynBool1 = dflag.Dyn(flag.CommandLine, "example_bool1", false, "Something true... or false. Starting false.")
 	// Or explicit:
 	dynBool2 = dflag.DynBool(flag.CommandLine, "example_bool2", true, "Something true... or false. Starting true.")
-
+	// Or new style:
+	dynBool3 = dflag.NewBool(true, "defined in 2 steps... Starting true.")
+	dynStr2  = dflag.New("starting string value", "explanation of the config variable")
 	// This is an example of a dynamically-modifiable JSON flag of an arbitrary type.
 	dynJSON = dflag.DynJSON(
 		flag.CommandLine,
@@ -46,6 +49,8 @@ var (
 )
 
 func main() {
+	dynBool3 = dflag.FlagBool("example_bool3", dynBool3)
+	dynStr2 = dflag.Flag("example_str2", dynStr2)
 	flag.Parse()
 	u, err := configmap.Setup(flag.CommandLine, *dirPathWatch)
 	if err != nil {

go.mod

@@ -3,7 +3,7 @@ module fortio.org/dflag
 go 1.19
 
 require (
-	fortio.org/assert v1.1.2
+	fortio.org/assert v1.1.3
 	fortio.org/log v1.1.0
 	github.com/fsnotify/fsnotify v1.6.0
 	golang.org/x/exp v0.0.0-20230210204819-062eb4c674ab

go.sum

@@ -1,5 +1,5 @@
-fortio.org/assert v1.1.2 h1:t6WGDqPD5VFrUvx30U0+3mgXXcoPonrdKqt0vfJHn8E=
-fortio.org/assert v1.1.2/go.mod h1:039mG+/iYDPO8Ibx8TrNuJCm2T2SuhwRI3uL9nHTTls=
+fortio.org/assert v1.1.3 h1:zXm8xiNiKvq2xG/YQ3sONAg3287XUuklKIDdjyD9pyg=
+fortio.org/assert v1.1.3/go.mod h1:039mG+/iYDPO8Ibx8TrNuJCm2T2SuhwRI3uL9nHTTls=
 fortio.org/log v1.1.0 h1:tCSTZwyLYXS2+1LD2edUoFzEzIFa1Fi75mpHwGoMU4Y=
 fortio.org/log v1.1.0/go.mod h1:u/8/2lyczXq52aT5Nw6reD+3cR6m/EbS2jBiIYhgiTU=
 github.com/fsnotify/fsnotify v1.6.0 h1:n+5WquG0fcWoWp6xPWfHdbskMCQaFnG6PfBrh1Ky4HY=