Documentation
¶
Overview ¶
Package casing rewrites identifier-like strings according to declarative token replacement rules.
"Identifier-like strings" here means names that are structured as code or configuration identifiers rather than arbitrary prose, for example:
- camelCase names such as `apiClient` or `sourceName`
- PascalCase names such as `ApiClient` or `SourceName`
- mixed acronym-containing identifiers such as `HttpAPIClient`
It is intended for cases where callers need to preserve the overall casing shape of such identifiers while forcing specific words to use a canonical replacement and exempting other whole words through an exception list.
This differs from simpler alternatives such as:
- `strings.Replacer`, which is useful for literal substring replacement but does not understand identifier word boundaries or case reconstruction
- regexp-based rewriting, which can express some token patterns but becomes awkward when replacement depends on identifier-style word splitting, acronym policies, and explicit exception lists
The package therefore combines identifier splitting with rule-based word replacement, rather than treating the input as an arbitrary free-form string.
Unlike libraries that automatically apply a built-in Go initialism list, this package only applies that behaviour when explicitly requested. Callers can opt into it by creating a replacer from InitialismRules or by reusing the ready-made InitialismReplacer. This keeps the package predictable for domain-specific casing policies while still providing built-in optional Go initialism support when wanted.
Typical uses include:
- normalising known acronyms in generated identifiers
- preserving exception words that should not be rewritten
- applying a shared replacement policy across tools or generators
Related references:
- Go initialisms guidance in effective naming: https://go.dev/wiki/CodeReviewComments#initialisms
- `ettle/strcase`, which includes a broad casing test corpus and built-in Go-initialism-aware conversions: https://github.com/ettle/strcase
The case-conversion helpers in this package accept `...*Replacer` so callers can use one common helper shape whether they want replacement or not. Only the first replacer is used; passing more than one replacer is not supported.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var InitialismReplacer = mustNewReplacer(InitialismRules...)
InitialismReplacer is a ready-to-use replacer built from InitialismRules.
This variable provides built-in optional Go initialism support without requiring callers to construct a replacer explicitly.
var InitialismRules = []Rule{
{Token: "Acl", Replacement: "ACL"},
{Token: "Api", Replacement: "API"},
{Token: "Ascii", Replacement: "ASCII"},
{Token: "Cpu", Replacement: "CPU"},
{Token: "Css", Replacement: "CSS"},
{Token: "Dns", Replacement: "DNS"},
{Token: "Eof", Replacement: "EOF"},
{Token: "Guid", Replacement: "GUID"},
{Token: "Html", Replacement: "HTML"},
{Token: "Http", Replacement: "HTTP"},
{Token: "Https", Replacement: "HTTPS"},
{Token: "Id", Replacement: "ID"},
{Token: "Ip", Replacement: "IP"},
{Token: "Json", Replacement: "JSON"},
{Token: "Lhs", Replacement: "LHS"},
{Token: "Qps", Replacement: "QPS"},
{Token: "Ram", Replacement: "RAM"},
{Token: "Rhs", Replacement: "RHS"},
{Token: "Rpc", Replacement: "RPC"},
{Token: "Sla", Replacement: "SLA"},
{Token: "Smtp", Replacement: "SMTP"},
{Token: "Sql", Replacement: "SQL"},
{Token: "Ssh", Replacement: "SSH"},
{Token: "Tcp", Replacement: "TCP"},
{Token: "Tls", Replacement: "TLS"},
{Token: "Ttl", Replacement: "TTL"},
{Token: "Udp", Replacement: "UDP"},
{Token: "Ui", Replacement: "UI"},
{Token: "Uid", Replacement: "UID"},
{Token: "Uuid", Replacement: "UUID"},
{Token: "Uri", Replacement: "URI"},
{Token: "Url", Replacement: "URL"},
{Token: "Utf8", Replacement: "UTF8"},
{Token: "Vm", Replacement: "VM"},
{Token: "Xml", Replacement: "XML"},
{Token: "Xmpp", Replacement: "XMPP"},
{Token: "Xsrf", Replacement: "XSRF"},
{Token: "Xss", Replacement: "XSS"},
}
InitialismRules defines replacement rules for the common Go initialisms.
This variable can be passed directly to NewReplacer to opt into built-in Go-style initialism normalisation, for example:
r, err := NewReplacer(InitialismRules...)
The list is based on the standard Go initialism guidance: https://go.dev/wiki/CodeReviewComments#initialisms
Functions ¶
func ToCamelCase ¶
ToCamelCase converts value to camelCase and optionally applies a replacer to the resulting identifier. Only the first replacer is used.
func ToKebabCase ¶
ToKebabCase converts value to kebab-case and optionally applies a replacer to the identifier before the final case conversion. Only the first replacer is used.
func ToPascalCase ¶
ToPascalCase converts value to PascalCase and optionally applies a replacer to the resulting identifier. Only the first replacer is used.
func ToSnakeCase ¶
ToSnakeCase converts value to snake_case and optionally applies a replacer to the identifier before the final case conversion. Only the first replacer is used.
Types ¶
type Replacer ¶
type Replacer struct {
// contains filtered or unexported fields
}
Replacer applies token replacement rules to identifier-like strings.
A replacer works at identifier word boundaries rather than by performing raw substring replacement. In practice, this means it splits names such as `OpenAiApiKey`, `openAiApiKey`, or `HTTPApiToken` into logical words, looks up each word against the configured rules, and then rebuilds the identifier while preserving its overall case style.
If a word matches a configured rule, the rule's replacement is used unless that word is listed in the rule's exceptions. If a word does not match any rule, or it is exempted by an exception, it is reconstructed according to the identifier shape being processed:
- all-uppercase words are preserved as-is
- the first word of a camelCase identifier remains lower camel case
- subsequent words are emitted in PascalCase
This makes Replacer useful for normalising acronyms and canonical tokens such as `API`, `HTTP`, `ID`, or `AI` across generated names, configuration keys, and code identifiers without losing the surrounding naming convention.
func NewReplacer ¶
NewReplacer constructs a Replacer from the provided rules.
Source Files