File Coverage

blib/lib/Text/Trim.pm
Criterion Covered Total %
statement 34 34 100.0
branch 36 36 100.0
condition 9 9 100.0
subroutine 6 6 100.0
pod 3 3 100.0
total 88 88 100.0


line stmt bran cond sub pod time code
1             package Text::Trim;
2              
3 6     6   448164 use strict;
  6         51  
  6         173  
4 6     6   30 use warnings;
  6         9  
  6         370  
5              
6             =head1 NAME
7              
8             Text::Trim - remove leading and/or trailing whitespace from strings
9              
10             =head1 VERSION
11              
12             version 1.02_01
13              
14             =cut
15              
16             our $VERSION = '1.02_01';
17              
18             =head1 SYNOPSIS
19              
20             use Text::Trim;
21              
22             $text = "\timportant data\n";
23             $data = trim $text;
24             # now $data contains "important data" and $text is unchanged
25            
26             # or:
27             trim $text; # work in-place, $text now contains "important data"
28              
29             @lines = ;
30             rtrim @lines; # remove trailing whitespace from all lines
31              
32             # Alternatively:
33             @lines = rtrim ;
34              
35             # Or even:
36             while () {
37             trim; # Change $_ in place
38             # ...
39             }
40              
41             =head1 DESCRIPTION
42              
43             This module provides functions for removing leading and/or trailing whitespace
44             from strings. It is basically a wrapper around some simple regexes with a
45             flexible context-based interface.
46              
47             =head1 EXPORTS
48              
49             All functions are exported by default.
50              
51             =cut
52              
53 6     6   37 use Exporter;
  6         9  
  6         3056  
54              
55             our @ISA = qw( Exporter );
56             our @EXPORT = qw( rtrim ltrim trim );
57              
58             =head1 CONTEXT HANDLING
59              
60             =head2 void context
61              
62             Functions called in void context change their arguments in-place
63              
64             trim(@strings); # All strings in @strings are trimmed in-place
65              
66             ltrim($text); # remove leading whitespace on $text
67              
68             rtrim; # remove trailing whitespace on $_
69              
70             No changes are made to arguments in non-void contexts.
71              
72             =head2 list context
73              
74             Values passed in are changed and returned without affecting the originals.
75              
76             @result = trim(@strings); # @strings is unchanged
77              
78             @result = rtrim; # @result contains rtrimmed $_
79              
80             ($result) = ltrim(@strings); # like $result = ltrim($strings[0]);
81              
82             =head2 scalar context
83              
84             As list context but multiple arguments are stringified before being returned.
85             Single arguments are unaffected. This means that under these circumstances,
86             the value of C<$"> (C<$LIST_SEPARATOR>) is used to join the values. If you
87             don't want this, make sure you only use single arguments when calling in
88             scalar context.
89              
90             @strings = ("\thello\n", "\tthere\n");
91             $trimmed = trim(@strings);
92             # $trimmed = "hello there"
93              
94             local $" = ', ';
95             $trimmed = trim(@strings);
96             # Now $trimmed = "hello, there"
97              
98             $trimmed = rtrim;
99             # $trimmed = $_ minus trailing whitespace
100              
101             =head2 Undefined values
102              
103             If any of the functions are called with undefined values, the behaviour is in
104             general to pass them through unchanged. When stringifying a list (calling in
105             scalar context with multiple arguments) undefined elements are excluded, but
106             if all elements are undefined then the return value is also undefined.
107              
108             $foo = trim(undef); # $foo is undefined
109             $foo = trim(undef, undef); # $foo is undefined
110             @foo = trim(undef, undef); # @foo contains 2 undefined values
111             trim(@foo) # @foo still contains 2 undefined values
112             $foo = trim('', undef); # $foo is ''
113              
114             =head1 FUNCTIONS
115              
116             =head2 trim
117              
118             Removes leading and trailing whitespace from all arguments, or C<$_> if none
119             are provided.
120              
121             =cut
122              
123             sub trim {
124 14 100   14 1 16605 @_ = @_ ? @_ : $_ if defined wantarray;
    100          
125              
126 14 100       41 for (@_ ? @_ : $_) { next unless defined; s/\A\s+//; s/\s+\z// }
  32 100       60  
  24         76  
  24         83  
127              
128 14 100 100     71 return @_ if wantarray || !defined wantarray;
129              
130 6 100       29 if (my @def = grep defined, @_) { return "@def" } else { return }
  5         31  
  1         6  
131             }
132              
133             =head2 rtrim
134              
135             Like C but removes only trailing (right) whitespace.
136              
137             =cut
138              
139             sub rtrim {
140 12 100   12 1 10945 @_ = @_ ? @_ : $_ if defined wantarray;
    100          
141              
142 12 100       36 for (@_ ? @_ : $_) { next unless defined; s/\s+\z// }
  30 100       51  
  22         91  
143              
144 12 100 100     54 return @_ if wantarray || !defined wantarray;
145              
146 5 100       26 if (my @def = grep defined, @_) { return "@def" } else { return }
  4         20  
  1         13  
147             }
148              
149             =head2 ltrim
150              
151             Like C but removes only leading (left) whitespace.
152              
153             =cut
154              
155             sub ltrim {
156 12 100   12 1 5634 @_ = @_ ? @_ : $_ if defined wantarray;
    100          
157              
158 12 100       28 for (@_ ? @_ : $_) { next unless defined; s/\A\s+// }
  30 100       48  
  22         69  
159              
160 12 100 100     47 return @_ if wantarray || !defined wantarray;
161              
162 5 100       20 if (my @def = grep defined, @_) { return "@def" } else { return }
  4         21  
  1         5  
163             }
164              
165             1;
166              
167             __END__