briandfoy / mac-propertylist

(Perl) work with Mac plists at a low level

The Mac::PropertyList module

This is the README for the Mac::PropertyList Perl module. It handles the XML and binary property list formats (but not the JSON yet).

You're probably looking at this because you don't know where else to find what you're looking for. Read this once and you might never have to read one again for any Perl module.

Documentation

To read about Mac::PropertyList, look at the embedded documentation in the module itself. Inside the distribution, you can format it with perldoc:

% perldoc lib/Mac/PropertyList.pm

If you have already installed the module, you can specify the module name instead of the file location:

% perldoc Mac::PropertyList

You can read the documentation and inspect the meta data at MetaCPAN.

The standard module documentation has example uses in the SYNOPSIS section, but you can also look in the examples/ directory (if it's there), or look at the test files in t/.

Installation

You can install this module with a CPAN client, which will resolve and install the dependencies:

% cpan Mac::PropertyList
% cpanm Mac::PropertyList

You can also install directly from the distribution directory, which will also install the dependencies:

% cpan .
% cpanm .

You could install just this module manually:

% perl Makefile.PL
% make
% make test
% make install

You probably don't want to do that unless you're fiddling with the module and only want to run the tests without installing anything.

Source location

The meta data, such as the source repository and bug tracker, is in Makefile.PL or the META.* files it creates. You can find that on those CPAN web interfaces, but you can also look at files directly in the source repository:

• https://github.com/briandfoy/mac-propertylist

If you find a problem, file a ticket in the issue tracker:

• https://github.com/briandfoy/mac-propertylist/issues

Getting help

Although I'm happy to hear from module users in private email, that's the best way for me to forget to do something.

Besides the issue trackers, you can find help at Perlmonks or Stackoverflow, both of which have many competent Perlers who can answer your question, almost in real time. They might not know the particulars of this module, but they can help you diagnose your problem.

You might like to read brian's Guide to Solving Any Perl Problem.

Copyright and License

You should have received a LICENSE file, but the license is also noted in the module files. About the only thing you can't do is pretend that you wrote code that you didn't.

Good luck!

Enjoy,

brian d foy, [email protected]

mac-propertylist's Issues

Invalid XML in t/array.t (extra closing </array>)

@kulp (working on a SAX version of this module) version noted that an extra closing tag is in the XML in t/array.t.

Handle the old-style ASCII property list

• Where is that documented - https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/OldStylePlists/OldStylePLists.html
• How can I read it?
• How can I write it? Even though the Mac tools won't write it, we can

I've found real-world instances of 128bit ints in plists

This was running under macOS 11.4beta upgraded from 10.13
so was originally confused by sandboxing.

I'm writing a utility to report differences in plist files.
This means I'm recursively traversing all files under:
/Library/Preferences
~/Library/Preferences
using Mac::PropertyList::parse_plist_file. I'm using v1.502,
albeit by not properly installing but by unpacking and copying
the 'lib' directory, which is normally OK for Pure-Perl modules.

After modifying my script to ignore non-plist files and
allowing Terminal full-access to the disk, I was getting
croak "Integer > 8 bytes = $length"

After applying the attached diff, I got the following output
with no croaks(). The file-path is printed by my script before
it calls parse_plist_file
/Users/dthomas/Library/Preferences/.GlobalPreferences.plist
128bit int has top 64bits of zero
00000000 00000000 00000000 000007D0
so truncate it to a 64bit int
/Users/dthomas/Library/Preferences/com.apple.finder.plist
128bit int has top 64bits of zero
00000000 00000000 00000000 00000001
so truncate it to a 64bit int
/Users/dthomas/Library/Preferences/com.apple.ncprefs.plist
128bit int has top 64bits of zero
00000000 00000000 80000000 00000000
so truncate it to a 64bit int
128bit int has top 64bits of zero
00000000 00000000 80000000 00000007
so truncate it to a 64bit int
128bit int has top 64bits of zero
00000000 00000000 80000000 00000000
so truncate it to a 64bit int
128bit int has top 64bits of zero
00000000 00000000 80000000 00000007
so truncate it to a 64bit int
128bit int has top 64bits of zero
00000000 00000000 80000000 00000000
so truncate it to a 64bit int
128bit int has top 64bits of zero
00000000 00000000 80000000 00000000
so truncate it to a 64bit int
128bit int has top 64bits of zero
00000000 00000000 80000000 00000000
so truncate it to a 64bit int

Originally I thought I might have to provide some support for
128bit integers. But since all the cases I've seen can be
truncated, there's no need.

NB The irony is the length bits of ints/reals in
https://github.com/opensource-apple/CF/blob/master/CFBinaryPList.c
are marked '0nnn', whereas 'nnnn' was the case in the older
https://opensource.apple.com/source/CF/CF-550/CFBinaryPList.c

I thought I could create a test file with one attribute having a
128bit integer value
$ defaults write t1 128bit-integer -int 1208925819614629174706176
which is 2^80
$ plutil -convert xml1 -o - ~/Library/Preferences/t1.plist

128bit-integer 9223372036854775807 My script does not report the attribute valeu being 128bits, so it looks like defaults silently truncates integers to < 2^64. [ReadBinary.pm.diff.txt](https://github.com/briandfoy/mac-propertylist/files/6527406/ReadBinary.pm.diff.txt)

Handle JSON property list format

• Where is that documented
• How can I read it?
• How can I write it?

To reverse engineer it, you can convert an existing property list to JSON. Remember that the plutil command replaces the original content if you don't use the -o switch:

% plutil -convert json -o plist.json some.plist

But, not everything that was valid Property List data in XML or binary is valid in JSON. I don't know what those are, but plutil will complain.

Debug code left in Mac::PropertyList::ReadBinary?

Thank you very much for your continued maintenance of Mac::PropertyList.

It appears that the _read_object() method of Mac::PropertyList::ReadBinary contains some extraneous say() statements. Were these left over from debugging? I am willing to prepare a pull request conditionalizing them on lexical $Debug, which gets initialized as in Mac::PropertyList itself.

I searched for 'say' statements other places, and did not find any.

Help with attribution for tests

@briandfoy -- I am sorry for using an issue for this. I am happy to move this discussion elsewhere if helpful.

My question is: how would you prefer your test files to be attributed if I use them in Mac::PropertyList::SAX?

I would like to use kulp/Mac-PropertyList-SAX#4 to incorporate your improved tests, verbatim wherever possible, particularly covering functionality that was added to Mac::PropertyList since my implementation of Mac::PropertyList::SAX. As you may know, I have been using modified versions of them for years, with unfortunately-worded "Stolen from ..." comments, and I would like to do better.

I was thinking of including a README.md file in the t/ directory to point at your repository. Can you suggest better content for that file, or a different idea?

Since both your project and mine are licensed under the same terms as Perl (although mine only says so in POD, so far), I think this is a question more of good practice than of licensing per se, but please let me know your thoughts.

Thank you.

Does not read binary true/false values correctly

When a binary plist with <true/> / <false/> values is read, it makes an unblessed array which causes the writer to croak.