| 1 | ##============================================================================== | ||||||||||
| 2 | ## Text::Conjunct - join lists of items together | ||||||||||
| 3 | ##============================================================================== | ||||||||||
| 4 | ## $Id: Conjunct.pm,v 1.0 2004/05/23 05:44:28 kevin Exp $ | ||||||||||
| 5 | ##============================================================================== | ||||||||||
| 6 | 1 | require 5.006; | |||||||||
| 7 | |||||||||||
| 8 | package Text::Conjunct; | ||||||||||
| 9 | 1 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 10 | 1 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 11 | 1 | ▶ | our ($VERSION) = q$Revision: 1.0 $ =~ /Revision:\s+(\S+)/ or $VERSION = "0.0"; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 12 | 1 | ▶ | use base qw(Exporter); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 13 | 1 | our @EXPORT = qw(conjunct); | |||||||||
| 14 | |||||||||||
| 15 | 1 | our $SERIAL_COMMA = 1; | |||||||||
| 16 | |||||||||||
| 17 | =pod | ||||||||||
| 18 | |||||||||||
| 19 | =head1 NAME | ||||||||||
| 20 | |||||||||||
| 21 | Text::Conjunct - join lists of items together | ||||||||||
| 22 | |||||||||||
| 23 | =head1 SYNOPSIS | ||||||||||
| 24 | |||||||||||
| 25 | C<< use Text::Conjunct; >> | ||||||||||
| 26 | |||||||||||
| 27 | C<< print conjunct "and", "3 apples", "2 pears", "no oranges"; >> | ||||||||||
| 28 | |||||||||||
| 29 | prints | ||||||||||
| 30 | |||||||||||
| 31 | C<< 3 apples, 2 pears, and no oranges >> | ||||||||||
| 32 | |||||||||||
| 33 | =head1 DESCRIPTION | ||||||||||
| 34 | |||||||||||
| 35 | Text::Conjunct joins strings together with a conjunction, typically "and" or | ||||||||||
| 36 | "or". | ||||||||||
| 37 | |||||||||||
| 38 | =over 4 | ||||||||||
| 39 | |||||||||||
| 40 | =item * | ||||||||||
| 41 | |||||||||||
| 42 | If there is only one string, it is just returned. | ||||||||||
| 43 | |||||||||||
| 44 | =item * | ||||||||||
| 45 | |||||||||||
| 46 | If there are two strings, they are returned with the supplied conjunction | ||||||||||
| 47 | between them. | ||||||||||
| 48 | |||||||||||
| 49 | =item * | ||||||||||
| 50 | |||||||||||
| 51 | If there are three or more strings, all but the last are separated by commas. | ||||||||||
| 52 | The separator between the second-to-last and the last is the conjunction, | ||||||||||
| 53 | possibly with a comma preceding it (see L<"SERIAL COMMAS"> below). | ||||||||||
| 54 | |||||||||||
| 55 | =back | ||||||||||
| 56 | |||||||||||
| 57 | =head1 EXPORTED ROUTINE | ||||||||||
| 58 | |||||||||||
| 59 | =over 4 | ||||||||||
| 60 | |||||||||||
| 61 | =item conjunct | ||||||||||
| 62 | |||||||||||
| 63 | C<< I<$string> = conjunct I<$conjunction>, I<@list>; >> | ||||||||||
| 64 | |||||||||||
| 65 | Returns the strings conjoined as explained above. I<$conjunction> can be any | ||||||||||
| 66 | string, which can yield nonsensical results; generally it will be "and" or "or". | ||||||||||
| 67 | |||||||||||
| 68 | =back | ||||||||||
| 69 | |||||||||||
| 70 | =head1 EXAMPLES | ||||||||||
| 71 | |||||||||||
| 72 | =over 4 | ||||||||||
| 73 | |||||||||||
| 74 | =item C<< conjunct "and", "one apple" >> | ||||||||||
| 75 | |||||||||||
| 76 | C<< one apple >> | ||||||||||
| 77 | |||||||||||
| 78 | =item C<< conjunct "and", "one apple", "two oranges" >> | ||||||||||
| 79 | |||||||||||
| 80 | C<< one apple and two oranges >> | ||||||||||
| 81 | |||||||||||
| 82 | =item C<< conjunct "and", "one apple", "two oranges", "three pears" >> | ||||||||||
| 83 | |||||||||||
| 84 | C<< one apple, two oranges, and three pears >> | ||||||||||
| 85 | |||||||||||
| 86 | =back | ||||||||||
| 87 | |||||||||||
| 88 | =head1 SERIAL COMMAS | ||||||||||
| 89 | |||||||||||
| 90 | Text::Conjunct defaults to placing a comma before the final conjunction if there | ||||||||||
| 91 | are more than two connected phrases (William Strunk Jr. and E.B. White, I<The | ||||||||||
| 92 | Elements of Style>, rule 2). This is commonly called the I<serial comma>. Many | ||||||||||
| 93 | people, however, omit this comma. I am not one of them, because this seems | ||||||||||
| 94 | illogical to me, and frequently results in unintended ambiguity. Compare | ||||||||||
| 95 | |||||||||||
| 96 | =over 4 | ||||||||||
| 97 | |||||||||||
| 98 | I'd like to thank my parents, Ayn Rand and God. | ||||||||||
| 99 | |||||||||||
| 100 | =back | ||||||||||
| 101 | |||||||||||
| 102 | with | ||||||||||
| 103 | |||||||||||
| 104 | =over 4 | ||||||||||
| 105 | |||||||||||
| 106 | I'd like to thank my parents, Ayn Rand, and God. | ||||||||||
| 107 | |||||||||||
| 108 | =back | ||||||||||
| 109 | |||||||||||
| 110 | and see which you think makes more sense. Commas in writing generally reflect | ||||||||||
| 111 | pauses in speech, and pretty much everybody except the children of Ayn Rand and | ||||||||||
| 112 | God will pause between those two terms. | ||||||||||
| 113 | |||||||||||
| 114 | But this is Perl, where the standard dogma is that we don't do dogma. You can | ||||||||||
| 115 | set the global variable C<$Text::Conjunct::SERIAL_COMMA> to reflect your | ||||||||||
| 116 | preference or requirements. It defaults to 1 to reflect my personal preference, | ||||||||||
| 117 | but you can set it to zero if you would rather do it the other way. | ||||||||||
| 118 | |||||||||||
| 119 | =head1 COPYRIGHT AND LICENSE | ||||||||||
| 120 | |||||||||||
| 121 | Copyright 2004 Kevin Michael Vail | ||||||||||
| 122 | |||||||||||
| 123 | This program is free software; you can redistribute it and/or modify it under | ||||||||||
| 124 | the same terms as Perl itself. | ||||||||||
| 125 | |||||||||||
| 126 | =head1 AUTHOR | ||||||||||
| 127 | |||||||||||
| 128 | Kevin Michael Vail <F<kevin>@F<vaildc>.F<net>> | ||||||||||
| 129 | |||||||||||
| 130 | =cut | ||||||||||
| 131 | |||||||||||
| 132 | ##============================================================================== | ||||||||||
| 133 | ## conjunct | ||||||||||
| 134 | ##============================================================================== | ||||||||||
| 135 | 5 | ▶ | sub conjunct ($@) { | ||||||||
|
Subroutine
conjunct: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||
| 136 | 5 | my $conjunction = shift; | |||||||||
| 137 | |||||||||||
| 138 | 5 | ▶ | return shift if @_ <= 1; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 139 | |||||||||||
| 140 | 4 | ▶ | return join(" $conjunction ", @_) if @_ == 2; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 141 | |||||||||||
| 142 | 3 | my $final = pop @_; | |||||||||
| 143 | 3 | my $temp = join ', ', @_; | |||||||||
| 144 | 3 | ▶ | $temp .= ',' if $SERIAL_COMMA; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 145 | |||||||||||
| 146 | 3 | join " $conjunction ", $temp, $final; | |||||||||
| 147 | } | ||||||||||
| 148 | |||||||||||
| 149 | 1 | 1; | |||||||||
| 150 | |||||||||||
| 151 | ##============================================================================== | ||||||||||
| 152 | ## $Log: Conjunct.pm,v $ | ||||||||||
| 153 | ## Revision 1.0 2004/05/23 05:44:28 kevin | ||||||||||
| 154 | ## Initial revision | ||||||||||
| 155 | ## | ||||||||||
| 156 | ##============================================================================== | ||||||||||