motion_model 0.2.5 → 0.2.6

data/CHANGELOG

@@ -1,3 +1,11 @@
+2012-10-14: Primary New Feature: Notifications
+
+MotionModel: Added bulk update, which suppresses notifications and added it to delete_all.
+MotionModel: Added notifications of type MotionModelDataDidChangeNotification on data change.
+MotionModel: Added classification code to save to differentiate between save-new and update
+MotionModel: Added notification calls to save and delete
+
+
 2012-09-05: Basically rewrote how the data is stored.
 
 The API remains consistent, but a certain amount of

data/README.md

@@ -133,12 +133,13 @@ already present, it's left alone. If it's missing, then it is created for you.
 Each row id is guaranteed to be unique, so you can use this when communicating
 with a server or syncing your rowset to a UITableView.
 
-Things That Work
+Using MotionModel
 -----------------
 
-* Models, in general, work. They aren't ultra full-featured, but more is in the
-  works. In particular, finders are just coming online. All column data may be
-  accessed by member name, e.g., `@task.name`.
+* Your data in a model is accessed in a very ActiveRecord (or Railsey) way.
+  This should make transitioning from Rails or any ORM that follows the
+  ActiveRecord pattern pretty easy. Some of the finder syntactic sugar is
+  similar to that of Sequel or DataMapper.
   
   * Finders are implemented using chaining. Here is an examples:
 
@@ -169,6 +170,13 @@ Things That Work
     @tasks = Task.order{|one, two| two.details <=> one.details}.all # Get tasks ordered descending by :details
     ```
 
+    You can implement some aggregate functions using map/reduce:
+
+```ruby
+  @task.all.map{|task| task.number_of_items}.reduce(:+)                # implements sum
+  @task.all.map{|task| task.number_of_items}.reduce(:+) / @task.count  #implements average
+```
+
 * Serialization is part of MotionModel. So, in your `AppDelegate` you might do something like this:
 
   ```ruby
@@ -181,16 +189,18 @@ Things That Work
     Task.serialize_to_file('tasks.dat')
   end
   ```
+  After the first serialize or deserialize, your model will remember the file
+  name so you can call these methods without the filename argument.
   
-  Note that the this serialization of any arbitrarily complex set of relations
+  Implementation note: that the this serialization of any arbitrarily complex set of relations
   is automatically handled by `NSCoder` provided you conform to the coding
-  protocol. When you declare your columns, `MotionModel` understands how to
-  serialize your data so you need take no further action.
+  protocol (which MotionModel does). When you declare your columns, `MotionModel` understands how to
+  serialize your data so you need take no specific action.
   
   **Warning**: As of this release, persistence will serialize only one
-  model at a time and not your entire data store. This will be fixed next.
+  model at a time and not your entire data store.
   
-  * Relations now are usable, although not complete fleshed out:
+  * Relations
   
   ```ruby
   class Task
@@ -230,10 +240,86 @@ Things That Work
   At this point, there are a few methods that need to be added
   for relations, and they will.
   
-  * delete
   * destroy
+  
+Notifications
+-------------
 
-* Core extensions work. The following are supplied:
+  Notifications are issued on object save, update, and delete. They work like this:
+  
+  ```ruby
+  def viewDidAppear(animated)
+    super
+    # other stuff here to set up your view
+    
+    NSNotificationCenter.defaultCenter.addObserver(self, selector:'dataDidChange:', name:'MotionModelDataDidChangeNotification', object:nil)
+  end
+  
+  def viewWillDisappear(animated)
+    super
+    NSNotificationCenter.defaultCenter.removeObserver self
+  end
+  
+  # ... more stuff ...
+  
+  def dataDidChange(notification)
+    # code to update or refresh your view based on the object passed back
+    # and the userInfo. userInfo keys are:
+    #   action
+    #     'add'
+    #     'update'
+    #     'delete'
+  end
+  ```
+  
+  In your dataDidChange notification handler, you can respond to the `'MotionModelDataDidChangeNotification'` notification any way you like,
+  but in the instance of a tableView, you might want to use the id of the object passed back to locate
+  the correct row in the table and act upon it instead of doing a wholesale `reloadData`.
+  
+  Note that if you do a delete_all, no notifications are issued because there is no single object
+  on which to report. You pretty much know what you need to do: Refresh your view.
+
+  This is implemented as a notification and not a delegate so you can dispatch something
+  like a remote synch operation but still be confident you will be updating the UI only on the main thread.
+  MotionModel does not currently send notification messages that differentiate by class, so if your
+  UI presents `Task`s and you get a notification that an `Assignee` has changed:
+  
+  ```ruby
+  class Task
+    include MotionModel::Model
+    has_many :assignees
+    # etc
+  end
+  
+  class Assignee
+    include MotionModel::Model
+    belongs_to :task
+    # etc
+  end
+
+  # ...
+  
+  task = Task.create :name => 'Walk the dog'  # Triggers notification with a task object
+  task.assignees.create :name => 'Adam'       # Triggers notification with an assignee object
+  
+  # ...
+  
+  # We set up observers for `MotionModelDataDidChangeNotification` someplace and:
+  def dataDidChange(notification)
+  if notification.object is_a?(Task)
+    # Update our UI
+  else
+    # This notification is not for us because
+    # We don't display anything other than tasks
+  end
+  ```
+  
+  The above example implies you are only presenting, say, a list of tasks in the current
+  view. If, however, you are presenting a list of tasks along with their assignees and
+  the assignees could change as a result of a background sync, then your code could and
+  should recognize the change to assignee objects.
+  
+Core Extensions
 
   - String#humanize
   - String#titleize
@@ -245,7 +331,8 @@ Things That Work
   - Hash#empty?
   - Symbol#titleize
   
-  Also in the extensions is a debug class to log stuff to the console.
+  Also in the extensions is a `Debug` class to log stuff to the console.
+  It uses NSLog so you will have a separate copy in your application log.
   This may be preferable to `puts` just because it's easier to spot in
   your code and it gives you the exact level and file/line number of the
   info/warning/error in your console output:
@@ -289,7 +376,6 @@ Things That Work
 Things In The Pipeline
 ----------------------
 
-- More robust id assignment
 - Adding validations and custom validations
 
 Problems/Comments
@@ -304,8 +390,8 @@ one).
 Then be sure references to motion_model are commented out or removed from your Gemfile
 and/or Rakefile and put this in your Rakefile:
 
-```
-require "~/github/local//MotionModel/lib/motion_model.rb"
+```ruby
+require "~/github/local/MotionModel/lib/motion_model.rb"
 ```
 
 The `~/github/local` is where I cloned it, but you can put it anyplace. Next, make
@@ -314,9 +400,9 @@ sure you are following the project on GitHub so you know when there are changes.
 Submissions/Patches
 ------------------
 
-Obviously, the ideal one is a pull request from your own fork, complete with passing
+Obviously, the ideal patch request is really a pull request from your own fork, complete with passing
 specs.
 
-Really, even a failing spec or some proposed code is fine. I really want to make
+Really, for a bug report, even a failing spec or some proposed code is fine. I really want to make
 this a decent tool for RubyMotion developers who need a straightforward data
 modeling and persistence framework.

data/lib/motion_model/model/model.rb

@@ -51,6 +51,20 @@ module MotionModel
     end
     
     module ClassMethods
+      # Use to do bulk insertion, updating, or deleting without
+      # making repeated calls to a delegate. E.g., when syncing
+      # with an external data source.
+      def bulk_update(&block)
+        @call_delegate_method = false
+        yield
+        @call_delegate_method = true
+      end
+      
+      def call_delegate(object, info) #nodoc
+        @call_delegate_method = true if @call_delegate_method.nil?
+        NSNotificationCenter.defaultCenter.postNotificationName('MotionModelDataDidChangeNotification', object: object, userInfo: info) if @call_delegate_method && !object.nil?
+      end
+
       def add_field(name, options, default = nil) #nodoc
         col = Column.new(name, options, default)
         @_columns.push col
@@ -217,6 +231,12 @@ module MotionModel
 
       # Empties the entire store.
       def delete_all
+        # Do each delete so any on_delete and
+        # cascades are called, then empty the
+        # collection and compact the array.
+        bulk_update do
+          self.each{|item| item.delete}
+        end
         @collection = [] # TODO: Handle cascading or let GC take care of it.
         @_next_id = 1
         @collection.compact!
@@ -286,10 +306,10 @@ module MotionModel
 
       unless options[:id]
         options[:id] = self.class.next_id
-        self.class.increment_id
       else
         self.class.next_id = [options[:id].to_i, self.class.next_id].max
       end
+      self.class.increment_id
 
       columns.each do |col|
         unless [:belongs_to, :belongs_to_id, :has_many].include? column_named(col).type
@@ -330,24 +350,28 @@ module MotionModel
     def to_s
       columns.each{|c| "#{c}: #{self.send(c)}\n"}
     end
-
+    
     def save
       collection = self.class.instance_variable_get('@collection')
       @dirty = false
       
       # Existing object implies update in place
       # TODO: Optimize location of existing id
+      action = 'add'
       if obj = collection.find{|o| o.id == @data[:id]}
-        obj = self
+        collection = self
+        action = 'update'
       else
         collection << self
       end
+      self.class.call_delegate(self, :action => action)
     end
     
     def delete
       collection = self.class.instance_variable_get('@collection')
       target_index = collection.index{|item| item.id == self.id}
       collection.delete_at(target_index)
+      self.class.call_delegate(self, :action => 'delete')
     end
 
     def length

data/lib/motion_model/version.rb

@@ -1,3 +1,3 @@
 module MotionModel
-  VERSION = "0.2.5"
+  VERSION = "0.2.6"
 end

data/spec/finder_spec.rb

@@ -0,0 +1,140 @@
+class Task
+  include MotionModel::Model
+  columns       :name => :string, 
+  							:details => :string,
+  							:some_day => :date
+end
+
+describe 'finders' do
+  before do
+    Task.delete_all
+    1.upto(10) {|i| Task.create(:name => "task #{i}", :id => i)}
+  end
+
+  describe 'find' do
+    it 'finds elements within the collection' do
+      Task.count.should == 10
+      Task.find(3).name.should.equal("task 3")
+    end
+
+    it 'returns nil if find by id is not found' do
+      Task.find(999).should.be.nil
+    end
+      
+    it 'looks into fields if field name supplied' do
+      Task.create(:name => 'find me')
+      tasks = Task.find(:name).eq('find me')
+      tasks.count.should.equal(1)
+      tasks.first.name.should == 'find me'
+    end
+      
+    it "provides an array of valid model instances when doing a find" do
+      Task.create(:name => 'find me')
+      tasks = Task.find(:name).eq('find me')
+      tasks.first.name.should.eql 'find me'
+    end
+      
+    it 'allows for multiple (chained) query parameters' do
+      Task.create(:name => 'find me', :details => "details 1")
+      Task.create(:name => 'find me', :details => "details 2")
+      tasks = Task.find(:name).eq('find me').and(:details).like('2')
+      tasks.first.details.should.equal('details 2')
+      tasks.all.length.should.equal(1)
+    end
+
+    it 'where should respond to finder methods' do
+      Task.where(:details).should.respond_to(:contain)
+    end
+      
+    it 'returns a FinderQuery object' do
+      Task.where(:details).should.is_a(MotionModel::FinderQuery)
+    end
+      
+    it 'using where instead of find' do
+      atask = Task.create(:name => 'find me', :details => "details 1")
+      found_task = Task.where(:details).contain("s 1").first.details.should == 'details 1'
+    end
+      
+    it "performs set inclusion(in) queries" do
+      class InTest
+        include MotionModel::Model
+        columns :name
+      end
+        
+      1.upto(10) do |i|
+        InTest.create(:id => i, :name => "test #{i}")
+      end
+        
+      results = InTest.find(:id).in([3, 5, 7])
+      results.length.should == 3
+    end
+      
+    it 'handles case-sensitive queries' do
+      task = Task.create :name => 'Bob'
+      Task.find(:name).eq('bob', :case_sensitive => true).all.length.should == 0
+    end
+    
+    it 'all returns all members of the collection as an array' do
+      Task.all.length.should.equal(10)
+    end
+    
+    it 'each yields each row in sequence' do
+      task_id = nil
+      Task.each do |task|
+        task_id.should.<(task.id) if task_id
+        task_id = task.id
+      end
+    end
+      
+    describe 'block-style finders' do
+      before do
+        @items_less_than_5 = Task.find{|item| item.name.split(' ').last.to_i < 5}
+      end
+        
+      it 'returns a FinderQuery' do
+        @items_less_than_5.should.is_a MotionModel::FinderQuery
+      end
+        
+      it 'handles block-style finders' do
+        @items_less_than_5.length.should == 4
+      end
+        
+      it 'deals with any arbitrary block finder' do
+        @even_items = Task.find do |item|
+          test_item = item.name.split(' ').last.to_i
+          test_item % 2 == 0 && test_item <= 6
+        end
+        @even_items.each{|item| item.name.split(' ').last.to_i.should.even?}
+        @even_items.length.should == 3   # [2, 4, 6]
+      end
+    end
+  end
+    
+  describe 'sorting' do
+    before do
+      Task.delete_all
+      Task.create(:name => 'Task 3', :details => 'detail 3')
+      Task.create(:name => 'Task 1', :details => 'detail 1')
+      Task.create(:name => 'Task 2', :details => 'detail 6')
+      Task.create(:name => 'Random Task', :details => 'another random task')
+    end
+
+    it 'sorts by field' do
+      tasks = Task.order(:name).all
+      tasks[0].name.should.equal('Random Task')
+      tasks[1].name.should.equal('Task 1')
+      tasks[2].name.should.equal('Task 2')
+      tasks[3].name.should.equal('Task 3')
+    end
+
+    it 'sorts observing block syntax' do
+      tasks = Task.order{|one, two| two.details <=> one.details}.all
+      tasks[0].details.should.equal('detail 6')
+      tasks[1].details.should.equal('detail 3')
+      tasks[2].details.should.equal('detail 1')
+      tasks[3].details.should.equal('another random task')
+    end
+  end
+    
+end
+

data/spec/model_spec.rb

@@ -131,138 +131,6 @@ describe "Creating a model" do
 
   end
 
-  describe 'finders' do
-    before do
-      Task.delete_all
-      @tasks = []
-      10.times {|i| @tasks.push Task.create(:name => "task #{i}")}
-    end
-
-    describe 'find' do
-      it 'finds elements within the collection' do
-        task = Task.find(3).name.should.equal(@tasks[2].name) # zero based
-      end
-
-      it 'returns nil if find by id is not found' do
-        Task.find(999).should.be.nil
-      end
-      
-      it 'looks into fields if field name supplied' do
-        Task.create(:name => 'find me')
-        tasks = Task.find(:name).eq('find me')
-        tasks.all.length.should.equal(1)
-        tasks.first.name.should == 'find me'
-      end
-      
-      it "provides an array of valid model instances when doing a find" do
-        Task.create(:name => 'find me')
-        tasks = Task.find(:name).eq('find me')
-        tasks.first.name.should.eql 'find me'
-      end
-      
-      it 'allows for multiple (chained) query parameters' do
-        Task.create(:name => 'find me', :details => "details 1")
-        Task.create(:name => 'find me', :details => "details 2")
-        tasks = Task.find(:name).eq('find me').and(:details).like('2')
-        tasks.first.details.should.equal('details 2')
-        tasks.all.length.should.equal(1)
-      end
-
-      it 'where should respond to finder methods' do
-        Task.where(:details).should.respond_to(:contain)
-      end
-      
-      it 'returns a FinderQuery object' do
-        Task.where(:details).should.is_a(MotionModel::FinderQuery)
-      end
-      
-      it 'using where instead of find' do
-        atask = Task.create(:name => 'find me', :details => "details 1")
-        found_task = Task.where(:details).contain("s 1").first.details.should == 'details 1'
-      end
-      
-      it "performs set inclusion(in) queries" do
-        class InTest
-          include MotionModel::Model
-          columns :name
-        end
-        
-        1.upto(10) do |i|
-          InTest.create(:id => i, :name => "test #{i}")
-        end
-        
-        results = InTest.find(:id).in([3, 5, 7])
-        results.length.should == 3
-      end
-      
-      it 'handles case-sensitive queries' do
-        task = Task.create :name => 'Bob'
-        Task.find(:name).eq('bob', :case_sensitive => true).all.length.should == 0
-      end
-    
-      it 'all returns all members of the collection as an array' do
-        Task.all.length.should.equal(10)
-      end
-    
-      it 'each yields each row in sequence' do
-        i = 0
-        Task.each do |task|
-          task.name.should.equal("task #{i}")
-          i += 1
-        end
-      end
-      
-      describe 'block-style finders' do
-        before do
-          @items_less_than_5 = Task.find{|item| item.name.split(' ').last.to_i < 5}
-        end
-        
-        it 'returns a FinderQuery' do
-          @items_less_than_5.should.is_a MotionModel::FinderQuery
-        end
-        
-        it 'handles block-style finders' do
-          @items_less_than_5.length.should == 5 # Zero based
-        end
-        
-        it 'deals with any arbitrary block finder' do
-          @even_items = Task.find do |item|
-            test_item = item.name.split(' ').last.to_i
-            test_item % 2 == 0 && test_item < 5
-          end
-          @even_items.each{|item| item.name.split(' ').last.to_i.should.even?}
-          @even_items.length.should == 3   # [0, 2, 4]
-        end
-      end
-    end
-    
-    describe 'sorting' do
-      before do
-        Task.delete_all
-        Task.create(:name => 'Task 3', :details => 'detail 3')
-        Task.create(:name => 'Task 1', :details => 'detail 1')
-        Task.create(:name => 'Task 2', :details => 'detail 6')
-        Task.create(:name => 'Random Task', :details => 'another random task')
-      end
-
-      it 'sorts by field' do
-        tasks = Task.order(:name).all
-        tasks[0].name.should.equal('Random Task')
-        tasks[1].name.should.equal('Task 1')
-        tasks[2].name.should.equal('Task 2')
-        tasks[3].name.should.equal('Task 3')
-      end
-
-      it 'sorts observing block syntax' do
-        tasks = Task.order{|one, two| two.details <=> one.details}.all
-        tasks[0].details.should.equal('detail 6')
-        tasks[1].details.should.equal('detail 3')
-        tasks[2].details.should.equal('detail 1')
-        tasks[3].details.should.equal('another random task')
-      end
-    end
-    
-  end
   
   describe 'deleting' do
     before do
@@ -272,7 +140,7 @@ describe "Creating a model" do
     it 'deletes a row' do
       target = Task.find(:name).eq('task 3').first
       target.delete
-      Task.find(:description).eq('Task 3').length.should.equal 0
+      Task.find(:name).eq('task 3').count.should.equal 0
     end
     
     it 'deleting a row changes length' do
@@ -351,3 +219,65 @@ describe "Creating a model" do
   end
 end
 
+class NotifiableTask
+  include MotionModel::Model
+  columns :name
+  has_many :assignees
+  
+  attr_accessor :notification_called, :notification_details
+  
+  def hookup_events
+    NSNotificationCenter.defaultCenter.addObserver(self, selector:'dataDidChange:', name:'MotionModelDataDidChangeNotification', object:nil)
+    @notification_details = nil
+  end
+
+  def dataDidChange(notification)
+    @notification_called = true
+    @notification_details = notification.userInfo
+  end
+
+  def teardown_events
+    NSNotificationCenter.defaultCenter.removeObserver self
+  end
+end
+
+describe 'data change notifications' do
+  before do
+    @task = NotifiableTask.new
+    @task.hookup_events
+  end
+  
+  after do
+    @task.teardown_events
+  end
+  
+  it "fires a change notification when an item is added" do
+    @task.notification_called = false
+    lambda{@task.save}.should.change{@task.notification_called}
+  end
+  
+  it "contains an add notification for new objects" do
+    @task.save
+    @task.notification_details[:action].should == 'add'
+  end
+  
+  it "contans an update notification for an updated object" do
+    @task.save
+    @task.name = "Bill"
+    @task.save
+    @task.notification_details[:action].should == 'update'
+  end
+  
+  it "contains a delete notification for a deleted object" do
+    @task.save
+    @task.delete
+    @task.notification_details[:action].should == 'delete'
+  end
+  
+  it "does not get a delete notification for delete_all" do
+    @task = NotifiableTask.create :name => 'Bob'
+    @task.notification_called = nil
+    lambda{NotifiableTask.delete_all}.should.not.change{@task.notification_called}
+  end
+end
+

data/spec/persistence_spec.rb

@@ -174,4 +174,5 @@ describe "serialization of relations" do
     Parent.first.children.count.should == 2
     Parent.first.children.first.name.should == 'Fergie'
   end
-end
+end
+

data/spec/relation_spec.rb

@@ -99,3 +99,4 @@ describe 'related objects' do
     end
   end
 end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: motion_model
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-11 00:00:00.000000000 Z
+date: 2012-10-24 00:00:00.000000000 Z
 dependencies: []
 description: Simple model and validation mixins for RubyMotion
 email:
@@ -34,6 +34,7 @@ files:
 - lib/motion_model/version.rb
 - motion_model.gemspec
 - spec/ext_spec.rb
+- spec/finder_spec.rb
 - spec/model_spec.rb
 - spec/persistence_spec.rb
 - spec/relation_spec.rb
@@ -63,6 +64,7 @@ specification_version: 3
 summary: Simple model and validation mixins for RubyMotion
 test_files:
 - spec/ext_spec.rb
+- spec/finder_spec.rb
 - spec/model_spec.rb
 - spec/persistence_spec.rb
 - spec/relation_spec.rb