default exports

capitalize

Makes the inital 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.

Words that don't get capitalized

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

presents some admirably 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 consider the case:

  "It Waits Underneath the Sea"

Should the word "underneath" be downcased because it's a preposition? Most English speakers would be surprised to see it that way. Consequently, the default list of exceptions to capitalization 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 may note that the last row is not composed of English words. The honorary "de" has been included in honor of "Honoré de Balzac". And "von" was added for the sake of equal time.

Customizing the Exceptions to Capitalization

  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 like to simply add a word to the list, for example "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

   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

   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

   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

   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 (e.g. by using 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 that "über maus" becomes "Über Maus".

2.

Minor words following leading punctuation become upper case:

   "...And Justice for All"
    

3.

It works with multiple sentence input (e.g. "And sooner. And later." should probably not be "And sooner. and later.")

4.

The list of minor words is more extensive (i.e. includes: so, yet, nor), and is also customizable.

5.

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.

6.

capitalize_title is roughly ten times faster.

Another difference is that 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

(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...)