blib/lib/File/Kvpar.pm untested

filter: Statementstmt 0.0% 0 / 127 Branchbran 0.0% 0 / 48 Conditioncond 0.0% 0 / 6 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 0.0% 0 / 17 Podpod 0.0% 0 / 13 totaltotal 0.0% 0 / 214 CC 25 SCAR 30.0
CC
25
Cov
0%
new
42.0
_par2hash
42.0
_hash2par
30.0
CRAP 20.1
1 package File::Kvpar;
2  
3 use strict;
4 use warnings;
5  
6 use constant HEAD => 1;
7 use constant TAIL => 2;
8  
9 sub new {
10 my $cls = shift;
11 my ($mode, $file, $fh);
12 my %self = (
13 'elements' => [],
14 'have_read' => 0,
15 'pos' => 0,
16 );
17 if (@_ == 1) {
18 $file = shift;
19 if (ref $file) {
20 ($fh, $file) = ($file, "<$file>");
21 $mode = '<';
22 }
23 elsif ($file =~ s/^([<>+]+)//) {
24 $mode = $1;
25 }
26 else {
27 $mode = '<';
28 }
29 }
30 elsif (@_ == 2) {
31 ($mode, $file) = @_;
32 }
33 if (!defined $fh) {
34 open $fh, $mode, $file or die "Can't open $file: $!";
35 }
36 @self{qw(file fh)} = ($file, $fh);
37 bless \%self, $cls;
38 }
39  
40 sub iter {
41 my ($self) = @_;
42 my @elems = @{ $self->{'elements'} };
43 return sub {
44 return shift @elems if @elems;
45 return if $self->{'have_read'} & TAIL;
46 return $self->_read_one;
47 }
48 }
49  
50 sub write {
51 my $self = shift;
52 return if !@_;
53 my ($fh, $elems, $pos) = @$self{qw(fh elements pos)};
54 my @elems = @$elems;
55 splice @elems, $pos, @elems - $pos, @_ if $pos > 0;
56 my @pars = map { _hash2par($_) } @_;
57 print $fh @pars;
58 my $ofs = tell $fh;
59 truncate $fh, $ofs;
60 push @elems, @_;
61 $self->{'pos'} = @elems;
62 @$elems = @elems;
63 return $self;
64 }
65  
66 sub append {
67 my $self = shift;
68 return if !@_;
69 my ($fh, $elems, $pos) = @$self{qw(fh elements pos)};
70 seek $fh, 0, 2 or die "Can't seek to end: $!";
71 my @elems = @$elems;
72 push @elems, @_;
73 my @pars = map { _hash2par($_) } @_;
74 print $fh @pars;
75 $self->{'pos'} = @$elems;
76 @$elems = @elems;
77 return $self;
78 }
79  
80 sub truncate {
81 my ($self) = @_;
82 my ($fh, $elems, $pos) = @$self{qw(fh elements pos)};
83 my $ofs = tell $fh;
84 truncate $fh, $ofs;
85 splice @$elems, $pos;
86 return $self;
87 }
88  
89 sub _hash2par {
90 my ($hash) = @_;
91 my $par = '';
92 my %hash = %$hash;
93 my ($at, $lb) = delete @hash{'@','#'};
94 if (defined $at) {
95 $par .= '@' . $at;
96 $par .= ' ' . $lb if defined $lb;
97 $par .= "\n";
98 }
99 foreach my $k (sort keys %hash) {
100 my $v = $hash{$k};
101 $par .= "$k $v\n" if defined $v;
102 }
103 $par = "#empty\n" if !length $par;
104 return $par . "\n";
105 }
106  
107 sub _par2hash {
108 my ($par) = @_;
109 chomp $par;
110 my %hash;
111 foreach (split /\n/, $par) {
112 if (/^[@](\S*)(?: (.+))?$/) {
113 $hash{'@'} = $1 if length $1;
114 $hash{'#'} = $2 if defined $2;
115 }
116 elsif (/^[#]/) {
117 next;
118 }
119 elsif (/^(\S+) (.*)$/) {
120 $hash{$1} = $2;
121 }
122 }
123 return \%hash;
124 }
125  
126 sub _read_one {
127 my ($self) = @_;
128 my $fh = $self->{'fh'};
129 local $/ = '';
130 my $elems = $self->{'elements'};
131 if (my $par = <$fh>) {
132 $self->{'pos'}++;
133 my $hash = _par2hash($par);
134 push @{ $elems }, $hash;
135 $self->{'have_read'} |= HEAD;
136 return $hash;
137 }
138 else {
139 $self->{'have_read'} |= TAIL;
140 return;
141 }
142 }
143  
144 sub _read_remainder {
145 my ($self) = @_;
146 my ($hash, @rem);
147 while ($hash = $self->_read_one) {
148 push @rem, $hash;
149 }
150 return @rem;
151 }
152  
153 sub head {
154 my ($self) = @_;
155 my $elems = $self->{'elements'};
156 return $self->_read_one if !@$elems;
157 return $elems->[0];
158 }
159  
160 sub tail {
161 my ($self) = @_;
162 my $elems = $self->{'elements'};
163 $self->_read_remainder if !( $self->{'have_read'} & TAIL );
164 return if @$elems < 2;
165 return @$elems[1..$#$elems];
166 }
167  
168 sub reset {
169 my ($self) = @_;
170 seek $self->{'fh'}, 0, 0 or die "Can't seek to beginning of file: $!";
171 $self->{'pos'} = 0;
172 $self->{'elements'} = [];
173 $self->{'have_read'} = 0;
174 return $self;
175 }
176  
177 sub elements {
178 my ($self) = @_;
179 my $elems = $self->{'elements'};
180 $self->_read_remainder if ( $self->{'have_read'} & (HEAD|TAIL) ) != (HEAD|TAIL);
181 return @$elems;
182 }
183  
184 1;
185  
186 =pod
187  
188 =head1 NAME
189  
190 File::Kvpar - read and write files containing key-value paragraphs
191  
192 =head1 SYNOPSIS
193  
194 $kv = File::Kvpar->new($file);
195 $kv = File::Kvpar->new($mode, $file); # $mode = '<' || '>' || ...
196 $kv = File::Kvpar->new($fh);
197 $iter = $kv->iter;
198 while ($elem = &$iter) {
199 ...
200 }
201 @a = $kv->elements;
202 $a = $kv->head;
203 @a = $kv->tail;
204 foreach ($kv->elements) {
205 ...
206 }
207  
208 =head1 DESCRIPTION
209  
210 A B<kvpar> file consists of zero or more paragraphs (delimited by blank lines).
211 Each line in a paragraph has the form C<< I<KEY> I<VAL> >>; the key and value
212 are separated by a single space (ASCII character 32).
213  
214 A single element may have the form C<< @I<STR> I<VAL> >> -- if it does, the
215 element's hash will be augmented with the key/value pairs
216 (
217 C<@> => I<STR>,
218 C<#> => I<VAL>
219 ). No further interpretation is made, but one use of this might be to treat
220 I<STR> as the object's B<type> and I<VAL> as the object's B<primary key>.
221  
222 =head1 METHODS
223  
224 =over 4
225  
226 =item B<new>
227  
228 $kv = File::Kvpar->new($file);
229 $kv = File::Kvpar->new($mode, $file);
230 $kv = File::Kvpar->new($fh);
231  
232 Open or create a kvpar-formatted file.
233  
234 I<$mode> defaults to C<< E<lt> >> if a file path is the only argument.
235  
236 For greater control, pass a filehandle as the only argument. Passing both a
237 mode and filehandle will cause an exception to be thrown.
238  
239 =item B<iter>
240  
241 $iter = $kv->iter;
242 while ($hash = &$iter) { ... }
243 while ($hash = $iter->()) { ... }
244  
245 Return a CODE reference that may be invoked to obtain the next element in the
246 file. It returns the undefined value if all elements have been read.
247  
248 =item B<elements>
249  
250 Return a list (not an array reference) of all elements in the file. Any unread
251 elements will be read.
252  
253 =item B<head>
254  
255 Return the first element in the file. It will be read if it hasn't already been.
256  
257 =item B<tail>
258  
259 @elems = $kv->tail;
260  
261 Return a list of all elements after the first. Any unread elements will be read.
262  
263 =item B<write>
264  
265 $kv->write(@hashes);
266  
267 Write I<@hashes> to the current position in the file. The file will be
268 truncated afterwards, since the alternative would totally mess up files in most
269 cases. The file must have been opened for write access, of course.
270  
271 =item B<append>
272  
273 $kv->append(@hashes);
274  
275 Write I<@hashes> to the end of the file. The file must have been opened for
276 write access, of course.
277  
278 =item B<truncate>
279  
280 $kv = File::Kvpar->new('<+', $file);
281 $kv->head; # Read and discard the first element
282 $kv->truncate;
283 $kv->write({...});
284  
285 Truncate the file at the current position and discard any elements that may
286 have been read at or after the current position. If nothing has been read from
287 the file, the file will become empty.
288  
289 =item B<reset>
290  
291 $kv->reset;
292  
293 Set the file position to 0 -- i.e., seek to the beginning of the file -- and
294 discard any elements that have already been read. If the file has been opened
295 for write access, the next B<write> will truncate it. If it has been opened
296 for append access, the next B<append> will wreak havoc unless you call
297 B<truncate> first.
298  
299 This will throw an exception if the underlying filehandle is not seekable.
300  
301 =back
302  
303 =cut
304