Property list

the plist formats, XML and ASCII

plists

The property list (or plist) formats supported by Oolite are standard formats handled by Mac OS X. They’re based on OpenStep formats. OS X supports three representations for property lists, XML, “old-style ASCII” (the original NextStep/OpenStep format) and binary. The non-Mac versions of Oolite support GNUStep’s superset of ASCII format, and XML format through a custom parser. Binary format is not supported on these systems and therefore not reccomended for use with Oolite.

(ASCII is a misnomer, since the format is usually stored in UTF-8 or UTF-16 encoding. However, since Oolite’s text rendering only supports ASCII, the previous sentence can be safely ignored.)

Both XML and ASCII format support the full set of data types used for Oolite, and can therefore be used interchangeably. These types are: strings, integers, reals, arrays and dictionaries.

string

A string is a block of text. In ASCII format plists, this is surrounded by straight double quotation marks, with \ being used to escape quotation marks within the string: "a string with a \"quotation\" and a <tag>". ASCII format plists also allow single-word strings to be used without quotation marks when this is unambiguous. In XML format, it is surrounded by <string> tags, with normal XML escapes: <string>a string with a "quotation" and a <tag></string>.

integer

An integer is a whole number. In ASCII format plists, an integer is written unquoted:-12345. In XML format, it is surrounded by <integer> tags:<integer>-12345</integer>.

real

A real is a number with a fractional part. In ASCII format plists, reals are again written unquoted: 42.123. In XML format, it is surrounded by <real> tags:<real>42.123</real>. Large reals can be expressed in scientific notation: 1.35e+20. Integers and reals are mostly interchangeable in Oolite.

boolean

A boolean is either of the values true and false. It isn’t listed above since it isn’t supported by ASCII format; however, it is treated as a special case of an integer. Anywhere true would normally be used, the integer 1 can be used instead. False can be replaced with 0. In XML format, the tags <true/> and <false/> can be used.

array

An array is an ordered list of objects. In ASCII format, it is contained in parentheses, with items separated by commas: (0, 1, two, "three and a half"). In XML format, it is contained in <array> tags: <array><integer>0</integer> <true/> <string>two</string> <string>three and a half</string>.

dict

Dictionaries are the most complex type. The consist of key/value pairs – each pair consists of a key, which is always a string, and a value, which can be any type. Each key must be unique, and the order of pairs is not significant.

In ASCII format, dictionaries are contained in braces, with key and value separated by = signs and pairs separated by semicolons: {length = 42; width = 36.5; "long name" = "this is a thing with a really quite long name"; attributes = (hairy, muscular);}.

In XML format, dictionaries are contained in <dict> tags, with keys specified by <key> tags and immediately followed by values with their type tag: <dict><key>length</key><integer>42> <key>width><real>36.5</real> <key>long name</key><string>this is a thing with a really quite long name</string> <key>attributes</key><array><string>hairy</string><string>muscular</string><array></dict>.

Every property list has a single value as its root. Typically this is a dictionary. In XML format, the root value must be surrounded by <plist> tags in addition to its normal type tag: <plist><dictionary><key>green</key><array><integer>0</integer><integer>1</integer><integer>0</integer></array></dictionary></plist> (ASCII equivalent: green = (0, 1, 0);).

comment

Both formats can also contain comments, which are ignored by the program but are useful to human readers. In ASCII format, these can either start with // and continue to the end of the line, or start with /* and end with */. In XML, they start with <!-- and end with --> (and must not contain -- anywhere else in the comment).

Examples:

 /*this line is safe for comments in ASCII*/

<!-- this line is safe for comments in XML -->

XML Preamble

XML plists also need a standard header, which looks like this:

<?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">

Links

• OXP howto