hs.plist
ModuleModule for reading and writing macOS property list (plist) files.
Property lists are a structured data format used extensively on Apple platforms for storing configuration, preferences, and serialized data. This module supports both XML and binary plist formats.
JavaScript ↔ plist type mapping:
- JavaScript strings ↔ plist strings
- JavaScript numbers ↔ plist integers and reals
- JavaScript booleans ↔ plist true/false
- JavaScript arrays ↔ plist arrays
- JavaScript objects ↔ plist dictionaries
- JavaScript null is not supported by the plist format and will cause write operations to fail
- Plist Date and Data values are returned as opaque objects and may not be directly usable in JavaScript
Properties
This module has no properties.
Methods
hs.plist.fromFile(path) -> any
Read a plist file and return its contents as a JavaScript value.
Supports both XML and binary plist formats. Returns a JavaScript object for
dictionary-rooted plists, an array for array-rooted plists, or a string or
number for scalar-rooted plists.
Declaration
hs.plist.fromFile(path) -> anyParameters
| Name | Type | Description |
|---|---|---|
| path | string | Path to the plist file |
Returns
any
The plist contents, or null if the file could not be read or parsed
Example
const prefs = hs.plist.fromFile("/Users/me/Library/Preferences/com.example.app.plist")
console.log(prefs.SomeKey)hs.plist.fromString(plistString) -> any
Read a plist from an XML string and return its contents as a JavaScript value.
Declaration
hs.plist.fromString(plistString) -> anyParameters
| Name | Type | Description |
|---|---|---|
| plistString | string | An XML plist string |
Returns
any
The plist contents, or null if the string could not be parsed
Example
const xml = '<?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>Test</string></dict></plist>'
const data = hs.plist.fromString(xml)
console.log(data.Name)hs.plist.toFile(path, data, binary) -> boolean
Write a JavaScript object to a plist file on disk.
Keys must be strings. Values may be strings, numbers, booleans, arrays, or
nested objects. JavaScript null values are not plist-compatible and will cause
the write to fail.
Declaration
hs.plist.toFile(path, data, binary) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| path | string | Destination file path |
| data | {[key: string]: any} | A JavaScript object to serialize as a property list |
| binary | boolean | If true, write binary plist format; if false (default), write XML plist format |
Returns
boolean
true if the file was written successfully
Example
hs.plist.toFile("/tmp/test.plist", { name: "Hammerspoon", version: 2 })
hs.plist.toFile("/tmp/test.plist", { name: "Hammerspoon" }, true)hs.plist.toString(data, binary) -> string
Serialize a JavaScript object to a plist string.
With binary set to false (default), returns an XML plist string suitable for
storing in text files or passing to `readString`. With binary set to true,
returns a base64-encoded binary plist string.
Declaration
hs.plist.toString(data, binary) -> stringParameters
| Name | Type | Description |
|---|---|---|
| data | {[key: string]: any} | A JavaScript object to serialize as a property list |
| binary | boolean | If true, produce base64-encoded binary plist output; if false (default), produce an XML string |
Returns
string
The serialized plist string, or null if serialization failed
Example
const xml = hs.plist.toString({ name: "Hammerspoon", version: 2 })
const b64 = hs.plist.toString({ name: "Hammerspoon" }, true)