File Coverage

blib/lib/Mac/PropertyList/XS.pm
Criterion Covered Total %
statement 21 23 91.3
branch n/a
condition n/a
subroutine 8 8 100.0
pod n/a
total 29 31 93.5


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Mac::PropertyList::XS - work with Mac plists at a low level, really fast
4              
5             =cut
6              
7             package Mac::PropertyList::XS;
8              
9             =head1 SYNOPSIS
10              
11             See L and L
12              
13             =head1 DESCRIPTION
14              
15             L was my first attempt to speed up property-list
16             parsing. It achieves about a 30x speed boost, but large files still take
17             too long for my taste. This module addresses some remaining speed gains
18             by implementing some expensive operations in C.
19              
20             This module is intended to be a drop-in replacement for
21             L, which is itself a drop-in replacement for
22             L.
23              
24             =cut
25              
26 19     19   222578 use 5.008008;
  19         111  
27 19     19   74 use strict;
  19         23  
  19         381  
28 19     19   70 use warnings;
  19         24  
  19         542  
29 19     19   72 use Carp;
  19         26  
  19         1487  
30              
31             require Exporter;
32 19     19   8338 use AutoLoader;
  19         20974  
  19         84  
33              
34             # Passthrough function
35 19     19   8752 use Mac::PropertyList qw(plist_as_string);
  19         517337  
  19         1665  
36 19     19   8799 use Mac::PropertyList::SAX qw(create_from_ref create_from_hash create_from_array);
  19         615956  
  19         1852  
37 19     19   11996 use XML::Parser;
  0            
  0            
38              
39             use base qw(Exporter);
40              
41             our @EXPORT_OK = qw(
42             parse_plist
43             parse_plist_fh
44             parse_plist_file
45             parse_plist_string
46             plist_as_string
47             create_from_ref
48             create_from_hash
49             create_from_array
50             );
51              
52             our %EXPORT_TAGS = (
53             all => \@EXPORT_OK,
54             create => [ qw(create_from_ref create_from_hash create_from_array plist_as_string) ],
55             parse => [ qw(parse_plist parse_plist_fh parse_plist_file parse_plist_string) ],
56             );
57              
58             our $VERSION = '0.00_01';
59             our $XS_VERSION = $VERSION;
60             $VERSION = eval $VERSION; # see L
61              
62             sub AUTOLOAD {
63             # This AUTOLOAD is used to 'autoload' constants from the constant()
64             # XS function.
65              
66             my $constname;
67             our $AUTOLOAD;
68             ($constname = $AUTOLOAD) =~ s/.*:://;
69             croak "&Mac::PropertyList::XS::constant not defined" if $constname eq 'constant';
70             my ($error, $val) = constant($constname);
71             if ($error) { croak $error; }
72             {
73             no strict 'refs';
74             # Fixed between 5.005_53 and 5.005_61
75             #XXX if ($] >= 5.00561) {
76             #XXX *$AUTOLOAD = sub () { $val };
77             #XXX }
78             #XXX else {
79             *$AUTOLOAD = sub { $val };
80             #XXX }
81             }
82             goto &$AUTOLOAD;
83             }
84              
85             require XSLoader;
86             XSLoader::load('Mac::PropertyList::XS', $XS_VERSION);
87              
88             =head1 EXPORTS
89              
90             By default, no functions are exported. Specify individual functions to export
91             as usual, or use the tags ':all', ':create', and ':parse' for the appropriate
92             sets of functions (':create' includes the create* functions as well as
93             plist_as_string; ':parse' includes the parse* functions).
94              
95             =head1 FUNCTIONS
96              
97             =over 4
98              
99             =item parse_plist_file
100              
101             See L
102              
103             =cut
104              
105             sub parse_plist_file
106             {
107             my $file = shift;
108              
109             if (ref $file) {
110             _parse(parse => $file);
111             } else {
112             carp("parse_plist_file: file [$file] does not exist!"), return unless -e $file;
113             open my $fh, "<", $file;
114             _parse(parse => $fh);
115             }
116             }
117              
118             sub _parse
119             {
120             my ($how, $what) = @_;
121             my $p = new XML::Parser(Handlers => { Init => \&handle_init,
122             Start => \&handle_start,
123             End => \&handle_end,
124             Char => \&handle_char,
125             Final => \&handle_final });
126             return $p->$how($what);
127             }
128              
129             =item parse_plist_fh
130              
131             See L
132              
133             =cut
134              
135             sub parse_plist_fh { _parse(parse => @_) }
136              
137             =item parse_plist
138              
139             See L
140              
141             =cut
142              
143             sub parse_plist { _parse(parse => @_) }
144              
145             =item parse_plist_string
146              
147             An alias to parse_plist, provided for better regularity compared to Perl SAX.
148              
149             =cut
150              
151             *parse_plist_string = \&parse_plist;
152              
153             =item create_from_ref( HASH_REF | ARRAY_REF )
154              
155             Create a plist from an array or hash reference.
156              
157             The values of the hash can be simple scalars or references. Hash and array
158             references are handled recursively, and L objects are output
159             correctly. All other scalars are treated as strings (use L
160             objects to represent other types of scalars).
161              
162             Returns a string representing the reference in serialized plist format.
163              
164             =item create_from_hash( HASH_REF )
165              
166             Provided for backward compatibility with L: aliases
167             create_from_ref.
168              
169             =item create_from_array( ARRAY_REF )
170              
171             Provided for backward compatibility with L: aliases
172             create_from_ref.
173              
174             =back
175              
176             =head1 BUGS / CAVEATS
177              
178             Certainly !
179              
180             =head1 SUPPORT
181              
182             Please contact the author with bug reports or feature requests.
183              
184             =head1 AUTHOR
185              
186             Darren M. Kulp, C<< >>
187              
188             =head1 THANKS
189              
190             brian d foy, who created the L module whose tests were
191             appropriated for this module.
192              
193             =head1 SEE ALSO
194              
195             L, the inspiration for this module.
196              
197             =head1 COPYRIGHT AND LICENSE
198              
199             Copyright (C) 2009 by Darren Kulp
200              
201             This library is free software; you can redistribute it and/or modify
202             it under the same terms as Perl itself, either Perl version 5.8.4 or,
203             at your option, any later version of Perl 5 you may have available.
204              
205             =cut
206              
207             1;
208             __END__