resort-bjones 0.3.0

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.rvmrc

@@ -0,0 +1 @@
+rvm --create use ruby-1.9.3@resort

data/.travis.yml

@@ -0,0 +1,8 @@
+# http://about.travis-ci.org/docs/user/build-configuration/
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - ree
+  - ruby-head
+  - rbx
+  - rbx-2.0

data/Gemfile

@@ -0,0 +1,20 @@
+source "http://rubygems.org"
+
+gem 'activerecord', '>= 3.0.5', '< 3.2'
+
+group :development, :test do
+  gem 'jeweler', '>= 1.5.2'
+  gem 'rake'
+  gem 'sqlite3'
+  gem 'rspec'
+  gem 'yard'
+  gem 'bluecloth'
+  gem 'generator_spec', '~> 0.8.1'
+
+  # For debugging under ruby 1.9 special gems are needed
+#  gem 'ruby-debug19', :platform => :mri
+  # See http://blog.wyeworks.com/2011/11/1/ruby-1-9-3-and-ruby-debug
+#  gem 'ruby-debug-base19', '>=0.11.26'
+#  gem 'linecache19', '>=0.5.13'
+end
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Codegram
+
+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 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/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "resort-bjones"
+  gem.version = version
+  gem.homepage = "http://github.com/bjones/resort"
+  gem.license = "MIT"
+  gem.summary = %Q{Positionless model sorting for Rails 3.}
+  gem.description = %Q{Positionless model sorting for Rails 3.}
+  gem.email = "cbj@gnu.org"
+  gem.authors = ["Oriol Gual", "Josep M. Bach", "Josep Jaume Rey", "Brian Jones"]
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new(:docs) do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options = ['-m', 'markdown', '--no-private', '-r', 'Readme.md', '--title', 'Resort documentation']
+end
+
+task :doc => :docs
+
+desc "Generate and open class diagram (needs Graphviz installed)"
+task :graph do |t|
+ `bundle exec yard graph -d --full --no-private | dot -Tpng -o graph.png && open graph.png`
+end
+

data/Readme.md

@@ -0,0 +1,177 @@
+#resort
+
+Resort provides sorting capabilities to your Rails 3 models.  
+
+##Versions
+
+This is a fork of resort, named resort-bjones, which adds ActiveRecord 3.1 support.
+
+* resort-bjones 0.3.0 should work with ActiveRecord 3.0 and ActiveRecord 3.1
+* resort 0.2.3 works with ActiveRecord 3.0 only
+
+##Install
+
+    $ gem install resort-bjones
+
+Or in your Gemfile:
+
+```ruby
+gem 'resort-bjones'
+```
+
+##Rationale
+
+Most other sorting plugins work with an absolute `position` attribute that sets
+the _weight_ of a given element within a tree. This field has no semantic sense,
+since "84" by itself gives you absolutely no information about an element's
+position or its relations with other elements of the tree.
+
+Resort is implemented like a [linked list](http://en.wikipedia.org/wiki/Linked_list),
+rather than relying on absolute position values. This way, every model
+references a `next` element, which seems a bit more sensible :)
+
+##Usage
+
+First, run the migration for the model you want to Resort:
+
+    $ rails generate resort:migration product
+    $ rake db:migrate
+
+Then in your Product model:
+
+```ruby
+class Product < ActiveRecord::Base
+  resort!
+end
+```
+
+**NOTE**: By default, Resort will treat _all products_ as a single big tree.
+If you wanted to limit the tree scope, i.e. treating every ProductLine as a
+separate tree of sortable products, you must override the `siblings` method:
+
+```ruby
+class Product < ActiveRecord::Base
+  resort!
+
+  def siblings
+    # Tree contains only products from my own product line
+    self.product_line.products
+  end
+end
+```
+
+### Concurrency
+
+Multiple users modifying the same list at the same time could be a problem, 
+so it's always a good practice to wrap the changes in a transaction:
+    
+```ruby
+Product.transaction do
+  my_product.append_to(another_product)
+end
+```
+        
+###API
+
+**Every time a product is created, it will be appended after the last element.**
+
+Moreover, now a `product` responds to the following methods:
+
+* `first?` &mdash; Returns true if the element is the first of the tree.
+* `append_to(other_element)` &mdash; Appends the element _after_ another element.
+* `next` &mdash; Returns the next element in the list
+* `previous` &mdash; Returns the previous element in the list
+
+And the class Product has a new scope named `ordered` that returns the
+products in order.
+
+### Examples
+
+Given our `Product` example defined before, we can do things like:
+
+Getting products in order:
+
+```ruby
+Product.first_in_order # returns the first ordered product.
+Product.last_in_order # returns the last ordered product.
+Product.ordered # returns all products ordered as an Array, not a Relation!
+```
+
+Find ordered products with scopes or conditions:
+
+```ruby
+Product.where('price > 10').ordered # => Ordered array of products with price > 10
+Product.with_custom_scope.ordered # => Ordered array of products with your custom conditions
+```
+
+Modify the list of products:
+
+```ruby
+product = Product.create(:name => 'Bread')
+product.first? # => true
+
+another_product = Product.create(:name => 'Milk')
+yet_another_product = Product.create(:name => 'Salami')
+
+yet_another_product.append_to(product) # puts the products right after the first one
+
+Product.ordered.map(&:name) # => ['Bread', 'Salami', 'Milk']
+```
+
+Check neighbours:
+
+```ruby
+product = Product.create(:name => 'Bread')
+second_product = Product.create(:name => 'Milk')
+third_product = Product.create(:name => 'Salami')
+
+second_product.previous.name # => 'Bread'
+second_product.next.name # => 'Salami'
+
+third_product.next # => nil
+```
+
+Maybe you need different orders depending on the product vendor:
+
+```ruby
+class Product < ActiveRecord::Base
+  resort!
+
+  belongs_to :vendor
+
+  def siblings
+    self.vendor.products
+  end
+end
+
+bread = Product.create(:name => 'Bread', :vendor => Vendor.where(:name => 'Bread factory'))
+bread.first? # => true
+
+milk = Product.create(:name => 'Milk', :vendor => Vendor.where(:name => 'Cow world'))
+milk.first? # => true
+
+# bread and milk aren't neighbours
+```
+
+##Under the hood
+
+Run the test suite by typing:
+
+    rake spec
+
+You can also build the documentation with the following command:
+
+    rake docs
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send us a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2011 Codegram. See LICENSE for details.

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/generators/active_record/resort_generator.rb

@@ -0,0 +1,30 @@
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Resort
+  # Module containing Resort generators
+  module Generators
+
+    # Rails generator to add a migration for Resort
+    class MigrationGenerator < ActiveRecord::Generators::Base
+      # Implement the required interface for `Rails::Generators::Migration`.
+      # Taken from `ActiveRecord` code.
+      # @see http://github.com/rails/rails/blob/master/activerecord/lib/generators/active_record.rb
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          "%.3d" % (current_migration_number(dirname) + 1)
+        end
+      end
+      
+      desc "Creates a Resort migration."
+      source_root File.expand_path("../templates", __FILE__)
+
+      # Copies a migration file adding resort fields to a given model
+      def copy_migration_file
+        migration_template 'migration.rb', "db/migrate/add_resort_fields_to_#{table_name.pluralize}.rb"
+      end
+    end
+  end
+end

data/lib/generators/active_record/templates/migration.rb

@@ -0,0 +1,17 @@
+# Migration to add the necessary fields to a resorted model
+class AddResortFieldsTo<%= table_name.camelize %> < ActiveRecord::Migration
+  # Adds Resort fields, next_id and first, and indexes to a given model
+  def self.up
+    add_column :<%= table_name %>, :next_id, :integer
+    add_column :<%= table_name %>, :first,   :boolean
+    add_index :<%= table_name %>, :next_id
+    add_index :<%= table_name %>, :first
+  end
+
+  # Removes Resort fields
+  def self.down
+    remove_column :<%= table_name %>, :next_id
+    remove_column :<%= table_name %>, :first
+  end
+end
+

data/lib/resort-bjones.rb

@@ -0,0 +1 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'resort'))

data/lib/resort.rb

@@ -0,0 +1,237 @@
+require 'generators/active_record/resort_generator' if defined?(Rails)
+require 'active_record' unless defined?(ActiveRecord)
+
+# # Resort
+#
+# A tool that allows any ActiveRecord model to be sorted.
+#
+# Unlike most Rails sorting plugins (acts_as_list, etc), Resort is based
+# on linked lists rather than absolute position fields.
+#
+# @example Using Resort in an ActiveRecord model
+#     # In the migration
+#     create_table :products do |t|
+#       t.text       :name
+#       t.references :next
+#       t.boolean    :first
+#     end
+#
+#     # Model
+#     class Product < ActiveRecord::Base
+#       resort!
+#
+#       # A sortable model must implement #siblings method, which should
+#       # return and ActiveRecord::Relation with all the models to be
+#       # considered as `peers` in the list representing the sorted
+#       # products, i.e. its siblings.
+#       def siblings
+#         self.class.scoped
+#       end
+#     end
+#
+#     product = Product.create(:name => 'Bread')
+#     product.first? # => true
+#
+#     another_product = Product.create(:name => 'Milk')
+#     yet_another_product = Product.create(:name => 'Salami')
+#
+#     yet_another_product.append_to(product)
+#
+#     Product.ordered.map(&:name)
+#     # => ['Bread', 'Salami', 'Milk']
+module Resort
+  # The module encapsulating all the Resort functionality.
+  #
+  # @todo Refactor into a more OO solution, maybe implementing a LinkedList
+  #   object.
+  module Sortable
+    class << self
+      # When included, extends the includer with {ClassMethods}, and includes
+      # {InstanceMethods} in it.
+      #
+      # It also establishes the required relationships. It is necessary that
+      # the includer table has the following database columns:
+      #
+      #     t.references :next
+      #     t.boolean :first
+      #
+      # @param [ActiveRecord::Base] base the includer `ActiveRecord` model.
+      def included(base)
+        base.extend ClassMethods
+        base.send :include, InstanceMethods
+
+        base.has_one :previous, :class_name => base.name, :foreign_key => 'next_id', :inverse_of => :next
+        base.belongs_to :next, :class_name => base.name, :inverse_of => :previous
+
+        base.after_create :include_in_list!
+        base.after_destroy :delete_from_list
+      end
+    end
+
+    # Class methods to be used from the model class.
+    module ClassMethods
+      # Returns the first element of the list.
+      #
+      # @return [ActiveRecord::Base] the first element of the list.
+      def first_in_order
+        scoped.where(:first => true).first
+      end
+
+      # Returns the last element of the list.
+      #
+      # @return [ActiveRecord::Base] the last element of the list.
+      def last_in_order
+        scoped.where(:next_id => nil).first
+      end
+
+      
+      # Returns eager-loaded Components in order.
+      #
+      # OPTIMIZE: Use IdentityMap when available
+      # @return [Array<ActiveRecord::Base>] the ordered elements
+      def ordered
+        ordered_elements = []
+        elements = {}
+
+        scoped.each do |element|
+          if ordered_elements.empty? && element.first?
+            ordered_elements << element
+          else
+            elements[element.id] = element
+          end
+        end
+
+        raise "Multiple or no first items in the list where found. Consider defining a siblings method" if ordered_elements.length != 1 && elements.length > 0
+        
+        elements.length.times do
+          ordered_elements << elements[ordered_elements.last.next_id]
+        end
+        ordered_elements.compact
+      end
+    end
+
+    # Instance methods to use.
+    module InstanceMethods
+
+      # Default definition of siblings, i.e. every instance of the model.
+      #
+      # Can be overriden to specify a different scope for the siblings.
+      # For example, if we wanted to limit a products tree inside a ProductLine
+      # scope, we would do the following:
+      #
+      #     class Product < ActiveRecord::Base
+      #       belongs_to :product_line
+      #
+      #       resort!
+      #
+      #       def siblings
+      #         self.product_line.products
+      #       end
+      #
+      # This way, every product line is an independent tree of sortable
+      # products.
+      #
+      # @return [ActiveRecord::Relation] the element's siblings relation.
+      def siblings
+        self.class.scoped
+      end
+      # Includes the object in the linked list.
+      #
+      # If there are no other objects, it prepends the object so that it is
+      # in the first position. Otherwise, it appends it to the end of the
+      # empty list.
+      def include_in_list!
+        self.class.transaction do
+          self.lock!
+          _siblings.count > 0 ? last!\
+                              : prepend
+        end
+      end
+
+      # Puts the object in the first position of the list.
+      def prepend
+        self.class.transaction do
+          self.lock!
+          return if first?
+          if _siblings.count > 0
+            delete_from_list
+            old_first = _siblings.first_in_order
+            raise(ActiveRecord::RecordNotSaved) unless self.update_attribute(:next_id, old_first.id)
+            raise(ActiveRecord::RecordNotSaved) unless old_first.update_attribute(:first, false)
+          end
+          raise(ActiveRecord::RecordNotSaved) unless self.update_attribute(:first, true)
+        end
+      end
+
+      # Puts the object in the last position of the list.
+      def push
+        self.class.transaction do
+          self.lock!
+          self.append_to(_siblings.last_in_order) unless last?
+        end
+      end
+
+      # Puts the object right after another object in the list.
+      def append_to(another)
+        self.class.transaction do
+          self.lock!
+          return if another.next_id == id
+          another.lock!
+          delete_from_list
+          if self.next_id or (another && another.next_id)
+            raise(ActiveRecord::RecordNotSaved) unless self.update_attribute(:next_id, another.next_id)
+          end
+          if another
+            raise(ActiveRecord::RecordNotSaved) unless another.update_attribute(:next_id, self.id)
+          end
+        end
+      end
+
+      private
+
+      def delete_from_list
+        if first? && self.next
+          self.next.lock!
+          raise(ActiveRecord::RecordNotSaved) unless self.next.update_attribute(:first, true)
+        elsif self.previous
+          self.previous.lock!
+          p = self.previous
+          self.previous = nil unless frozen?
+          raise(ActiveRecord::RecordNotSaved) unless p.update_attribute(:next_id, self.next_id)
+        end
+        unless frozen?
+          self.first = false 
+          self.next = nil 
+          save!
+        end
+      end
+
+      def last?
+        !self.first && !self.next_id
+      end
+
+      def last!
+        self.class.transaction do
+          self.lock!
+          raise(ActiveRecord::RecordNotSaved) unless _siblings.last_in_order.update_attribute(:next_id, self.id)
+        end
+      end
+
+      def _siblings
+        table = self.class.arel_table
+        siblings.where(table[:id].not_eq(self.id))
+      end
+    end
+  end
+  # Helper class methods to be injected into ActiveRecord::Base class.
+  # They will be available to every model.
+  module ClassMethods
+    # Helper class method to include Resort::Sortable in an ActiveRecord
+    # model.
+    def resort!
+      include Sortable
+    end
+  end
+end
+
+ActiveRecord::Base.extend Resort::ClassMethods