Section 13.2. Viewing and Editing Property Lists

13.2. Viewing and Editing Property Lists

There are two ways you can view and edit the contents of an application's preferences file:

• With the Property List Editor ( /Developer/Applications/Utilities )

• From the command line, using the defaults command

The Property List Editor is available on your system only after installing the Xcode Tools; however, the defaults command is available with the base installation of Mac OS X, and doesn't require you to install any additional software.

Viewing is one thing, but knowing what you can enter into a plist file requires a bit of investigative work. An application asserts its domain through the CFBundleIdentifier key in its internal Info .plist file, which is stored in an application's /Contents directory. For example, the Info.plist file for the Dock can be found in /System/Library/CoreServices/Dock.app/Contents .

The preferences available to an application are defined via the CFBundleExecutable key in the Info.plist file. Typically, the string for CFBundleExecutable is the short name for the application (e.g., Dock). This executable can be found in an application's /Contents/MacOS directory; e.g., the Dock executable is located in /System/Library/CoreServices/Dock.app/Contents/MacOS .

To see a listing of available keys and strings for an application, use the strings command in the Terminal, followed by the path to the application's short name as defined by CFBundleExecutable :

 $  strings /System/Library/CoreServices/Dock.app/Contents/MacOS/Dock  

Unfortunately, the output from strings doesn't have a discernible structure. You'll need to sift through the output to find hints about the preferences you can set and alter using the Property List Editor or the defaults command, defined in the following sections.

13.2.1. Using the Property List Editor

The Property List Editor, shown in Figure 13-1, is a GUI tool that lets you view and edit property list files.

At their base, every plist has a Root item, which contains all the dictionaries, arrays, keys, and values that define the preferences for an application. When you initially open a plist file, all its elements are hidden inside the Root item. If you click on the disclosure triangle next to Root (this is similar to the List View of the Finder), the keys of the plist are revealed in the first column.

If you select a Dictionary or Array item in the Property List column that has a disclosure triangle next to it, you can use -right (or left) arrow to respectively open or close a disclosure triangle. Likewise, Option- -right (or left) Arrow respectively opens or closes all of the disclosure triangles in the Property List Editor. For example, if you select Root and hit Option- -right arrow, all of the contents of that plist file are shown in the upper display; Option- -left arrow closes them again.

As shown in Figure 13-1, there are three columns in the Property List Editor's display:

Property List

The Property List column lists the items seen in the <key/> tags of a plist 's XML file.

Figure 13-1. The Property List Editor

Class

The Class column lists the classes available for each key definition. Clicking on the set of up/down arrows next to a class reveals a pop-up menu, from which you can select from one of seven possible classes including:

String

A string can contain alphanumeric text, such as an application path (e.g., /Applications/Mail.app/ ), a single-word response that defines the action of a key, or the default position of the application's window (e.g., {{125 , 0} , {205 , 413}} ).

Dictionary

Dictionary items are grayed out in the Property List Editor's display and give you details on the number of key/value pairs listed in that dictionary item. Dictionaries are tagged as <dict/> in the XML file.

Array

Like dictionaries, the Value column is grayed out for an Array, showing you the number of ordered objects available in that array. Within each array, you will find another Dictionary item listing its key/value pairs. Arrays are tagged as <array/> in the XML file.

Boolean

Contains YES or NO responses as its value, and are tagged as <true/> or <false/> , respectively, as the value in the XML file.

Number

Contains a floating-point value for the key, such as a percentage value for the opaqueness of the Terminal application (e.g., 0.750000 for 75 percent) or the version number for an application. Values in the Number class are tagged in the plist file using <integer/> .

Date

Contains the date in MM/DD/YY format. The Date Value can also include a time, in HH:MM:SS format.

Data

Data information is stored as a string of encoded alphanumeric data, inside a set of opening and closing angle brackets. If you look closely at the Value, you'll see that the numbers are in blocks of eight characters (digits or letters from A to F), which reveal its form as binary data. Example 13-3 shows the Data Value for Mail.app 's icon alias in the Dock.

Example 13-3. The Data Value for _CFURLAliasData as binary data

 <00000000 00900003 00010000 bbbeeb35 0000482b 00000000 0000032a 000046b2 0000bb61 8cb00000 00000920 fffe0000 00000000 0000ffff ffff0001 00040000 032a000e 00120008 004d0061 0069006c 002e0061 00700070 000f0010 00070050 0061006e 00740068 00650072 00120015 4170706c 69636174 696f6e73 2f4d6169 6c2e6170 70000013 00012f00 ffff0000 > 

Value

Contains the value for the Class.

To view the XML source for the plist file, click on the Dump button in the upper-right corner of the Property List Editor's window. You can't edit the XML source in the Property List Editor; edits to the plist file are made in the upper portion of the window.

You should avoid changing a plist file used by an application that's currently in use, because it can crash the application or cause it and your system to behave strangely.

To edit an item, double-click on the item you want to edit to select it, type in the new value, and then hit Return to accept the new value. If you want to see the change in the XML source, hit the Dump button again. After the changes have been entered, save the file before closing (File Save, or -S).

13.2.2. The defaults Command

Another way to view and change the contents of a plist file is with the defaults command from the Terminal. The defaults command gives you an abstract way to read from and write to the preferences system. It lets you quickly modify any or all of an application's saved-state settings, which can prove quite handy when debugging your own applications. As with any command-line program, you can write shell scripts to run several invocations of defaults with a single command, letting you set the application's stage however you like in an instant.

If the preferences domain is bound to a specific host, you must specify a host with the - host option or refer to the current machine with the - currentHost option.

The following section contains a complete reference for the defaults command.

defaults

---

 defaults [   host   ]   subcommand domain   [   option   ] [   key   ]     defaults [-currentHost  -host   hostname   ] read [   domain   [   key   ]]     defaults [-currentHost  -host   hostname   ] read-type   domain key   defaults [-currentHost  -host   hostname   ] write   domain   { 'plist'   domain     key   '   value   ' }     defaults [-currentHost  -host   hostname   ] rename   domain old_key new_key   defaults [-currentHost  -host   hostname   ] delete [   domain   [   key   ]]     defaults [-currentHost  -host   hostname   ] {   domains   find   word     help   } 

Used to access Mac OS X's user defaults database to read, write (set or change), and delete system and application preferences.

The defaults command allows users and administrators to read, write, and delete Mac OS X user defaults from a command-line shell. An application's defaults belong to a domain , which typically correspond to individual applications; however, they can apply to system settings made via the System Preferences panels. Each domain has a dictionary of keys and values representing its defaults. Keys are always strings, but values can be complex data structures comprising arrays, dictionaries, strings, and binary data. These data structures are stored as XML property lists.

Though all applications, system services, and other programs have their own domains, they also share a domain named NSGlobalDomain . If a default isn't specified in the application's domain but is specified in NSGlobalDomain , the application uses the value in that domain.

Host

-currentHost

Restricts the actions of the defaults command to the domains listed in ~/Library/Preferences/ByHost .

-host hostname

Used to specify the hostname , based on the Ethernet MAC address of the system the user is logged in to.

Subcommands

read

Prints all the user's defaults, for every domain, to standard output.

read domain

Prints all the user's defaults for domain to standard output.

read-type domain key

Prints the type of key for the given domain .

read domain key

Prints the value for the default of domain identified by key .

write domain key ' value '

Writes value as the value for key in domain . The value must be a property list and must be enclosed in single quotes. For example:

 defaults write com.companyname.appname "Default Color" '(255, 0, 0)' 

sets the application's value for the key ( Default Color ) to an array, which contains the string 255 , , (for the RGB values). Note that the key is enclosed in quotation marks because it contains a space.

write domain plist

Overwrites the defaults information in a domain with that given as plist . plist must be a property list representation of a dictionary and must be enclosed in single quotes. For example:

 defaults write   com.companyname.appname   '{ "Default Color" = (255, 0, 0);     "Default Font" = Helvetica; }'; 

erases any previous defaults for com.companyname.appname and writes the values for the two names into the defaults system.

delete domain

Removes all default information for domain .

delete domain key

Removes the default named key from domain .

domains

Prints the names of all defaults domains on the user's system.

find word

Searches for word in the domain names, keys, and values of the user's defaults, and prints the results to standard output.

help

Prints a list of possible command formats.

-h

Prints an abbreviated list of possible command formats.

Options

-g

Used as a synonym for the domain NSGlobalDomain . You can also use " Apple Global Domain " (including the quotation marks) as a synonym for the domain NSGlobalDomain . For example:

 $  defaults read "Apple Global Domain"  

displays the same thing as:

 $  defaults read -g  

or:

 $  defaults read NSGlobalDomain  

or:

 $  defaults read -globalDomain  

The following list specifies values for preference keys:

-app

Specifies an application found in the /Applications directory, rather than using its domain. For example:

 $  defaults read -app Mail  

outputs the defaults data for the Mail application.

-array

Allows the user to specify an array as the value for the given preference key:

 defaults write   somedomain preferenceKey   -array   element1 element2     element3   

The specified array overwrites the value of the key if the key is present at the time of the write . If the key isn't present, it's created with the new value.

-array-add

Allows the user to add new elements to the end of an array for a key , which has an array as its value. Usage is the same as - array . If the key isn't present at the time of the write , it's created with the specified array as its value.

-dict

Allows the user to add a dictionary to the defaults database for a domain. Keys and values are specified in order:

 defaults write   somedomain preferenceKey   -dict   key1 value1 key2 value2   

The specified dictionary overwrites the value of the key if the key is present at the time of the write . If the key isn't present, it's created with the new value .

-dict-add

Allows the user to add new key/value pairs to a dictionary for a key that has a dictionary as its value. Usage is the same as - dict . If the key isn't present at the time of the write , it is created with the specified dictionary as its value.

Host-Specific Preferences

A folder called ByHost can exist within ~/Library/Preferences . ByHost contains property list files defining preferences specific to an application on a certain host. These files have filenames following the format of com.apple. address .plist , in which address is the Ethernet MAC address associated with the -currentHost .

To read the plist files located in the ByHost directory, you need to specify the -currentHost option, as follows :

 $  defaults -currentHost read com.apple.screensaver  

Notice that you don't need to specify the Ethernet address that's part of the filename. The - currentHost option tells the defaults command to read the specified domain from the ByHost directory.