Section 13.1. Property Lists

13.1. Property Lists

User -defined property lists are stored in ~/Library/Preferences , and the appropriate plist is called up when an application launches. Property lists can contain literal preferences set through the application's ApplicationPreferences dialog, or subtler things such as window coordinates or the state of an option (such as whether to display the battery menu extra in the menu bar, as shown in Example 13-1).

Example 13-1. The com.apple.menuextra.battery.plist file in XML format

 <?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>YES</string>         <key>ShowTime</key>         <string>NO</string> </dict> </plist> 

Each property list is named after its domain , the unique namespace that an application uses when working with its preference files . Domains can look like any string, but the Apple-recommended format is similar to a URL, just in reverse. The naming convention is based on the developer's company or organization's name, using the application's name as the domain. All of the plist files for the System Preferences and other iApps use the syntax com.apple. domain .plist , where domain is the name of the service or application. For example, the plist file for the Dock's preferences is com.apple.dock.plist , while the preferences file for OmniGraffle (if you have it installed) is com.omnigroup.OmniGraffle.plist .

Not all application preference files are part of the preferences system. Some applications may write their user preference files in a proprietary format to ~/Library/Preferences . These are typically Carbon applications not packaged into bundles, and hence lacking the Info .plist files they need to claim a preferences domain. As such, these preference files can't be read or altered by the defaults command (described later), even though they are stored in ~/Library/Preferences .

Classic applications, on the other hand, are even more antisocial , always writing their preference files in opaque formats in Mac OS 9's /System Folder/Preferences folder.

To get a list of the com.apple. domain plist files in the ~/Library/Preferences directory, issue the following commands:

 $  cd ~/Library/Preferences  $  ls com.apple.* > ~/Desktop/plists.txt  

The first command places you in the ~/Library/Preferences directory; the second gives a wildcard search for all files that begin with com.apple , and then redirects that listing to a file named plists.txt and saves that file on your Desktop. Because each application, including the menu extras, creates its own plist file, this listing can be long.

Note that plists can be in one of two formats: Binary and XML. By default, Mac OS X will use binary plist files, which is more efficient for space, but makes it impossible for human readers to read. Here's what a binary format file looks like if you try to display it like a text file:

 $  cd ~/Library/Preferences  $  cat com.apple.windowclock.plist  bplist00<D1>^A^B_^P^TNSWindow Frame Clock_^P^^1081 788 128 128 0 0 1280 938 

NSGlobalDomain, the Master Domain

One special domain named NSGlobalDomain acts as a parent to all the other preferences domains on the system. They inherit its settings, which are all related to system-wide preferences that applications access frequently, such as localized time-format information and the currently selected system beep.

Run defaults read NSGlobalDomain or simply defaults read -g within the Terminal to see NSGlobalDomain 's current settings.

The output may include strange garbage characters . To look at it in a friendly format, you'll need to convert it to XML using the plutil command to convert to xml1 (that's "ex-em-el-one" format):

 $  plutil -convert xml1 com.apple.windowclock.plist  $  cat com.apple.windowclock.plist  <?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>NSWindow Frame Clock</key>             <string>1081 788 128 128 0 0 1280 938 </string>     </dict>     </plist> 

There's no need to convert back to binary format, since Mac OS X will handle them identically, but if you really want to:

 $  plutil -convert binary1 com.apple.windowclock.plist  

Looking at Example 13-1, you can see the basic structure of a plist file. At the most basic level, a plist file can be broken down into three parts : dictionaries, keys, and values for the keys. The dictionary sections, denoted with <dict/> , set the structure; keys ( <key/> ) define an available preference, and the values for the keys in this example are strings ( <string/> ).

The values for a key are defined within either a <data/> , <date/> , <boolean/> , <string/> , or <integer/> tag. Keys can also contain nested dictionary sections or arrays ( <array/> ) sections for holding encoded values or a series of strings. Nested dictionaries are referred to as children of the parent dictionary. For example, com.apple.dock.plist has a persistent-apps key, which contains an array for all of the applications in the Dock (to the left of the divider bar). Within the array, you'll see a number of nested dictionaries that define the parameters for the application's icon in the Dock. Example 13-2 shows the array item for Mail.app 's Dock icon.

Example 13-2. Mail.app's array in com.apple.dock.plist in XML format

 <key>persistent-apps</key> <array> ....         <dict>             <key>GUID</key>             <integer>1871630911</integer>             <key>tile-data</key>             <dict>                 <key>file-data</key>                 <dict>                     <key>_CFURLAliasData</key>                     <data>                     AAAAAACQAAMAAQAAu77rNQAASCsAAAAAAAAD                     KgAARrIAALthjLAAAAAACSD//gAAAAAAAAAA                     /////wABAAQAAAMqAA4AEgAIAE0AYQBpAGwA                     LgBhAHAAcAAPABAABwBQAGEAbgB0AGgAZQBy                     ABIAFUFwcGxpY2F0aW9ucy9NYWlsLmFwcAAA                     EwABLwD//wAA                     </data>                     <key>_CFURLString</key>                     <string>/Applications/Mail.app</string>                     <key>_CFURLStringType</key>                     <integer>0</integer>                 </dict>                 <key>file-label</key>                 <string>Mail</string>                 <key>file-mod-date</key>                 <integer>-1136549615</integer>                 <key>file-type</key>                 <integer>9</integer>                 <key>parent-mod-date</key>                 <integer>-1134631645</integer>             </dict>             <key>tile-type</key>             <string>file-tile</string>         </dict> ... </array> 

Because a plist file is nothing more than text, you can use any text editor (such as TextEdit, BBEdit, vi , or Emacs) to view and edit its contents; however, the preferred method is to use the Property List Editor ( /Developer/Applications/Utilities ), described later. The Property List Editor application is installed when you install the Xcode Tools.