Text::Capitalize(3pm)

📦
version 1.5 · 2 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Welcome to the Text::Capitalize(3pm) page, bestie — it's part of the User Contributed Perl Documentation. The module is Text::Capitalize, and it capitalizes strings. Like, "to WORK AS titles" becomes "To Work as Titles". No cap. ✨

🌸 SYNOPSIS 🌸

use Text::Capitalize;

print capitalize( "...and justice for all" ), "\n";
   ...And Justice For All

print capitalize_title( "...and justice for all" ), "\n";
   ...And Justice For All

print capitalize_title( "agent of SFPUG", PRESERVE_ALLCAPS=>1 ), "\n";
   Agent of SFPUG

print capitalize_title( "the ring:  symbol or cliche?",
                        PRESERVE_WHITESPACE=>1 ), "\n";
   The Ring:  Symbol or Cliche?
   (Note, double-space after colon is still there.)

# To work on international characters, may need to set locale
use Env qw( LANG );
$LANG = "en_US";
print capitalize_title( "ueber maus" ), "\n";
   Ueber Maus

use Text::Capitalize qw( scramble_case );
print scramble_case( 'It depends on what you mean by "mean"' );
   It dEpenDS On wHAT YOu mEan by "meAn".

💖 ABSTRACT 💖

Text::Capitalize is for capitalizing strings in a manner suitable for use in titles. Basically, it's giving title-case energy. 👑

🦋 DESCRIPTION 🦋

Text::Capitalize provides some routines for title-like formatting of strings.

The simple capitalize function just makes the initial character of each word uppercase, and forces the rest to lowercase.

The capitalize_title function applies English title case rules (discussed below) where only the "important" words are supposed to be capitalized. There are also some customization features provided to allow the user to choose variant rules.

Comparing capitalize and captialize_title:

Input:             "lost watches of splitsville"
capitalize:        "Lost Watches Of Splitsville"
capitalize_title:  "Lost Watches of Splitsville"

Some examples of formatting with capitalize_title:

Input:             "KiLLiNG TiMe"
capitalize_title:  "Killing Time"

Input:             "we have come to wound the autumnal city"
capitalize_title:  "We Have Come to Wound the Autumnal City"

Input:             "ask for whom they ask for"
captialize_title:  "Ask for Whom They Ask For"

Text::Capitalize also provides some functions for special effects such as scramble_case, which typically would be used for this sort of transformation:

Input:            "get whacky"
scramble_case:    "gET wHaCkY"  (or something similar)

👑 EXPORTS 👑

default exports 💅

  • capitalize — Makes the initial character of each word uppercase, and forces the rest to lowercase.

The original routine by Stanislaw Y. Pusep.

  • capitalize_title — Applies English title case rules (See BACKGROUND) where only the "important" words are supposed to be capitalized.

The one required argument is the string to be capitalized.

Some customization options may be passed in as pairs of names and values following the required argument.

The following customizations are allowed:

Boolean:

  • PRESERVE_WHITESPACE
  • PRESERVE_ALLCAPS
  • PRESERVE_ANYCAPS

Array reference:

  • NOT_CAPITALIZED

See "Customizing the Exceptions to Capitalization".

optional exports ✨

  • @exceptions — The list of minor words that don't usually get capitalized in titles (used by capitalize_title). Defaults to:
                a an the
                and or nor for but so yet
                to of by at for but in with has
                de von
  • %defaults_capitalize_title — Defines the default arguments for the capitalize_title function. Initially, this is set-up to shut off the features PRESERVE_WHITESPACE, PRESERVE_ALLCAPS and PRESERVE_ANYCAPS; it also has @exceptions as the NOT_CAPITALIZED list.
  • scramble_case — This routine provides a special effect: sCraMBliNg tHe CaSe.

The algorithm here uses a modified probability distribution to get a weirder looking effect than simple randomization such as with random_case.

For a discussion of the algorithm, see "SPECIAL EFFECTS".

  • random_case — Randomizes the case of each character with a 50-50 chance of each one becoming upper or lower case.
  • zippify_case — Function to provide a special effect: "RANDOMLY upcasing WHOLE WORDS at a TIME".

This uses a similar algorithm to scramble_case, though it also ignores words on the @exceptions list, just as capitalize_title does.

🌸 BACKGROUND 🌸

Okay bestie, so here's the tea: capitalize_title tries to do the right thing by default — it takes any random chunk of text and glams it up so it can be used as a title. But like… human languages are messy, and coming up with programmatic rules that cover every case is lowkey impossible. 🙈

✨ Words that don't get capitalized ✨

So there's this web page:

http://www.continentallocating.com/World.Literature/General2/LiteraryTitles2.htm

and it lays out some genuinely clear rules for capitalizing titles:

ALL words in EVERY title are capitalized except
(1) a, an, and the,
(2) two and three letter conjunctions (and, or, nor, for, but, so, yet),
(3) prepositions.
Exceptions:  The first and last words are always capitalized even
if they are among the above three groups.

But like, consider this case:

"It Waits Underneath the Sea"

Should "underneath" be downcased just because it's a preposition? Bestie, most English speakers would be so thrown off seeing it that way. So the default list of exceptions in this module only includes the shortest of the common prepositions (to of by at for but in).

The default entries on the exception list are:

     a an the
     and or nor for but so yet
     to of by at for but in with has
     de von

The observant girlies may notice the last row is not English words. The honorary de got included in honor of "Honore de Balzac" 💅 and von was added for the sake of equal time.

✨ Customizing the Exceptions to Capitalization ✨

If you have different ideas about the "rules" of English (or maybe you're using this code with another language that has different rules), you might want to swap in a whole new exception list of your own:

capitalize_title( "Dude, we, like, went to Old Slavy, and uh, they didn't have it",
                   NOT_CAPITALIZED => [ qw( uh duh huh wha like man you know ) ] );

This should return:

   Dude, We, like, Went To Old Slavy, And uh, They Didn't Have It

Less radically, you might just want to add one word to the list, like "from":

use Text::Capitalize 0.2 qw( capitalize_title @exceptions );
push @exceptions, "from";

print capitalize_title( "fungi from yuggoth",
                        NOT_CAPITALIZED => \@exceptions);

This should output:

    Fungi from Yuggoth

✨ All Uppercase Words ✨

To work with a wide range of input strings, by default capitalize_title presumes that upper-case input needs adjusting (so "DOOM APPROACHES!" becomes "Doom Approaches!"). But that doesn't leave room for things like an acronym in a title (like, "RAM Prices Plummet" ideally should not become "Ram Prices Plummet", right?). If the PRESERVE_ALLCAPS option is set, then it presumes an all-uppercase word is that way for a reason and leaves it alone:

print capitalize_title( "ram more RAM down your throat",
                        PRESERVE_ALLCAPS => 1 );

This should output:

      Ram More RAM Down Your Throat

✨ Preserving Any Usage of Uppercase for Mixed-case Words ✨

There are some other odd cases that are hard to handle well — notably mixed-case words like "iMac", "CHiPs", and so on. For these, a PRESERVE_ANYCAPS option exists, which presumes that any usage of uppercase is there for a reason, in which case the entire word gets passed through untouched. With PRESERVE_ANYCAPS on, only the case of all-lowercase words ever gets adjusted:

print capitalize_title( "TLAs i have known and loved",
                    PRESERVE_ANYCAPS => 1 );

This should output:

TLAs I Have Known and Loved
print capitalize_title( "the next iMac: just another NeXt?",
                         PRESERVE_ANYCAPS => 1);

This should output:

The Next iMac: Just Another NeXt?

✨ Handling Whitespace ✨

By default, capitalize_title presumes you're trying to clean up potential title strings. As an extra feature it collapses multiple spaces and tabs into single spaces. If that's not what you want and you'd rather it literally restrict itself to adjusting capitalization, you can force that behavior with the PRESERVE_WHITESPACE option:

print capitalize_title( "it came from texas:  the new new world order?",
                        PRESERVE_WHITESPACE => 1);

This should output:

      It Came From Texas:  The New New World Order?

(Note: the double-space after the colon is still there. 👀)

✨ Comparison to Text::Autoformat ✨

As you'd expect, there's more than one way to do this, and these two pieces of code perform very similar functions:

use Text::Capitalize 0.2;
print capitalize_title( $t ), "\n";

use Text::Autoformat;
print autoformat { case => "highlight", right => length( $t ) }, $t;

Note: with autoformat, supplying the length of the string as the "right margin" is much faster than plugging in an arbitrarily large number. There doesn't seem to be any other way of turning off line-breaking (like, via the "fill" parameter) though possibly there will be in the future.

As of this writing, "capitalize_title" has some advantages:

  1. It works on characters outside the English 7-bit ASCII range — for example with my locale setting (en_US) the ISO-8859-1 International characters are handled correctly, so "ueber maus" becomes "Ueber Maus".
  2. Minor words following leading punctuation become upper case:
  "...And Justice for All"
  1. It works with multiple sentence input (like, "And sooner. And later." should probably not be "And sooner. and later.")
  2. The list of minor words is more extensive (i.e. includes: so, yet, nor), and is also customizable.
  3. There's a way of preserving acronyms via the PRESERVE_ALLCAPS option and, similarly, mixed-case words ("iMac", "NeXt", etc") with the PRESERVE_ANYCAPS option.
  4. capitalize_title is roughly ten times faster.

Another difference: Text::Autoformat's "highlight" always preserves whitespace, something like capitalize_title does with the PRESERVE_WHITESPACE option set.

However, it should be pointed out that Text::Autoformat is under active maintenance by Damian Conway. It also does far more than this module, and you may want to use it for other reasons.

✨ Still more ways to do it ✨

Late breaking news 🗞️: the second edition of the Perl Cookbook has just come out. It now includes "Properly Capitalizing a Title or Headline" as recipe 1.14. You should familiarize yourself with this if you want to become a true master of all title capitalization routines.

(And I see that recipe 1.13 includes a "randcap" program as an example, which as it happens does something like the random_case function described below…)

🎀 SPECIAL EFFECTS 🎀

Some functions have been provided to make strings look weird by scrambling their capitalization ("lIKe tHiS"): random_case and scramble_case. The function "random_case" does a straight-forward randomization of capitalization so each letter has a 50-50 chance of being upper or lower case. The function "scramble_case" does a very similar thing, but does a slightly better job of producing something "weird-looking".

The difficulty is that human perception of randomness and actual randomness are not the same. Consider the fact that of the sixteen ways the four letter word "word" can be capitalized, three of them are rather boring: "word", "Word" and "WORD". To make it less likely that scramble_case produces dull output when you want "weird" output, a modified probability distribution is used that records the history of previous outcomes and tweaks the likelihood of the next decision in the opposite direction, back toward the expected average. In effect, this simulates a world where the Gambler's Fallacy is correct ("Hm... red has come up a lot, I bet that black is going to come up now."). "Streaks" are much less likely with scramble_case than with random_case.

Additionally, with scramble_case the probability that the first character of the input string becomes upper-case has been tweaked to less than 50%. (Future versions may apply this tweak on a per-word basis rather than just on a per-string basis.)

There's also a function that scrambles capitalization on a word-by-word basis called "zippify_case", which should produce output like: "In my PREVIOUS life i was a LATEX-novelty REPAIRMAN!"

💖 EXPORT 💖

By default, this version of the module provides the two functions capitalize and capitalize_title. Future versions will have no further additions to the default export list.

Optionally, the following functions may also be exported:

  • scramble_case — a function to scramble capitalization in a wEiRD loOOkInG wAy. Supposed to look a little stranger than the simpler random_case output
  • random_case — function to randomize capitalization of each letter in the string. Compare to "scramble_case"
  • zippify_case — a function like "scramble_case" that acts on a word-by-word basis (Somewhat LIKE this, YOU know?).

It's also possible to export the following variables:

  • @exceptions — the list of minor words that capitalize_title uses by default to determine the exceptions to capitalization.
  • %defaults-capitalize_title — the hash of allowed arguments (with defaults) that the capitalize_title function uses.

💀 BUGS 💀

  1. In capitalize_title, quoted sentence terminators are treated as actual sentence breaks, e.g. in this case:
     'say "yes but!" and "know what?"'

The program sees the ! and effectively treats this as two separate sentences: the word "but" becomes "But" (under the rule that last words must always be uppercase, even if they're on the exception list) and the word "and" becomes "And" (under the first word rule).

  1. There's no good way to automatically handle names like "McCoy". Consider the difficulty of disambiguating "Macadam Roads" from "MacAdam Rode". If you need to solve problems like this, consider using the case_surname function of Lingua::En::NameParse.
  2. In general, Text::Capitalize is a very parochial English oriented module that looks like it belongs in the "Lingua::En::*" tree.
  3. There's currently no way of doing a PRESERVE_ANYCAPS that also adjusts capitalization of words on the exception list, so that "iMac Or iPod" would become "iMac or iPod".

🌈 SEE ALSO 🌈

⭐ VERSION ⭐

Version 0.9

👑 AUTHORS 👑

Okay bestie, these are the literal masterminds behind all this capitalization excellence, show some respect 💖

  • Joseph M. Brenner
  • Stanislaw Y. Pusep (who wrote "capitalize") — the way he just... gave us the whole capitalize thing? iconic, no notes 🫶

And many thanks (for feature suggestions and code examples) to:

  • Belden Lyman
  • Yary Hcluhan
  • Randal Schwartz

not me getting emotional over a credits list 😭 the community really said "we're all in this together" fr fr 🌸

Copyright 2003 by Joseph Brenner. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. periodt. 💅

okay so like — same terms as Perl itself. That's the whole legal vibe. Go forth, remix, redistribute, be free, slay responsibly ✨

And that's a wrap on the whole page, bestie!! 🦋 This was Text::Capitalize(3pm) from the perl v5.36.0 docs, dated 2023-02-03 — so yeah, this page is lowkey a vintage queen and still serving 👑💜 Go capitalize something beautiful. Mwah! 💖🌷

📦 where this page comes from