jens@6: //
jens@6: //  MYOttoman.h
jens@6: //  Ottoman
jens@6: //
jens@6: //  Created by Jens Alfke on 9/21/09.
jens@6: //  Copyright 2009 Jens Alfke. All rights reserved.
jens@6: //
jens@6: 
jens@6: #import <Foundation/Foundation.h>
jens@6: 
jens@6: @class MYVersionDictionary, MYCurrentVersionDictionary;
jens@6: 
jens@6: 
jens@6: /** A version-controlled persistent dictionary. 
jens@6:     Each version is stored as a MYVersionDictionary, 
jens@6:     unsaved changes as an MYCurrentVersionDictionary. */
jens@6: @interface MYOttoman : NSObject 
jens@6: {
jens@6:     void *_ottoman;
jens@6:     MYVersionDictionary *_lastVersion;
jens@6:     MYCurrentVersionDictionary *_currentVersion;
jens@6: }
jens@6: 
jens@6: /** Creates an "untitled" Ottoman with no file and no lastVersion.
jens@6:     After adding values to the currentVersion, use saveAs to save it. */
jens@6: - (id) init;
jens@6: 
jens@6: /** Opens an existing Ottoman file. */
jens@6: - (id) initWithURL: (NSURL*)fileURL writeable: (BOOL)writeable error: (NSError**)outError;
jens@6: 
jens@6: /** Closes an Ottoman. */
jens@6: - (void) close;
jens@6: 
jens@6: /** The current file, or nil if the receiver is still in the "untitled" state. */
jens@6: @property (readonly) NSURL *URL;
jens@6: 
jens@6: /** The latest saved version of the dictionary. 
jens@6:     Earlier versions can be accessed through its previousVersion property.
jens@6:     This will be nil if the receiver is still in the "untitled" state. */
jens@6: @property (readonly) MYVersionDictionary* lastVersion;
jens@6: 
jens@6: /** A mutable overlay representing the current state of the dictionary.
jens@6:     Changes are made in memory until -save is called.
jens@6:     This will be nil if the receiver was opened read-only (writeable=NO). */
jens@6: @property (readonly) MYCurrentVersionDictionary* currentVersion;
jens@6: 
jens@6: /** Has the on-disk file been updated with newer revisions than what I know about? */
jens@6: @property (readonly) BOOL needsSync;
jens@6: 
jens@6: /** Reads any newer versions from disk.
jens@6:     Returns YES if new versions were read, NO if there were none or on error.
jens@6:     Afterwards, -lastVersion will return the latest version in the file. 
jens@6:     (The old lastVersion dictionary is still around, so you can save a pointer to it 
jens@6:     before the call and use it later to see what changed.)
jens@6:     Changes made to the -currentVersion dictionary are not lost, but are now relative
jens@6:     to the new lastVersion. You may want to scan them and resolve conflicts. */
jens@6: - (BOOL) sync: (NSError**)outError;
jens@6: 
jens@6: /** Saves the current version to the file, by appending.
jens@6:     Returns NO if there is a version conflict; in that case you need to call -sync,
jens@6:     possibly resolve conflicts, and then call -save again. */
jens@6: - (BOOL) save: (NSError**)outError;
jens@6: 
jens@6: /** Saves the current version to the file, by writing to a new temporary file and
jens@6:     then atomically replacing the original. 
jens@6:     Older versions, and older copies of the data, are not preserved, so this
jens@6:     will typically shrink the file quite a bit.
jens@6:     Returns NO if there is a version conflict. */
jens@6: - (BOOL) saveAndCompact: (NSError**)outError;
jens@6: 
jens@6: /** Saves the current version to a new file, leaving the new file open, 
jens@6:     so subsequent saves will be written to it. */
jens@6: - (BOOL) saveAs: (NSURL*)newFileURL
jens@6:          overwriteAllowed: (BOOL)overwriteAllowed
jens@6:          error: (NSError**)outError;
jens@6: 
jens@6: /** Scans the file for damage. Returns YES if the file is OK, NO if problems are found.
jens@6:     If the 'repair' flag is set, will truncate the file to the last valid version. */
jens@6: - (BOOL) scavengeAndRepair: (BOOL)repair error: (NSError**)outError;
jens@6: 
jens@6: @end