PropertyList/WriteBinary.pm

filter: Statementstmt 92.7% 153 / 165 Branchbran 87.0% 47 / 54 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 93.3% 28 / 30 Podpod 0.0% 0 / 1 totaltotal 91.2% 228 / 250 CC 29 SCAR 15.5
CC
29
Cov
91%
_assign_id
12.0
_create_fragments
7.2
as_string
4.0
CRAP 4.7
↑ Summary PropertyList.pm »
1 4 ▶use v5.10;
Subroutine BEGIN: called CC=1 SCAR=0.0
2  
3 package Mac::PropertyList::WriteBinary;
4 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 4 ▶use Encode ();
Subroutine BEGIN: called CC=1 SCAR=0.0
8 4 ▶use Mac::PropertyList ();
Subroutine BEGIN: called CC=1 SCAR=0.0
9 4 ▶use Math::BigInt;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 4 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 =encoding utf8
13  
14 =head1 NAME
15  
16 Mac::PropertyList::WriteBinary - pack data into a Mac "binary property list"
17  
18 =head1 SYNOPSIS
19  
20 use Mac::PropertyList::WriteBinary;
21  
22 my $data = Mac::PropertyList::dict->new( { ... => ... } );
23 my $buf = Mac::PropertyList::WriteBinary::as_string($data);
24  
25 =head1 DESCRIPTION
26  
27 The C<as_string> function converts a property list structure
28 (composed of instances of C<Mac::PropertyList::dict>,
29 C<Mac::PropertyList::integer>, etc.) into a binary format compatible
30 with the Apple CoreFoundation binary property list functions.
31  
32 It takes a single argument, the top-level object to write, and returns
33 a byte string.
34  
35 The property list can contain the following perl objects:
36  
37 =over 4
38  
39 =item C<Mac::PropertyList> value objects
40  
41 These are written according to their class.
42  
43 =item Unblessed references to Perl lists and hashes
44  
45 These are written as arrays and dictionaries, respectively.
46  
47 =item Perl scalars
48  
49 All Perl scalars are written as strings; this is similar to the behavior
50 of writing an oldstyle OpenStep property list, which does not
51 distinguish between numbers and strings, and then reading it using
52 CoreFoundation functions.
53  
54 =item C<undef>
55  
56 This is written as the null object. CoreFoundation will read this as
57 C<kCFNull>, but appears to be unable to write it.
58  
59 =back
60  
61 Strings are uniqued (two equal strings will be written as references
62 to the same object). If the same reference appears more than once in
63 the structure, it will likewise only be represented once in the
64 output. Although the bplist format can represent circular data
65 structures, they cannot be written by this module (they will be
66 detected and result in an error — they wouldn't be read correctly by
67 CoreFoundation anyway, so you aren't missing much).
68  
69 =head1 BUGS
70  
71 C<Mac::PropertyList::date> objects are not handled yet.
72  
73 Objects other than strings (and null) are not uniqued by value,
74 only by reference equality. This may change in a future version.
75  
76 Perl's dictionary keys can only be strings, but a bplist's can be
77 any scalar object.
78  
79 There is no way to write the C<UID> objects used by the keyed archiver.
80  
81 Perls that do not use IEEE-754 format internally for floating point
82 numbers will produce incorrect output.
83  
84 =cut
85  
86 4 ▶use constant {
Subroutine BEGIN: called CC=2 SCAR=7.0
87 header => 'bplist00',
88  
89 tagInteger => 0x10,
90 tagFloat => 0x20,
91 tagDate => 0x30,
92 tagData => 0x40,
93 tagASCII => 0x50,
94 tagUTF16 => 0x60,
95 tagUID => 0x80,
96 tagArray => 0xA0,
97 tagSet => 0xC0,
98 tagDict => 0xD0,
99  
100 # If we can actually represent an integer close to 2^64 with full
101 # precision and pack it with 'Q', then we can use that
102 4 ▶ havePack64 => ( eval { pack('Q>', 1153202979583557643) eq "\x10\x01\0\0\0\0\0\x0B" } ? 1 : 0 ),
Branch: 1 branch
BranchTrueFalseTotal
eval { do { !0 } } ? : 4 0 4
103 4 };
104  
105 4 our $VERSION = '1.608';
106 4 our @EXPORT_OK = qw( as_string );
107  
108 49 ▶sub as_string {
Subroutine as_string: called CC=4 SCAR=14.0
Pod undocumented
109 49 my($value) = @_;
110 49 my($ctxt) = _create_fragments($value);
111 47 my(@offsets, $xref_offset, $offset_size);
112  
113 # The header (magic number and version, which is 00)
114 47 my($buf) = header;
115  
116 # Write each fragment, making note of its offset in the file
117 47 foreach my $objid (0 .. $ctxt->{nextid}-1) {
118 96 $offsets[$objid] = length $buf;
119 96 $buf .= $ctxt->{fragments}->{$objid};
120 }
121  
122 # ... and the offset of the beginning of the offsets table
123 47 $xref_offset = length $buf;
124  
125 # Figure out how many bytes to use to represent file offsets,
126 # and append the offset table
127 47 ▶ if ($xref_offset < 256) {
Branch: 2 branches
BranchTrueFalseTotal
if ($xref_offset < 256) { } 46 1 47
elsif ($xref_offset < 65536) { } 1 0 1
128 46 $buf .= pack('C*', @offsets);
129 46 $offset_size = 1;
130 } elsif ($xref_offset < 65536) {
131 1 $buf .= pack('n*', @offsets);
132 1 $offset_size = 2;
133 } else {
134 0 $buf .= pack('N*', @offsets);
135 0 $offset_size = 4;
136 }
137  
138 # Write the file trailer
139 $buf .= pack('x5 CCC ' . ( havePack64? 'Q>' : 'x4N' ) x 3,
140 0, $offset_size, $ctxt->{objref_size},
141 47 $ctxt->{nextid}, $ctxt->{rootid}, $xref_offset);
142  
143 47 $buf;
144 }
145  
146 # sub to_file {
147 # To consider:
148 # It might be useful to have a version of &as_string which writes
149 # the fragments directly to a file handle without having to build a
150 # single large buffer in RAM. This would be more efficient for
151 # larger structures. On the other hand, if you're writing large
152 # structures with this module, you're already suffering needlessly,
153 # so perhaps it's not worth optimizing overmuch for that case.
154 # }
155  
156  
157 # _assign_id is the workhorse function which recursively
158 # descends the data structure and assigns object ids to each node,
159 # as well as creating fragments of the final file.
160 120 ▶sub _assign_id {
Subroutine _assign_id: called CC=12 SCAR=24.8
161 120 my($context, $value) = @_;
162  
163 # The type of this value
164 120 my($tp) = ref $value;
165  
166 # Unblessed scalars are either strings or undef.
167 120 ▶ if ($tp eq '') {
Branch: 1 branch
BranchTrueFalseTotal
if ($tp eq "") 31 89 120
168 31 ▶ if (!defined $value) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $value) { } 2 29 31
169 $context->{nullid} = $context->{nextid} ++
170 2 ▶ unless defined $context->{nullid};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $context->{"nullid"} 2 0 2
171 2 return $context->{nullid};
172 } else {
173 $context->{strings}->{$value} = $context->{nextid} ++
174 29 ▶ unless exists $context->{strings}->{$value};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $context->{"strings"}{$value} 22 7 29
175 29 return $context->{strings}->{$value};
176 }
177 }
178  
179 # If we reach here we know that $value is a ref. Keep a table of
180 # stringified refs, so that we can re-use the id of an object
181 # we've seen before.
182 89 ▶ if(exists $context->{refs}{$value}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $context->{"refs"}{$value}) 4 85 89
183 4 my($thisid) = $context->{refs}->{$value};
184 4 ▶ die "Recursive data structure\n" unless defined $thisid;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $thisid 1 3 4
185 3 return $thisid;
186 }
187 85 $context->{refs}->{$value} = undef;
188  
189 # Serialize the object into $fragment if possible. Since we
190 # don't yet know how many bytes we will use to represent object
191 # ids in the final file, don't serialize those yet–keep them
192 # as a list of integers for now.
193 85 my($fragment, @objrefs);
194  
195 85 ▶ if($tp eq 'ARRAY') {
Branch: 3 branches
BranchTrueFalseTotal
if ($tp eq 'ARRAY') { } 4 81 85
elsif ($tp eq 'HASH') { } 3 78 81
elsif (UNIVERSAL::can($tp, '_as_bplist_fragment')) { } 77 1 78
196 4 $fragment = _counted_header(tagArray, scalar @$value);
197 4 @objrefs = map { $context->_assign_id($_) } @$value;
198 } elsif($tp eq 'HASH') {
199 3 my(@ks) = sort (CORE::keys %$value);
200 3 $fragment = _counted_header(tagDict, scalar @ks);
201 6 @objrefs = ( ( map { $context->_assign_id($_) } @ks ),
202 3 ( map { $context->_assign_id($value->{$_}) } @ks ) );
203 } elsif(UNIVERSAL::can($tp, '_as_bplist_fragment')) {
204 77 ($fragment, @objrefs) = $value->_as_bplist_fragment($context);
205 } else {
206 1 die "Cannot serialize type '$tp'\n";
207 }
208  
209 # As a special case, a fragment of 'undef' indicates that
210 # the object ID was already assigned.
211 81 ▶ return $objrefs[0] if !defined $fragment;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $fragment 6 75 81
212  
213 # Assign the next object ID to this object.
214 75 my($thisid) = $context->{nextid} ++;
215 75 $context->{refs}->{$value} = $thisid;
216  
217 # Store the fragment and unpacked object references (if any).
218 75 $context->{fragments}->{$thisid} = $fragment;
219 75 ▶ $context->{objrefs}->{$thisid} = \@objrefs if @objrefs;
Branch: 1 branch
BranchTrueFalseTotal
if @objrefs 11 64 75
220  
221 75 return $thisid;
222 }
223  
224 49 ▶sub _create_fragments {
Subroutine _create_fragments: called CC=7 SCAR=19.8
225 49 my ($value) = @_;
226  
227 # Set up the state needed by _assign_id
228  
229 49 my ($ctxt) = bless({
230 nextid => 0, # The next unallocated object ID
231 nullid => undef, # The object id of 'null'
232 strings => { }, # Maps string values to object IDs
233 refs => { }, # Maps stringified refs to object IDs
234 fragments => { }, # Maps object IDs to bplist fragments, except object lists
235 objrefs => { }, # Maps object IDs to objref lists
236 });
237  
238 # Traverse the data structure, and remember the id of the root object
239 49 $ctxt->{rootid} = $ctxt->_assign_id($value);
240  
241 # Figure out how many bytes to use to represent an object id.
242 47 my ($objref_pack);
243 47 ▶ if ($ctxt->{nextid} < 256) {
Branch: 2 branches
BranchTrueFalseTotal
if ($ctxt->{'nextid'} < 256) { } 47 0 47
elsif ($ctxt->{'nextid'} < 65536) { } 0 0 0
244 47 $objref_pack = 'C*';
245 47 $ctxt->{objref_size} = 1;
246 } elsif ($ctxt->{nextid} < 65536) {
247 0 $objref_pack = 'n*';
248 0 $ctxt->{objref_size} = 2;
249 } else {
250 0 $objref_pack = 'N*';
251 0 $ctxt->{objref_size} = 4;
252 }
253  
254 47 my($objid, $reflist, $stringval);
255  
256 # Append the unformatted object ids to their corresponding fragments,
257 # now that we know how to pack them.
258 47 ▶ while (($objid, $reflist) = each %{$ctxt->{objrefs}}) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$$ctxt{"objrefs"};}) 11 47 58
259 11 $ctxt->{fragments}->{$objid} .= pack($objref_pack, @$reflist);
260 }
261 47 delete $ctxt->{objrefs};
262  
263 # Create fragments for all the strings.
264 # TODO: If &to_file is written, it would be worth
265 # breaking this out so that the conversion can be done on the
266 # fly without keeping all of the converted strings in memory.
267 {
268 47 my($ascii) = Encode::find_encoding('ascii');
269 47 my($utf16be) = Encode::find_encoding('UTF-16BE');
270  
271 47 ▶ while (($stringval, $objid) = each %{$ctxt->{strings}}) {
Branch: 1 branch
BranchTrueFalseTotal
if (($stringval, $objid) = each %{$$ctxt{"strings"};}) 19 47 66
272 19 my($fragment);
273  
274 # Strings may be stored as ASCII (7 bits) or UTF-16-bigendian.
275 19 ▶ if ($stringval =~ /\A[\x01-\x7E]*\z/s) {
Branch: 1 branch
BranchTrueFalseTotal
if ($stringval =~ /\A[\x01-\x7E]*\z/s) { } 16 3 19
276 # The string is representable in ASCII.
277 16 $fragment = $ascii->encode($stringval);
278 16 $fragment = _counted_header(tagASCII, length $fragment) . $fragment;
279 } else {
280 3 $fragment = $utf16be->encode($stringval);
281 3 $fragment = _counted_header(tagUTF16, (length $fragment)/2) . $fragment;
282 }
283  
284 19 $ctxt->{fragments}->{$objid} = $fragment;
285 }
286 }
287  
288 # If there's a <null> in the file, create its fragment.
289 $ctxt->{fragments}->{$ctxt->{nullid}} = "\x00"
290 47 ▶ if defined $ctxt->{nullid};
Branch: 1 branch
BranchTrueFalseTotal
if defined $ctxt->{"nullid"} 2 45 47
291  
292 47 $ctxt;
293 }
294  
295 38 ▶sub _counted_header {
Subroutine _counted_header: called CC=2 SCAR=6.9
296 38 my ($typebyte, $count) = @_;
297  
298 # Datas, strings, and container objects have a count/size encoded
299 # in the lower 4 bits of their type byte. If the count doesn't fit
300 # in 4 bits, the bits are set to all-1s and the actual value
301 # follows, encoded as an integer (including the integer's
302 # own type byte).
303  
304 38 ▶ if ($count < 15) {
Branch: 1 branch
BranchTrueFalseTotal
if ($count < 15) { } 32 6 38
305 32 return pack('C', $typebyte + $count);
306 } else {
307 6 return pack('C', $typebyte + 15) . &_pos_integer($count);
308 }
309 }
310  
311 14 ▶sub _neg_integer {
Subroutine _neg_integer: called CC=1 SCAR=0.0
312 14 my($count) = @_;
313 14 if (havePack64) {
314 14 return pack('Cq>', tagInteger + 3, $count);
315 } else {
316 return _pack_int_64(Math::BigInt->new($count)->badd(
317 Math::BigInt->new('0x10000000000000000')));
318 }
319 }
320  
321 35 ▶sub _pos_integer {
Subroutine _pos_integer: called CC=4 SCAR=13.9
322 35 my($count) = @_;
323  
324 35 ▶ if ($count < 256) {
Branch: 3 branches
BranchTrueFalseTotal
if ($count < 256) { } 18 17 35
elsif ($count <= 65535) { } 5 12 17
elsif ($count <= 4294967295) { } 4 8 12
325 18 return pack('CC', tagInteger + 0, $count);
326 } elsif ($count <= 65535) { # 0xFFFF
327 5 return pack('CS>', tagInteger + 1, $count);
328 } elsif ($count <= 4294967295) { # 0xFFFFFFFF
329 4 return pack('CN', tagInteger + 2, $count);
330 } elsif (havePack64) {
331 8 return pack('Cq>', tagInteger + 3, $count);
332 } else {
333 return _pack_int_64($count);
334 }
335 }
336  
337 0 ▶sub _pack_int_64 {
Subroutine _pack_int_64: not called CC=1 SCAR=6.9
338 0 my($val) = @_;
339 0 my $low = Math::BigInt->new($val)->bmod(Math::BigInt->new('0x100000000'));
340 0 my $high = Math::BigInt->new($val)->brsft(32);
341 0 return pack( 'CNN', tagInteger + 3, $high->numify, $low->numify);
342 }
343  
344 package Mac::PropertyList::array;
345  
346 3 ▶sub _as_bplist_fragment {
Subroutine _as_bplist_fragment: called CC=1 SCAR=0.0
347 3 my($context, @items) = ( $_[1], $_[0]->value );
348 3 @items = map { $context->_assign_id($_) } @items;
349  
350 3 return ( Mac::PropertyList::WriteBinary::_counted_header(Mac::PropertyList::WriteBinary::tagArray, scalar @items),
351 @items );
352 }
353  
354 package Mac::PropertyList::dict;
355  
356 6 ▶sub _as_bplist_fragment {
Subroutine _as_bplist_fragment: called CC=1 SCAR=0.0
357 6 my($self, $context) = @_;
358 6 my($value) = scalar $self->value; # Returns a ref in scalar context
359 6 my(@keys) = sort (CORE::keys %$value);
360  
361 return ( Mac::PropertyList::WriteBinary::_counted_header(Mac::PropertyList::WriteBinary::tagDict, scalar @keys),
362 13 ( map { $context->_assign_id($_) } @keys ),
363 6 ( map { $context->_assign_id($value->{$_}) } @keys ));
364  
365 }
366  
367 package Mac::PropertyList::date;
368  
369 4 ▶use Scalar::Util ( 'looks_like_number' );
Subroutine BEGIN: called CC=1 SCAR=0.0
370 4 ▶use Time::Local ( 'timegm' );
Subroutine BEGIN: called CC=1 SCAR=0.0
371  
372 4 ▶sub _as_bplist_fragment {
Subroutine _as_bplist_fragment: called CC=3 SCAR=11.2
373 4 my($value) = scalar $_[0]->value;
374 4 my($posixval);
375  
376 4 ▶ if (looks_like_number($value)) {
Branch: 2 branches
BranchTrueFalseTotal
if (&looks_like_number($value)) { } 1 3 4
elsif ($value =~ /\A(\d\d\d\d)-(\d\d)-(\d\d)T(\d\d)\:(\d\d)\:(\d\d(?:\.\d+)?)Z\z/) { } 3 0 3
377 1 $posixval = $value;
378 } elsif ($value =~ /\A(\d\d\d\d)-(\d\d)-(\d\d)T(\d\d)\:(\d\d)\:(\d\d(?:\.\d+)?)Z\z/) {
379 3 $posixval = timegm($6, $5, $4, $3, $2 - 1, $1);
380 } else {
381 0 die "Invalid plist date '$value'\n";
382 }
383  
384 # Dates are simply stored as floating-point numbers (seconds since the
385 # start of the CoreFoundation epoch) with a different tag value.
386 # See the notes in Mac::PropertyList::real on float format.
387 4 return pack('Cd>', Mac::PropertyList::WriteBinary::tagDate + 3,
388 $posixval - 978307200);
389 }
390  
391 package Mac::PropertyList::real;
392  
393 # Here we're assuming that the 'd' format for pack produces
394 # an IEEE-754 double-precision (64-bit) floating point
395 # representation, because ... it does on practically every
396 # system. However, this will not be portable to systems which
397 # don't natively use IEEE-754 format!
398  
399 5 ▶sub _as_bplist_fragment {
Subroutine _as_bplist_fragment: called CC=1 SCAR=0.0
400 5 my($self) = shift;
401  
402 5 return pack('Cd>', Mac::PropertyList::WriteBinary::tagFloat + 3, $self->value);
403 }
404  
405 package Mac::PropertyList::integer;
406  
407 4 ▶use constant tagInteger => 0x10;
Subroutine BEGIN: called CC=1 SCAR=0.0
408  
409 43 ▶sub _as_bplist_fragment {
Subroutine _as_bplist_fragment: called CC=2 SCAR=6.9
410 43 my($value) = $_[0]->value;
411  
412 # Per comments in CFBinaryPList.c, only 8-byte integers (and
413 # 16-byte integers, if they're supported, which they're not) are
414 # interpreted as signed. Shorter integers are always unsigned.
415 # Therefore all negative numbers must be written as 8-byte
416 # integers.
417  
418 43 ▶ my $method = $value < 0 ? '_neg_integer' : '_pos_integer';
Branch: 1 branch
BranchTrueFalseTotal
$value < 0 ? : 14 29 43
419 43 my $sub = Mac::PropertyList::WriteBinary->can($method);
420 43 $sub->($value);
421 }
422  
423 package Mac::PropertyList::uid;
424  
425 4 ▶use constant tagUID => Mac::PropertyList::WriteBinary->tagUID;
Subroutine BEGIN: called CC=1 SCAR=0.0
426  
427 4 ▶sub _as_bplist_fragment {
Subroutine _as_bplist_fragment: called CC=1 SCAR=0.0
428 4 my( $value ) = $_[0]->value;
429  
430 # TODO what about UIDs longer than 16 bytes? Or are there none?
431 4 return pack 'CH*', tagUID + length( $value ) / 2 - 1, $value;
432 }
433  
434 package Mac::PropertyList::string;
435  
436 6 ▶sub _as_bplist_fragment {
Subroutine _as_bplist_fragment: called CC=1 SCAR=0.0
437 # Returning a fragment of 'undef' indicates we've already assigned
438 # an object ID.
439 6 return ( undef, $_[1]->_assign_id($_[0]->value) );
440 }
441  
442 package Mac::PropertyList::ustring;
443  
444 0 ▶sub _as_bplist_fragment {
Subroutine _as_bplist_fragment: not called CC=1 SCAR=6.9
445 # Returning a fragment of 'undef' indicates we've already assigned
446 # an object ID.
447 0 return ( undef, $_[1]->_assign_id($_[0]->value) );
448 }
449  
450 package Mac::PropertyList::data;
451  
452 3 ▶sub _as_bplist_fragment {
Subroutine _as_bplist_fragment: called CC=1 SCAR=0.0
453 3 my($value) = $_[0]->value;
454 3 return (&Mac::PropertyList::WriteBinary::_counted_header(Mac::PropertyList::WriteBinary::tagData, length $value) .
455 $value);
456 }
457  
458 package Mac::PropertyList::true;
459  
460 2 ▶sub _as_bplist_fragment { return "\x09"; }
Subroutine _as_bplist_fragment: called CC=1 SCAR=0.0
461  
462 package Mac::PropertyList::false;
463  
464 1 ▶sub _as_bplist_fragment { return "\x08"; }
Subroutine _as_bplist_fragment: called CC=1 SCAR=0.0
465  
466 =head1 AUTHOR
467  
468 Wim Lewis, C<< <wiml@cpan.org> >>
469  
470 Copyright © 2012-2024 Wim Lewis. All rights reserved.
471  
472 Tom Wyant added support for UID types.
473  
474 This program is free software; you can redistribute it and/or modify
475 it under the same terms as Perl itself.
476  
477 =head1 SEE ALSO
478  
479 L<Mac::PropertyList::ReadBinary> for the inverse operation.
480  
481 Apple's partial published CoreFoundation source code:
482 L<http://opensource.apple.com/source/CF/>
483  
484 =cut
485  
486 4 "One more thing";
↑ Summary PropertyList.pm »