Working with Property Lists

Editing Property Lists

Opening a property list file

You can open any file which is using the property list format (plist) of macOS, or the strict JSON format. Just double-click the file in the Finder, or select the menu item File > Open (⌘ + O) in PropEdit. The window to review the contents of the file will open.

The upper bar in the window, just below the tool bar, is used by PropEdit to indicate whether the currently presented data is in a form

• that would allow storage in either a plist or JSON format,
• that would allow use as a settings file in the preferences subsystem of macOS.

If you have permission to do so, you can change any aspect of the stored data. Just click on key, type or value to edit the contents of those fields. Nested entries like dictionaries or arrays can be opened by clicking on the disclosure triangles displayed in front of the respective lines.

• When entering numbers or dates as values for the types Integer Number, Real Number or Date/Time, respectively, PropEdit will automatically respect your personal preferences to format those entries in accordance with the rules of your current locale. For example, decimal places are separated by a decimal point in most English-speaking countries, while other locales may use a decimal comma. Even if you are modifying a date entry in a foreign application which writes dates with the year specification at first position, for example, you can (and should) enter the date following the guidelines of your own preferred language. This rule does not apply when using numbers or dates within values of the type String, however. In that case, the application using the data defines how it will interpret the entered texts. Further notes on specifying dates are given in a separate chapter.
• In specific cases, Strings, whether property keys or values, may contain multiple lines or invisible control characters. This can happen, for example, if a property list contains a modern string table, such as the ones used to internationalize macOS programs for use in multiple languages. If such a key or value is recognized, it naturally cannot be displayed directly in the table. Instead, the message —Control characters! Double-click to show— will appear. For more information, see the respective section below.
• Values of type Binary Data must be specified as sequence of bytes, written as 2-digit hexadecimal numbers, separated by single spaces and enclosed in angle brackets. Example: The three bytes with the decimal values 2, 129 and 254 must be entered as <02 A1 FE>.
• Remember that property keys of dictionaries must be unique. PropEdit will automatically warn you if you are trying to use two identical keys in the same dictionary.
• To remove an item of a nested structure, select the item in the table, then click the button Remove Item in the toolbar of the window. You can also the menu item Edit > Delete.
• To add an item of a nested structure, ensure the correct nesting level is selected in the table and click the Add button in the toolbar of the window. You can alternatively select the menu item Edit > Add entry. PropEdit automatically tries to “guess” if you like to add an item at the same nesting level or at a deeper level in the hierarchy. This will be reflected in the toolbar which switches between Add Item and Add Child, respectively.
• You can use the editing features Cut (⌘ + X), Copy (⌘ + C) and Paste (⌘ + V) on any entry. This allows you to easily transfer one entry or a whole nested structure from one position to another. When pasting an entry, PropEdit will use the same strategy to decide whether to add the item at the same level or as child, as discussed in the previous item. Of course, copying is also possible between different windows, and in some cases even with other applications, such as the property list editor of Apple’s Xcode.
• You can reorder items by drag and drop or move them within the same or different windows.

Items of the types dictionary or array can be strongly nested. It can be tedious work to click all disclosure triangles to navigate to elements deeper in the hierarchy. To simplify that task, you can select an item at an upper level in the hierarchy and open all nested child entries by a single operation. Select the menu item Edit > Fully Expand Entry to do so. The corresponding feature to collapse all entries of a hierarchy is also available. Instead of using the main menu, you can alternatively use the context menu via the right mouse button.

All changes you make to a file are usually stored immediately. This is compliant with the behavior which Apple stipulates for up-to-date versions of macOS. You don’t need to care about saving data. However, it is still possible to store changes “explicitly and immediately” as you may be used to from classic applications. Select the menu item File > Save or press the key combination ⌘ + S.

It is technically possible to extend the official property list definition, permitting values of additional data types, for example. For a property list in text format, this can be done by introducing new XML tags. For a property list in binary format, this can be implemented by encoding data in new record types. In both cases, the resulting files are no longer compliant with the official property list definition, so only the applications that created them can fully “understand” their contents. In practice, such files may unfortunately even have the path extension .plist although they are no true property list files. When you try to open such a proprietary file with PropEdit, you will receive a warning that the file is invalid. However, in many cases, PropEdit will try its best to decode the contents of the file nevertheless. If a file maintains the basic structure of a property list, but uses proprietary data types, PropEdit will open an interpreted version of this file as untitled document. In this interpreted version, all values with invalid data types are replaced by strings that contain a short, technical text description of the proprietary data. This can help you to get a first impression of the file’s contents. Because the interpreted copy is a true property list, it can also be saved as new document. However, you should keep in mind that this is just a substitute representation where unknown values have been made readable to a certain extent. The readable version cannot replace the original file.

Accessing plist Files Belonging to the macOS Preferences System

If you access a plist file that contains settings for an application, it will be indicated by a special banner in the top bar of the window, with a message like this:

    Preference settings for application X, user Y, computer Z.

where X, Y, and Z are replaced with actual names. PropEdit automatically analyzes which scope the opened preference file belongs to. Modifying and saving such files is possible, but since these files belong to the macOS settings system, it cannot be guaranteed that the changes will actually take effect or persist. The entire collection of settings files forms a large database managed by the macOS preferences server cfprefsd, with most of its contents being cached in main memory while the system is running. macOS can overwrite any change made to a preferences file at any time, so you receive a warning message when trying to save such a file using PropEdit.

We do not recommend using PropEdit to modify settings for macOS applications. Our alternative program PrefEdit was designed specifically for this purpose.

Undoing changes

Any changes you have made to data in a file can be undone completely. There are two different approaches:

Small changes can be reverted in single steps by using the menu item Edit > Undo or pressing ⌘ + Z. Each new call of this function will go back one more step in the past. If you mistakenly have undone one step too much, you can also revert this by selecting Edit > Redo or pressing ⌘ + ⇧ + Z.

The possibility to undo single operations stops at the point where the file was either opened or saved explicitly. If you like to go even further in the past and the respective modifications have been made by PropEdit, you can use the feature Versions of the operating system to restore an old, saved variant of the file. Select the menu item File > Revert To > Last Opened to restore the file to the state when you originally opened it. You can also use the menu item File > Revert to > Browse All Versions to review earlier variants of the file in a time line and search for the point in time you like to restore. The user interface will resemble the Time Machine function of the operating system.

Depending on the operating system version you are using, small details in the operation of Versions, or the designations of menu items can slightly differ. To get more information about Versions, please search for the term Document Versions in the reference manual of your operating system version. You can open the manual via the item Help > Mac User Guide in the Finder application.

Depending on operating system, you can use additional menu items or the title bar of the window to duplicate, rename, move, or protect the file. To save a file with a different name, select File > Duplicate and enter the desired name for the duplicate.

Strings with multiple lines or control characters

Keys or values can contain control characters. If a character represents a line feed (LF), it means that the entry contains multiple lines. Such entries cannot be displayed directly in the table. Instead, the message —Control characters! Double-click to show— appears.

If you double-click the respective entry, PropEdit displays a special window that displays the string in two text boxes. In all situations where the text can be modified, you can edit the string immediately at this point. The box on the left is used for this purpose. The right box, on the other hand, cannot be changed, but identifies the invisible characters via a special presentation. You can choose between displaying the special characters

• as ISO symbols with the official Unicode name of the control character, or the name according to the international standard ISO 646, respectively,
• or in C syntax, i.e. in a readable replacement representation with a backslash, just as the characters are typed in all programming languages of the C family. This format is used in many other programming languages as well.

For better readability, PropEdit displays the line feed character directly as the end of a line. If this is not desired, you can uncheck Evaluate line feeds.

Control characters in property lists may not be permitted by macOS in all situations. Only the characters for line feed (LF), carriage return (CR) and horizontal tab (HT) are guaranteed to be supported in every case and will also be saved again during further processing of a file. All other control characters may be automatically removed or ignored.

If you have made changes in the text box, they will not be commited until you click the OK button. When you click Cancel, the previous value remains unchanged.

Deleting multiple entries at the same level

The table presenting the property list only permits to select one line at a time only, because many operations that can be performed with the data may not make sense for reasons of logic when being executed with multiple entries simultaneously. This can be impractical if you like to remove multiple entries from a container element at the same time, like an array or dictionary. You can do so via a specific deletion dialog, however, which is used as follows:

1. Select an array or dictionary in the table.
2. Open the menu item Edit > Delete Multiple Items…, or the equally named item in the context menu, or press the key combination ⌘ + -.
3. A dialog window will appear that only shows the content objects of the array or dictionary at the selected level. You can now select several items for deletion.
4. Click the button Delete to remove the selected objects.

Exporting binary data

If a property list file contains entries of type Binary Data, this will often be sequences of bytes which actually belong to a different file format. For example, if a photo should be stored in a property list, it will be a common method to convert the photo into the JPEG file format and to insert the bytes of the resulting file into an entry of type binary data. In that case in can be helpful to export such an entry to file. In many other cases, it can also be useful to have a byte sequence in form of a separate file, for example when you like to analyze unknown data with a different application. Perform the following steps to export binary data as file:

1. Select an entry of type Binary Data in the property list.
2. Open the menu item Edit > Export Binary Data as File… or use the equally named item of the context menu.
3. Confirm folder location and file name in the save sheet and click the button Export.

Sorting data

XML is a format describing data in textual form. This means a property list stored in XML format implicitly defines a specific order in which the elements of the list appear within the text. This is not the case for binary format. Elements of type dictionary don’t have any predefined order, so macOS may sort them at random to optimize processing speed, making access as efficient as possible. These differences are respected by PropEdit.

If a file is stored in XML format, PropEdit will ensure that the order the elements appear in the file is matching the shown order in the window (top down). By default, the pop-up button in the upper right corner of the window will display the mode Keep sort order of file.

This won’t be guaranteed if the XML file contains syntactical errors. A file with slight errors that would still be accepted by macOS during processing will also be opened by PropEdit, the order of entries may then be lost, however.

You can re-sort the columns Property Key and Type if you like. Just click once on the header of the respective table column to get an alphabetic sorting. Another click will cause sorting in reverse order. The pop-up button in the upper right corner will automatically change to Allow sorting by columns in that case. This sorting will only change the shown order of the items, not the physical order in the file. You can go back to the file order any time by selecting Keep sort order of file.

During the time the window is in mode Keep sort order of file, you can also change the actual, physical order of the items, however. Furthermore, after selecting the top line of a dictionary, you can let PropEdit sort the dictionary in alphabetical order of its keys by selecting the menu item Edit > Sort Dictionary by Keys (or by the matching item in the context menu).

Changing the order of elements is possible for files in binary format, too. The new order may have no lasting effect on dictionaries however, because macOS may change the order during each save operation for efficiency reasons, as already mentioned.

It is currently not possible to influence the order of dictionaries within JSON files, however. In this case, the pop-up button at the top right of the window will be suppressed.

Search for contents in the opened file

PropEdit will display a standard macOS Find dialog in the upper part of the window, when you select the menu item Edit > Find > Find… or press the key combination ⌘ + F. You can search for all contents of the property list, i.e. both for keys and values, but not for type names. In addition, values of type Boolean, Date/Time and Binary Data won’t be considered during search, because no obvious representation of them can be formulated as input text. Click the button Done to close the search dialog.

PropEdit is fully compliant with the macOS design guidelines for search operations:

• The key combination ⌘ + G will find the next occurrence of the already entered search text, continuing the search in forward direction.
• The key combination ⌘ + ⇧ + G will do the same in reverse direction, finding the previous occurrence.
• The key combination ⌘ + E will cause your current text selection to become the text to search for.
• The key combination ⌘ + J forces the window content to jump to the current selection, making sure the selected item becomes visible.

By clicking on the disclosure triangle next to the magnifying glass, you can specify additional search modes, e.g. case-sensitivity, search in the whole document, search for words, or search by regular expressions.

Converting between file formats

If the status bar at the top of the window indicates that the contents can be saved as either a plist file or JSON file, an additional button labeled Convert will also be shown. When you click this button, the format will switch back and forth between the two. So, if it’s currently in plist format, clicking the button will convert it to JSON, and vice versa. Note that the existing filename, which usually includes the extension .plist or .json, cannot be preserved. You should save the file under a new name after clicking the button.

Further information about the compatibility of both file formats can be found at the end of the chapter JSON Files - JavaScript Object Notation.

It is additionally possible to export the data which not only allows to switch to a different file type, but also to a different variant of the same type.

For new files, PropEdit always assumes the file type to be property list.