feat: improve definition and validation of exception lists

example/default/main.go

@@ -39,7 +39,10 @@ func main() {
 	// STEP 4: Initialize a menu!
 	// Provide a pointer to your struct, blacklisted or
 	// whitelisted fields, and any custom options.
-	model, err := menu.NewMenu(&newApplication, []string{"BlacklistedField"}, true, customMenuOptions)
+	//
+	// NOTE: Black() and White() exist as convenience wrappers to satisfy
+	// validation logic for exceptions under the hood.
+	model, err := menu.NewMenuWithOptions(&newApplication, customMenuOptions, menu.Black("BlacklistedField")...)
 	if err != nil {
 		log.Fatalf("Trouble generating the application: %s", err)
 	}

example/withIDX/main.go

@@ -39,7 +39,10 @@ func main() {
 	// STEP 4: Initialize a menu!
 	// Provide a pointer to your struct, blacklisted or
 	// whitelisted fields, and any custom options.
-	model, err := menu.NewMenu(&newApplication, []string{"BlacklistedField"}, true, customMenuOptions)
+
+	// NOTE: Black() and White() exist as convenience wrappers to satisfy
+	// validation logic for exceptions under the hood.
+	model, err := menu.NewMenuWithOptions(&newApplication, customMenuOptions, menu.Black("BlacklistedField")...)
 	if err != nil {
 		log.Fatalf("Trouble generating the application: %s", err)
 	}

go.mod

@@ -2,25 +2,34 @@ module github.com/bntrtm/structly
 
 go 1.25.5
 
-require github.com/charmbracelet/bubbletea v1.3.10
+require (
+	github.com/alecthomas/assert/v2 v2.11.0
+	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/stretchr/testify v1.11.1
+)
 
 require (
+	github.com/alecthomas/repr v0.4.0 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
 	github.com/charmbracelet/lipgloss v1.1.0 // indirect
 	github.com/charmbracelet/x/ansi v0.10.1 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
 	github.com/charmbracelet/x/term v0.2.1 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/hexops/gotextdiff v1.0.3 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	golang.org/x/sys v0.36.0 // indirect
 	golang.org/x/text v0.3.8 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,3 +1,7 @@
+github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=
+github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
+github.com/alecthomas/repr v0.4.0 h1:GhI2A8MACjfegCPVq9f1FLvIBS+DrQ2KQBFZP1iFzXc=
+github.com/alecthomas/repr v0.4.0/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
 github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
 github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
@@ -12,8 +16,12 @@ github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd h1:vy0G
 github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
 github.com/charmbracelet/x/term v0.2.1 h1:AQeHeLZ1OqSXhrAWpYUtZyX1T3zVxfpZuEQMIQaGIAQ=
 github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNEEkHUMCmsxdUg=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
+github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=
+github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=
 github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
 github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
@@ -28,9 +36,13 @@ github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELU
 github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 golang.org/x/exp v0.0.0-20220909182711-5c715a9e8561 h1:MDc5xs78ZrZr3HMQugiXOAkSZtfTpbJLDr/lwfgO53E=
@@ -41,3 +53,7 @@ golang.org/x/sys v0.36.0 h1:KVRy2GtZBrk1cBYA7MKu5bEZFxQk4NIDV6RLVcC8o0k=
 golang.org/x/sys v0.36.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/text v0.3.8 h1:nAL+RVCQ9uMn3vJZbV+MRnydTJFPf8qqY42YiA6MrqY=
 golang.org/x/text v0.3.8/go.mod h1:E6s5w1FMmriuDzIBO73fBruAKo1PCIq6d2Q6DHfQ8WQ=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

menu/exceptions.go

@@ -0,0 +1,60 @@
+package menu
+
+import "fmt"
+
+// these constants are used to indicate exception lists
+// as blacklists or whitelists.
+const (
+	BlacklistIndicator = "BL"
+	WhitelistIndicator = "WL"
+)
+
+// Black accepts one or more strings and returns a slice of strings
+// with an exception indicator for blacklisting appended to it.
+//
+// It is a convenience wrapper used to define a blacklist to be passed to
+// exception variadics in NewMenu functions. If the input list contains
+// no elements, Black will panic, as the call is unnecessary.
+func Black(list ...string) []string {
+	if len(list) == 0 {
+		panic("unnecessary call to define blacklist; no inputs provided")
+	}
+	return append(list, BlacklistIndicator)
+}
+
+// White accepts one or more strings and returns a slice of strings
+// with an exception indicator for whitelisting appended to it.
+//
+// It is a convenience wrapper used to define a whitelist to be passed to
+// exception variadics in NewMenu functions. If the input list contains
+// no elements, White will panic, as the call is unnecessary.
+func White(list ...string) []string {
+	if len(list) == 0 {
+		panic("unnecessary call to define whitelist; no inputs provided")
+	}
+	return append(list, WhitelistIndicator)
+}
+
+// validateExceptionList ensures that the input string slice,
+// if not empty, has a last element matching a constant that
+// would define the slice as a blacklist or whitelist.
+//
+// If a non-zero -length slice successfully validates, the
+// constant is popped and returned alongside  the slice of
+// remaining elements.
+//
+// Zero-length inputs are always valid, returning zero values.
+func validateExceptionList(exceptions []string) (string, []string, error) {
+	if len(exceptions) == 0 {
+		return "", nil, nil
+	}
+	const errPre = "could not validate field exceptions as whitelist or blacklist; "
+	lastIndex := len(exceptions) - 1
+	if last := exceptions[lastIndex]; last == BlacklistIndicator || last == WhitelistIndicator {
+		if lastIndex == 0 {
+			return "", nil, fmt.Errorf(errPre + "no field exceptions were provided (unnecessary list)")
+		}
+		return last, exceptions[:lastIndex], nil
+	}
+	return "", nil, fmt.Errorf(errPre+"expected last element value as an exception indicator ('%s' or '%s')", WhitelistIndicator, BlacklistIndicator)
+}

menu/exceptions_test.go

@@ -0,0 +1,140 @@
+package menu
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestExceptionIndicatorConstants exists as a sanity
+// check to ensure that the BlacklistIndicator and
+// WhitelistIndicator constants are distinct.
+func TestExceptionIndicatorConstants(t *testing.T) {
+	if BlacklistIndicator == WhitelistIndicator {
+		t.Errorf("expected distinct exception indicators, but both are declared as '%s'", BlacklistIndicator)
+	}
+}
+
+func TestExceptionConvenienceWrappers(t *testing.T) {
+	tests := []struct {
+		name            string
+		f               func(...string) []string
+		expectIndicator string
+	}{
+		{
+			name:            "Test blacklisting wrapper 'Black'",
+			f:               Black,
+			expectIndicator: BlacklistIndicator,
+		},
+		{
+			name:            "Test whitelisting wrapper 'White'",
+			f:               White,
+			expectIndicator: WhitelistIndicator,
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Run("panics to report unnecessary call", func(t *testing.T) {
+				assert.Panics(t, func() { tc.f() })
+			})
+			t.Run("appends indicator", func(t *testing.T) {
+				exceptionList := tc.f("fieldName1", "fieldName2")
+				if exceptionList[len(exceptionList)-1] != tc.expectIndicator {
+					t.Fail()
+				}
+			})
+		})
+	}
+}
+
+func TestValidateExceptionList(t *testing.T) {
+	t.Run("empty list is validated", func(t *testing.T) {
+		ind, elist, err := validateExceptionList(nil)
+		if ind != "" {
+			t.Errorf("empty list unexpectedly returned indicator: %s", ind)
+		}
+		if len(elist) != 0 {
+			t.Errorf("empty exception list unexpectedly returned elements: %s", elist)
+		}
+		if err != nil {
+			t.Errorf("expected no error, but got: %s", err)
+		}
+	})
+
+	t.Run("errors with only indicator provided", func(t *testing.T) {
+		_, _, err := validateExceptionList([]string{BlacklistIndicator})
+		if err == nil {
+			t.Errorf("expected error with only exception indicator provided, but got none")
+		}
+	})
+
+	t.Run("errors with no indicator appended", func(t *testing.T) {
+		_, _, err := validateExceptionList([]string{"fieldName1", "fieldName2"})
+		if err == nil {
+			t.Errorf("expected error with no indicator provided, but got none")
+		}
+	})
+
+	t.Run("pops indicator", func(t *testing.T) {
+		t.Run("with distinct last exception", func(t *testing.T) {
+			ind, elist, err := validateExceptionList([]string{"fieldName1", "fieldName2", BlacklistIndicator})
+			if err != nil {
+				t.Errorf("unexpected error: %s", err)
+			}
+			if ind != BlacklistIndicator {
+				t.Errorf("expected validation to return provided indicator, but got indicator as: %s", ind)
+			}
+			if ind == elist[len(elist)-1] {
+				t.Errorf("expected validation to return exception list without indicator appended")
+			}
+		})
+		// in an edge case where an exception happens to match an indicator,
+		// we must ensure that it is not left out of the list
+		t.Run("with identical last exception", func(t *testing.T) {
+			for _, withInd := range []string{BlacklistIndicator, WhitelistIndicator} {
+				ind, elist, err := validateExceptionList([]string{"fieldName1", withInd, withInd})
+				if err != nil {
+					t.Errorf("unexpected error: %s", err)
+				}
+				if ind != withInd {
+					t.Errorf("expected validation to return provided indicator, but got indicator as: %s", ind)
+				}
+				if withInd != elist[len(elist)-1] {
+					t.Errorf("expected validation to return exception matching indicator value, but failed")
+				}
+			}
+		})
+	})
+
+	t.Run("validates blacklist exceptions", func(t *testing.T) {
+		t.Run("with literal arguments", func(t *testing.T) {
+			_, _, err := validateExceptionList([]string{"fieldName1", "fieldName2", BlacklistIndicator})
+			if err != nil {
+				t.Errorf("expected call to validate two blacklist exceptions, but got error: %s", err)
+			}
+		})
+
+		t.Run("with convenience wrapper", func(t *testing.T) {
+			_, _, err := validateExceptionList(Black("fieldName1", "fieldName2"))
+			if err != nil {
+				t.Errorf("expected to validate exceptions, but got error: %s", err)
+			}
+		})
+	})
+
+	t.Run("validates whitelist exceptions", func(t *testing.T) {
+		t.Run("with literal arguments", func(t *testing.T) {
+			_, _, err := validateExceptionList([]string{"fieldName1", "fieldName2", WhitelistIndicator})
+			if err != nil {
+				t.Errorf("expected call to validate two whitelist exceptions, but got error: %s", err)
+			}
+		})
+
+		t.Run("with convenience wrapper", func(t *testing.T) {
+			_, _, err := validateExceptionList(White("fieldName1", "fieldName2"))
+			if err != nil {
+				t.Errorf("expected to validate exceptions, but got error: %s", err)
+			}
+		})
+	})
+}