Provide option to flatten structs

Author: itzg

docs.go

@@ -174,6 +174,15 @@ the field should be ignored and no flag is declared. For example,
 	Host        string `flag:"server_address"
 	GetsIgnored string `flag:""`
 
+To help with organization, struct fields can be flattened such that the resolved flag name does not include the name of the struct itself. For example, this struct will accept the flags named simply `-host` and `-port`.
+
+	type struct Config {
+		NetworkConfig struct {
+			Host string
+			Port int
+		}
+	}
+
 Environment variable naming and processing can be overridden with the `env:"name"` tag, where
 the given name will be used exactly as the mapped environment variable name. If the WithEnv
 or WithEnvRenamer options were enabled, a field can be excluded from environment variable

flagset.go

@@ -18,6 +18,15 @@ var (
 	stringToStringMapType = reflect.TypeOf(map[string]string{})
 )
 
+const (
+	TagDefault       = "default"
+	TagEnv           = "env"
+	TagFlag          = "flag"
+	TagFlatten       = "flatten"
+	TagOverrideValue = "override-value"
+	TagType          = "type"
+)
+
 // FlagSetFiller is used to map the fields of a struct into flags of a flag.FlagSet
 type FlagSetFiller struct {
 	options *fillerOptions
@@ -57,6 +66,8 @@ func (f *FlagSetFiller) Fill(flagSet *flag.FlagSet, from interface{}) error {
 	}
 }
 
+// isSupportedStruct checks if the given field reference is a registered extended type or implements
+// encoding.TextUnmarshaler
 func isSupportedStruct(in any) bool {
 	t := reflect.TypeOf(in)
 	_, ok := extendedTypes[getTypeName(t)]
@@ -106,15 +117,14 @@ func (f *FlagSetFiller) walkFields(flagSet *flag.FlagSet, prefix string,
 		field := structType.Field(i)
 		fieldValue := structVal.Field(i)
 
-		if flagTag, ok := field.Tag.Lookup("flag"); ok {
+		if flagTag, ok := field.Tag.Lookup(TagFlag); ok {
 			if flagTag == "" {
 				continue
 			}
 		}
 
 		switch field.Type.Kind() {
 		case reflect.Struct:
-			// fieldTypeName := getTypeName(field.Type)
 			if field.IsExported() {
 				if isSupportedStruct(fieldValue.Addr().Interface()) {
 					err := handleDefault(field, fieldValue)
@@ -124,7 +134,11 @@ func (f *FlagSetFiller) walkFields(flagSet *flag.FlagSet, prefix string,
 					continue
 				}
 			}
-			err := f.walkFields(flagSet, prefix+field.Name, fieldValue, field.Type)
+
+			err := f.walkFields(flagSet,
+				qualifiedNameForStructField(field, prefix),
+				fieldValue,
+				field.Type)
 			if err != nil {
 				return fmt.Errorf("failed to process %s of %s: %w", field.Name, structType.String(), err)
 			}
@@ -146,7 +160,10 @@ func (f *FlagSetFiller) walkFields(flagSet *flag.FlagSet, prefix string,
 					}
 				}
 
-				err := f.walkFields(flagSet, field.Name, fieldValue.Elem(), field.Type.Elem())
+				err := f.walkFields(flagSet,
+					qualifiedNameForStructField(field, prefix),
+					fieldValue.Elem(),
+					field.Type.Elem())
 				if err != nil {
 					return fmt.Errorf("failed to process %s of %s: %w", field.Name, structType.String(), err)
 				}
@@ -163,11 +180,27 @@ func (f *FlagSetFiller) walkFields(flagSet *flag.FlagSet, prefix string,
 	return nil
 }
 
+func qualifiedNameForStructField(field reflect.StructField, prefix string) string {
+	if !shouldFlatten(field) {
+		return prefix + field.Name
+	} else {
+		return prefix
+	}
+}
+
+func shouldFlatten(field reflect.StructField) bool {
+	value, ok := field.Tag.Lookup(TagFlatten)
+	if !ok {
+		return false
+	}
+	return value == "true"
+}
+
 func (f *FlagSetFiller) processField(flagSet *flag.FlagSet, fieldRef interface{},
 	name string, t reflect.Type, tag reflect.StructTag) (err error) {
 
 	var envName string
-	if override, exists := tag.Lookup("env"); exists {
+	if override, exists := tag.Lookup(TagEnv); exists {
 		envName = override
 	} else if len(f.options.envRenamer) > 0 {
 		envName = name
@@ -182,12 +215,12 @@ func (f *FlagSetFiller) processField(flagSet *flag.FlagSet, fieldRef interface{}
 		usage = fmt.Sprintf("%s (env %s)", usage, envName)
 	}
 
-	tagDefault, hasDefaultTag := tag.Lookup("default")
+	tagDefault, hasDefaultTag := tag.Lookup(TagDefault)
 
-	fieldType, _ := tag.Lookup("type")
+	fieldType, _ := tag.Lookup(TagType)
 
 	var renamed string
-	if override, exists := tag.Lookup("flag"); exists {
+	if override, exists := tag.Lookup(TagFlag); exists {
 		if override == "" {
 			// empty flag override signal to skip this field
 			return nil
@@ -231,7 +264,7 @@ func (f *FlagSetFiller) processField(flagSet *flag.FlagSet, fieldRef interface{}
 
 	case t == stringSliceType, fieldType == "stringSlice":
 		var override bool
-		if overrideValue, exists := tag.Lookup("override-value"); exists {
+		if overrideValue, exists := tag.Lookup(TagOverrideValue); exists {
 			if value, err := strconv.ParseBool(overrideValue); err == nil {
 				override = value
 			}

flagset_test.go

@@ -278,6 +278,9 @@ func TestNestedStructPtr(t *testing.T) {
 	type Config struct {
 		Host         string
 		SomeGrouping *Nested
+		Inner        struct {
+			Deeper *Nested
+		}
 	}
 
 	var config Config
@@ -288,11 +291,15 @@ func TestNestedStructPtr(t *testing.T) {
 	err := filler.Fill(&flagset, &config)
 	require.NoError(t, err)
 
-	err = flagset.Parse([]string{"--host", "h1", "--some-grouping-some-field", "val1"})
+	err = flagset.Parse([]string{"--host", "h1",
+		"--some-grouping-some-field", "val1",
+		"--inner-deeper-some-field", "val2"})
+	require.NoError(t, err)
 	require.NoError(t, err)
 
 	assert.Equal(t, "h1", config.Host)
 	assert.Equal(t, "val1", config.SomeGrouping.SomeField)
+	assert.Equal(t, "val2", config.Inner.Deeper.SomeField)
 }
 
 func TestNestedUnexportedStructPtr(t *testing.T) {
@@ -880,6 +887,33 @@ func TestFlagNameOverride(t *testing.T) {
 
 }
 
+func TestFlatten(t *testing.T) {
+	type Config struct {
+		Flattened struct {
+			FlattenedField string
+		} `flatten:"true"`
+		PtrFlattened *struct {
+			PtrFlattenedField string
+		} `flatten:"true"`
+	}
+
+	var config Config
+
+	filler := flagsfiller.New()
+
+	var flagset flag.FlagSet
+	err := filler.Fill(&flagset, &config)
+	require.NoError(t, err)
+
+	err = flagset.Parse([]string{"--flattened-field", "val1",
+		"--ptr-flattened-field", "val2"})
+	require.NoError(t, err)
+	require.NoError(t, err)
+
+	assert.Equal(t, "val1", config.Flattened.FlattenedField)
+	assert.Equal(t, "val2", config.PtrFlattened.PtrFlattenedField)
+}
+
 type flagSet interface {
 	SetOutput(io.Writer)
 	PrintDefaults()