nano-store 0.2.4 → 0.3.0

data/.gitignore

@@ -1,3 +1,4 @@
 vendor/*/build-*
+pkg/*
 .repl_history
 build

data/.gitmodules

@@ -1,3 +0,0 @@
-[submodule "vendor/BubbleWrap"]
-	path = vendor/BubbleWrap
-	url = https://github.com/mattetti/BubbleWrap.git

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in gemspec
-gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,24 @@
+PATH
+  remote: .
+  specs:
+    nano-store (0.3.0)
+      bubble-wrap (>= 0.1.1)
+      motion-cocoapods (>= 1.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    bubble-wrap (0.1.1)
+    cocoapods (0.5.1)
+      xcodeproj (~> 0.1.0)
+    motion-cocoapods (1.0.1)
+      cocoapods (>= 0.5.1)
+    motion-redgreen (0.0.2)
+    xcodeproj (0.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  motion-redgreen
+  nano-store!

data/README.md

@@ -89,6 +89,11 @@ User.all # => [<User#1>, <User#2>]
 
 # find model by criteria
 users = User.find(:name, NSFEqualTo, "Bob")
+
+# or use hash
+users = User.find(:name => "Bob")
+users = User.find(:name => { NSFEqualTo => "Ronald" })
+users = User.find(:name => { NSFEqualTo => "Ronald" }, :age => { NSFGreaterThan => 50 })
 ````
 
 ### Update

data/Rakefile

@@ -1 +1,21 @@
-require "bundler/gem_tasks"
+$:.unshift("/Library/RubyMotion/lib")
+require 'motion/project'
+require 'motion-cocoapods'
+require 'bubble-wrap'
+require 'motion-redgreen'
+
+Motion::Project::App.setup do |app|
+  app.name = 'NanoStoreDemo'
+
+  app.files += Dir.glob(File.join(app.project_dir, 'lib/nano_store/*.rb'))
+  app.pods do
+    dependency 'NanoStore'
+  end
+end
+
+desc "Build the gem"
+task :gem do
+  sh "bundle exec gem build nano-store.gemspec"
+  sh "mkdir -p pkg"
+  sh "mv *.gem pkg/"
+end

data/lib/nano_store.rb

@@ -4,6 +4,8 @@ unless defined?(Motion::Project::Config)
   raise "This file must be required within a RubyMotion project Rakefile."
 end
 
+require 'bubble-wrap'
+
 Motion::Project::App.setup do |app|
   Dir.glob(File.join(File.dirname(__FILE__), 'nano_store/*.rb')).each do |file|
     app.files.unshift(file)

data/lib/nano_store/finder.rb

@@ -0,0 +1,76 @@
+module NanoStore
+  module FinderMethods    
+    # find model by criteria
+    #
+    # Return array of models
+    #
+    # Examples:
+    #   User.find(:name, NSFEqualTo, "Bob") # => [<User#1>]
+    #   User.find(:name => "Bob") # => [<User#1>]
+    #   User.find(:name => {NSFEqualTo => "Bob"}) # => [<User#1>]
+    #
+    def find(*arg)
+      if arg[0].is_a?(Hash)
+        # hash style
+        options = arg[0]
+      elsif arg[0] && arg[1] && arg[2]
+        # standard way to find
+        options = {arg[0] => {arg[1] => arg[2]}}
+      end
+      search = NSFNanoSearch.searchWithStore(self.store)
+      expressions = expressions_with_options(options)
+      search.setExpressions(expressions)
+      error_ptr = Pointer.new(:id)
+      searchResults = search.searchObjectsWithReturnType(NSFReturnObjects, error:error_ptr)
+      raise NanoStoreError, error_ptr[0].description if error_ptr[0]
+      searchResults.values
+    end
+    
+    # find model keys by criteria
+    #
+    # Return array of keys
+    #
+    # Examples:
+    #   User.find(:name, NSFEqualTo, "Bob") # => [<User#1>]
+    #   User.find(:name => "Bob") # => [<User#1>]
+    #   User.find(:name => {NSFEqualTo => "Bob"}) # => [<User#1>]
+    #
+    def find_keys(*arg)
+      if arg[0].is_a?(Hash)
+        # hash style
+        options = arg[0]
+      elsif arg[0] && arg[1] && arg[2]
+        # standard way to find
+        options = {arg[0] => {arg[1] => arg[2]}}
+      end
+      search = NSFNanoSearch.searchWithStore(self.store)
+      expressions = expressions_with_options(options)
+      search.setExpressions(expressions)
+      error_ptr = Pointer.new(:id)
+      searchResults = search.searchObjectsWithReturnType(NSFReturnKeys, error:error_ptr)
+      raise NanoStoreError, error_ptr[0].description if error_ptr[0]
+      searchResults
+    end
+    
+    protected
+    def expressions_with_options(options)
+      expressions = []
+      options.each do |key, val|
+        attribute = NSFNanoPredicate.predicateWithColumn(NSFAttributeColumn, matching:NSFEqualTo, value:key.to_s)
+        expression = NSFNanoExpression.expressionWithPredicate(attribute)
+
+        if val.is_a?(Hash)
+          val.each do |operator, sub_val|
+            value = NSFNanoPredicate.predicateWithColumn(NSFValueColumn, matching:operator, value:sub_val)
+            expression.addPredicate(value, withOperator:NSFAnd)
+          end
+        else
+          value = NSFNanoPredicate.predicateWithColumn(NSFValueColumn, matching:NSFEqualTo, value:val)
+          expression.addPredicate(value, withOperator:NSFAnd)
+        end
+        expressions << expression
+      end
+      return expressions
+    end
+  end # module FinderMethods
+end # module NanoStore

data/lib/nano_store/model.rb

@@ -87,38 +87,6 @@ module NanoStore
       raise NanoStoreError, error_ptr[0].description if error_ptr[0]
       searchResults.values
     end
-    
-    # find model by criteria
-    #
-    # Return array of models
-    #
-    # Example:
-    #
-    #   User.find(:name, NSFEqualTo, "Bob") => [<User#1>]
-    #
-    def find(attribute, match, value)
-      search = search_with_store(self.store, attribute, match, value)
-      error_ptr = Pointer.new(:id)
-      searchResults = search.searchObjectsWithReturnType(NSFReturnObjects, error:error_ptr)
-      raise NanoStoreError, error_ptr[0].description if error_ptr[0]
-      searchResults.values
-    end
-    
-    # find model keys by criteria
-    #
-    # Return array of model keys
-    #
-    # Example:
-    #
-    #   User.find(:name, NSFEqualTo, "Bob") => [<User#1>]
-    #
-    def find_keys(attribute, match, value)
-      search = search_with_store(self.store, attribute, match, value)
-      error_ptr = Pointer.new(:id)
-      searchResults = search.searchObjectsWithReturnType(NSFReturnKeys, error:error_ptr)
-      raise NanoStoreError, error_ptr[0].description if error_ptr[0]
-      searchResults
-    end
 
     def inherited(subclass)
       subclass.instance_variable_set(:@attributes, [])
@@ -138,5 +106,6 @@ module NanoStore
   class Model < NSFNanoObject
     include ModelInstanceMethods
     extend ModelClassMethods
+    extend ::NanoStore::FinderMethods
   end
 end

data/lib/nano_store/version.rb

@@ -1,3 +1,3 @@
 module NanoStore
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
 end

data/nano-store.gemspec

@@ -16,4 +16,5 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency 'bubble-wrap', '>= 0.1.1'
   gem.add_dependency 'motion-cocoapods', '>= 1.0.1'
+  gem.add_development_dependency 'motion-redgreen'
 end

data/spec/finder_spec.rb

@@ -0,0 +1,67 @@
+describe "Finder" do
+  def stub_user(name, age, created_at)
+    user = User.new
+    user.name = name
+    user.age  = age
+    user.created_at = created_at
+    user
+  end
+
+  after do
+    NanoStore.shared_store = nil
+  end
+  
+  before do
+    NanoStore.shared_store = NanoStore.store
+
+    user = stub_user("Bob", 10, Time.now)
+    user.save
+      
+    user2 = stub_user("Amy", 11, Time.now)
+    user2.save
+    
+    user3 = stub_user("Carl", 4, Time.now)
+    user3.save
+  end
+  
+  it "search object traditional way: supply key, operator and value" do
+    users = User.find(:name, NSFEqualTo, "Bob")
+    users.should.not.be.nil
+    user = users.first
+    user.should.not.be.nil
+    user.name.should.be == "Bob"
+    user.age.should.be == 10
+  end
+
+  it "search object with simple hash" do
+    user = User.find(:name => "Carl").first
+    user.name.should.be == "Carl"
+    user.age.should.be == 4
+  end
+
+  it "search object with multiple parameters" do
+    stub_user("Ronald", 18, Time.now).save
+    stub_user("Ronald", 29, Time.now).save
+    stub_user("Ronald", 36, Time.now).save
+    stub_user("Ronald", 39, Time.now).save
+    stub_user("Ronald", 49, Time.now).save
+    stub_user("Ronald", 59, Time.now).save
+
+    users = User.find(:name => { NSFEqualTo => "Ronald" }, :age => { NSFGreaterThan => 50 })
+    users.size.should == 1
+    user = users.first
+    user.name.should.be == "Ronald"
+    user.age.should.be == 59
+    
+    users = User.find(:name => { NSFEqualTo => "Ronald" }, :age => { NSFLessThan => 30 })
+    users.size.should == 2    
+    user = users.first
+    user.name.should.be == "Ronald"
+  end
+
+  it "find object" do
+    user = User.find(:name, NSFEqualTo, "Bob").first
+    user.name.should == "Bob"
+  end
+  
+end

data/spec/model_spec.rb

@@ -67,21 +67,6 @@ describe NanoStore::Model do
     user2.key.should == user.key
   end
   
-  it "find object" do
-    user = stub_user("Bob", 10, Time.now)
-    user.save
-    
-    users = User.find(:name, NSFEqualTo, "Bob")
-    users.should.not.be.nil
-    users.count.should == 1
-    users.first.name.should == user.name
-    
-    users = User.find_keys(:name, NSFEqualTo, "Bob")
-    users.should.not.be.nil
-    users.count.should == 1
-    users.first.should == user.key
-  end
-  
   it "delete object" do
     user = stub_user("Bob", 10, Time.now)
     user.save
@@ -112,19 +97,4 @@ describe NanoStore::Model do
     users.collect(&:key).include?(user2.key)
   end
 
-  it "search object" do
-    user = stub_user("Bob", 10, Time.now)
-    user.save
-    
-    user2 = stub_user("Amy", 11, Time.now)
-    user2.save
-
-    User.count.should == 2
-    users = User.find(:name, NSFEqualTo, "Bob")
-    users.should.not.be.nil
-    user = users.first
-    user.should.not.be.nil
-    user.name.should.be == "Bob"
-    user.age.should.be == 10
-  end
 end

data/vendor/Podfile.lock

@@ -0,0 +1,5 @@
+PODS:
+  - NanoStore (2.0.1)
+
+DEPENDENCIES:
+  - NanoStore

data/vendor/Pods/Headers/NanoStore/NSFNanoBag.h

@@ -0,0 +1,306 @@
+/*
+     NSFNanoBag.h
+     NanoStore
+     
+     Copyright (c) 2010 Webbo, L.L.C. All rights reserved.
+     
+     Redistribution and use in source and binary forms, with or without modification, are permitted
+     provided that the following conditions are met:
+     
+     * Redistributions of source code must retain the above copyright notice, this list of conditions
+     and the following disclaimer.
+     * Redistributions in binary form must reproduce the above copyright notice, this list of conditions
+     and the following disclaimer in the documentation and/or other materials provided with the distribution.
+     * Neither the name of Webbo nor the names of its contributors may be used to endorse or promote
+     products derived from this software without specific prior written permission.
+     
+     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
+     WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+     PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY
+     DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+     PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+     OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+     SUCH DAMAGE.
+ */
+
+/*! @file NSFNanoBag.h
+ @brief A bag is a loose collection of objects stored in a document store.
+ */
+
+/** @class NSFNanoBag
+ * A bag is a loose collection of objects stored in a document store.
+ *
+ * @note
+ * The objects must conform to the \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink. For your convenience, NanoStore provides you with NSFNanoObject, which is the standard
+ * way of storing and retrieving objects from/to a bag.
+ *
+ * @par
+ * It's more efficient to make your storage objects \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant, thus eliminating the need to convert your objects to/from
+ * objects of type NSFNanoObject.
+ *
+ * @details <b>Example:</b>
+ @code
+ // Instantiate a NanoStore and open it
+ NSFNanoStore *nanoStore = [NSFNanoStore createAndOpenStoreWithType:NSFMemoryStoreType path:nil error:nil];
+ [nanoStore removeAllObjectsFromStoreAndReturnError:nil];
+ 
+ // Add some data to a bag
+ NSFNanoBag *bag = [NSFNanoBag bag];
+ NSDictionary *info = ...;
+ NSFNanoObject *obj1 = [NSFNanoObject nanoObjectWithDictionary:info];
+ NSFNanoObject *obj2 = [NSFNanoObject nanoObjectWithDictionary:info];
+ NSFNanoObject *obj3 = [NSFNanoObject nanoObjectWithDictionary:info];
+ [bag addObjectsFromArray:[NSArray arrayWithObjects:obj1, obj2, obj3, nil] error:nil];
+ 
+ // Add the bag and its objects to the document store
+ [nanoStore addObject:bag error:nil];
+ 
+ // Obtain the bags from the document store
+ NSArray *bags = [nanoStore bags];
+ 
+ // Close the document store
+ [nanoStore closeWithError:nil];
+ @endcode
+*/
+
+#import "NSFNanoObjectProtocol.h"
+
+@interface NSFNanoBag : NSObject <NSFNanoObjectProtocol, NSCopying>
+
+/** * The store where the bag is located.  */
+@property (nonatomic, weak, readonly) NSFNanoStore *store;
+/** * The name of the bag.  */
+@property (nonatomic, copy, readwrite) NSString *name;
+/** * The UUID of the bag.  */
+@property (nonatomic, copy, readonly) NSString *key;
+/** * Dictionary of NSString (key) and id<NSFNanoObjectProtocol> (value). */
+@property (nonatomic, readonly) NSDictionary *savedObjects;
+/** * Dictionary of NSString (key) and id<NSFNanoObjectProtocol> (value). */
+@property (nonatomic, readonly) NSDictionary *unsavedObjects;
+/** * Dictionary of NSString (key) and id<NSFNanoObjectProtocol> (value). */
+@property (nonatomic, readonly) NSDictionary *removedObjects;
+/** * To determine whether the bag has uncommited changes.  */
+@property (nonatomic, assign, readonly) BOOL hasUnsavedChanges;
+
+/** @name Creating and Initializing Bags
+ */
+
+//@{
+
+/** * Creates and returns an empty bag.
+ * @return An empty bag upon success, nil otherwise.
+ */
+
++ (NSFNanoBag *)bag;
+
+/** * Creates and returns a bag adding to it the objects contained in the given array.
+ * @param theObjects an array of objects conforming to the \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink.
+ * @return A bag only containing the objects with conform to the \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink upon success, nil otherwise.
+ * @see \link initBagWithNanoObjects: - (NSFNanoBag*)initBagWithNanoObjects:(NSArray *)theObjects \endlink
+ */
+
++ (NSFNanoBag *)bagWithObjects:(NSArray *)theObjects;
+
+/** * Creates and returns an empty bag with the specified name
+ * @param theName the name of the bag. Can be nil.
+ * @return An empty bag upon success, nil otherwise.
+ */
+
++ bagWithName:(NSString *)theName;
+
+/** * Creates and returns a bag with the specified name adding to it the objects contained in the given array.
+ * @param theName the name of the bag. Can be nil.
+ * @param theObjects an array of objects conforming to the \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink.
+ * @return A bag only containing the objects with conform to the \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink upon success, nil otherwise.
+ * @see \link initBagWithNanoObjects: - (NSFNanoBag*)initBagWithNanoObjects:(NSArray *)theObjects \endlink
+ */
+
++ bagWithName:(NSString *)theName andObjects:(NSArray *)theObjects;
+
+/** * Initializes a newly allocated bag with the specified name adding to it the objects contained in the given array.
+ * @param theName the name of the bag. Can be nil.
+ * @param theObjects an array of objects conforming to the \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink.
+ * @return A bag only containing the objects with conform to the \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink upon success, nil otherwise.
+ * @see \link bagWithObjects: + (NSFNanoBag*)bagWithObjects:(NSArray *)theObjects \endlink
+ */
+
+- (id)initBagWithName:(NSString *)theName andObjects:(NSArray *)someObjects;
+
+//@}
+
+/** @name Adding and Removing Objects
+ */
+
+//@{
+
+/** * Adds an \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant object to the bag.
+ * @param theObject is added to the bag.
+ * @param outError is used if an error occurs. May be NULL.
+ * @return YES upon success, NO otherwise.
+ * @warning This value cannot be nil and it must be \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant.
+ * @throws NSFNonConformingNanoObjectProtocolException is thrown if the object is non-\link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink compliant.
+ * @see \link addObjectsFromArray:error: - (BOOL)addObjectsFromArray:(NSArray *)theObjects error:(out NSError **)outError \endlink
+ */
+
+- (BOOL)addObject:(id <NSFNanoObjectProtocol>)theObject error:(out NSError **)outError;
+
+/** * Adds a series of \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant objects to the bag.
+ * @param theObjects is an array of objects to be added to the bag. The objects must be \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant.
+ * @param outError is used if an error occurs. May be NULL.
+ * @return YES upon success, NO otherwise.
+ * @warning The objects of the array must be \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant.
+ * @throws NSFNonConformingNanoObjectProtocolException is thrown if the object is non-\link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink compliant.
+ * @see \link addObject:error: - (BOOL)addObject:(id <NSFNanoObjectProtocol>)theObject error:(out NSError **)outError \endlink
+ */
+
+- (BOOL)addObjectsFromArray:(NSArray *)theObjects error:(out NSError **)outError;
+
+/** * Removes the specified object from the bag.
+ * @param theObject the object to be removed from the bag.
+ * @warning The object must be \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant.
+ * @see \link removeObjectsInArray: - (void)removeObjectsInArray:(NSArray *)theObjects \endlink
+ * @see \link removeObjectWithKey: - (void)removeObjectWithKey:(NSString *)theObjectKey \endlink
+ * @see \link removeObjectsWithKeysInArray: - (void)removeObjectsWithKeysInArray:(NSArray *)theKeys \endlink
+ * @see \link removeAllObjects - (void)removeAllObjects \endlink
+ */
+
+- (void)removeObject:(id <NSFNanoObjectProtocol>)theObject;
+
+/** * Empties the bag of all its elements.
+ * @see \link removeObject: - (void)removeObject:(id <NSFNanoObjectProtocol>)theObject \endlink
+ * @see \link removeObjectsInArray: - (void)removeObjectsInArray:(NSArray *)theObjects \endlink
+ * @see \link removeObjectWithKey: - (void)removeObjectWithKey:(NSString *)theObjectKey \endlink
+ * @see \link removeObjectsWithKeysInArray: - (void)removeObjectsWithKeysInArray:(NSArray *)theKeys \endlink
+ */
+
+- (void)removeAllObjects;
+
+/** * Removes the list of objects from the bag.
+ * @param theObjects the list of objects to be removed from the bag.
+ * @warning The objects of the array must be \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant.
+ * @see \link removeObject: - (void)removeObject:(id <NSFNanoObjectProtocol>)theObject \endlink
+ * @see \link removeObjectWithKey: - (void)removeObjectWithKey:(NSString *)theObjectKey \endlink
+ * @see \link removeObjectsWithKeysInArray: - (void)removeObjectsWithKeysInArray:(NSArray *)theKeys \endlink
+ * @see \link removeAllObjects - (void)removeAllObjects \endlink
+ */
+
+- (void)removeObjectsInArray:(NSArray *)theObjects;
+
+/** * Removes the object with a given key from the bag.
+ * @param theObjectKey the key of the object to be removed from the bag.
+ * @warning The object referenced by theObjectKey must be \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant.
+ * @see \link removeObject: - (void)removeObject:(id <NSFNanoObjectProtocol>)theObject \endlink
+ * @see \link removeObjectsInArray: - (void)removeObjectsInArray:(NSArray *)theObjects \endlink
+ * @see \link removeObjectsWithKeysInArray: - (void)removeObjectsWithKeysInArray:(NSArray *)theKeys \endlink
+ * @see \link removeAllObjects - (void)removeAllObjects \endlink
+ */
+
+- (void)removeObjectWithKey:(NSString *)theObjectKey;
+
+/** * Removes from the bag the objects specified by elements in a given array.
+ * @param theKeys an array of objects specifying the keys to remove from the bag
+ * @warning The objects referenced by theKeys must be \link NSFNanoObjectProtocol::initNanoObjectFromDictionaryRepresentation:forKey:store: NSFNanoObjectProtocol\endlink-compliant.
+ * @see \link removeObject: - (void)removeObject:(id <NSFNanoObjectProtocol>)theObject \endlink
+ * @see \link removeObjectsInArray: - (void)removeObjectsInArray:(NSArray *)theObjects \endlink
+ * @see \link removeObjectWithKey: - (void)removeObjectWithKey:(NSString *)theObjectKey \endlink
+ * @see \link removeAllObjects - (void)removeAllObjects \endlink
+ */
+
+- (void)removeObjectsWithKeysInArray:(NSArray *)theKeys;
+
+//@}
+
+/** @name Saving, Reloading and Undoing
+ */
+
+//@{
+
+/** * Saves the bag and its contents. Also, saves all the changes made since the last save.
+ * @param outError is used if an error occurs. May be NULL.
+ * @return YES upon success, NO otherwise.
+ * @note Check property hasUnsavedChanges to find out whether the bag has unsaved contents.
+ * @see \link reloadBagWithError: - (BOOL)reloadBagWithError:(out NSError **)outError \endlink
+ * @see \link undoChangesWithError: - (BOOL)undoChangesWithError:(out NSError **)outError \endlink
+ */
+
+- (BOOL)saveAndReturnError:(out NSError **)outError;
+
+/** * Refreshes the bag to match the contents stored in the document store. The unsaved contents are preserved.
+ * @param outError is used if an error occurs. May be NULL.
+ * @return YES upon success, NO otherwise.
+ * @note Check properties savedObjects, unsavedObjects and removedObjects to find out the current state of the bag.
+ * @see \link saveAndReturnError: - (BOOL)saveAndReturnError:(out NSError **)outError \endlink
+ * @see \link undoChangesWithError: - (BOOL)undoChangesWithError:(out NSError **)outError \endlink
+ */
+
+- (BOOL)reloadBagWithError:(out NSError **)outError;
+
+/** * Discards the changes made in the bag.
+ * @param outError is used if an error occurs. May be NULL.
+ * @return YES upon success, NO otherwise.
+ * @note Check properties savedObjects, unsavedObjects and removedObjects to find out the current state of the bag.
+ * @see \link saveAndReturnError: - (BOOL)saveAndReturnError:(out NSError **)outError \endlink
+ * @see \link reloadBagWithError: - (BOOL)reloadBagWithError:(out NSError **)outError \endlink
+ */
+
+- (BOOL)undoChangesWithError:(out NSError **)outError;
+
+//@}
+
+/** @name Inflating and Deflating
+ */
+
+//@{
+
+/** * Inflates the bag by reconstructing the objects flattened with - (void)deflateBag;
+ * @note Check properties savedObjects, unsavedObjects and removedObjects to find out the current state of the bag.
+ * @see \link deflateBag - (void)deflateBag \endlink
+ */
+
+- (void)inflateBag;
+
+/** * Releases memory by "flattening" the objects from the bag.
+ * @note Check properties savedObjects, unsavedObjects and removedObjects to find out the current state of the bag.
+ * @see \link inflateBag - (void)inflateBag \endlink
+ */
+
+- (void)deflateBag;
+
+//@}
+
+/** @name Miscellaneous
+ */
+
+//@{
+
+/** * Returns the number of objects currently in the bag.
+ * @return The number of objects currently in the bag.
+ */
+
+- (NSUInteger)count;
+
+/** * Compares the receiving bag to another bag.
+ * @param otherNanoBag is a bag.
+ * @return YES if the contents of otherNanoBag are equal to the contents of the receiving bag, otherwise NO.
+ */
+
+- (BOOL)isEqualToNanoBag:(NSFNanoBag *)otherNanoBag;
+
+/** * Returns a dictionary that contains the information stored in the bag.
+ * @note Check properties savedObjects, unsavedObjects and removedObjects to find out the current state of the bag.
+ * @see \link description - (NSString *)description \endlink
+ */
+
+- (NSDictionary *)dictionaryRepresentation;
+
+/** * Returns a string representation of the bag.
+ * @note Check properties savedObjects, unsavedObjects and removedObjects to find out the current state of the bag.
+ * @see \link dictionaryRepresentation - (NSDictionary *)dictionaryRepresentation \endlink
+ */
+
+- (NSString *)description;
+
+//@}
+
+@end