save_queue 0.2.3 → 0.3.0

data/.gitignore

@@ -2,12 +2,21 @@
 .bundle
 Gemfile.lock
 pkg/*
-.idea/
+.idea/*
 doc/
-log/*.log
-/tmp/
-tmp/
+log/*
+tmp/*
 db/*.sqlite3
 /coverage
 /coverage.data
 /.yardoc
+.rvmrc
+
+## generic files to ignore
+*~
+*.lock
+*.DS_Store
+*.swp
+*.out
+*.swo
+*.md.html

data/.travis.yml

@@ -2,6 +2,9 @@ rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
-  - jruby
+  #- jruby-19mode # Not working on travis
+  - jruby-18mode
+  - rbx-19mode
+  - rbx-18mode
   - ruby-head
   - ree

data/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+Contributing to Save Queue
+==========================
+Save Queue is an open source project. Anyone can use the code, but more importantly, anyone can contribute. This is a
+ group effort and we value your input. Please consider making a contribution to help improve the Save Queue. This
+ guide covers:
+
+* How to file a ticket when you discover a bug
+* How to contribute fixes and improvements to the core
+* Information on how to improve the documentation
+
+### Notification via Ticket
+
+You can also search existing bug reports/issues and file a new one if you do not find an issue relevant to your
+ proposed change. See Filing an Issue for more details.
+
+The important thing is that you communicate your intention in advance of doing a lot of work. Simple bug fixes and
+ non-controversial changes do not require this approach but you can save some time by suggesting an improvement and
+ having it rejected before you write a bunch of the code.
+
+## Filing an Issue
+
+If you would like to file a bug report, please create an issue in our Github Issues Tracker. You should do a basic
+ search of the issues database before creating a new issue to ensure that you are not creating a duplicate issue.
+
+### Providing a Patch
+
+If you are filing and issue and supplying a patch at the same time, please file a Pull Request instead. The pull
+ request will also create an issue at the same time but its superior to just creating an issue because the code and
+ issue can be linked.
+
+If the ticket already exists, however, and you want to supply a patch after the fact,
+ you can simply reference the issue number in your commit message. For example, if your commit fixed issue #123 you
+ could use the following commit message:
+
+    Fixed a problem with Facebook authentication.
+
+    [Fixes #123]
+Github will automatically detect this commit message when you push it and link the issue. Please see the detailed
+ Github Issues blog post for more details.
+
+### Feature Requests
+
+We’re interested in hearing your ideas for new features. A feature request is any idea you have to improve the software experience that
+ is not strictly related to a bug or error of omission.
+
+Feature requests that are accompanied by source code are always welcome. In this case you should read the next
+ section on Creating a Pull Request.
+
+## Creating a Pull Request
+
+If you are going to contribute code to the Save Queue project, the best mechanism for doing this is to create a pull
+ request in Github. If you’re unfamiliar with the general concept of pull requests you may want to read more on pull
+ requests in Github.
+
+If your code is associated with an existing issue then you can provide a patch instead of creating a pull request.
+
+### Creating a Fork
+
+The official Save Queue source code is maintained in Github under the AlexParamonov/save_queue
+
+You simply need to “fork” the project and then start hacking.
+
+See the Github guide on creating forks for more details.
+
+### Topic Branches
+
+Git branches are “cheap.” Creating branches in Git is incredibly easy and its an ideal way to isolate a specific set
+ of changes. You may be fixing several things at one time but by keeping your changes isolated it will help us to
+ find and apply only the changes we’re interested in. You should create a clean branch based on the latest
+ save_queue/master when doing this. It is important you follow these steps exactly,
+ it will prevent you from accidentally including unrelated changes from your local repository into the branch.
+
+For example, if we were submitting a patch to fix an issue with the CSS in the flash error message you could create
+ a branch as follows:
+
+    $ git remote add upstream git://github.com/AlexParamonov/save_queue.git
+    $ git fetch upstream
+    $ git checkout -b fix-css-for-error-flash --track upstream/master
+
+The fetch command will grab all of the latest commits from the Save Queue master branch. Don’t worry,
+ it doesn’t alter your working repository in a harmful way. The track part of the command will tell git that this
+ branch should track with the remote version of the upstream master. This is another way of saying that the branch
+ should be based on a clean copy of the latest official source code (without any of your unrelated local changes.)
+
+You can then do work locally on this topic branch and push it up to your Github fork when you are done. So in our
+ previous example we do something like:
+
+    $ git push origin fix-css-for-error-flash
+
+Of course if you want the fix for yourself to use in your own local code you should probably merge it down to your
+ own personal master branch that you’re using for development
+
+    $ git checkout master
+    $ git merge fix-css-for-error-flash
+
+You should probably also clean up after yourself a little. The branch has been pushed to Github and you’ve merged it
+  locally so you don’t really need a local copy of the branch laying around.
+
+    $ git branch -D fix-css-for-error-flash
+
+### Including a Test
+
+Ideally your pull request will also include a test that verifies a bug (or the absence of the new feature) before
+ your fix and also verifies proper functionality when you are finished. Please read the Testing Guide for more
+ information on writing and running your tests.
+
+Pull requests with tests are given top priority. Failure to include a test will likely delay acceptance of your patch.
+
+### Creating the Pull Request
+
+Once your code is ready to go and you have pushed your topic branch to Github then you are ready to create the pull
+ request and notify the Save Queue team that your contribution is ready. You do this by browsing your project in
+ Github and changing to the topic branch you just pushed. Once you are on the topic branch simply create a pull
+ request by pressing the “Pull Request” button.
+
+The Github guide on pull requests describes this in more detail with screenshots if you’re still confused on this
+ part.
+
+## Contributing to the Documentation
+Improvements to the documentation is encouraged.

data/HISTORY.md

@@ -1,3 +1,14 @@
+0.3.x
+=====
++ Notification plugin
++ add save! method
++ refactor Validation plugin
++ bugfixing
+
+0.2.x
+=====
+Implemented main functionality, add Validation plugin
+
 0.0.1
 =====
 Initial release. Add README, LICENSE, .gitignore, etc

data/LICENSE

@@ -1,7 +1,16 @@
-Copyright (c) 2011 Alexander N Paramonov
+Copyright (c) 2011-2012 Alexander N Paramonov
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ documentation files (the "Software"), to deal in the Software without restriction,
+ including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+ USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,123 +1,347 @@
 Save Queue
 ==========
-Save Queue allows to push related objects to an object's queue for delayed save, that will triggered on object#save. In this case object wil store all related information on its save.
+Save Queue allows to push objects to other object's queue for a delayed save.
+Queue save will be triggered by object#save.
+
+
+Contents
+---------
+1. Installation
+1. Contributing
+1. Usage
+    * Getting started
+    * Tracking changes
+    * Error handling
+1. Plugins
+    * Validation
+    * Notification
+1. Creating your own Queues / TODO
+1. FAQ
+1. Requirements
+1. Compatibility
+1. Copyright
 
 Installation
 ------------
     gem install save_queue
 
+Contributing
+-------------
+__Please help to improve this project!__
+
+See [contributing guide](http://github.com/AlexParamonov/save_queue/blob/master/CONTRIBUTING.md) for best practices
+
 Usage
 -----
 
-How to start:
+### Getting started
 
 1. include SaveQueue:
 
         require 'save_queue'
+
         class Artice
           include SaveQueue
         end
 
 2. call \#mark_as_changed method when object gets dirty:
 
+        require 'save_queue'
+
         class Artice
+          include SaveQueue
+
           def change_attribute attr, value
+            @attributes ||= {}
             @attributes[attr] = value
             mark_as_changed # call this and object will be marked for save
           end
         end
 
-3. point save method to your save logic or dont care if you use #save already:
-
-        class Artice
-          # @return [boolean]
-          def save
-            write
-          end
-        end
-
-4.  If you want to use validation, include SaveQueue::Plugins::Validation and implement #valid? method. You may got failed objects by save_queue.objects_with_errors
-
-        class Artice
-          include SaveQueue::Plugins::Validation
-
-          # @return [boolean]
-          def valid?
-            true
-          end
-        end
-
-5. add SaveQueue to some other classes:
+3. add SaveQueue to some other classes (or implement #save and #has_unsaved_changes? in it):
 
         require 'save_queue'
+
         class Tag
           include SaveQueue
+
+          @attributes ||= {}
+          @attributes[attr] = value
+          mark_as_changed # call this and object will be marked for save
         end
 
+4. Add some functionality:
+
         class Artice
-          def tags= tag_objects
+          def tags=(tag_objects)
             @tags = tag_objects
-            saved_queue.add_all tag_objects
+            save_queue.add_all tag_objects
           end
 
-          def add_tag tag
+          def add_tag(tag)
             @tags ||= []
             @tags << tag
-            saved_queue.add tag
+            save_queue.add tag # you may use also #<<, #push methods
           end
         end
 
-6. Use it:
+6. Voila!
 
         article = Article.new
-        tag_objects = [Tag.new, Tag.new, Tag.new]
-        article.tags = tag_object
-        article.add_tag Tag.new
+
+        tag_objects = []
+        3.times do
+          tag = Tag.new
+          tag.change_attribute :title, "new tag"
+          tag.should_receive(:save).once
+          tag_objects << tag
+        end
+        
+        article.tags = tag_objects
+
+        tag = Tag.new
+        tag.change_attribute :title, "single tag"
+        tag.should_receive(:save).once
+
+        article.add_tag tag
 
         # that will save article and all tags in this article if article
         # and tags are valid, and if article.save and all tag.save returns true
-        article.save
+        # You may also use #save! method, that will trigger save_queue.save! and
+        # raise SaveQueue::FailedSaveError on fail
+        article.save.should be_true
 
-7. Handle errors
+        # You may call save on queue explicitly:
+        #
+        # article.save_queue.save
+        # article.save
 
-  7.1. You did not include SaveQueue::Plugins::Validation:
+7. Read README for more details :)
 
-        begin
-          article.save
-        rescue SaveQueue::FailedSaveError => save_error
 
-          # @params [Hash] info
-          # @option info [Array<Object>] :saved
-          # @option info [Object]        :failed
-          # @option info [Array<Object>] :pending
-          save_error.context
-        end
+### Tracking changes
+By default SaveQueue provide changes tracking functional.
+In order to use it, call #mark_as_changed method in your mutator methods like this:
 
-  7.2. You've included SaveQueue::Plugins::Validation:
+    require "save_queue"
+    class Artice
+      include SaveQueue
 
-        # Note nothing was actually saved. You dont need to do a cleanup
-        unless article.save then
-          failed_objects = article.saved_query.objects_with_errors
-        end
+      def change_attribute attr, value
+        @attributes[attr] = value
+        mark_as_changed # call this and object will be marked for save
+      end
+    end
 
+If you want to mark object as saved, you may use #mark_as_saved method. SaveQueue will automatically call #mark_as_saved
+after saving an object.
+This marks are used when SaveQueue calls #save. Object will be saved only, if it #has_unsaved_changes? returns true.
+There are some docs from spec tests:
 
+    #has_unsaved_changes?
+      should return true for changed object
+      should return false for unchanged object
+      should return false for new object
 
 If you have custom logic for marking objects dirty then you may want to override
-\#has_unsaved_changes? method in you class like this:
+\#has_unsaved_changes? method, methods #mark_as_saved and #mark_as_changed in you class like this:
 
     def has_unsaved_changes?
-      dirty? # dirty is you custom method to determine has object unsaved_changes or not
+      dirty? # dirty is your custom method to determine has object unsaved_changes or not
+    end
+
+    def mark_as_saved
+      # your custom methods
+    end
+
+    def mark_as_changed
+      # your custom methods
+    end
+
+
+### Error handling
+
+SaveQueue assumes, that #save method returns true/false and #save! raise an Exception if save failed:
+
+    unless article.save
+      # You may use article.save_queue.errors.any? or article.save_queue.errors.empty? also
+
+      # returns a [Hash] that contains information about saving proccess:
+      # @option [Array<Object>] :processed
+      # @option [Array<Object>] :saved
+      # @option [Object]        :failed
+      # @option [Array<Object>] :pending
+      article.save_queue.errors[:save]
+    end
+
+
+    begin
+      article.save!
+    rescue SaveQueue::FailedSaveError => error
+
+      # returns a [Hash] that contains information about saving proccess:
+      # @option [Array<Object>] :processed
+      # @option [Array<Object>] :saved
+      # @option [Object]        :failed
+      # @option [Array<Object>] :pending
+      error.context
+
+      article.save_queue.errors[:save] # also set
     end
 
-method \#mark_as_saved becomes useless in this case and you should mark objects by your self.
 
 
-Note: Today Save Queue use only #save method to perform save actions on an objects, but later this should be changed to custom option.
+Plugins
+-------
+I am trying to extract any "extra" functionality into separate plugins, that you may want to include.
+
+### Validation
+
+If you want to use validation, include SaveQueue::Plugins::Validation and implement #valid? method.
+You may got failed objects from save_queue.errors\[:validation] array.
+\save_queue.errors are empty if no errors occurs
+
+    require 'save_queue'
+    require 'save_queue/plugins/validation'
+
+    class Artice
+      include SaveQueue
+      include SaveQueue::Plugins::Validation
+
+      # @return [boolean]
+      def valid?
+        true
+      end
+
+      # ...
+    end
+
+There are specs for them:
+
+    ValidQueue
+      invalid objects
+        save
+          should not be saved
+          should set errors
+        save!
+          should raise SaveQueue::FailedValidationError exception
+          should set errors
+      valid objects
+        save
+          should be saved
+          should not set errors
+        save!
+          should not raise an exception
+          should not set errors
+
+Also you got more error hangling options:
+
+    # Note: queue was not saved. You dont need to do a cleanup
+    unless article.save then
+      failed_objects = article.errors[:validation]
+    end
+
+    begin
+      article.save!
+    rescue SaveQueue::FailedValidationError => error
+      # [Array<Object>]
+      error.failed_objects
+
+      article.save_queue.errors[:validation] # also set
+    end
+
+You may catch both save and validation errors by
+
+    begin
+      article.save!
+    rescue SaveQueue::Error
+      # do something
+    end
+
+if you want not to save an object if save_queue is invalid then add this check to your save method (or any other method that you use, ex: valid?):
+
+    def save
+      return false unless save_queue.valid?
+      #..
+    end
+
+or you may add it to your validation.
+Note, that #valid? and #validate return true/false and #validate! raises SaveQueue::FailedValidationError exception
+
+### Notification
+
+If you want to use notification, include SaveQueue::Plugins::Notification.
+You'll get object notified by #queue_changed_event method, which by default call #mark_as_changed method if queue was successfuly changed.
+You may override this method in your object if you want to.
+
+    class Artice
+      include SaveQueue
+      include SaveQueue::Plugins::Notification
+    end
+
+    article = Article.new
+    article.mark_as_saved
+    article.save_queue << tag
+    article.should have_unsaved changes
+
+    class Artice
+      def queue_changed_event(result, object)
+        super
+        puts "queue was changed!"
+      end
+    end
+
+    article = Article.new
+    article.mark_as_saved
+    article.save_queue << tag # "queue was changed!"
+    article.should have_unsaved changes
+
+
+Creating your own Queues
+-------------------------
+
+/ TODO
+
+FAQ
+---
+
+__Q: I use #write method to store object, how can i use SaveQueue?__
+
+A: You may implement save method like this:
+
+    class Artice
+      # @return [boolean]
+      def save
+        write
+      end
+    end
+
+Note that SaveQueue assumes, that #save method returns true/false and #save! raise an Exception if save failed
+
+__Q: Where i can get more information?__
+
+A: See test specs for more details.
+
+__How?__
+
+clone git project by
+
+    git clone git://github.com/AlexParamonov/save_queue.git
+
+cd into it and run bundle
+
+    cd save_queue
+    bundle
+
+and run rake
+
+    rake
+
 
 Requirements
 ------------
 
-* ActiveSupport
+* hooks
 * rspec2 for testing
 
 Compatibility
@@ -127,7 +351,9 @@ tested with Ruby
 * 1.8.7
 * 1.9.2
 * 1.9.3
-* jruby
+* jruby-18mode
+* rbx-19mode
+* rbx-18mode
 * ruby-head
 * ree
 
@@ -135,4 +361,5 @@ see [build history](http://travis-ci.org/#!/AlexParamonov/save_queue/builds)
 
 Copyright
 ---------
-Copyright © 2011 Alexander N Paramonov. See LICENSE for details.
+Copyright © 2011-2012 Alexander N Paramonov.
+Released under the MIT License. See the LICENSE file for further details.

data/Rakefile

@@ -1,5 +1,12 @@
+# encoding: utf-8
+# GEMS
 require "bundler/gem_tasks"
-require 'rspec'
+
+# SPECS
+require 'rspec/core'
 require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec)
-task :default => [:spec]
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+#Rake::Task["spec"].execute
+task :default => :spec

data/lib/save_queue/exceptions.rb

@@ -0,0 +1,13 @@
+module SaveQueue
+  class Error < RuntimeError; end
+  class FailedSaveError < Error
+    attr_reader :context
+    def initialize(context_hash)
+      @context = context_hash
+    end
+
+    def to_s # Some default way to display errors
+      "#{super}: " + @context.to_s
+    end
+  end
+end