GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Mac::PropertyList(3) User Contributed Perl Documentation Mac::PropertyList(3)

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

        use Mac::PropertyList qw(:all);

        my $data  = parse_plist( $text );
        my $perl  = $data->as_perl;

                # == OR ==
        my $data  = parse_plist_file( $filename );

                # == OR ==
        open my( $fh ), $filename or die "...";
        my $data  = parse_plist_fh( $fh );


        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 );

        my $perl  = $plist->as_perl;

This module is a low-level interface to the Mac OS X Property List (plist) format in either XML or binary. 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 have to look at 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. :)

You don't need to be on Mac OS X to use this. It simply parses and manipulates a text format that Mac OS X uses.

If you need to work with the old ASCII or newer JSON formet, you can use the plutil tool that comes with MacOS X:

        % plutil -convert xml1 -o ExampleBinary.xml.plist ExampleBinary.plist

Or, you can extend this module to handle those formats (and send a pull request).

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.

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::uid
        Mac::PropertyList::date
        Mac::PropertyList::array
        Mac::PropertyList::dict
        Mac::PropertyList::true
        Mac::PropertyList::false

Note that the Xcode property list editor abstracts the "true" and "false" objects as just "Boolean". They are separate tags in the plist format though.

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.
as_perl
Turn the plist data structure, which is decorated with extra information, into a lean Perl data structure without the value type information or blessed objects.

These functions are available for individual or group import. Nothing will be imported unless you ask for it.

        use Mac::PropertyList qw( parse_plist );

        use Mac::PropertyList qw( :all );

parse_plist( TEXT )
Parse the XML plist in TEXT and return the "Mac::PropertyList" object.
parse_plist_fh( FILEHANDLE )
Parse the XML plist from FILEHANDLE and return the "Mac::PropertyList" data structure. Returns false if the arguments is not a reference.

You can do this in a couple of ways. You can open the file with a lexical filehandle (since Perl 5.6).

        open my( $fh ), $file or die "...";
        parse_plist_fh( $fh );
    

Or, you can use a bareword filehandle and pass a reference to its typeglob. I don't recommmend this unless you are using an older Perl.

        open FILE, $file or die "...";
        parse_plist_fh( \*FILE );
    
parse_plist_file( FILE_PATH )
Parse the XML plist in FILE_PATH and return the "Mac::PropertyList" data structure. Returns false if the file does not exist.

Alternately, you can pass a filehandle reference, but that just calls "parse_plist_fh" for you.

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.

create_from_string( STRING )
Returns a string representing the string in the plist format.
create_from
Dispatches to either "create_from_array", "create_from_hash", or "create_from_string" based on the argument. If none of those fit, this "croak"s.
read_string
read_data
read_integer
read_date
read_real
read_true
read_false
Reads a certain sort of property list data
read_next
Read the next data item
read_dict
Read a dictionary
read_array
Read an array

XML_head
Returns a string that represents the start of the PList XML.
XML_foot
Returns a string that represents the end of the PList XML.
plist_as_string
Return the plist data structure as XML in the Mac Property List format.
plist_as_perl
Return the plist data structure as an unblessed Perl data structure. There won't be any "Mac::PropertyList" objects in the results. This is really just "as_perl".

This project is in Github:

        git://github.com/briandfoy/mac-propertylist.git

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

Mike Ciul provided some classes for the different input modes, and these allow us to optimize the parsing code for each of those.

Ricardo Signes added the "as_basic_types()" methods so you can dump all the plist junk and just play with the data.

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

brian d foy, "<bdfoy@cpan.org>"

Tom Wyant added support for UID types.

Copyright © 2004-2021, brian d foy <bdfoy@cpan.org>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

http://www.apple.com/DTDs/PropertyList-1.0.dtd
2021-01-19 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.