Section 14.1. Property Lists

14.1. Property Lists

A property list (plist) file is a file that contains all kinds of data in a structured form. There are three formats for a property list file: an older ASCII-based property list format, the XML-based property list format used in earlier versions of Mac OS X, and the new binary format used in Tiger. We saw an example of the older ASCII property list format in Chapter 5 when we looked at Startup Items. This is one of the few places where you'll see the older format in use. In most places, including the defaults database, you'll see the new binary format. In still other places, the XML format may still be used. A simple XML property list used by the battery menu extra is shown in Example 14-1. If you've ever looked at HTML or other XML dialects, the basic structure of this file should look somewhat familiar.

For the sake of explanation, most of the following discussion assumes you're looking at property list files that are either still in the XML-based format used in Panther or have been converted from the binary format into XML-based format using plutil (as described later).

Example 14-1. The com.apple.menuextra.battery.plist file

 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict>     <key>ShowPercent</key>     <string>NO</string>     <key>ShowTime</key>     <string>YES</string> </dict> </plist>

The binary files aren't nearly as interesting to look at from the command line; unfortunately, they are not human-readable. Luckily, Apple includes a tool to convert between the binary and XML formats. This tool, plutil, makes it quite a bit easier when you want to tweak .plist files by hand. To convert from the new binary format to the XML format used in earlier versions of Mac OS X, use the xml1 (XML followed by the numeral 1) format option for plutil's -convert switch:

     $ plutil -convert xml1com.example.myprogram.plist

Once you're done making changes to the file while it's in XML form, you can convert it back to binary format with the binary1 format option, as in:

     $ plutil -convert binary1com.example.myprogram.plist

Before you convert it back, however, you may want to check the syntax of your changes. The plutil tool can help you with that as well; just call it using its -lint switch:

     $ plutil -lintcom.example.myprogram.plist

The structure of a property list file contains a plist root element that contains one or more data elements. In Example 14-1, as in all property lists used by the defaults system, the child element of plist is named dict (which stands for dictionarya mapping between names and values) and contains a set of key and string elements. Each set of key and string elements defines a name-value pair. In essence, the example file can be interpreted as "this file contains a dictionary in which the key ShowPercent is set to NO and the key ShowTime is set to YES."

Unless you have modified the battery menu extra, you may not have the file shown in Example 14-1 or many other plist files that are mentioned in this chapter. The plist files for a preference domain typically are created only on demand.

The XML elements that can appear in a property list file are listed in Table 14-1. One thing you might notice in Example 14-1 is that even though there are the true and false values that can appear as tags in the XML file, the ShowPercent and ShowTime keys have string values set to NO and YES, respectively. It's unfortunate, but this inconsistency crops up in many of the defaults keys used by applications and is something you should be aware of.

Table 14-1. Property list elements

Element	Description
plist	Root element of a property list.
dict	A dictionary to hold other data elements in key value form. The contents of this element are a set of <key> elements, followed by the data associated with the key.
array	Contains a set of data values in a particular order. The contents of these elements are simply a list of data elements.
string	Contains a data value as a string.
real	Contains a data value as a real number, such as 8.14.
integer	Contains a data value as an integer, such as 10 or -9.
date	Contains data that represents a date in ISO 8601 (a standard format for dates), such as 2003-10-24T08:00:00Z which represents 8:00 p.m. October 24th, 2003 (the time Panther was released to the public).
true	Indicates that the value is true.
false	Indicates that the value is false.
data	Contains arbitrary data.