# PropertyList Service

The `PropertyList` service allows you to read and write property list files in all formats supported by the Core Foundation API: XML, binary, JSON, and OpenStep (read-only).

This service is only available on Darwin platforms such as OS X and iOS.

## Making the Service Available

In order to gain access to property list operations, you need to import the service using the following statement at the top of your project file:

    import qbs.PropertyList

## Available operations

### Constructor

    PropertyList()

Allocates and returns a new PropertyList object.

### clear

    clear()

Voids the property list by deleting its internal object reference.

### isEmpty

    isEmpty()

Returns true if the property list has no internal object reference set, otherwise false.

### format

    format()

Returns the data format that the property list data was deserialized from. This property is set after calling `readFromString` or `readFromFile`. Possible return values include: `"binary1"`, `"json"`, `"openstep"`, and `"xml1"`. If the property list object is empty or the input format could not be determined, returns `undefined`.

### readFromFile

    readFromFile(filePath)

Parses the file and stores the result in the property list. Throws an exception if an I/O error occurs or the input is in an invalid format.

### readFromString

    readFromString(input)

Parses `input` and stores the result in the property list. This is most useful for initializing a property list object from the result of a `JSON.stringify` call. Throws an exception if the input is in an invalid format.

### toJSONString

    toJSONString(style)

Returns a string representation of the property list in JSON format. Possible values for `style` include `"pretty"` and `"compact"`. The default is compact.

### toString

    toString(format)

Returns a string representation of the property list in the specified format. Possible values for `format` include: `"json"` (compact), `"json-compact"`, `"json-pretty"`, and `"xml1"`. Currently, the OpenStep format is not supported. Throws an exception if the object cannot be written in the given format.

### toXMLString

    toXMLString()

Returns a string representation of the property list in XML format. This function is a synonym for `toString("xml1")`.

### writeToFile

    writeToFile(filePath, format)

Writes the property list to the file in the given format. Possible values for `format` include: `"binary1"`, `"json"` (compact), `"json-compact"`, `"json-pretty"`, and `"xml1"`. Currently, the OpenStep format is not supported for writing. Throws an exception if an I/O error occurs or the object cannot be written in the given format.