NAME
Mac::PropertyList::SAX - work with Mac plists at a low level, fast
SYNOPSIS
DESCRIPTION
Mac::PropertyList is useful, but very slow on large files because it does XML parsing itself, intead of handing it off to a dedicated parser. This module uses XML::SAX::ParserFactory to select a parser capable of doing the heavy lifting, reducing parsing time on large files by a factor of 30 or more.
This module does not, however, replace Mac::PropertyList; in fact, it depends on it for several package definitions and the plist printing routines. You should, however, be able to replace all "use Mac::PropertyList" lines with "use Mac::PropertyList::SAX", making no other changes, and notice an immediate improvement in performance on large input files.
Be aware that performance will depend largely on the parser that XML::SAX::ParserFactory selects for you; if you have not installed XML::SAX::Expat or another fast parser, the default XML::SAX::PurePerl parser will be used; this will probably give worse performance than Mac::PropertyList, so ensure that a fast parser is being used before you complain to me about performance :-). See XML::SAX::ParserFactory for information on how to set which parser is used.
VERSION
Version 0.62
EXPORTS
By default, no functions are exported. Specify individual functions to export as usual, or use the tags ':all', ':create', and ':parse' for the appropriate sets of functions (':create' includes the create* functions as well as plist_as_string; ':parse' includes the parse* functions).
FUNCTIONS
- parse_plist_file
- parse_plist_fh
- parse_plist
- create_from_ref( HASH_REF | ARRAY_REF )
-
Create a plist from an array or hash reference.
The values of the hash can be simple scalars or references. References are handled recursively, and Mac::PropertyList objects are output correctly. All plain scalars are treated as strings (use Mac::PropertyList objects to represent other types of scalars).
Returns a string representing the hash in the plist format.
- create_from_hash( HASH_REF )
-
Provided for backward compatibility with Mac::PropertyList: aliases create_from_ref.
- create_from_array( ARRAY_REF )
-
Provided for backward compatibility with Mac::PropertyList: aliases create_from_ref.
BUGS / CAVEATS
Behavior is not exactly the same as Mac::PropertyList's; specifically, in the case of special characters, such as accented characters and ampersands. Ampersands encoded (for example, as '&') in the original property list will be decoded by the XML parser in this module; Mac::PropertyList leaves them as-is. Also, accented/special characters are converted into '\x{ff}' sequences by the XML parser in this module, but are preserved in their original encoding by Mac::PropertyList. The differences may be evident when creating a plist file from a parsed data structure, but this has not yet been tested.
In addition, unlike Mac::PropertyList and old versions (< 0.60) of Mac::PropertyList::SAX, this module does not trim leading and trailing whitespace parsed from plist inputs. The difference in behavior is noticeable only in extremely rare cases, but I believe this module's current behavior is the more correct. If someone could point me to documentation (probably on the plist format specifically) that covers this problem, I would be grateful.
The behavior of create_from_hash and create_from_array has changed: these functions (which are really just aliases to the new create_from_ref function) are now capable of recursively serializing complex data structures. For inputs that Mac::PropertyList's create_from_* functions handlsd, the output should be the same, but the addition of functionality means that the reverse is not true.
SUPPORT
Please contact the author with bug reports or feature requests.
AUTHOR
Darren M. Kulp, <kulp @ cpan.org>
THANKS
brian d foy, who created the Mac::PropertyList module whose tests were appropriated for this module.
SEE ALSO
Mac::PropertyList, the inspiration for this module.
COPYRIGHT AND LICENSE
Copyright (C) 2007 by Darren Kulp
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.