blib/lib/File/Navigate.pm

filter: Statementstmt 13.1% 10 / 76 Branchbran 0.0% 0 / 30 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 16.6% 2 / 12 Podpod 88.8% 8 / 9 totaltotal 15.7% 20 / 127 CC 16 SCAR 27.8
CC
16
Cov
9%
new
42.0
get
20.0
find
12.0
CRAP 16.1
↑ Summary
1 package File::Navigate;
2 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 =head1 NAME
6  
7 File::Navigate - Navigate freely inside a text file
8  
9 =head1 DESCRIPTION
10  
11 The module is a glorified wrapper for tell() and seek().
12  
13 It aims to simplify the creation of logfile analysis tools by
14 providing a facility to jump around freely inside the contents
15 of large files without creating the need to slurp excessive
16 amounts of data.
17  
18 =head1 SYNOPSIS
19  
20 use File::Navigate;
21 my $nav = File::Navigate->new('/var/log/messages');
22  
23 # Read what's below the "cursor":
24 my $first = $nav->get;
25  
26 # Advance the cursor before reading:
27 my $second = $nav->getnext;
28 my $third = $nav->getnext;
29  
30 # Advance the cursor by hand:
31 $nav->next;
32 my $fourth = $nav->get;
33  
34 # Position the cursor onto an arbitrary line:
35 $nav->cursor(10);
36 my $tenth = $nav->get;
37  
38 # Reverse the cursor one line backward:
39 $nav->prev;
40 my $ninth = $nav->get;
41  
42 # Reverse the cursor before reading:
43 my $eigth = $nav->getprev;
44  
45 # Read an arbitrary line:
46 my $sixth = $nav->get(6);
47  
48 =cut
49  
50 1 our @ISA = qw(Exporter);
51 1 our @EXPORT_OK = qw();
52 1 our $VERSION = '1.0';
53  
54 =head1 CLASS METHODS
55  
56 =head2 I<new()>
57  
58 Open the file and create an index of the lines inside of it.
59  
60 my $mapper = File::Navigate->new($filename);
61  
62 =cut
63  
64 0 ▶sub new($){
Subroutine new: not called CC=6 SCAR=37.4
Pod documented
65 0 my $class = shift;
66 0 my $file;
67 0 ▶ unless ($file = shift){
Branch: 1 branch
BranchTrueFalseTotal
unless ($file = shift()) 0 0 0
68 0 die "No file specified\n";
69 }
70 0 ▶ unless (-e $file){
Branch: 1 branch
BranchTrueFalseTotal
unless (-e $file) 0 0 0
71 0 die "File not found: $file\n";
72 }
73 0 ▶ unless (-r $file){
Branch: 1 branch
BranchTrueFalseTotal
unless (-r $file) 0 0 0
74 0 die "File not readable: $file\n";
75 }
76 0 my $self = {};
77 0 $self->{'cursor'} = 1;
78 0 $self->{'lineindex'} = {};
79 0 $self->{'lineindex'}->{1} = 0;
80 0 ▶ open my $fh, "$file"
Branch: 1 branch
BranchTrueFalseTotal
open my $fh, "$file" or die "Can't open ${file}: $!\n" 0 0 0
81 or die "Can't open $file: $!\n";
82 0 ▶ while (<$fh>){
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $fh)) 0 0 0
83 0 my $thisline = $.;
84 0 my $nextline = $thisline + 1;
85 0 $self->{'lineindex'}->{$nextline} = tell $fh;
86 }
87 0 $self->{'length'} = scalar(keys %{$self->{'lineindex'}}) - 1 ;
88 0 $self->{'fh'} = $fh;
89 0 bless $self;
90 }
91  
92 =head1 OBJECT METHODS
93  
94 =head2 I<count()>
95  
96 Returns the number of lines in the file ("wc -l")
97  
98 my $lines = $nav->count;
99  
100 =cut
101  
102 0 ▶sub length(){
Subroutine length: not called CC=1 SCAR=6.9
Pod undocumented
103 0 my $self = shift;
104 0 return $self->{'length'};
105 }
106  
107 =head2 I<cursor()>
108  
109 Returns the current cursor position and/or sets the cursor.
110  
111 my $cursor = $nav->cursor(); # Query cursor position.
112 my $cursor = $nav->cursor(10); # Set cursor to line 10
113  
114 =cut
115  
116 0 ▶sub cursor($){
Subroutine cursor: not called CC=2 SCAR=17.9
Pod documented
117 0 my $self = shift;
118 0 ▶ if (my $goto = shift){
Branch: 1 branch
BranchTrueFalseTotal
if (my $goto = shift()) 0 0 0
119 0 $self->{'cursor'} = $goto;
120 }
121 0 return $self->{'cursor'};
122 }
123  
124 =head2 I<get()>
125  
126 Gets the line at the cursor position or at the given position.
127  
128 my $line = $nav->get(); # Get line at cursor
129 my $line = $nav->get(10); # Get line 10
130  
131 =cut
132  
133 0 ▶sub get($){
Subroutine get: not called CC=4 SCAR=30.0
Pod documented
134 0 my $self = shift;
135 0 my $fh = $self->{'fh'};
136  
137 0 my $getline;
138 0 ▶ $getline = $self->{'cursor'} unless ($getline = shift);
Branch: 1 branch
BranchTrueFalseTotal
unless $getline = shift() 0 0 0
139  
140 0 ▶ if ($getline < 1){
Branch: 2 branches
BranchTrueFalseTotal
if ($getline < 1) { } 0 0 0
elsif ($getline > $self->{'length'}) { } 0 0 0
141 0 warn "WARNING: Seek before first line.";
142 0 return undef;
143 }elsif($getline > $self->{'length'}){
144 0 warn "WARNING: Seek beyond last line.";
145 0 return undef;
146 }
147 0 seek ($fh, $self->{'lineindex'}->{$getline}, 0);
148 0 my $gotline = <$fh>;
149 0 chomp $gotline;
150 0 return $gotline;
151 }
152  
153 =head2 I<next()>
154  
155 Advance the cursor position by one line. Returns the new cursor position.
156 Returns I<undef> if the cursor is already on the last line.
157  
158 my $newcursor = $nav->next();
159  
160 =cut
161  
162 0 ▶sub next(){
Subroutine next: not called CC=2 SCAR=17.9
Pod documented
163 0 my $self = shift;
164 0 ▶ if ($self->{'cursor'} == $self->{'length'}){
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"cursor"} == $self->{"length"}) 0 0 0
165 0 return undef;
166 }
167 0 $self->{'cursor'}++;
168 0 return $self->{'cursor'};
169 }
170  
171 =head2 I<prev()>
172  
173 Reverse the cursor position by one line. Returns the new cursor position.
174 Returns I<undef> if the cursor is already on line 1.
175  
176 my $newcursor = $nav->prev();
177  
178 =cut
179  
180 0 ▶sub prev(){
Subroutine prev: not called CC=2 SCAR=17.9
Pod documented
181 0 my $self = shift;
182 0 ▶ if ($self->{'cursor'} == 1){
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"cursor"} == 1) 0 0 0
183 0 return undef;
184 }
185 0 $self->{'cursor'}--;
186 0 return $self->{'cursor'};
187 }
188  
189 =head2 I<getnext()>
190  
191 Advance to the next line and return it.
192 Returns I<undef> if the cursor is already on the last line.
193  
194 my $newcursor = $nav->getnext();
195  
196 =cut
197  
198 0 ▶sub getnext(){
Subroutine getnext: not called CC=2 SCAR=17.9
Pod documented
199 0 my $self = shift;
200 0 ▶ $self->next or return undef;
Branch: 1 branch
BranchTrueFalseTotal
$self->next or return undef 0 0 0
201 0 return $self->get;
202 }
203  
204 =head2 I<getprev()>
205  
206 Reverse to the previous line and return it:
207 Returns I<undef> if the cursor is already on line 1.
208  
209 my $newcursor = $nav->getprev();
210  
211 =cut
212  
213 0 ▶sub getprev(){
Subroutine getprev: not called CC=2 SCAR=17.9
Pod documented
214 0 my $self = shift;
215 0 ▶ $self->prev or return undef;
Branch: 1 branch
BranchTrueFalseTotal
$self->prev or return undef 0 0 0
216 0 return $self->get;
217 }
218  
219 =head2 I<find()>
220  
221 Find lines containing given regex. Returns array with line numbers.
222  
223 my @lines = @{$nav->find(qr/foo/)};
224  
225 =cut
226  
227 0 ▶sub find($){
Subroutine find: not called CC=3 SCAR=24.8
Pod documented
228 0 my $self = shift;
229 0 my $regex = shift;
230
231 0 my @results;
232 0 ▶ for (my $lineno = 1; $lineno <= $self->{'length'}; $lineno++){
Branch: 1 branch
BranchTrueFalseTotal
if ($lineno <= $self->{"length"}) 0 0 0
233 0 my $line = $self->get($lineno);
234 0 ▶ if ($line =~ $regex){
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /$regex/) 0 0 0
235 0 push @results, $lineno;
236 }
237 }
238 0 return \@results;
239 }
240  
241 0 ▶sub DESTROY(){
Subroutine DESTROY: not called CC=1 SCAR=6.9
242 0 my $self = shift;
243 0 close $self->{'fh'};
244 }
245  
246 =head1 EXAMPLE
247  
248 I<tac>, the opposite of I<cat>, in Perl using File::Navigate:
249  
250 #!/usr/bin/perl -w
251 use strict;
252 use File::Navigate;
253
254 foreach my $file (reverse(@ARGV)){
255 my $nav = File::Navigate->new($file);
256 # Force cursor beyond last line
257 $nav->cursor($nav->length()+1);
258 print $nav->get()."\n" while $nav->prev();
259 }
260  
261 =head1 BUGS
262  
263 Seems to lack proper error handling.
264  
265 =head1 LIMITATIONS
266  
267 Works only on plain text files. Sockets, STDIO etc. are not supported.
268  
269 =head1 PREREQUISITES
270  
271 Tested on Perl 5.6.1.
272  
273 =head1 STATUS
274  
275 Mostly harmless.
276  
277 =head1 AUTHOR
278  
279 Martin Schmitt <mas at scsy dot de>
280  
281 =cut
282  
283 1 1;
↑ Summary