Mangling: added support for pluralized initialisms (#107)

Pluralized initialisms are of the simplest form, e.g. ID -> IDs.

Initialisms that end with an S (such as DNS) or that conflict with
another initialism that ends with an S (such as HTTP) are invariant
and do not support a pluralized form.

* fixes #46

Other changes that stem from newly supported initialisms that are not
fully upper-cased:

* replaced IPV4 and IPV6 by IPv4 and IPv6
* now ToGoName doesn't force names like "IPv4Etc" in "IPV4Etc", but
  leaves the casing of IPv4.
* if it happens (by adding non default initialisms) that 2 initialisms
  differ only in case, the mixed-case one will be favored over the
  capitalized.

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

initialism_index.go

@@ -30,43 +30,55 @@ var (
 	// a copy of initialisms pre-baked as []rune
 	initialismsRunes      [][]rune
 	initialismsUpperCased [][]rune
+	initialismsPluralForm []pluralForm // pre-baked indexed support for pluralization
 
 	isInitialism func(string) bool
 
 	maxAllocMatches int
 )
 
 func init() {
-	// Taken from https://github.com/golang/lint/blob/3390df4df2787994aea98de825b964ac7944b817/lint.go#L732-L769
+	// List of initialisms taken from https://github.com/golang/lint/blob/3390df4df2787994aea98de825b964ac7944b817/lint.go#L732-L769
+	//
+	// Now superseded by: https://github.com/mgechev/revive/blob/master/lint/name.go#L93
+	//
+	// Notice that initialisms are not necessarily uppercased.
+	// In particular, we may find plural forms with mixed case like "IDs" or legit values like "IPv4" or "IPv6".
+	//
+	// At this moment, we don't support pluralization of terms that ends with an 's' (or 'S').
+	// We don't want to support pluralization of terms which would otherwise conflict with another one,
+	// like "HTTPs" vs "HTTPS". All these should be considered invariant. Hence: "Https" matches "HTTPS" and
+	// "HTTPSS" is "HTTPS" followed by "S".
 	configuredInitialisms := map[string]bool{
+		// initialism: true|false = accept a pluralized form 'Xs' - false means invariant plural
 		"ACL":   true,
 		"API":   true,
 		"ASCII": true,
 		"CPU":   true,
-		"CSS":   true,
-		"DNS":   true,
+		"CSS":   false,
+		"DNS":   false,
 		"EOF":   true,
 		"GUID":  true,
 		"HTML":  true,
-		"HTTPS": true,
-		"HTTP":  true,
+		"HTTPS": false,
+		"HTTP":  false,
 		"ID":    true,
 		"IP":    true,
-		"IPv4":  true,
-		"IPv6":  true,
+		"IPv4":  true, // prefer the mixed case outcome IPv4 over the capitalized IPV4
+		"IPv6":  true, // prefer the mixed case outcome
 		"JSON":  true,
 		"LHS":   true,
-		"OAI":   true,
-		"QPS":   true,
+		"OAI":   true, // not in the linter's list, but added for the openapi context
+		"QPS":   false,
 		"RAM":   true,
-		"RHS":   true,
+		"RHS":   false,
 		"RPC":   true,
 		"SLA":   true,
 		"SMTP":  true,
 		"SQL":   true,
 		"SSH":   true,
 		"TCP":   true,
-		"TLS":   true,
+		"TLS":   false,
 		"TTL":   true,
 		"UDP":   true,
 		"UI":    true,
@@ -79,7 +91,7 @@ func init() {
 		"XML":   true,
 		"XMPP":  true,
 		"XSRF":  true,
-		"XSS":   true,
+		"XSS":   false,
 	}
 
 	// a thread-safe index of initialisms
@@ -88,6 +100,7 @@ func init() {
 	initialismsRunes = asRunes(initialisms)
 	initialismsUpperCased = asUpperCased(initialisms)
 	maxAllocMatches = maxAllocHeuristic(initialismsRunes)
+	initialismsPluralForm = asPluralForms(initialisms, commonInitialisms)
 
 	// a test function
 	isInitialism = commonInitialisms.isInitialism
@@ -112,6 +125,16 @@ func asUpperCased(in []string) [][]rune {
 	return out
 }
 
+// asPluralForms bakes an index of pluralization support.
+func asPluralForms(in []string, idx *indexOfInitialisms) []pluralForm {
+	out := make([]pluralForm, len(in))
+	for i, initialism := range in {
+		out[i] = idx.pluralForm(initialism)
+	}
+
+	return out
+}
+
 func maxAllocHeuristic(in [][]rune) int {
 	heuristic := make(map[rune]int)
 	for _, initialism := range in {
@@ -139,12 +162,14 @@ func maxAllocHeuristic(in [][]rune) int {
 func AddInitialisms(words ...string) {
 	for _, word := range words {
 		// commonInitialisms[upper(word)] = true
-		commonInitialisms.add(upper(word))
+		uword := upper(word)
+		commonInitialisms.add(uword, !strings.HasSuffix(uword, "S"))
 	}
 	// sort again
 	initialisms = commonInitialisms.sorted()
 	initialismsRunes = asRunes(initialisms)
 	initialismsUpperCased = asUpperCased(initialisms)
+	initialismsPluralForm = asPluralForms(initialisms, commonInitialisms)
 }
 
 // indexOfInitialisms is a thread-safe implementation of the sorted index of initialisms.
@@ -175,8 +200,8 @@ func (m *indexOfInitialisms) isInitialism(key string) bool {
 	return ok
 }
 
-func (m *indexOfInitialisms) add(key string) *indexOfInitialisms {
-	m.index.Store(key, true)
+func (m *indexOfInitialisms) add(key string, hasPlural bool) *indexOfInitialisms {
+	m.index.Store(key, hasPlural)
 	return m
 }
 
@@ -192,6 +217,40 @@ func (m *indexOfInitialisms) sorted() (result []string) {
 	return
 }
 
+// pluralForm denotes the kind of pluralization to be used for initialisms.
+//
+// At this moment, initialisms are either invariant or follow a simple plural form with an
+// extra (lower case) "s".
+type pluralForm uint8
+
+const (
+	notPlural pluralForm = iota
+	invariantPlural
+	simplePlural
+)
+
+// pluralForm indicates how we want to pluralize a given initialism.
+//
+// Besides configured invariant forms (like HTTP and HTTPS),
+// an initialism is normally pluralized by adding a single 's', like in IDs.
+//
+// Initialisms ending with an 'S' or an 's' are configured as invariant (we don't
+// support plural forms like CSSes or DNSes, however the mechanism could be extended to
+// do just that).
+func (m *indexOfInitialisms) pluralForm(key string) pluralForm {
+	v, ok := m.index.Load(key)
+	if !ok {
+		return notPlural
+	}
+
+	acceptsPlural := v.(bool)
+	if !acceptsPlural {
+		return invariantPlural
+	}
+
+	return simplePlural
+}
+
 type byInitialism []string
 
 func (s byInitialism) Len() int {
@@ -200,10 +259,14 @@ func (s byInitialism) Len() int {
 func (s byInitialism) Swap(i, j int) {
 	s[i], s[j] = s[j], s[i]
 }
+
+// Less specifies the order in which initialisms are prioritized:
+// 1. match longest first
+// 2. when equal length, match in reverse lexicographical order, lower case match comes first
 func (s byInitialism) Less(i, j int) bool {
 	if len(s[i]) != len(s[j]) {
 		return len(s[i]) < len(s[j])
 	}
 
-	return strings.Compare(s[i], s[j]) > 0
+	return s[i] < s[j]
 }

split.go

@@ -26,6 +26,7 @@ type (
 		initialisms              []string
 		initialismsRunes         [][]rune
 		initialismsUpperCased    [][]rune // initialisms cached in their trimmed, upper-cased version
+		initialismsPluralForm    []pluralForm
 		postSplitInitialismCheck bool
 	}
 
@@ -35,6 +36,7 @@ type (
 		body       []rune
 		start, end int
 		complete   bool
+		hasPlural  pluralForm
 	}
 	initialismMatches []initialismMatch
 )
@@ -149,6 +151,7 @@ func newSplitter(options ...splitterOption) splitter {
 		initialisms:              initialisms,
 		initialismsRunes:         initialismsRunes,
 		initialismsUpperCased:    initialismsUpperCased,
+		initialismsPluralForm:    initialismsPluralForm,
 	}
 
 	for _, option := range options {
@@ -242,25 +245,68 @@ func (s splitter) gatherInitialismMatches(nameRunes []rune) *initialismMatches {
 			for _, match := range *matches {
 				if keepCompleteMatch := match.complete; keepCompleteMatch {
 					*newMatches = append(*newMatches, match)
+
+					// the match is complete: keep it then move on to next rune
 					continue
 				}
 
-				// drop failed match
 				currentMatchRune := match.body[currentRunePosition-match.start]
 				if currentMatchRune != currentRune {
+					// failed match, move on to next rune
 					continue
 				}
 
 				// try to complete ongoing match
 				if currentRunePosition-match.start == len(match.body)-1 {
 					// we are close; the next step is to check the symbol ahead
-					// if it is a small letter, then it is not the end of match
-					// but beginning of the next word
+					// if it is a lowercase letter, then it is not the end of match
+					// but the beginning of the next word.
+					//
+					// NOTE(fredbi): this heuristic sometimes leads to counterintuitive splits and
+					// perhaps (not sure yet) we should check against case _alternance_.
+					//
+					// Example:
+					//
+					// In the current version, in the sentence "IDS initialism", "ID" is recognized as an initialism,
+					// leading to a split like "id_s_initialism" (or IDSInitialism),
+					// whereas in the sentence "IDx initialism", it is not and produces something like
+					// "i_d_x_initialism" (or IDxInitialism). The generated file name is not great.
+					//
+					// Both go identifiers are tolerated by linters.
+					//
+					// Notice that the slightly different input "IDs initialism" is correctly detected
+					// as a pluralized initialism and produces something like "ids_initialism" (or IDsInitialism).
 
 					if currentRunePosition < len(nameRunes)-1 {
 						nextRune := nameRunes[currentRunePosition+1]
+
+						// recognize a plural form for this initialism (only simple pluralization is supported)
+						if nextRune == 's' && match.hasPlural == simplePlural {
+							// detected a pluralized initialism
+							match.body = append(match.body, nextRune)
+							currentRunePosition++
+							if currentRunePosition < len(nameRunes)-1 {
+								nextRune = nameRunes[currentRunePosition+1]
+								if newWord := unicode.IsLower(nextRune); newWord {
+									// it is the start of a new word.
+									// Match is only partial and the initialism is not recognized : move on
+									continue
+								}
+							}
+
+							// this is a pluralized match: keep it
+							match.complete = true
+							match.hasPlural = simplePlural
+							match.end = currentRunePosition
+							*newMatches = append(*newMatches, match)
+
+							// match is complete: keep it then move on to next rune
+							continue
+						}
+
 						if newWord := unicode.IsLower(nextRune); newWord {
-							// oh ok, it was the start of a new word
+							// it is the start of a new word
+							// Match is only partial and the initialism is not recognized : move on
 							continue
 						}
 					}
@@ -269,18 +315,20 @@ func (s splitter) gatherInitialismMatches(nameRunes []rune) *initialismMatches {
 					match.end = currentRunePosition
 				}
 
+				// append the ongoing matching attempt (not necessarily complete)
 				*newMatches = append(*newMatches, match)
 			}
 		}
 
 		// check for new initialism matches
 		for i := range s.initialisms {
-			initialismRunes := s.initialismsRunes[i]
-			if initialismRunes[0] == currentRune {
+			r := s.initialismsRunes[i]
+			if r[0] == currentRune {
 				*newMatches = append(*newMatches, initialismMatch{
-					start:    currentRunePosition,
-					body:     initialismRunes,
-					complete: false,
+					start:     currentRunePosition,
+					body:      r,
+					complete:  false,
+					hasPlural: s.initialismsPluralForm[i],
 				})
 			}
 		}