mirror of
https://github.com/claunia/plist-cil.git
synced 2025-12-16 19:14:26 +00:00
Updated readme. Fixes #1.
This commit is contained in:
145
README.md
145
README.md
@@ -1,35 +1,148 @@
|
||||
# plist-cil
|
||||
This library enables .NET (CLR) applications to work with property lists in various formats.
|
||||
# plist-cil - A C# library for working with property lists
|
||||
|
||||
[](httsp://travis-ci.org/claunia/plist-cil)
|
||||
|
||||
This library enables .NET (CLR) applications to handle property lists of various formats.
|
||||
It is mostly based on [dd-plist for Java](https://github.com/3breadt/dd-plist).
|
||||
And as it, this is licensed under the terms of the MIT license.
|
||||
|
||||
You can parse existing property lists (e.g. those created by an iOS application) and work with the contents on any operating system.
|
||||
Property lists are files used to store user settings and serialized objects.
|
||||
They originate from the NeXTSTEP programming environment and are now a basic part of thhe Cocoa framework (macOS and iOS) as well as the GNUstep framework.
|
||||
|
||||
The library also enables you to create your own property lists from scratch and store them in various formats.
|
||||
## Features
|
||||
|
||||
The provided API mimics the Cocoa/NeXTSTEP API, and where applicable, the .NET API, granting access to the basic functions of classes like NSDictionary, NSData, etc.
|
||||
* Read / write property lists from / to files, streams or byte arrays
|
||||
* Convert between property lists formats
|
||||
* Property list contents are provided as objects from the NeXTSTEP environment (NSDictionary, NSArray, NSString, etc.)
|
||||
* Serialie native .NET data structures to property list objects
|
||||
* Deserialize from property list objects to native .NET data structures
|
||||
|
||||
### Supported formats
|
||||
## Supported formats
|
||||
|
||||
| Format | Read | Write |
|
||||
| ---------------------- | ---- | ----- |
|
||||
| OS X / iOS XML | yes | yes |
|
||||
| OS X / iOS Binary (v0) | yes | yes |
|
||||
| OS X / iOS ASCII | yes | yes |
|
||||
| GNUstep ASCII | yes | yes |
|
||||
* Cocoa XML
|
||||
* Cocoa Binary (v0)
|
||||
* Cocoa / NeXTSTEP / GNUstep ASCII
|
||||
|
||||
### Requirements
|
||||
## Requirements
|
||||
.NET Framework 4.0, Mono or .NET Core.
|
||||
Targets .NET Framework 4.0, .NET Framework 4.5, .NET Standard 1.3, .NET Standard 1.4 and .NET Standard 1.6 so it should be compatible with Mono, Xamarin.iOS, Xamarin.Mac, UWP, etc.
|
||||
If you find an incompatibility, please create an issue.
|
||||
|
||||
### Download
|
||||
## Download
|
||||
|
||||
The latest releases can be downloaded [here](https://github.com/claunia/plist-cil/releases).
|
||||
|
||||
### NuGet support
|
||||
## NuGet support
|
||||
You can download the NuGet package directly from the [release](https://github.com/claunia/plist-cil/releases) page or from the [NuGet Gallery](https://www.nuget.org/) or from [here](https://www.nuget.org/packages/plist-cil/).
|
||||
|
||||
### Help
|
||||
## Help
|
||||
The API documentation is included in the download.
|
||||
|
||||
When you encounter a bug please report it by on the [issue tracker](https://github.com/claunia/plist-cil/issues).
|
||||
|
||||
## Usage examples
|
||||
|
||||
### Reading
|
||||
|
||||
Parsing can be done with the PropertyListParser class. You can feed the `PropertyListParser` with a `FileInfo`, a `Stream` or a `byte` array.
|
||||
The `Parse` method of the `PropertyListParser` will parse the input and give you a `NSObject` as result. Generally this is a `NSDictionary` but it can also be a `NSArray`.
|
||||
|
||||
_Note: Property lists created by `NSKeyedArchiver` are not yet supported._
|
||||
|
||||
You can then navigate the contents of the property lists using the various classes extending `NSObject`. These are modeled in such a way as to closely resemble the respective Cocoa classes.
|
||||
|
||||
You can also directly convert the contained `NSObject` objects into native .NET Objects with the `NSOBject.ToObject()` method. Using this method you can avoid working with `NSObject` instances altogether.
|
||||
|
||||
### Writing
|
||||
|
||||
You can create your own property list using the various constructors of the different `NSObject` classes. Or you can wrap existing native .NET structures with the method `NSObject.Wrap(Object o)`. Just make sure that the root object of the property list is either a `NSDictionary` (can be created from objects of the type `Dictionary<string, Object>`) or a `NSArray` (can be created from object arrays).
|
||||
|
||||
For building a XML property list you can then call the `ToXml` method on the root object of your property list. It will give you an UTF-8 `string` containing the property list in XML format.
|
||||
|
||||
If you want to have the property list in binary format use the `BinaryPropertyListWriter` class. It can write the binary property list directly to a file or to a `Stream`.
|
||||
|
||||
When you directly want to save your property list to a file, you can also use the `SaveAsXml` or `SaveAsBinary` methods of the `PropertyListParser` class.
|
||||
|
||||
### Converting
|
||||
|
||||
For converting a file into another format there exist convenience methods in the `PropertyListParser` class: `ConvertToXml`, `ConvertToBinary`, `ConvertToASCII` and `ConvertToGnuStepASCII`.
|
||||
|
||||
## Code snippets
|
||||
|
||||
### Reading
|
||||
|
||||
try
|
||||
{
|
||||
FileInfo file = new FileInfo("Info.plist");
|
||||
NSDictionary rootDict = (NSDictionary)PropertyListParser.Parse(file);
|
||||
string name = rootDict.ObjectForKey("Name").ToString();
|
||||
NSObject[] parameters = ((NSArray)rootDict.ObjectForKey("Parameters")).GetArray();
|
||||
foreach(NSObject param in parameters)
|
||||
{
|
||||
if(param.GetType().Equals(typeof(NSNumber)))
|
||||
{
|
||||
NSNumber num = (NSNumber)param;
|
||||
switch(num.GetNSNumberType())
|
||||
{
|
||||
case NSNumber.BOOLEAN:
|
||||
{
|
||||
boolean bool = num.ToBool();
|
||||
// ...
|
||||
break;
|
||||
}
|
||||
case NSNumber.INTEGER:
|
||||
{
|
||||
long l = num.ToLong();
|
||||
// or int i = num.ToInt();
|
||||
// ...
|
||||
break;
|
||||
}
|
||||
case NSNumber.REAL:
|
||||
{
|
||||
double d = num.ToDouble();
|
||||
// ...
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
// else...
|
||||
}
|
||||
}
|
||||
catch(Exception ex)
|
||||
{
|
||||
Console.WriteLine(ex.StackTrace);
|
||||
}
|
||||
|
||||
### Writing
|
||||
|
||||
// Creating the root object
|
||||
NSDictionary root = new NSDictionary();
|
||||
|
||||
// Creation of an array of length 2
|
||||
NSArray people = new NSArray(2);
|
||||
|
||||
// Creation of the first object to be stored in the array
|
||||
NSDictionary person1 = new NSDictionary();
|
||||
// The NSDictionary will automatically wrap strings, numbers and dates in the respective NSObject subclasses
|
||||
person1.Add("Name", "Peter"); // This will become a NSString
|
||||
// Use the DateTime class
|
||||
person1.Add("RegistrationDate", new DateTime(2011, 1, 13, 9, 28, 0)); // This will become a NSDate
|
||||
person1.Add("Age", 23); // This will become a NSNumber
|
||||
person1.Add("Photo", new NSData(new FileInfo("peter.jpg")));
|
||||
|
||||
// Creation of the second object to be stored in the array
|
||||
NSDictionary person2 = new NSDictionary();
|
||||
person2.Add("Name", "Lisa");
|
||||
person2.Add("Age", 42);
|
||||
person2.Add("RegistrationDate", new NSDate("2010-09-23T12:32:42Z"));
|
||||
person2.Add("Photo", new NSData(new FileInfo("lisa.jpg")));
|
||||
|
||||
// Put the objects into the array
|
||||
people.SetValue(0, person1);
|
||||
people.SetValue(1, person2);
|
||||
|
||||
// Put the array into the property list
|
||||
root.Add("People", people);
|
||||
|
||||
// Save the property list
|
||||
PropertyListParser.SaveAsXml(root, new FileInfo("people.plist"));
|
||||
Reference in New Issue
Block a user