Darren Kulp > Mac-PropertyList-SAX-0.85 > Mac::PropertyList::SAX

Download:
Mac-PropertyList-SAX-0.85.tar.gz

Dependencies

Annotate this POD

Related Modules

Mac::PropertyList
more...
By perlmonks.org

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.85   Source  

NAME ^

Mac::PropertyList::SAX - work with Mac plists at a low level, fast

SYNOPSIS ^

See Mac::PropertyList

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

See "parse_plist_file" in Mac::PropertyList

parse_plist_fh

See "parse_plist_fh" in Mac::PropertyList

parse_plist

See "parse_plist" in Mac::PropertyList

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/.

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-2010 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.

syntax highlighting: