The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Mac::PropertyList - work with Mac plists at a low level

SYNOPSIS

        use Mac::PropertyList;

        my $data  = parse_plist( $text );

        my $text  = plist_as_string( $data );

        my $plist = create_from_hash(  \%hash  );
        my $plist = create_from_array( \@array );

        my $plist = Mac::PropertyList::dict->new( \%hash );
                
        

DESCRIPTION

This module is a low-level interface to the Mac OS X Property List (plist) format. You probably shouldn't use this in applications---build interfaces on top of this so you don't have to put all the heinous multi-level object stuff where people can see it.

You can parse a plist file and get back a data structure. You can take that data structure and get back the plist as XML. If you want to change the structure inbetween that's your business. :)

The Property List format

The MacOS X Property List format is simple XML. You can read the DTD to get the details.

        http://www.apple.com/DTDs/PropertyList-1.0.dtd

One big problem exists---its dict type uses a flat structure to list keys and values so that values are only associated with their keys by their position in the file rather than by the structure of the DTD. This problem is the major design hinderance in this module. A smart XML format would have made things much easier.

If the parse_plist encounters an empty key tag in a dict structure (i.e. <key></key> ) the function croaks.

The Mac::PropertyList classes

A plist can have one or more of any of the plist objects, and we have to remember the type of thing so we can go back to the XML format. Perl treats numbers and strings the same, but the plist format doesn't.

Therefore, everything Mac::PropertyList creates is an object of some sort. Container objects like Mac::PropertyList::array and Mac::PropertyList::dict hold other objects.

There are several types of objects:

        Mac::PropertyList::string
        Mac::PropertyList::data
        Mac::PropertyList::real
        Mac::PropertyList::integer
        Mac::PropertyList::date
        Mac::PropertyList::array
        Mac::PropertyList::dict
new( VALUE )

Create the object.

value

Access the value of the object. At the moment you cannot change the value

type

Access the type of the object (string, data, etc)

write

Create a string version of the object, recursively if necessary.

FUNCTIONS

parse_plist( TEXT )

Parse the XML plist in TEXT and return the Mac::PropertyList object.

parse_plist_file( FILE_PATH )

Parse the XML plist in TEXT and return the Mac::PropertyList data structure.

create_from_hash( HASH_REF )

Create a plist dictionary from the hash reference.

The values of the hash can only be simple scalars---not references. Reference values are silently ignored.

Returns a string representing the hash in the plist format.

create_from_array( ARRAY_REF )

Create a plist array from the array reference.

The values of the array can only be simple scalars---not references. Reference values are silently ignored.

Returns a string representing the array in the plist format.

SOURCE AVAILABILITY

This source is part of a SourceForge project which always has the latest sources in CVS, as well as all of the previous releases.

        https://sourceforge.net/projects/brian-d-foy/

If, for some reason, I disappear from the world, one of the other members of the project can shepherd this module appropriately.

CREDITS

Thanks to Chris Nandor for general Mac kung fu and Chad Walker for help figuring out the recursion for nested structures.

TO DO

* change the value of an object

* validate the values of objects (date, integer)

* methods to add to containers (dict, array)

* do this from a filehandle or a scalar reference instead of a scalar + generate closures to handle the work.

AUTHOR

brian d foy, <bdfoy@cpan.org>

SEE ALSO

http://www.apple.com/DTDs/PropertyList-1.0.dtd