blib/lib/File/Stream.pm

filter: Statementstmt 65.4% 87 / 133 Branchbran 36.3% 16 / 44 Conditioncond 33.3% 6 / 18 MC/DCmcdc 9.0% 1 / 11 Subroutinesub 62.9% 17 / 27 Podpod 100% 4 / 4 totaltotal 55.2% 131 / 237 CC 30 SCAR 27.9
CC
30
Cov
56%
READ
72.0
find
15.7
PRINT
12.0
CRAP 16.2
↑ Summary
1  
2 =head1 NAME
3  
4 File::Stream - Regular expression delimited records from streams
5  
6 =head1 SYNOPSIS
7  
8 use File::Stream;
9 my $stream = File::Stream->new($filehandle);
10
11 $/ = qr/\s*,\s*/;
12 print "$_\n" while <$stream>;
13  
14 # or:
15 ($handler, $stream) = File::Stream->new(
16 $filehandle,
17 read_length => 1024,
18 separator => qr{to_be_used_instead_of_$/},
19 );
20
21 while(<$stream>) {...}
22 my $line = $stream->readline(); # similar
23
24 # extended usage:
25 use URI;
26 my $uri = URI->new('http://steffen-mueller.net');
27 my ($pre_match, $match) =
28 $handler->find('literal_string', qr/regex/, $uri);
29
30 # $match contains whichever argument to find() was found first.
31 # $pre_match contains all that was before the first token that was found.
32 # both the contents of $match and $pre_match have been removed from the
33 # data stream (buffer).
34
35 # Since version 2.10 of the module, you can use seek() and tell() on
36 # File::Stream objects:
37 my $position = tell($stream);
38 # ...
39 seek($stream, 0, $position); # rewind
40  
41 =head1 DESCRIPTION
42  
43 Perl filehandles are streams, but sometimes they just aren't powerful enough.
44 This module offers to have streams from filehandles searched with regexes
45 and allows the global input record separator variable to contain regexes.
46  
47 Thus, readline() and the <> operator can now return records delimited
48 by regular expression matches.
49  
50 There are some very important gripes with applying regular expressions to
51 (possibly infinite) streams. Please read the CAVEATS section of this
52 documentation carfully.
53  
54 =head2 EXPORT
55  
56 None.
57  
58 =cut
59  
60 package File::Stream;
61  
62 2 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
63 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
64 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
65  
66 2 ▶use FileHandle;
Subroutine BEGIN: called CC=1 SCAR=0.0
67 2 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
68 2 ▶use YAPE::Regex;
Subroutine BEGIN: called CC=1 SCAR=0.0
69  
70 2 ▶use vars qw/$End_Of_String/;
Subroutine BEGIN: called CC=1 SCAR=0.0
71 2 our $VERSION = '2.30';
72  
73 =head2 new
74  
75 The new() constructor takes a filehandle (or a glob reference) as first
76 argument. The following arguments are interpreted as key/value pairs with
77 the following parameters being defined:
78  
79 =over 4
80  
81 =item separator
82  
83 This may be set to either a string, a compiled regular expression (qr//), or
84 an object which is overloaded in stringification context to return a string.
85  
86 If separator is set, its value will be used in calls to readline() (including
87 the <> diamond operator which calls readline internally) instead of $/,
88 the global input record separator.
89  
90 String will be interpreted as literal strings, not regular expressions.
91  
92 =item read_length
93  
94 Defaults to 1024 bytes. Sets the number of bytes to read into the internal
95 buffer at once. Large values may speed up searching considerably, but
96 increase memory usage.
97  
98 =item die_on_anchors
99  
100 Defaults to true. If set, any call to C<find()> will die on
101 regular expressions which contain anchors (C<^ and $>). Usually, those
102 do not make much sense in regular expressions applied to streams.
103 If, however, you're using the C<//m> option, these anchors match
104 the start and end of each line respectively. In that case, you can suppress
105 the fatal error by setting C<die_on_anchors =E<gt> 0>.
106  
107 =back
108  
109 The new() method returns a fresh File::Stream object that has been tied to
110 be a filehandle and a filehandle. All the usual file operations should work
111 on the filehandle and the File::Stream methods should work on the object.
112  
113 =cut
114  
115 1 ▶sub new {
Subroutine new: called CC=2 SCAR=7.2
Pod documented
116 1 my $proto = shift;
117 1 ▶ my $class = ref($proto) || $proto;
Condition33%1/3
ref $proto || $proto
l!l&&r!l&&!r
010
MC/DC0%0/2
ref $proto || $proto
ref $proto $proto
Truth table33%1/3
A || B
A= ref $protoB= $proto
ABresult
1X1
011
000
118  
119 1 my $filehandle = new FileHandle;
120 1 my $handler = tie *$filehandle => $class, @_;
121 1 return ( $handler, $filehandle );
122 }
123  
124 =head2 readline
125  
126 The readline method on a File::Stream object works just like the
127 builtin except that it uses the objects record separator instead
128 of $/ if it has been set via new() and honours regular expressions.
129  
130 This is also internally used when readline() is called on the tied
131 filehandle.
132  
133 =cut
134  
135 4 ▶sub readline {
Subroutine readline: called CC=4 SCAR=17.9
Pod documented
136 4 my $self = shift;
137 4 my $separator = $self->{separator};
138 4 ▶ $separator = $/ if not defined $separator;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $separator 0 4 4
139 4 my ( $pre_match, $match ) = $self->find($separator);
140 4 ▶ if ( not defined $pre_match ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $pre_match) 0 4 4
141 0 my $buf = $self->{buffer};
142 0 $self->{buffer} = '';
143 0 ▶ return undef if $buf eq '';
Branch: 1 branch
BranchTrueFalseTotal
if $buf eq "" 0 0 0
144 0 return $buf;
145 }
146 4 return $pre_match . $match;
147 }
148  
149 =head2 find
150  
151 Finds the first occurrance one of its arguments in the stream. For example,
152  
153 $stream_handler->find('a', 'b');
154  
155 finds the first character 'a' or 'b' in the stream whichever comes first.
156 Returns two strings: The data read from the stream I<before> the match
157 and the match itself. The arguments to find() may be regular expressions,
158 but please see the CAVEATS section of this documentation about that.
159 If any of the arguments is an object, it will be evaluated in stringification
160 context and the result of that will be matched I<literally>, ie. not as a
161 regular expression.
162  
163 As with readline(), this is a method on the stream handler object.
164  
165 =cut
166  
167 7 ▶sub find {
Subroutine find: called CC=14 SCAR=27.6
Pod documented
168 7 my $self = shift;
169 7 my @terms = @_;
170 2 ▶ use re 'eval';
Subroutine BEGIN: called CC=1 SCAR=0.0
171 7 $End_Of_String = 0;
172 my @regex_tokens =
173 map {
174 10 my $yp = YAPE::Regex->new($_);
175 10 my $str = '';
176 10 my $token;
177 10 ▶ while ($token = $yp->next()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($token = $yp->next) 36 10 46
178 36 my $tstr = $token->string();
179 36 ▶ if ($self->{die_on_anchors} and $tstr eq '^' or $tstr eq '$') {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"die_on_anchors"} and $tstr eq "^" or $tstr eq "\$") 0 36 36
Condition33%2/6
$self->{"die_on_anchors"} and $tstr eq "^" or $tstr eq "\$"
l!l&&r!l&&!r
0036
$self->{"die_on_anchors"} and $tstr eq "^"
!ll&&!rl&&r
0360
MC/DC0%0/3
$self->{"die_on_anchors"} and $tstr eq "^" or $tstr eq "\$"
$self->{"die_on_anchors"} $tstr eq "^" $tstr eq "\$"
Truth table20%1/5
A and B or C
A= $self->{"die_on_anchors"}B= $tstr eq "^"C= $tstr eq "\$"
ABCresult
11X1
0X11
1011
0X00
1000
180 0 croak "Invalid use of anchors (here: '$tstr') in a ",
181 "regular expression that will be\n",
182 "applied to a stream";
183 }
184 36 $str .= $tstr .
185 '(?:\z(?{$End_Of_String++})(?!)|)';
186 }
187 10 qr/$str/;
188 }
189 map {
190 7 ▶ if ( not ref($_) ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not ref $_) { } 6 4 10
elsif (ref $_ eq 'Regexp') { } 4 0 4
191 6 qr/\Q$_\E/
192 }
193 elsif ( ref($_) eq 'Regexp' ) {
194 4 $_
195 }
196 else {
197 0 my $string = "$_";
198 0 qr/\Q$string\E/
199 }
200 } @terms;
201
202 7 my $re = '(' . join( ')|(', @regex_tokens ) . ')';
203 7 my $compiled = qr/$re/s;
204  
205 7 while (1) {
206 9 my @matches = $self->{buffer} =~ $compiled;
207 9 ▶ if ($End_Of_String or not @matches) {
Branch: 1 branch
BranchTrueFalseTotal
if ($File::Stream::End_Of_String or not @matches) { } 2 7 9
Condition66%2/3
$File::Stream::End_Of_String or not @matches
l!l&&r!l&&!r
027
MC/DC50%1/2
$File::Stream::End_Of_String or not @matches
$File::Stream::End_Of_String not @matches
Truth table66%2/3
A or not(B)
A= $File::Stream::End_Of_StringB= not @matches
ABresult
1X1
011
000
208 2 $End_Of_String = 0;
209 2 ▶ return undef unless $self->fill_buffer();
Branch: 1 branch
BranchTrueFalseTotal
unless $self->fill_buffer 0 2 2
210 2 next;
211 }
212 else {
213 7 my $index = undef;
214 7 for ( 0 .. $#matches ) {
215 8 ▶ $index = $_, last if defined $matches[$_];
Branch: 1 branch
BranchTrueFalseTotal
if defined $matches[$_] 7 1 8
216 }
217 7 ▶ die if not defined $index; # sanity check
Branch: 1 branch
BranchTrueFalseTotal
unless defined $index 0 7 7
218 7 my $match = $matches[$index];
219 7 ▶ $self->{buffer} =~ s/^(.*?)\Q$match\E//s or die;
Branch: 1 branch
BranchTrueFalseTotal
$self->{"buffer"} =~ s/^(.*?)\Q$match\E//s or die 7 0 7
220 7 return ( $1, $match );
221 }
222 }
223 }
224  
225 =head2 fill_buffer
226  
227 It is unlikely that you will need to call this method directly.
228 Reads more data from the internal filehandle into the buffer.
229 First argument may be the number of bytes to read, otherwise the
230 'read_length' attribute is used.
231  
232 Again, call this on the handler object, not the file handle.
233  
234 =cut
235  
236 2 ▶sub fill_buffer {
Subroutine fill_buffer: called CC=3 SCAR=11.4
Pod documented
237 2 my $self = shift;
238 2 ▶ my $length = shift || $self->{read_length};
Condition33%1/3
shift() || $self->{'read_length'}
l!l&&r!l&&!r
020
MC/DC0%0/2
shift() || $self->{'read_length'}
shift() $self->{'read_length'}
Truth table33%1/3
A || B
A= shift()B= $self->{'read_length'}
ABresult
1X1
011
000
239 2 my $data;
240 2 my $bytes = read( $self->{fh}, $data, $length );
241 2 ▶ return 0 if not $bytes;
Branch: 1 branch
BranchTrueFalseTotal
unless $bytes 0 2 2
242 2 $self->{buffer} .= $data;
243 2 return $bytes;
244 }
245  
246 1 ▶sub TIEHANDLE {
Subroutine TIEHANDLE: called CC=1 SCAR=0.0
247 1 my $class = shift;
248 1 my $fh = shift;
249 1 my $self = {
250 fh => $fh,
251 read_length => 1024,
252 separator => undef,
253 buffer => '',
254 die_on_anchors => 1,
255 @_
256 };
257 1 bless $self => $class;
258 }
259  
260 3 ▶sub READLINE { goto &readline; }
Subroutine READLINE: called CC=1 SCAR=0.0
261  
262 0 ▶sub PRINT {
Subroutine PRINT: not called CC=3 SCAR=24.8
263 0 my $self = shift;
264 0 ▶ my $buf = join( defined $, ? $, : "", @_ );
Branch: 1 branch
BranchTrueFalseTotal
defined $, ? : 0 0 0
265 0 ▶ $buf .= $\ if defined $\;
Branch: 1 branch
BranchTrueFalseTotal
if defined $\ 0 0 0
266 0 $self->WRITE( $buf, length($buf), 0 );
267 }
268  
269 0 ▶sub PRINTF {
Subroutine PRINTF: not called CC=1 SCAR=6.9
270 0 my $self = shift;
271  
272 0 my $buf = sprintf( shift, @_ );
273 0 $self->WRITE( $buf, length($buf), 0 );
274 }
275  
276 0 ▶sub GETC {
Subroutine GETC: not called CC=1 SCAR=6.9
277 0 my $self = shift;
278  
279 0 my $buf;
280 0 $self->READ( $buf, 1 );
281 0 return $buf;
282 }
283  
284 0 ▶sub READ {
Subroutine READ: not called CC=8 SCAR=42.8
285 0 ▶ croak if @_ < 3;
Branch: 1 branch
BranchTrueFalseTotal
if @_ < 3 0 0 0
286 0 my $self = shift;
287 0 my $bufref = \$_[0];
288 0 ▶ $$bufref = '' if not defined $$bufref;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $$bufref 0 0 0
289 0 my ( undef, $len, $offset ) = @_;
290 0 ▶ $offset = 0 if not defined $offset;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $offset 0 0 0
291 0 ▶ if ( length $self->{buffer} < $len ) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $self->{"buffer"} < $len) 0 0 0
292 0 my $bytes = 0;
293 0 ▶ while ( $bytes = $self->fill_buffer()
Branch: 1 branch
BranchTrueFalseTotal
if ($bytes = $self->fill_buffer and length $self->{"buffer"} < $len) 0 0 0
Condition0%0/3
$bytes = $self->fill_buffer and length $self->{"buffer"} < $len
!ll&&!rl&&r
000
MC/DC0%0/2
$bytes = $self->fill_buffer and length $self->{"buffer"} < $len
$bytes = $self->fill_buffer length $self->{"buffer"} < $len
Truth table0%0/3
A and B
A= $bytes = $self->fill_bufferB= length $self->{"buffer"} < $len
ABresult
0X0
100
111
294 and length( $self->{buffer} ) < $len )
295 { }
296  
297 0 ▶ if ( not $bytes ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($bytes) 0 0 0
298 0 my $length_avail = length( $self->{buffer} );
299 substr( $$bufref, $offset, $length_avail,
300 0 substr( $self->{buffer}, 0, $length_avail, '' ) );
301 0 return $length_avail;
302 }
303  
304 # only reached if buffer long enough.
305 }
306 0 substr( $$bufref, $offset, $len, substr( $self->{buffer}, 0, $len, '' ) );
307 0 return $len;
308 }
309  
310 0 ▶sub WRITE {
Subroutine WRITE: not called CC=1 SCAR=6.9
311 0 my $self = $_[0];
312 0 my $fh = $self->{fh};
313 0 print $fh substr( $_[1], 0, $_[2] );
314 }
315  
316 2 ▶sub TELL {
Subroutine TELL: called CC=1 SCAR=0.0
317 2 my $self = $_[0];
318 2 my $foffset = tell $self->{fh};
319 2 return $foffset - length($self->{buffer});
320 }
321  
322 1 ▶sub SEEK {
Subroutine SEEK: called CC=1 SCAR=0.0
323 1 my $self = $_[0];
324 1 seek $self->{fh}, $_[1], $_[2];
325 1 $self->{buffer} = '';
326 1 return 1;
327 }
328  
329 0 ▶sub EOF { not length( $_[0]->{buffer} ) and eof( *{ $_[0]->{fh} } ) }
Subroutine EOF: not called CC=2 SCAR=17.9
Branch: 1 branch
BranchTrueFalseTotal
not length $_[0]{"buffer"} and eof do { $_[0]{"fh"} } 0 0 0
330 0 ▶sub FILENO { fileno( *{ $_[0]->{fh} } ) }
Subroutine FILENO: not called CC=1 SCAR=6.9
331 0 ▶sub BINMODE { binmode( *{ $_[0]->{fh} }, @_ ) }
Subroutine BINMODE: not called CC=1 SCAR=6.9
332  
333 0 ▶sub CLOSE { close( *{ $_[0]->{fh} } ) }
Subroutine CLOSE: not called CC=1 SCAR=6.9
334 0 ▶sub UNTIE { close( *{ $_[0]->{fh} } ) }
Subroutine UNTIE: not called CC=1 SCAR=6.9
335 1 ▶sub DESTROY { close( *{ $_[0]->{fh} } ) }
Subroutine DESTROY: called CC=1 SCAR=0.0
336  
337 2 1;
338 __END__
↑ Summary