|
jens@6
|
1 |
//
|
|
jens@6
|
2 |
// MYOttoman.h
|
|
jens@6
|
3 |
// Ottoman
|
|
jens@6
|
4 |
//
|
|
jens@6
|
5 |
// Created by Jens Alfke on 9/21/09.
|
|
jens@6
|
6 |
// Copyright 2009 Jens Alfke. All rights reserved.
|
|
jens@6
|
7 |
//
|
|
jens@6
|
8 |
|
|
jens@6
|
9 |
#import <Foundation/Foundation.h>
|
|
jens@6
|
10 |
|
|
jens@6
|
11 |
@class MYVersionDictionary, MYCurrentVersionDictionary;
|
|
jens@6
|
12 |
|
|
jens@6
|
13 |
|
|
jens@6
|
14 |
/** A version-controlled persistent dictionary.
|
|
jens@6
|
15 |
Each version is stored as a MYVersionDictionary,
|
|
jens@6
|
16 |
unsaved changes as an MYCurrentVersionDictionary. */
|
|
jens@6
|
17 |
@interface MYOttoman : NSObject
|
|
jens@6
|
18 |
{
|
|
jens@6
|
19 |
void *_ottoman;
|
|
jens@6
|
20 |
MYVersionDictionary *_lastVersion;
|
|
jens@6
|
21 |
MYCurrentVersionDictionary *_currentVersion;
|
|
jens@6
|
22 |
}
|
|
jens@6
|
23 |
|
|
jens@6
|
24 |
/** Creates an "untitled" Ottoman with no file and no lastVersion.
|
|
jens@6
|
25 |
After adding values to the currentVersion, use saveAs to save it. */
|
|
jens@6
|
26 |
- (id) init;
|
|
jens@6
|
27 |
|
|
jens@6
|
28 |
/** Opens an existing Ottoman file. */
|
|
jens@6
|
29 |
- (id) initWithURL: (NSURL*)fileURL writeable: (BOOL)writeable error: (NSError**)outError;
|
|
jens@6
|
30 |
|
|
jens@6
|
31 |
/** Closes an Ottoman. */
|
|
jens@6
|
32 |
- (void) close;
|
|
jens@6
|
33 |
|
|
jens@6
|
34 |
/** The current file, or nil if the receiver is still in the "untitled" state. */
|
|
jens@6
|
35 |
@property (readonly) NSURL *URL;
|
|
jens@6
|
36 |
|
|
jens@6
|
37 |
/** The latest saved version of the dictionary.
|
|
jens@6
|
38 |
Earlier versions can be accessed through its previousVersion property.
|
|
jens@6
|
39 |
This will be nil if the receiver is still in the "untitled" state. */
|
|
jens@6
|
40 |
@property (readonly) MYVersionDictionary* lastVersion;
|
|
jens@6
|
41 |
|
|
jens@6
|
42 |
/** A mutable overlay representing the current state of the dictionary.
|
|
jens@6
|
43 |
Changes are made in memory until -save is called.
|
|
jens@6
|
44 |
This will be nil if the receiver was opened read-only (writeable=NO). */
|
|
jens@6
|
45 |
@property (readonly) MYCurrentVersionDictionary* currentVersion;
|
|
jens@6
|
46 |
|
|
jens@6
|
47 |
/** Has the on-disk file been updated with newer revisions than what I know about? */
|
|
jens@6
|
48 |
@property (readonly) BOOL needsSync;
|
|
jens@6
|
49 |
|
|
jens@6
|
50 |
/** Reads any newer versions from disk.
|
|
jens@6
|
51 |
Returns YES if new versions were read, NO if there were none or on error.
|
|
jens@6
|
52 |
Afterwards, -lastVersion will return the latest version in the file.
|
|
jens@6
|
53 |
(The old lastVersion dictionary is still around, so you can save a pointer to it
|
|
jens@6
|
54 |
before the call and use it later to see what changed.)
|
|
jens@6
|
55 |
Changes made to the -currentVersion dictionary are not lost, but are now relative
|
|
jens@6
|
56 |
to the new lastVersion. You may want to scan them and resolve conflicts. */
|
|
jens@6
|
57 |
- (BOOL) sync: (NSError**)outError;
|
|
jens@6
|
58 |
|
|
jens@6
|
59 |
/** Saves the current version to the file, by appending.
|
|
jens@6
|
60 |
Returns NO if there is a version conflict; in that case you need to call -sync,
|
|
jens@6
|
61 |
possibly resolve conflicts, and then call -save again. */
|
|
jens@6
|
62 |
- (BOOL) save: (NSError**)outError;
|
|
jens@6
|
63 |
|
|
jens@6
|
64 |
/** Saves the current version to the file, by writing to a new temporary file and
|
|
jens@6
|
65 |
then atomically replacing the original.
|
|
jens@6
|
66 |
Older versions, and older copies of the data, are not preserved, so this
|
|
jens@6
|
67 |
will typically shrink the file quite a bit.
|
|
jens@6
|
68 |
Returns NO if there is a version conflict. */
|
|
jens@6
|
69 |
- (BOOL) saveAndCompact: (NSError**)outError;
|
|
jens@6
|
70 |
|
|
jens@6
|
71 |
/** Saves the current version to a new file, leaving the new file open,
|
|
jens@6
|
72 |
so subsequent saves will be written to it. */
|
|
jens@6
|
73 |
- (BOOL) saveAs: (NSURL*)newFileURL
|
|
jens@6
|
74 |
overwriteAllowed: (BOOL)overwriteAllowed
|
|
jens@6
|
75 |
error: (NSError**)outError;
|
|
jens@6
|
76 |
|
|
jens@6
|
77 |
/** Scans the file for damage. Returns YES if the file is OK, NO if problems are found.
|
|
jens@6
|
78 |
If the 'repair' flag is set, will truncate the file to the last valid version. */
|
|
jens@6
|
79 |
- (BOOL) scavengeAndRepair: (BOOL)repair error: (NSError**)outError;
|
|
jens@6
|
80 |
|
|
jens@6
|
81 |
@end
|