NAME

Mac::Finder::DSStore - Read and write Macintosh Finder DS_Store files

DESCRIPTION

Mac::Finder::DSStore provides a handful of functions for reading and writing the desktop database files created by the Macintosh Finder.

FUNCTIONS

Many functions take a $store argument which is the opened file as an instance of Mac::Finder::DSStore::BuddyAllocator, or a $block argument which is a specific block of the file as an instance of Mac::Finder::DSStore::BuddyAllocator::Block.

@records = &Mac::Finder::DSStore::getDSDBEntries($store[, $callback])

Retrieves the "superblock" pointed to by the DSDB entry in the store's table of contents, and traverses the B-tree it points to, returning a list of the records in the tree. Alternately, you can supply a callback which will be invoked for each record, and getDSDBEntries will return an empty list.

&Mac::Finder::DSStore::putDSDBEntries($store, $arrayref)

$arrayref must contain a correctly ordered list of Mac::Finder::DSStore::Entry objects. They will be evenly organized into a B-tree structure and written to the $store. If there is an existing tree of records in the file already, it will be deallocated.

This function does not flush the allocator's information back to the file.

&Mac::Finder::DSStore::writeDSDBEntries($file, @entries)

A convenience function which sorts a list of entries and writes them to the specified file using putDSDBEntries, then flushes the allocator's data structures to disk. $file may be a filename or an open file handle. The store object is returned, but you don't need to do anything else with it.

&Mac::Finder::DSStore::makeEntries($filename, [ what => value ... ])

makeEntries encapsulates some information about the format of individual records in the DS_Store file. It returns a list of records constructed with the given filename and with the information specified in the rest of its args. Most args come in pairs, a name and a value, so makeEntries kind of looks like it takes a hash. Some names take no value and some could take several. Some produce more than one record as a result.

See the output of the examples/dsstore_dump.pl script for an example of how to use this, and check the source code for a list of the formats it accepts.

This function might change in the future.

Mac::Finder::DSStore::Entry

This class holds the individual records from the database. Each record contains a filename (in some cases, "." to refer to the containing directory), a 4-character record type, and a value. The value is one of a few concrete types, according to the record type.

$entry = ...::Entry->new($filename, $typecode)

Creates a new entry with no value. The concrete type is inferred from the record type code.

$entry->filename

Gets the filename of an entry.

$entry->strucId

Gets the record type of this entry, as a four-character string, indicating what aspect of the file the entry describes.

$entry->value([$value])

Gets or sets the value of an entry.

If the concrete type is blob or type, the value is interpreted as a byte string; if it is ustr, as a character string. If the concrete type is long, shor, comp, dutc, or bool, then the value should be an integer.

$entry->cmp($other)

Returns -1, 0, or 1 depending on the relative ordering of the two entries, according to (a guess at) the record ordering used by the store's B-tree.

SEE ALSO

See Mac::Finder::DSStore::Format for more detailed information on the record types found in a DS_Store file.

See Mac::Finder::DSStore::BuddyAllocator for the low-level organization of the DS_Store file.

AUTHOR

Copyright 2008 by Wim Lewis <wiml@hhhh.org>.

Some information is from Mark Mentovai via the Mozilla project. Thanks also to Martin Baker for bug reports.

cpanm Mac::Finder::DSStore

perl -MCPAN -e shell
install Mac::Finder::DSStore