simple-plist

What is simple-plist?

The simple-plist npm package allows for the reading, writing, and manipulation of plist (Property List) files, which are commonly used in macOS and iOS for storing serialized objects. It provides a straightforward API for handling plist data in XML and binary formats.

What are simple-plist's main functionalities?

Reading plist files

This feature allows for the synchronous reading of plist files from the filesystem. The `readFileSync` method reads the file from the given path and returns the plist data as a JavaScript object.

const plist = require('simple-plist');
const data = plist.readFileSync('/path/to/file.plist');

Writing plist files

This feature enables the synchronous writing of plist data to files. The `writeFileSync` method takes a file path and a JavaScript object, then serializes the object into plist format and writes it to the specified file.

const plist = require('simple-plist');
const data = { key: 'value' };
plist.writeFileSync('/path/to/file.plist', data);

Parsing plist data

This feature involves parsing plist data from a string. The `parse` method takes a plist-formatted string and converts it into a JavaScript object, allowing for easy manipulation and access to the data.

const plist = require('simple-plist');
const plistData = '<plist><dict><key>exampleKey</key><string>exampleValue</string></dict></plist>';
const data = plist.parse(plistData);

Other packages similar to simple-plist

plist

The 'plist' package offers similar functionality for parsing and building plist files. It supports both XML and binary plist formats. Compared to simple-plist, it might offer a more comprehensive API and additional options for customization.

bplist-parser

This package is specifically designed for parsing binary plist files. While it does not support writing plist files or handling XML plists, it's optimized for fast and efficient parsing of binary plist data, making it a good choice for applications that only need to read plist files.

README

simple-plist

A simple API for interacting with binary and plain text plist data.

Installation

# via npm
npm install simple-plist

# via yarn
yarn add simple-plist

Synchronous API

import * as plist from "simple-plist";

let data;

// read
data = plist.readFileSync("/path/to/some.plist");

// write xml
plist.writeFileSync("/path/to/plaintext.plist", data);

// write binary
plist.writeBinaryFileSync("/path/to/binary.plist", data);

Asynchronous API

Note: all of the async examples can optionally be converted to promises using node's util.promisify.

import * as plist from "simple-plist";

let data;

function callback(err, contents) {
  if (err) throw err;
  data = contents;
}

// read
plist.readFile("/path/to/some.plist", callback);

// write xml
plist.writeFile("/path/to/plaintext.plist", data, callback);

// write binary
plist.writeBinaryFile("/path/to/binary.plist", data, callback);

In Memory

plist.stringify()

const plist = require("simple-plist");

// Convert an object to a plist xml string
plist.stringify({ name: "Joe", answer: 42 });

/*
<?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">
  <dict>
    <key>name</key>
    <string>Joe</string>
    <key>answer</key>
    <integer>42</integer>
  </dict>
</plist>
*/

plist.parse()

import * as plist from "simple-plist";

const xml = `<plist>
	<dict>
		<key>name</key>
		<string>Joe</string>
	</dict>
</plist>`;

plist.parse(xml);
// { "name": "Joe" }

TypeScript Support

All functions have typescript signatures, but there are a few handy generics that are worth pointing out. Those generics belong to parse, readFile, and readFileSync. Here's an example:

import { parse, readFile, readFileSync } from "simple-plist";

type Profile = {
  name: string;
  answer: number;
};

const xml = `<plist>
	<dict>
		<key>name</key>
		<string>Joe</string>
		<key>answer</key>
		<integer>42</integer>
	</dict>
</plist>`;

// typed string parsing
const { answer } = parse<Profile>(xml);
// answer = 42;

// typed file loading
const { name } = readFileSync<Profile>("/path/to/profile.plist");