blib/lib/Text/Conjunct.pm

filter: Statementstmt 100% 21 / 21 Branchbran 87.5% 7 / 8 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 4 / 4 Podpod 100% 1 / 1 totaltotal 97.0% 33 / 34 CC 4 SCAR 10.0
CC
4
Cov
97%
conjunct
4.0
BEGIN
1.0
BEGIN
1.0
CRAP 2.7
↑ Summary
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
BranchTrueFalseTotal
our($VERSION) = "Revision: 1.0 " =~ /Revision:\s+(\S+)/ or $Text::Conjunct::VERSION = "0.0" 1 0 1
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
BranchTrueFalseTotal
if @_ <= 1 1 4 5
139  
140 4 ▶ return join(" $conjunction ", @_) if @_ == 2;
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 2 1 3 4
141  
142 3 my $final = pop @_;
143 3 my $temp = join ', ', @_;
144 3 ▶ $temp .= ',' if $SERIAL_COMMA;
Branch: 1 branch
BranchTrueFalseTotal
if $Text::Conjunct::SERIAL_COMMA 2 1 3
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 ##==============================================================================
↑ Summary