simple-plist

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

Installation

Package managers

# via npm
npm install simple-plist

# via yarn
yarn add simple-plist

Deno

Starting with version 1.4.0, you can also import simple-plist into your deno applications through esm.sh.

import plist from "https://esm.sh/[email protected]";

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");