The NSPropertyListSerialization class provides
facilities for serialising and deserializing
property list data in a number of formats. A
property list is roughly an
NSArray
or
NSDictionary
object, with these or
NSNumber
,
NSData
,
NSString
, or
NSDate
objects as members. (See below.)
You do not work with instances of this
class, instead you use a small number of
class methods to serialize and
deserialize property lists.
A property list may only
be one of the following classes -
An array which is either empty or
contains only
property list objects.
An array is delimited by round brackets
and its contents are comma
separated (there is no comma
after the last array element).
( "one", "two", "three" )
In XML format, an array is an element whose name is
array and whose content is the array
content.
A data object is represented as a series of pairs of
hexadecimal characters (each pair representing
a byte of data) enclosed in angle brackets. (Spaces are
ignored).
< 54637374 696D67 >
Base64 can be used since Base 1.24.9:
<[VGNzdGltZw==]>
In XML format, a data object is an element whose name is
data and whose content is a stream of
base64 encoded bytes.
Date objects were not traditionally allowed in
property lists but were added when the XML
format was introduced. GNUstep provides an extension
to the traditional property list format to
support date objects, but older code will not read
property lists containing this extension.
This format consists of an asterisk followed
by the letter 'D' then a date/time in YYYY-MM-DD
HH:MM:SS +/-ZZZZ format, all enclosed within angle
brackets.
<*D2002-03-22 11:30:00 +0100>
In XML format, a date object is an element whose name is
date and whose content is a date in the
format YYYY-MM-DDTHH:MM:SSZ (or the above dfate
format).
A dictionary which is either empty or contains only
string keys and property list
objects. A dictionary is delimited by curly
brackets and its contents are semicolon
terminated (there is a semicolon after each
value). Each item in the dictionary is a key/value
pair with an equals sign after the key and before the
value.
{
"key1" = "value1";
}
In XML format, a dictionary is an element whose name is
dict and whose content consists of pairs
of string key and other
property list objects.
Number objects were not traditionally allowed in
property lists but were added when the XML
format was introduced. GNUstep provides an extension
to the traditional property list format to
support number objects, but older code will not
read property lists containing this
extension. Numbers are stored in a
variety of formats depending on their values.
boolean... either <*BY> for
YES or <*BN> for
NO. In XML format this is
either <true /> or
<false />
integer... <*INNN> where NNN
is an integer. In XML format this is
<integer>NNN<integer>
real... <*RNNN> where NNN is a
real number. In XML format this is
<real>NNN<real>
A string is either stored literally (if it contains no
spaces or special characters), or is stored as a
quoted string with special characters escaped
where necessary. Escape conventions are
similar to those normally used in ObjectiveC
programming, using a backslash followed by -
\ a backslash character
" a quote character
b a backspace character
n a newline character
r a carriage return
character
t a tab character
OOO (three octal digits) an
arbitrary ascii character
UXXXX (where X is a
hexadecimal digit) a an arbitrary unicode
character
"hello world & others"
In XML format, the string is simply stored in UTF8 format
as the content of a string element, and the
only character escapes required are those used by XML
such as the '<' markup representing a '<'
character.
Creates and returns a data object containing a
serialized representation of plist. The argument
aFormat is used to determine the way in
which the data is serialised, and the
anErrorString argument is a pointer in
which an error message is returned on failure (
nil is returned on success).
Deserialises dataItem and returns the
resulting property list (or nil if
the data does not contain a property list
serialised in a supported format). The
argument anOption is used to control
whether the objects making up the deserialized
property list are mutable or not. The
argument aFormat is either null or a
pointer to a location in which the format of the
serialized property list will be returned.
Either nil or an error message
will be returned in anErrorString.