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, without changing anything else, 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. By default, XML::SAX::Expat is used; to change the parser used, set the environment variable MAC_PROPERTYLIST_SAX_PARSER to a value accepted by $XML::SAX::ParserPackage from XML::SAX::ParserFactory (or set $XML::SAX::ParserPackage directly).
CLASS VARIABLES
Class scoped variables that control the packages settings.
- ENCODE_ENTITIES
-
Allows the XHTML encoding of the data to be turned off. Default =
1 - ENCODE_UNSAFE_CHARS
-
A Perl character class definition containing the only characters to be XHTML encoded. See HTML::Entities::encode_entities for description of the $unsafe_chars parameter. Default =
undef - OLD_BEHAVIOR
-
Restores the old behavior of double encoding output data. Default =
0 - XML::SAX::ParserPackage
-
Parser to use. Can also be set with environment variable
MAC_PROPERTYLIST_SAX_PARSER. Default ="XML::SAX::Expat"
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
- parse_plist_string
-
An alias to parse_plist, provided for better regularity compared to Perl SAX.
- 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. Hash and array references are handled recursively, and Mac::PropertyList objects are output correctly. All other scalars are treated as strings (use Mac::PropertyList objects to represent other types of scalars).
Returns a string representing the reference in serialized 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.
- _escape( STRING )
-
Internal use only. Escapes illegal characters into XML entities.
BUGS / CAVEATS
Any sane XML parser you can find to use with this module will decode XHTML-encoded entities in the original property list; Mac::PropertyList doesn't touch them. Also, your XML parser may convert accented/special characters into '\x{ff}' sequences; these are preserved in their original encoding by Mac::PropertyList.
Before version 0.80 of this module, characters invalid in XML were not serialized properly from create_from_ref(); before version 0.82, they were not serialized properly in plist_as_string(). Thanks to Jon Connell for pointing out these problems.
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. That is: for inputs that Mac::PropertyList's create_from_* functions handled, the output should be the same, but this module supports inputs that Mac::PropertyList does not.
Before version 0.83, this module left the selection of a SAX-based parser entirely to the discretion of XML::SAX::ParserFactory. Unfortunately, it seems impossible to guarantee that the parser returned even supports XML (XML::SAX::RTF could be returned), so it has become necessary to select a parser by default: XML::SAX::Expat, which is now part of the dependencies of this module. If you know you will use another parser of a specific name, you can force installation without XML::SAX::Expat and always specify the parser you wish to use by setting $XML::SAX::ParserPackage or the MAC_PROPERTYLIST_SAX_PARSER environment variable (see "DESCRIPTION").
Before version 0.85, this module contained a bug that caused double encoding of special characters as X[HT]ML entities. Thanks to Bion Pohl and http://ingz-inc.com/ for reporting this issue and supplying a fixed version. The implementation of the $ENCODE_ENTITIES variable and the addition of the $ENCODE_UNSAFE_CHARS variable are also due to Bion Pohl and / or http://ingz-inc.com/.
Before version 0.86, this module did not handle binary plists. Now it delegates binary plists to Mac::PropertyList, but if used with filehandles, requires seekable streams (\*STDIN will work but only if it points to a seekable file, rather than a pipe).
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.
Bion Pohl and http://ingz-inc.com, for bug report and patch submission.
SEE ALSO
Mac::PropertyList, the inspiration for this module.
COPYRIGHT AND LICENSE
Copyright (C) 2007-2017 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.