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; 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.80

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. Numerically 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 version 0.80 on, they are converted to hexadecimal entity references. Thanks to Jon Connell for pointing out this problem.

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.

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.