NAME

Text::Pluralize - simple pluralization routine

SYNOPSIS

use Text::Pluralize;

print pluralize("file", $count);
print pluralize("%d file(s) copied\n"), $count;
print pluralize("There (was|were) {no|one|%d} error(s)\n", $count);

DESCRIPTION

Text::Pluralize provides a lightweight routine to produce the proper form, singular or plural, of a word or phrase. Its intended purpose is to produce messages for the user, whether error messages or informational messages, without the awkward "1 file(s) copied" appearance.

EXPORTED ROUTINE

pluralize

$string = pluralize($template, $count);

Returns $template customized by $count. $template may contain items matching the following formats:

(s1|pl)

If $count is equal to one, s1 will appear here; otherwise $pl will appear at this point in the output. Either s1 or pl can be empty.

(pl)

If $count is not equal to one, the string pl will appear at this point in the output. This is equivalent to (|pl).

(s1|s2|...|pl)

This can be generalized. s1 is used if $count is equal to one, s2 if the count is equal to two, and so forth; pl is used for anything greater than the last specific string applied.

{s0|s1|pl}

With curly braces, the choices start at zero. s0 is used if $count is zero, s1 if it's one, and pl if it's anything else.

{s0|s1|s2|...|pl}

As with the parenthesized version, this can be generalized.

If none of the above substitutions appear in $template, it is treated as if it ended in (s).

Once the above substitutions have been applied, the result is examined to see if it contains any % characters. If so, it is used as a format for sprintf, with the count and any other arguments passed to pluralize. This means that if you have a % in your template that is not supposed to be a format character, you must specify %% instead.

EXAMPLES

In each of the examples below, the first column represents the template, the second column the count, and the third column the result.

item                            0   items
                                1   item
                                2   items

item(s) need{|s|} attention     0   items need attention
                                1   item needs attention
                                2   items need attention

{No|%d} quer(y|ies) (is|are)    0   No queries are
                                1   1 query is
                                2   2 queries are

{No|One|Two|Three|%d} item(s)   0   No items
                                1   One item
                                2   Two items
                                3   Three items
                                4   4 items

NOTE

If the brackets for a substitution don't match up, the one on the left controls what happens.

HISTORY

1.0

Initial version

1.1

Fix a problem with format strings containing newlines.

COPYRIGHT AND LICENSE

Copyright 2007 Kevin Michael Vail, all rights reserved

This library is free software. You may modify and/or redistribute it under the same terms as Perl itself.

AUTHOR

Kevin Michael Vail <kvail@cpan.org>