1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/bindings/Cocoa/MYOttoman.h	Thu Sep 24 21:47:06 2009 -0700
     1.3 @@ -0,0 +1,81 @@
     1.4 +//
     1.5 +//  MYOttoman.h
     1.6 +//  Ottoman
     1.7 +//
     1.8 +//  Created by Jens Alfke on 9/21/09.
     1.9 +//  Copyright 2009 Jens Alfke. All rights reserved.
    1.10 +//
    1.11 +
    1.12 +#import <Foundation/Foundation.h>
    1.13 +
    1.14 +@class MYVersionDictionary, MYCurrentVersionDictionary;
    1.15 +
    1.16 +
    1.17 +/** A version-controlled persistent dictionary. 
    1.18 +    Each version is stored as a MYVersionDictionary, 
    1.19 +    unsaved changes as an MYCurrentVersionDictionary. */
    1.20 +@interface MYOttoman : NSObject 
    1.21 +{
    1.22 +    void *_ottoman;
    1.23 +    MYVersionDictionary *_lastVersion;
    1.24 +    MYCurrentVersionDictionary *_currentVersion;
    1.25 +}
    1.26 +
    1.27 +/** Creates an "untitled" Ottoman with no file and no lastVersion.
    1.28 +    After adding values to the currentVersion, use saveAs to save it. */
    1.29 +- (id) init;
    1.30 +
    1.31 +/** Opens an existing Ottoman file. */
    1.32 +- (id) initWithURL: (NSURL*)fileURL writeable: (BOOL)writeable error: (NSError**)outError;
    1.33 +
    1.34 +/** Closes an Ottoman. */
    1.35 +- (void) close;
    1.36 +
    1.37 +/** The current file, or nil if the receiver is still in the "untitled" state. */
    1.38 +@property (readonly) NSURL *URL;
    1.39 +
    1.40 +/** The latest saved version of the dictionary. 
    1.41 +    Earlier versions can be accessed through its previousVersion property.
    1.42 +    This will be nil if the receiver is still in the "untitled" state. */
    1.43 +@property (readonly) MYVersionDictionary* lastVersion;
    1.44 +
    1.45 +/** A mutable overlay representing the current state of the dictionary.
    1.46 +    Changes are made in memory until -save is called.
    1.47 +    This will be nil if the receiver was opened read-only (writeable=NO). */
    1.48 +@property (readonly) MYCurrentVersionDictionary* currentVersion;
    1.49 +
    1.50 +/** Has the on-disk file been updated with newer revisions than what I know about? */
    1.51 +@property (readonly) BOOL needsSync;
    1.52 +
    1.53 +/** Reads any newer versions from disk.
    1.54 +    Returns YES if new versions were read, NO if there were none or on error.
    1.55 +    Afterwards, -lastVersion will return the latest version in the file. 
    1.56 +    (The old lastVersion dictionary is still around, so you can save a pointer to it 
    1.57 +    before the call and use it later to see what changed.)
    1.58 +    Changes made to the -currentVersion dictionary are not lost, but are now relative
    1.59 +    to the new lastVersion. You may want to scan them and resolve conflicts. */
    1.60 +- (BOOL) sync: (NSError**)outError;
    1.61 +
    1.62 +/** Saves the current version to the file, by appending.
    1.63 +    Returns NO if there is a version conflict; in that case you need to call -sync,
    1.64 +    possibly resolve conflicts, and then call -save again. */
    1.65 +- (BOOL) save: (NSError**)outError;
    1.66 +
    1.67 +/** Saves the current version to the file, by writing to a new temporary file and
    1.68 +    then atomically replacing the original. 
    1.69 +    Older versions, and older copies of the data, are not preserved, so this
    1.70 +    will typically shrink the file quite a bit.
    1.71 +    Returns NO if there is a version conflict. */
    1.72 +- (BOOL) saveAndCompact: (NSError**)outError;
    1.73 +
    1.74 +/** Saves the current version to a new file, leaving the new file open, 
    1.75 +    so subsequent saves will be written to it. */
    1.76 +- (BOOL) saveAs: (NSURL*)newFileURL
    1.77 +         overwriteAllowed: (BOOL)overwriteAllowed
    1.78 +         error: (NSError**)outError;
    1.79 +
    1.80 +/** Scans the file for damage. Returns YES if the file is OK, NO if problems are found.
    1.81 +    If the 'repair' flag is set, will truncate the file to the last valid version. */
    1.82 +- (BOOL) scavengeAndRepair: (BOOL)repair error: (NSError**)outError;
    1.83 +
    1.84 +@end