GitLocker: The Coding Marketplace

Description:

propertylistserialization

iOS compatible plist serialization and deserialization library for Dart #
This library is open source (BSD-2). Development occurs on GitHub.
Package is hosted on dart packages.
Looking for an Android (Java) implementation?.
Features #
XML plist (xml1)

Character by character accurate output*1 from method PropertyListSerialization.dataFromPropertyList() with iOS method [NSPropertyListSerialization dataFromPropertyList:format:options:error:]
dict dictionaries are sorted by key (as per CFPropertyList.c)
key (dictionary) and string values are escaped for < > and & characters to \< \> and \& (as per CFPropertyList.c)

*1 character by character accuracy excludes <real> numbers - the floating point representation output with Dart will have on average 6 decimal places, compared to 12 decimal places for iOS).
Binary plist (binary1)

Supports version bplist00 constructs only (all data type conversions as per XML - if you can serialize/deserialize an object tree into XML, then you can serialize/deserialize the same object tree into Binary).
Also supports deserializing of NSKeyedArchiver CF$UID constructs.
Byte by byte accurate output *2 from method PropertyListSerialization.dataFromPropertyList() with iOS method [NSPropertyListSerialization dataFromPropertyList:format:options:error:]

*2 byte by byte accuracy excludes <dict> dictionaries with more than one key/value pair - unlike XML plists, they are not sorted by key, and therefore the ordering of the key/value pairs will differ. <data> elements are deduplicated more aggressively than Apple's implementation generally resulting in smaller output size, but still remaining compatible.
Distribution #

Minimum Dart version 2.12 (null safety)
Friendly BSD-2 license

Installation #
Import the library into your Dart code using:
import 'package:propertylistserialization/propertylistserialization.dart';
copied to clipboard
XML example (xml1 format) #
Writing/Serialization
var list = [];
var dict = <String, Object>{};
dict['Selected'] = true;
dict['IconName'] = 'largeIcon.png';
dict['IconSize'] = 32;
list.add(dict);

try {
var result = PropertyListSerialization.stringWithPropertyList(list); // result == String
} on PropertyListWriteStreamException catch (e) {
// handle error.
}
copied to clipboard
Result
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array>
<dict>
<key>IconName</key>
<string>largeIcon.png</string>
<key>IconSize</key>
<integer>32</integer>
<key>Selected</key>
<true/>
</dict>
</array>
</plist>
copied to clipboard
Reading/Deserialization
try {
var list = PropertyListSerialization.propertyListWithString(result) as List;

var dict = list[0];
var selected = dict['Selected']; // true
var iconName = dict['IconName']; // largeIcon.png
var iconSize = dict['IconSize']; // 32
} on PropertyListReadStreamException catch (e) {
// handle error.
}
copied to clipboard
Binary example (binary1 format) #
Writing/Serialization
var list = [];
var dict = <String, Object>{};
dict['Selected'] = true;
dict['IconName'] = 'largeIcon.png';
dict['IconSize'] = 32;
list.add(dict);

try {
var result = PropertyListSerialization.dataWithPropertyList(list); // result == ByteData
} on PropertyListWriteStreamException catch (e) {
// handle error.
}
copied to clipboard
Result
62 70 6c 69 73 74 30 30 a1 01 d3 02 03 04 05 06
07 58 49 63 6f 6e 4e 61 6d 65 58 49 63 6f 6e 53
69 7a 65 58 53 65 6c 65 63 74 65 64 5d 6c 61 72
67 65 49 63 6f 6e 2e 70 6e 67 10 20 09 08 0a 11
1a 23 2c 3a 3c 00 00 00 00 00 00 01 01 00 00 00
00 00 00 00 08 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 3d
copied to clipboard
Reading/Deserialization
try {
var list = PropertyListSerialization.propertyListWithData(result) as List;
var dict = list[0];
var selected = dict['Selected'];
var iconName = dict['IconName'];
var iconSize = dict['IconSize'];
} on PropertyListReadStreamException catch (e) {
// handle error.
}
copied to clipboard
Data type conversions #
Serialization (Dart -> plist)

Input Dart type
Equivalent Obj-C type
Output plist type

String
NSString
<string>

int
NSNumber (integerValue)
<integer>

Float32
NSNumber (floatValue)
<real> *3

double
NSNumber (doubleValue)
<real>

Map<String, Object>
NSDictionary
<dict>

List
NSArray
<array>

DateTime
NSDate
<date>

true
NSNumber (boolValue) YES
<true>

false
NSNumber (boolValue) NO
<false>

ByteData
NSData
<data>

*3 Serialization only, deserialization will always output double.
Deserialization (plist -> Dart)

Input plist type
Equivalent Obj-C type
Output Dart type

<string>
NSString
String

<integer>
NSNumber (longValue)
int

<real>
NSNumber (doubleValue)
double

<dict>
NSDictionary
Map<String, Object>

<array>
NSArray
List

<date>
NSDate
DateTime

<true>
NSNumber (boolValue) YES
true

<false>
NSNumber (boolValue) NO
false

<data>
NSData
ByteData

CF$UID (binary plist only)
n/a
UID

Class PropertyListSerialization #
String stringWithPropertyList(Object)
static String stringWithPropertyList(Object obj);
copied to clipboard
For the object graph provided, returns a property list as a xml String. Equivalent to iOS method [NSPropertyList dataWithPropertyList:format:options:error]
params obj - The object graph to write out as a xml property list. The object graph may only contain the following types: String, int, Float32, double, Map<String, Object>, List, DateTime, bool or ByteData.
returns String of the xml plist.
throws PropertyListWriteStreamException if the object graph is incompatible.

Object propertyListWithString(String)
static Object propertyListWithString(String string);
copied to clipboard
Creates and returns an object graph from the specified property list xml String. Equivalent to iOS method [NSPropertyList propertyListWithData:options:format:error]
params string - String of xml plist.
returns Returns one of String, int, double, Map<String, Object>, List, DateTime, bool or ByteData.
throws PropertyListReadStreamException if the plist is corrupt, values could not be converted or the input stream is EOF.

ByteData dataWithPropertyList(Object)
static ByteData dataWithPropertyList(Object obj);
copied to clipboard
For the object graph provided, returns a property list as a binary ByteData. Equivalent to iOS method [NSPropertyList dataWithPropertyList:format:options:error]
Hint: To convert any returned ByteData objects into a Uint8List, you should use the following pattern: data.buffer.asUint8List(data.offsetInBytes, data.lengthInBytes);
params obj - The object graph to write out as a binary property list. The object graph may only contain the following types: String, int, Float32, double, Map<String, Object>, List, DateTime, bool or ByteData.
returns ByteData of the binary plist.
throws PropertyListWriteStreamException if the object graph is incompatible.

Object propertyListWithData(ByteData)
static Object propertyListWithData(ByteData data, {bool keyedArchive = false});
copied to clipboard
Creates and returns an object graph from the specified property list binary ByteData. Equivalent to iOS method [NSPropertyList propertyListWithData:options:format:error]
Hint: To convert any returned ByteData objects into a Uint8List, you should use the following pattern: data.buffer.asUint8List(data.offsetInBytes, data.lengthInBytes);
params data - ByteData of binary plist.
params keyedArchive - bool - if true then deserialization also supports CF$UID constructs and returns it as a UID object.
returns Returns one of String, int, double, Map<String, Object>, List, DateTime, bool, ByteData or UID.
throws PropertyListReadStreamException if the plist is corrupt, values could not be converted or the input stream is EOF.