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 replace Mac::PropertyList: it depends on it for some package definitions and plist printing routines. You should, however, be able to replace all "use Mac::PropertyList" lines with "use Mac::PropertyList::SAX" and notice an immediate improvement in performance on large input files.
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, which may give worse performance than Mac::PropertyList. See XML::SAX::ParserFactory for information on how to set which parser is used.
VERSION
Version 0.64
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
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, but are preserved in their original encoding by Mac::PropertyList.
Unlike Mac::PropertyList and old versions (< 0.60) of Mac::PropertyList::SAX, this module does not trim leading and trailing whitespace from plist elements. The difference in behavior is thought to be rarely noticeable; in any case, I believe this module's current behavior is the more correct. Any documentation that covers this problem would be appreciated.
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 handled, the output should be the same, but 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.