1#lang scribble/manual
2@(require (for-label ds-store
3                     ds-store/alias
4                     racket/base
5                     racket/contract/base))
6
7@title{Reading Writing @filepath{.DS_Store} Files}
8
9A @filepath{.DS_Store} file is a metadata file on Mac OS X that holds
10information about folder and icons as viewed and manipulated in
11Finder. One common reason to manipulate @filepath{.DS_Store} files
12is to create a nice-looking disk image for a Mac OS X installer.
13
14@filepath{.DS_Store} reading and writing is based on a
15reverse-engineered description of the file format @cite["DS_Store"].
16
17@section[#:tag "ds-store-api"]{@filepath{.DS_Store} Files and Entries}
18
19@defmodule[ds-store]
20
21@defproc[(read-ds-store [path path-string?]
22                        [#:verbose verbose? any/c #f])
23         (listof ds?)]{
24
25Reads the @filepath{.DS_Store} file at @racket[path] returning a list
26of store items.}
27
28@defproc[(write-ds-store [path path-string?]
29                         [dses (listof ds?)])
30         void?]{
31
32Writes @racket[dses] to the @filepath{.DS_Store} file at
33@racket[path], replacing the file's current content.}
34
35@defstruct*[ds ([path (or/c path-element? 'same)]
36                [id symbol?]
37                [type (or/c 'long 'shor 'bool 'type 'ustr 'blob)]
38                [data (or/c exact-integer? boolean? symbol? string?
39                            bytes? iloc? fwind?)])
40            #:transparent]{
41
42Represents a entry in a @filepath{.DS_Store} file. A
43@filepath{.DS_Store} file typically has multiple entries for a single
44file or directory in the same directory as the @filepath{.DS_Store}.
45
46The @racket[path] should be @racket['same] only for a volume root
47directory; information about a directory is otherwise recorded in its
48parent directory's @filepath{.DS_Store} file.
49
50The @racket[id] symbols should each have four ASCII characters. See
51the @filepath{.DS_Store} format description @cite["DS_Store"] for more
52information @racket[id] and @racket[type] values.
53
54The @racket[data] field long should be an exact integer for
55@racket['long] and @racket['shor] types, a boolean for the
56@racket['bool] type, a 4-character ASCII symbol for the @racket['type]
57type, a string for the @racket['ustr] type, and either a byte string,
58@racket[iloc], or @racket[fwind] for the @racket['blob] type.}
59
60@defstruct*[iloc ([x exact-integer?] [y exact-integer?]) #:transparent]{
61
62Represents an icon location for an @racket['Iloc] entry.}
63
64@defstruct*[fwind ([t exact-integer?]
65                   [l exact-integer?]
66                   [b exact-integer?]
67                   [r exact-integer?]
68                   [mode symbol?]
69                   [sideview? any/c])
70            #:transparent]{
71
72Represent a window location for a @racket['fwi0] entry. The
73@racket[mode] field should have four ASCII characters, and recognized
74@racket[mode]s include @racket['icnv], @racket['clmv], and
75@racket['Nlsv].}
76
77@; ----------------------------------------
78
79@section[#:tag "aliases"]{Finder Aliases}
80
81A @racket['pict] entry in a @filepath{.DS_Store} file references a
82file through a Finder alias.
83
84@defmodule[ds-store/alias]
85
86@defproc[(path->alias-bytes [path path-string?]
87                            [#:wrt wrt-dir (or/c #f path-string?) #f])
88         (or/c bytes? #f)]{
89
90Constructs a byte string to represent a Finder alias but using the
91@filepath{CoreFoundation} library on Mac OS X.}
92
93@; ----------------------------------------
94
95@bibliography[(bib-entry #:key "DS_Store"
96                         #:title "DS_Store Format"
97                         #:author "Wim Lewis and Mark Mentovai"
98                         #:url "http://search.cpan.org/~wiml/Mac-Finder-DSStore/DSStoreFormat.pod")]
99