Documentation
¶
Overview ¶
Package naming parses identifiers written in any casing into words, and formats those words in any other casing.
Case conventions lose information: HTTPAPIClient doesn't say where HTTP ends, httpClient doesn't say http is an acronym, and IPv6Address looks like I + Pv6 + Address. Parsing recovers it from a dictionary of acronyms and terms first, and falls back to a case heuristic for everything else, so every casing of a name the dictionary covers parses to the same words.
The algorithm and the initial dictionary are specified in hack/designs/identifier-casing.md.
Index ¶
Constants ¶
const FirstVersion = "v1.0.0"
FirstVersion is the engine version that introduced identifier parsing, with the Initial dictionary. The engine names modules that declare an older engineVersion with its previous (strcase) rules instead; see hack/designs/identifier-casing.md.
const MaxLength = 256
MaxLength is the longest name, in bytes, that Parse accepts.
Variables ¶
var AcronymStyles = []AcronymStyle{Uppercase, Capitalized}
AcronymStyles lists every AcronymStyle.
var Casings = []Casing{Pascal, Camel, Snake, ScreamingSnake, Kebab, Flat}
Casings lists every Casing.
var ErrNoWords = errors.New("identifier must contain a letter or digit")
ErrNoWords is returned when parsing a name with no letters or digits.
var ErrNonASCII = errors.New("identifier must be ASCII")
ErrNonASCII is returned when parsing a name with non-ASCII characters.
var ErrTooLong = fmt.Errorf("identifier must be at most %d bytes", MaxLength)
ErrTooLong is returned when parsing a name longer than MaxLength.
var Initial = MustDictionary(initialTerms)
Initial is the dictionary the engine first shipped identifier parsing with. Don't edit it; see Dictionary. TestInitialDictionaryFrozen pins it.
var Latest = Initial
Latest is the newest dictionary, used by the package-level Parse.
Functions ¶
func Convert ¶
func Convert(name string, casing Casing, style AcronymStyle) (string, error)
Convert parses name with the Latest dictionary and formats it in a casing.
func Format ¶
func Format(id Identifier, casing Casing, style AcronymStyle) string
Format formats id's words in a casing.
Types ¶
type AcronymStyle ¶
type AcronymStyle int
AcronymStyle is how acronyms and terms are written where a word starts with a capital. It only affects Pascal and Camel.
const ( // Uppercase writes HTTPClient, IPv6Address, GitHubRepo. Uppercase AcronymStyle = iota // Capitalized writes HttpClient, Ipv6Address, GitHubRepo. Capitalized )
func (AcronymStyle) String ¶
func (s AcronymStyle) String() string
type Casing ¶
type Casing int
Casing is a convention for joining words into an identifier.
const ( // Pascal capitalizes every word: HTTPClient. Pascal Casing = iota // Camel lowercases the first word and capitalizes the rest: httpClient. Camel // Snake lowercases every word and joins them with "_": http_client. Snake // ScreamingSnake uppercases every word and joins them with "_": // HTTP_CLIENT. ScreamingSnake // Kebab lowercases every word and joins them with "-": http-client. Kebab // Flat lowercases every word and drops the boundaries: httpclient. It is // for Go package and Python module names, and doesn't round-trip. Flat )
type Dictionary ¶
type Dictionary struct {
// contains filtered or unexported fields
}
Dictionary is a set of acronyms and terms used to parse identifiers.
Adding a term renames every identifier that contains it, so a released dictionary must never change: additions go into a new Dictionary that is selected by engine version, leaving older modules on the one they had.
func DictionaryFor ¶
func DictionaryFor(engineVersion string) *Dictionary
DictionaryFor returns the dictionary for a module or client that declares engineVersion: the newest dictionary introduced at or before it.
Versions compare by their base version, like engine API views: every prerelease of vX.Y.Z (v1.0.0-beta.15, v1.0.0-dev-123) selects vX.Y.Z's dictionary. An empty version means the latest, as an empty view does. Versions older than FirstVersion, and invalid versions, get Initial; callers that need the pre-naming behavior for those check FirstVersion themselves.
func MustDictionary ¶
func MustDictionary(terms []Term) *Dictionary
MustDictionary is NewDictionary, panicking on error.
func NewDictionary ¶
func NewDictionary(terms []Term) (*Dictionary, error)
NewDictionary builds a dictionary from terms. It returns an error for an entry that is empty, not alphanumeric ASCII, duplicated (ignoring case), or missing a Capitalized form that can't be defaulted.
func (*Dictionary) Parse ¶
func (d *Dictionary) Parse(name string) (Identifier, error)
Parse parses a name in any casing into words.
func (*Dictionary) Terms ¶
func (d *Dictionary) Terms() []Term
Terms returns the dictionary's entries in definition order.
type Identifier ¶
type Identifier struct {
// Name is the name as given to Parse.
Name string
// Words are the words of the name, in order.
Words []Word
}
Identifier is a name parsed into words.
func Parse ¶
func Parse(name string) (Identifier, error)
Parse parses name with the Latest dictionary.
func (Identifier) Format ¶
func (id Identifier) Format(casing Casing, style AcronymStyle) string
Format formats the identifier's words in a casing.
type Term ¶
type Term struct {
// Spelling is the standard spelling: HTTP, IPv6, GitHub, iOS, 3D.
Spelling string
// Capitalized is the spelling in the CAPITALIZED acronym style: Http,
// Ipv6, GitHub, Ios, 3D. It can't be derived from Spelling (a brand like
// GitHub never changes), so terms with lowercase letters or leading
// digits must set it; plain acronyms default to the first letter
// capitalized and the rest lowercase.
Capitalized string
}
Term is a dictionary entry: an acronym (HTTP) or a term with a fixed mixed-case spelling (GitHub, IPv6).
type Word ¶
type Word struct {
Kind WordKind
// Text is the standard spelling: client (WORD), HTTP (ACRONYM), GitHub
// (TERM). A WORD's digits are part of its text: base64, v1.
Text string
// Suffix is trailing digits and/or a plural "s", in that order, on an
// acronym or term: SHA+"s", OAuth+"2", HTTP+"2s".
Suffix string
// Term is the dictionary entry the word matched, or nil for a word
// found by the case heuristic. It is shared with the dictionary and must
// not be modified.
Term *Term
}
Word is one unit of an identifier.
type WordKind ¶
type WordKind int
WordKind classifies a word of an identifier.
const ( // KindWord is an ordinary word, stored lowercase: client. KindWord WordKind = iota // KindAcronym is a word written in capitals, from the dictionary or a // run of capitals in the input: HTTP, E2E, 3D. KindAcronym // KindTerm is a dictionary entry with a fixed mixed-case spelling: // GitHub, IPv6, iOS. KindTerm )
Source Files