inflect

URL slugs, English pluralisation, ordinals and identifier case conversion. Pure - no capabilities.

ecko get github.com/ecko-lang/inflect
import inflect

Pure computation: it declares no capabilities, so it cannot touch the network, the filesystem or the environment.

Version 0.38.0 - source - MIT.


words(text)

The words of an identifier or phrase, lowercased.

Splits on anything that is not a letter or digit (in any script), and at a lowercase-to-uppercase step. A run of capitals stays together until its last one, so XMLHttpRequest gives ["xml", "http", "request"] rather than eleven single letters.

errors: bug/bad_argument when text is not a string.

inflect.words("helloWorldAgain")   # ["hello", "world", "again"]
inflect.words("Café Owner")        # ["café", "owner"]

capitalize(word)

The word with its first character uppercased and the rest left alone.

errors: bug/bad_argument when word is not a string.

inflect.capitalize("élan")   # "Élan"

translit_table()

The table of accented Latin characters and the ASCII each becomes.

Transliterating rather than dropping matters: "Café Münster" stripped is "caf-mnster", which is unreadable and collides with unrelated titles. Multi-character expansions (ß to ss, æ to ae) are the reason this is a table and not arithmetic.

transliterate(text)

The text lowercased, with accented Latin letters replaced by ASCII.

translit_table() covers the expansions (ß to ss, æ to ae); any other letter that decomposes into an ASCII letter plus accents loses the accents (ǎ to a). Anything else, such as Cyrillic or CJK, is left as it is.

errors: bug/bad_argument when text is not a string.

inflect.transliterate("Café Münster")   # "cafe munster"

slug(text, separator = "-", max_length = 0)

A URL slug: lowercase ASCII words joined by separator.

Accented Latin is transliterated (Café to cafe) and every run of anything else that is not a letter or digit becomes one separator, with none at either end. max_length (0, the default, is no limit) keeps whole words while they fit, never leaving a dangling separator; a first word longer than the limit is cut to it.

A letter or digit with no ASCII form (Cyrillic, Greek, CJK) is refused rather than dropped, since a slug missing its words collides with unrelated titles.

errors: inflect/untransliterable when text holds a letter or digit with no ASCII form; bug/bad_argument when text or separator is not a string or max_length is not a non-negative Int.

inflect.slug("Hello, World!")                      # "hello-world"
inflect.slug("the quick brown fox", max_length: 10)  # "the-quick"

uncountable()

Words whose plural is the same as their singular. Applying a rule to any of these produces "sheeps" or "informations".

irregular()

Irregular singular-to-plural pairs, in one direction. singular reverses this table rather than keeping a second one that could drift out of step, and both functions leave a word that is already the wanted form alone.

takes_ves()

Words ending in -f or -fe whose plural is -ves: wolf/wolves, knife/knives. Every other -f or -fe word takes a plain -s (roofs, chefs, cafes, giraffes), and singular turns any other -ves word back into -ve (gloves, drives).

o_takes_es()

Words ending in -o that take -es. Most take a plain -s (photos, pianos), so the shorter list is the exceptional one.

plural(word)

The plural of an English noun, with the caller's casing kept.

Exceptions win over rules: uncountable words come back unchanged, and an irregular word takes its listed plural. A word that is already a known irregular plural (people, data) is returned as it is. An all-caps acronym takes a lowercase suffix: ID gives IDs.

errors: bug/bad_argument when word is not a string.

inflect.plural("box")      # "boxes"
inflect.plural("Person")   # "People"

singular(word)

The singular of an English noun, with the caller's casing kept.

A word that is already singular comes back unchanged where the rules can tell: uncountables, the irregular singulars (analysis), and singulars that end in s (bus, status, lens, -ss, -us, -is).

errors: bug/bad_argument when word is not a string.

inflect.singular("houses")   # "house"
inflect.singular("People")   # "Person"

pluralize(count, word)

The count and the right form of word for it, joined by a space.

The singular is used for exactly 1 and -1, the plural for everything else, 0 and 1.5 included. word_for gives the word without the number.

errors: bug/bad_argument when count is not a number or word is not a string.

inflect.pluralize(3, "person")   # "3 people"

word_for(count, word)

The right form of word for count, without the number: the singular for exactly 1 and -1, the plural otherwise.

errors: bug/bad_argument when count is not a number or word is not a string.

inflect.word_for(1, "posts")   # "post"

ordinal(n)

The English ordinal of a whole number: 21 gives "21st".

The rule is not "look at the last digit": 11, 12 and 13 take "th" despite ending in 1, 2 and 3. A negative number takes the suffix of its magnitude (-1st, -11th). A Float is accepted only when it is whole (3.0).

errors: bug/bad_argument when n is not an Int or a whole Float.

inflect.ordinal(112)   # "112th"

snake(text)

The text as snake_case.

errors: bug/bad_argument when text is not a string.

inflect.snake("HelloWorld")   # "hello_world"

kebab(text)

The text as kebab-case.

errors: bug/bad_argument when text is not a string.

inflect.kebab("Hello World")   # "hello-world"

camel(text)

The text as camelCase: the first word lowercase, the rest capitalised.

errors: bug/bad_argument when text is not a string.

inflect.camel("naïve value")   # "naïveValue"

pascal(text)

The text as PascalCase: every word capitalised.

errors: bug/bad_argument when text is not a string.

inflect.pascal("post_id")   # "PostId"

title(text)

The text as Title Case: every word capitalised, spaces between.

errors: bug/bad_argument when text is not a string.

inflect.title("the_quick_brown_fox")   # "The Quick Brown Fox"

case_names()

The shape names to_case accepts: snake, kebab, camel, pascal and title.

to_case(text, name)

The text in the shape named by name, one of case_names().

An unknown name raises rather than passing the input through, because a silent passthrough turns a typo into a subtle data bug.

errors: bug/unknown_case when name is not one of case_names(); bug/bad_argument when text is not a string.

inflect.to_case("Hello World", "snake")   # "hello_world"