Skip to content

Commit 8ab85d9

Browse files
cvcv
committed
Overhaul README: FuncMap-first approach
- Lead with template integration as the primary Quick Start - Show a realistic multi-function template example - Move direct function calls to secondary section - Remove API Reference (redundant with godoc) - Simplify Custom Engine and Migration sections - More concise overall (~100 lines vs ~250)
1 parent faa8cdb commit 8ab85d9

1 file changed

Lines changed: 54 additions & 186 deletions

File tree

‎README.md‎

Lines changed: 54 additions & 186 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ A Go port of the Python [inflect](https://github.com/jaraco/inflect) library for
55
- **100+ functions** — pluralization, articles, numbers, verbs, and more
66
- **Case-preserving** — "CAT" → "CATS", "Child" → "Children"
77
- **Thread-safe** — all functions safe for concurrent use
8+
- **Template-ready** — `FuncMap()` for `text/template` and `html/template`
89
- **Minimal dependencies** — only `golang.org/x/text` for Unicode normalization
9-
- **Extensively tested** — benchmarks, fuzz tests, and high coverage
1010
- **Drop-in compatible** with `jinzhu/inflection` and `go-openapi/inflect`
1111

1212
## Installation
@@ -17,194 +17,80 @@ go get github.com/cv/go-inflect
1717

1818
## Quick Start
1919

20-
```go
21-
import "github.com/cv/go-inflect"
22-
23-
// Articles
24-
inflect.An("apple") // "an apple"
25-
inflect.An("hour") // "an hour" (silent h)
26-
27-
// Nouns
28-
inflect.Plural("child") // "children"
29-
inflect.Singular("mice") // "mouse"
30-
31-
// Verbs
32-
inflect.PastTense("go") // "went"
33-
inflect.PresentParticiple("run") // "running"
20+
The easiest way to use go-inflect is with Go templates:
3421

35-
// Numbers
36-
inflect.NumberToWords(42) // "forty-two"
37-
inflect.Ordinal(3) // "3rd"
38-
39-
// Lists
40-
inflect.Join([]string{"a", "b", "c"}) // "a, b, and c"
41-
42-
// Adjectives
43-
inflect.Comparative("big") // "bigger"
44-
inflect.Superlative("big") // "biggest"
45-
46-
// And more: possessives, fractions, currency, case conversion...
22+
```go
23+
import (
24+
"os"
25+
"text/template"
26+
"github.com/cv/go-inflect"
27+
)
28+
29+
func main() {
30+
tmpl := template.New("example").Funcs(inflect.FuncMap())
31+
tmpl.Parse(`
32+
You have {{.Count}} {{plural "message" .Count}}.
33+
That's {{numberToWords .Count}} {{plural "message" .Count}}!
34+
The {{ordinalWord .Position}} message is from {{possessive .Name}} account.
35+
`)
36+
tmpl.Execute(os.Stdout, map[string]any{
37+
"Count": 5,
38+
"Position": 1,
39+
"Name": "James",
40+
})
41+
}
42+
// Output:
43+
// You have 5 messages.
44+
// That's five messages!
45+
// The first message is from James' account.
4746
```
4847

49-
## API Reference
50-
51-
### Nouns
52-
53-
| Function | Example |
54-
|----------|---------|
55-
| `Plural(word)` | "cat" → "cats", "child" → "children" |
56-
| `Singular(word)` | "cats" → "cat", "mice" → "mouse" |
57-
| `PluralNoun(word, count...)` | Pluralize with optional count |
58-
| `SingularNoun(word, count...)` | Singularize with optional count |
59-
60-
### Verbs
61-
62-
| Function | Example |
63-
|----------|---------|
64-
| `PluralVerb(word, count...)` | "is" → "are", "runs" → "run" |
65-
| `PresentParticiple(verb)` | "run" → "running" |
66-
| `PastParticiple(verb)` | "take" → "taken" |
67-
| `PastTense(verb)` | "walk" → "walked", "go" → "went" |
68-
69-
### Articles & Adjectives
70-
71-
| Function | Example |
72-
|----------|---------|
73-
| `An(word)` / `A(word)` | "an apple", "a banana" |
74-
| `PluralAdj(word, count...)` | "this" → "these" |
75-
| `Comparative(adj)` | "big" → "bigger" |
76-
| `Superlative(adj)` | "big" → "biggest" |
77-
| `Adverb(adj)` | "quick" → "quickly" |
78-
| `Possessive(noun)` | "cat" → "cat's", "cats" → "cats'" |
79-
80-
### Numbers
81-
82-
| Function | Example |
83-
|----------|---------|
84-
| `NumberToWords(n)` | 42 → "forty-two" |
85-
| `NumberToWordsWithAnd(n)` | 101 → "one hundred and one" |
86-
| `NumberToWordsFloat(f)` | 3.14 → "three point one four" |
87-
| `FormatNumber(n)` | 1000 → "1,000" |
88-
| `Ordinal(n)` | 1 → "1st" |
89-
| `OrdinalWord(n)` | 1 → "first" |
90-
| `FractionToWords(num, den)` | (3, 4) → "three quarters" |
91-
| `CurrencyToWords(amt, code)` | (1.50, "USD") → "one dollar and fifty cents" |
92-
| `CountingWord(n)` | 1 → "once", 2 → "twice" |
93-
94-
### Lists
95-
96-
| Function | Example |
97-
|----------|---------|
98-
| `Join(words)` | ["a", "b", "c"] → "a, b, and c" |
99-
| `JoinWithConj(words, conj)` | Custom conjunction |
100-
| `JoinNoOxford(words)` | British style (no Oxford comma) |
101-
102-
### Comparison
103-
104-
| Function | Description |
105-
|----------|-------------|
106-
| `Compare(w1, w2)` | Returns "eq", "s:p", "p:s", "p:p", or "" |
107-
| `CompareNouns(n1, n2)` | Compare noun forms |
108-
| `CompareVerbs(v1, v2)` | Compare verb forms |
109-
110-
### Case Conversion
111-
112-
| Function | Example |
113-
|----------|---------|
114-
| `CamelCase(s)` | "hello_world" → "helloWorld" |
115-
| `PascalCase(s)` | "hello_world" → "HelloWorld" |
116-
| `SnakeCase(s)` | "HelloWorld" → "hello_world" |
117-
| `KebabCase(s)` | "HelloWorld" → "hello-world" |
118-
119-
### Rails-Style Helpers
120-
121-
| Function | Example |
122-
|----------|---------|
123-
| `Humanize(word)` | "employee_salary" → "Employee salary" |
124-
| `Tableize(word)` | "RawScaledScorer" → "raw_scaled_scorers" |
125-
| `Parameterize(word)` | "Hello World!" → "hello-world" |
126-
| `ForeignKey(word)` | "Person" → "person_id" |
127-
| `Typeify(word)` | "users" → "User" |
128-
| `Asciify(word)` | "café" → "cafe" |
129-
130-
### Utilities
131-
132-
| Function | Description |
133-
|----------|-------------|
134-
| `IsPlural(word)` / `IsSingular(word)` | Check word form |
135-
| `WordCount(text)` | Count words in text |
136-
| `Capitalize(s)` / `Titleize(s)` | Case helpers |
137-
138-
## Advanced Features
139-
140-
### Classical Mode
141-
142-
Enable classical/formal pluralization:
48+
50+ template functions available: `plural`, `singular`, `an`, `ordinal`, `ordinalWord`, `numberToWords`, `pastTense`, `presentParticiple`, `possessive`, `comparative`, `superlative`, `join`, `camelCase`, `snakeCase`, `tableize`, `humanize`, and [many more](https://pkg.go.dev/github.com/cv/go-inflect#FuncMap).
14349

144-
```go
145-
inflect.ClassicalAll(true)
146-
inflect.Plural("formula") // "formulae"
147-
inflect.Plural("cactus") // "cacti"
148-
149-
// Fine-grained control
150-
inflect.ClassicalAncient(true) // Latin/Greek plurals
151-
inflect.ClassicalPersons(true) // "persons" vs "people"
152-
```
50+
### Direct Function Calls
15351

154-
### Custom Definitions
52+
All functions are also available for direct use:
15553

15654
```go
157-
inflect.DefNoun("regex", "regexen")
158-
inflect.DefAn("herb") // US pronunciation
55+
inflect.Plural("child") // "children"
56+
inflect.Singular("mice") // "mouse"
57+
inflect.An("apple") // "an apple"
58+
inflect.NumberToWords(42) // "forty-two"
59+
inflect.Ordinal(3) // "3rd"
60+
inflect.PastTense("go") // "went"
61+
inflect.Possessive("James") // "James'"
62+
inflect.Join([]string{"a","b","c"}) // "a, b, and c"
63+
inflect.Comparative("big") // "bigger"
64+
inflect.CamelCase("hello_world") // "helloWorld"
15965
```
16066

161-
### Isolated Configurations
67+
See [pkg.go.dev](https://pkg.go.dev/github.com/cv/go-inflect) for the complete API.
68+
69+
## Custom Engine
16270

163-
Package functions share a default engine. For isolated settings, create separate engines:
71+
For isolated configurations (different classical modes, custom definitions), create a separate engine:
16472

16573
```go
74+
// Classical Latin/Greek plurals
16675
classical := inflect.NewEngine()
16776
classical.Classical(true)
16877
classical.Plural("formula") // "formulae"
78+
classical.Plural("cactus") // "cacti"
16979

80+
// Modern English (default)
17081
modern := inflect.NewEngine()
17182
modern.Plural("formula") // "formulas"
172-
```
173-
174-
### Gender for Pronouns
175-
176-
```go
177-
inflect.Gender("m")
178-
inflect.SingularNoun("they") // "he"
17983

180-
inflect.Gender("f")
181-
inflect.SingularNoun("they") // "she"
182-
```
183-
184-
### Template Integration
185-
186-
Use `FuncMap()` for seamless integration with `text/template` and `html/template`:
187-
188-
```go
189-
tmpl := template.New("example").Funcs(inflect.FuncMap())
190-
tmpl.Parse(`I have {{plural "cat" .Count}} and {{an "apple"}}`)
191-
tmpl.Execute(os.Stdout, map[string]int{"Count": 3})
192-
// Output: I have cats and an apple
193-
```
194-
195-
50+ template functions available including `plural`, `singular`, `an`, `ordinal`, `numberToWords`, `pastTense`, `possessive`, `join`, `camelCase`, `tableize`, and more. See [FuncMap documentation](https://pkg.go.dev/github.com/cv/go-inflect#FuncMap) for the complete list.
196-
197-
For custom configurations, use `Engine.FuncMap()`:
198-
199-
```go
84+
// Custom definitions
20085
eng := inflect.NewEngine()
201-
eng.DefNoun("foo", "fooz")
86+
eng.DefNoun("regex", "regexen")
87+
eng.DefNoun("pokemon", "pokemon")
88+
89+
// Use custom engine with templates
20290
tmpl := template.New("custom").Funcs(eng.FuncMap())
20391
```
20492

205-
## Migration
206-
207-
### From jinzhu/inflection or go-openapi/inflect
93+
## Migration from jinzhu/inflection
20894

20995
Core functions work identically:
21096

@@ -214,28 +100,11 @@ inflect.Singular("cats") // "cat"
214100
inflect.Underscore("Hello") // "hello"
215101
```
216102

217-
Compatibility aliases provided:
218-
219-
| Alias | Target |
220-
|-------|--------|
221-
| `Pluralize` | `Plural` |
222-
| `Singularize` | `Singular` |
223-
| `Camelize` | `PascalCase` |
224-
| `CamelizeDownFirst` | `CamelCase` |
225-
| `AddIrregular` | `DefNoun` |
226-
| `AddUncountable` | marks word as uncountable |
227-
228-
## Development
229-
230-
```bash
231-
make help # see all targets
232-
```
233-
234-
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
103+
Compatibility aliases: `Pluralize`, `Singularize`, `Camelize`, `CamelizeDownFirst`, `AddIrregular`, `AddUncountable`.
235104

236105
## Documentation
237106

238-
- [pkg.go.dev/github.com/cv/go-inflect](https://pkg.go.dev/github.com/cv/go-inflect)
107+
Full API documentation: [pkg.go.dev/github.com/cv/go-inflect](https://pkg.go.dev/github.com/cv/go-inflect)
239108

240109
## License
241110

@@ -246,4 +115,3 @@ MIT — see [LICENSE](LICENSE)
246115
- Port of [Python inflect](https://github.com/jaraco/inflect) by Jason R. Coombs
247116
- Compatibility APIs from [jinzhu/inflection](https://github.com/jinzhu/inflection) and [go-openapi/inflect](https://github.com/go-openapi/inflect)
248117
- Rails-style helpers inspired by [ActiveSupport::Inflector](https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html)
249-
- Written with [Claude](https://claude.ai) and [Nemotron](https://developer.nvidia.com/nemotron)

0 commit comments

Comments
 (0)