fast_tree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ef95899f36c494fb5bc3cea8317205591f61dae7
+  data.tar.gz: f84331649e1fbf73db8853f7629ef8b7144f69a4
+SHA512:
+  metadata.gz: 7a5137010f0f12bf4e6c03543814b542d218c61fecc8aee0e886e7fc7c66a6c39d2f51b1bcd9e843ef50ed99f07333e48002859ea5412dcb8d2b2e6d6ef94f9c
+  data.tar.gz: 8a6291deac4b760f876f50f24a2fec8c65262a1bf20b60c3a67041d60d4e6cdd4e13f3b789f71782c33a2e9c16f55782aacfde2534d60a5e8e5508082d9b66fd

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2017 Chisato HASEGAWA
+
+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/README.md

@@ -0,0 +1,177 @@
+# FastTree
+
+[![CircleCI](https://circleci.com/gh/chase0213/fast_tree/tree/master.svg?style=svg)](https://circleci.com/gh/chase0213/fast_tree/tree/master)
+
+Fast and Intuitive tree structure using nested sets model.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fast_tree'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install fast_tree
+```
+
+## Usage
+
+`fast_tree` provides a generator which adds left and right pointers used in nested sets model to your model class.
+Even if you have created a class or not, execute following commands in the terminal:
+
+```bash
+$ bin/rails g fast_tree YOUR_MODEL_NAME
+```
+
+After executing the command, add following sentence into your model:
+
+```ruby
+include FastTree::Model
+```
+
+Finally, you can use several methods as class methods and instance methods.
+
+If you are interested in how it works, see the section "How It Works" below.
+
+### Create a tree
+
+To initialize tree structure, do the following:
+
+```ruby
+attributes = { name: "root node" }
+YOUR_MODEL_NAME.create_tree(attributes)
+```
+
+### Create or add child
+
+To create a new leaf under a node,
+
+```ruby
+node = YOUR_MODEL_NAME.first
+
+attributes = { name: "root node" }
+node.create_child(attributes)
+```
+
+or, to add existed node to another,
+
+```ruby
+node = YOUR_MODEL_NAME.first
+
+new_node = YOUR_MODEL_NAME.second
+node.add_child(new_node)
+```
+
+### Create or add parent
+
+To create a new parent over a node,
+
+```ruby
+node = YOUR_MODEL_NAME.first
+
+attributes = { name: "root node" }
+YOUR_MODEL_NAME.create_parent(attributes, [node])
+```
+
+or, to add existed node to another,
+
+```ruby
+node = YOUR_MODEL_NAME.first
+
+parent = YOUR_MODEL_NAME.second
+YOUR_MODEL_NAME.add_parent(parent, [node])
+```
+
+You can add/create a parent over several nodes:
+
+```ruby
+children = YOUR_MODEL_NAME.take(3)
+parent = YOUR_MODEL_NAME.last
+YOUR_MODEL_NAME.add_parent(parent, children)
+```
+
+NOTE: this method has a issue: https://github.com/chase0213/fast_tree/issues/6
+
+### Remove a node
+
+To remove a node reconstructing the tree,
+
+```ruby
+node = YOUR_MODEL_NAME.take
+node.remove
+```
+
+If you don't want to reconstruct the tree after deleting a node, do the following:
+
+```ruby
+node = YOUR_MODEL_NAME.take
+node.destroy
+```
+
+### Copy a subtree under a node
+
+To copy a subtree under a node,
+
+```ruby
+root_of_subtree = YOUR_MODEL_NAME.first
+target = YOUR_MODEL_NAME.second
+
+root_of_subtree.copy_to(targe)
+```
+
+### Move a subtree under a node
+
+To move a subtree under a node,
+
+```ruby
+root_of_subtree = YOUR_MODEL_NAME.first
+target = YOUR_MODEL_NAME.second
+
+root_of_subtree.move_to(targe)
+```
+
+
+## How It Works
+The migration file will create a migration file, such as:
+
+```ruby
+class AddFastTreeToTestTrees < ActiveRecord::Migration[5.0]
+  def self.up
+    change_table :test_trees do |t|
+      ## Pointers
+      t.integer :l_ptr
+      t.integer :r_ptr
+
+    end
+
+    add_index :test_trees, :l_ptr
+    add_index :test_trees, :r_ptr
+  end
+
+  def self.down
+    # model already existed. Please edit below which fields you would like to remove in this migration.
+  end
+end
+```
+
+, but you don't have to care what `l_ptr` and `r_ptr` are:
+tree operations are executed in methods such as `create_child` or `remove`.
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'FastTree'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/fast_tree/model.rb

@@ -0,0 +1,260 @@
+module FastTree
+  module Model
+    extend ActiveSupport::Concern
+
+    # =================
+    # Class Methods
+    # =================
+
+    module ClassMethods
+
+      # ====================
+      # structure operation
+      # ====================
+
+      def add_parent(parent, children, &block)
+        # create space for parent
+        ptrs = _create_parent_embedded_space(children)
+
+        # parent node's pointer
+        parent.l_ptr = ptrs[:l_ptr]
+        parent.r_ptr = ptrs[:r_ptr]
+        parent.save
+      end
+
+      def create_parent(attributes = {}, children, &block)
+        # create space for parent
+        ptrs = _create_parent_embedded_space(children)
+
+        # parent node's pointer
+        attributes[:l_ptr] = ptrs[:l_ptr]
+        attributes[:r_ptr] = ptrs[:r_ptr]
+
+        self.create(attributes, &block)
+      end
+
+      def create_tree(attributes={}, &block)
+        root = self.find_root
+        if root
+          root
+        else
+          attributes[:l_ptr] = 0
+          attributes[:r_ptr] = 1
+          self.create(attributes, &block)
+        end
+      end
+
+
+      def _create_parent_embedded_space(children)
+        left  = children.max {|c| c.l_ptr}.l_ptr
+        right = children.min {|c| c.r_ptr}.r_ptr
+
+        sql = <<-"EOS"
+UPDATE #{self.to_s.underscore.pluralize}
+  SET l_ptr = CASE
+                WHEN l_ptr >= #{left}
+                  AND r_ptr <= #{right}
+                  THEN l_ptr + 1
+                WHEN l_ptr > #{right}
+                  THEN l_ptr + 2
+                ELSE l_ptr
+                END,
+      r_ptr = CASE
+                WHEN l_ptr >= #{left}
+                  AND r_ptr <= #{right}
+                  THEN r_ptr + 1
+                WHEN l_ptr < #{left}
+                  AND r_ptr > #{right}
+                  THEN r_ptr + 2
+                WHEN l_ptr > #{right}
+                  THEN r_ptr + 2
+                ELSE r_ptr
+              END
+  WHERE r_ptr > #{left}
+        EOS
+
+        ActiveRecord::Base.connection.execute(sql)
+
+        # return left and right pointers between which parent is embedded
+        {l_ptr: left, r_ptr: right + 2}
+      end
+
+      # ================
+      # model operation
+      # ================
+
+      def find_root
+        self.find_by(l_ptr: 0)
+      end
+
+      def find_subtree_by_root(node)
+        l_ptr = node.l_ptr
+        r_ptr = node.r_ptr
+
+        self.where(self.arel_table[:l_ptr].gteq(l_ptr))
+            .where(self.arel_table[:r_ptr].lteq(r_ptr))
+      end
+
+      # ================
+      # for debugging
+      # ================
+
+      def print_subtree(root)
+        puts("printing sub tree for #{root.name}...")
+        subtree = find_subtree_by_root(root)
+        subtree.order(l_ptr: :asc).each do |st_node|
+          st_node.reload
+          # white spaces on the left
+          wsl = st_node.l_ptr.times.map{|s| "_"}.join('')
+          # arrows
+          ars = (st_node.r_ptr - st_node.l_ptr ).times.map{|s| "-"}.join('')
+          # white spaces on the right
+          wsr = (root.width + 2 - wsl.size - ars.size).times.map{|s| " "}.join('')
+
+          puts("#{wsl}<#{ars}>#{wsr} ... #{st_node.name}")
+        end
+        puts("done.\n")
+      end
+    end
+
+
+    #     class methods
+    # =========================================================
+    #    instance methods
+
+
+    # =================
+    # Instance Methods
+    # =================
+
+    def add_child(node)
+      # bulk update nodes by a sql query
+      _update_nodes(r_ptr, r_ptr, "r_ptr >= #{r_ptr}")
+
+      # child node's pointer
+      node.l_ptr = r_ptr
+      node.r_ptr = r_ptr + 1
+      node.save
+    end
+
+    def create_child(attributes = {}, &block)
+      # bulk update nodes by a sql query
+      _update_nodes(r_ptr, r_ptr, "r_ptr >= #{r_ptr}")
+
+      # create child
+      attributes[:l_ptr] = r_ptr
+      attributes[:r_ptr] = r_ptr + 1
+      self.class.create(attributes, &block)
+    end
+
+    def copy_to(node)
+      subtree = self.class.find_subtree_by_root(self)
+
+      # create empty space into which subtree embedded
+      _update_nodes(node.l_ptr, node.r_ptr, "r_ptr >= #{r_ptr}", width + 1)
+
+      bias = node.l_ptr + 1 - l_ptr
+      subtree.each do |st_node|
+        attributes = st_node.attributes.to_h
+        attributes.delete("id")
+        attributes["l_ptr"] = attributes["l_ptr"] + bias
+        attributes["r_ptr"] = attributes["r_ptr"] + bias
+        self.class.create(attributes)
+      end
+    end
+
+    def depth
+      path.size - 1
+    end
+
+    def move_to(node)
+      # NOTE:
+      # copy_to and remove change node ids
+      # move operation should change nothing but left and right pointers
+
+      # bind subtree to a variable
+      subtree = self.class.find_subtree_by_root(self)
+
+      # fill (virtual) empty spaces that will be created by moving subtree
+      _update_nodes(l_ptr, r_ptr, "l_ptr > #{r_ptr}", - (width + 1))
+
+      # create empty spaces under the node
+      node.reload
+      _update_nodes(node.l_ptr, node.r_ptr, "l_ptr >= #{node.l_ptr} AND r_ptr <= #{node.r_ptr}", width + 1)
+
+      # move subtree under the given node
+      bias = node.l_ptr + 1 - l_ptr
+      subtree.each do |st_node|
+        st_node.l_ptr += bias
+        st_node.r_ptr += bias
+        st_node.save
+      end
+    end
+
+    def remove
+      # remove subtree
+      n_destroyed = self.class.find_subtree_by_root(self).destroy_all
+
+      # fill empty space
+      _update_nodes(l_ptr, r_ptr, "r_ptr >= #{r_ptr}", - (width + 1))
+
+      # return count of destroyed nodes
+      n_destroyed
+    end
+
+    def path
+      self.class.where(self.class.arel_table[:l_ptr].lteq(l_ptr))
+                .where(self.class.arel_table[:r_ptr].gteq(r_ptr))
+                .order(l_ptr: :asc)
+    end
+
+    def print_subtree
+      self.class.print_subtree(self)
+    end
+
+    def width
+      r_ptr - l_ptr
+    end
+
+
+    protected
+
+      def _update_nodes(left, right, condition, diff = 2)
+        #
+        # NOTE:
+        # Due to performance reason,
+        # use raw SQL query to move nodes
+        #
+
+        sql = <<-"EOS"
+UPDATE #{self.class.to_s.underscore.pluralize}
+SET l_ptr = CASE
+              WHEN l_ptr > #{right}
+                THEN l_ptr + #{diff}
+              WHEN l_ptr > #{left}
+                AND r_ptr < #{right}
+                THEN l_ptr + #{diff - 1}
+              ELSE l_ptr
+            END,
+    r_ptr = CASE
+              WHEN l_ptr <= #{left}
+                AND r_ptr >= #{right}
+                THEN r_ptr + #{diff}
+              WHEN l_ptr > #{right}
+                THEN r_ptr + #{diff}
+              WHEN l_ptr > #{left}
+                AND r_ptr < #{right}
+                THEN r_ptr + #{diff - 1}
+              ELSE
+                r_ptr
+            END
+WHERE #{condition}
+        EOS
+
+        ActiveRecord::Base.connection.execute(sql)
+      end
+
+      class InvalidTreeStructureError < ActiveRecord::RecordInvalid; end
+
+  end
+end

data/lib/fast_tree/version.rb

@@ -0,0 +1,3 @@
+module FastTree
+  VERSION = '0.1.0'
+end

data/lib/fast_tree.rb

@@ -0,0 +1,11 @@
+require 'rails'
+
+module FastTree
+
+  # =====================================
+  # Implementation of Fast Tree Structure
+  # =====================================
+
+  autoload :Model, 'fast_tree/model'
+
+end

data/lib/generators/active_record/fast_tree_generator.rb

@@ -0,0 +1,48 @@
+require 'rails/generators/active_record'
+require 'generators/fast_tree/orm_helpers'
+
+module ActiveRecord
+  module Generators
+    class FastTreeGenerator < ActiveRecord::Generators::Base
+      argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+      include FastTree::Generators::OrmHelpers
+      source_root File.expand_path("../templates", __FILE__)
+
+      def copy_fast_tree_migration
+        if (behavior == :invoke && model_exists?) || (behavior == :revoke && migration_exists?(table_name))
+          migration_template "migration_existing.rb", "db/migrate/add_fast_tree_to_#{table_name}.rb", migration_version: migration_version
+        else
+          migration_template "migration.rb", "db/migrate/fast_tree_create_#{table_name}.rb", migration_version: migration_version
+        end
+      end
+
+      def generate_model
+        invoke "active_record:model", [name], migration: false unless model_exists? && behavior == :invoke
+      end
+
+      def migration_data
+<<RUBY
+      ## Pointers
+      t.integer :l_ptr
+      t.integer :r_ptr
+RUBY
+      end
+
+      def rails5?
+        Rails.version.start_with? '5'
+      end
+
+      def postgresql?
+        config = ActiveRecord::Base.configurations[Rails.env]
+        config && config['adapter'] == 'postgresql'
+      end
+
+     def migration_version
+       if rails5?
+         "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+       end
+     end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+class FastTreeCreate<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :<%= table_name %> do |t|
+<%= migration_data -%>
+
+<% attributes.each do |attribute| -%>
+      t.<%= attribute.type %> :<%= attribute.name %>
+<% end -%>
+
+      t.timestamps null: false
+    end
+
+    add_index :<%= table_name %>, :l_ptr
+    add_index :<%= table_name %>, :r_ptr
+  end
+end

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

@@ -0,0 +1,18 @@
+class AddFastTreeTo<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def self.up
+    change_table :<%= table_name %> do |t|
+<%= migration_data -%>
+
+<% attributes.each do |attribute| -%>
+      t.<%= attribute.type %> :<%= attribute.name %>
+<% end -%>
+    end
+
+    add_index :<%= table_name %>, :l_ptr
+    add_index :<%= table_name %>, :r_ptr
+  end
+
+  def self.down
+    # model already existed. Please edit below which fields you would like to remove in this migration.
+  end
+end

data/lib/generators/fast_tree/fast_tree_generator.rb

@@ -0,0 +1,16 @@
+require 'rails/generators/named_base'
+
+module FastTree
+  module Generators
+    class FastTreeGenerator < Rails::Generators::NamedBase
+      include Rails::Generators::ResourceHelpers
+
+      namespace "fast_tree"
+      source_root File.expand_path("../templates", __FILE__)
+
+      desc "Generates a model with the given NAME (if one does not exist) with a migration file"
+
+      hook_for :orm
+    end
+  end
+end

data/lib/generators/fast_tree/orm_helpers.rb

@@ -0,0 +1,23 @@
+module FastTree
+  module Generators
+    module OrmHelpers
+      private
+
+      def model_exists?
+        File.exist?(File.join(destination_root, model_path))
+      end
+
+      def migration_exists?(table_name)
+        Dir.glob("#{File.join(destination_root, migration_path)}/[0-9]*_*.rb").grep(/\d+_add_fast_tree_to_#{table_name}.rb$/).first
+      end
+
+      def migration_path
+        @migration_path ||= File.join("db", "migrate")
+      end
+
+      def model_path
+        @model_path ||= File.join("app", "models", "#{file_path}.rb")
+      end
+    end
+  end
+end

data/lib/tasks/fast_tree_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :fast_tree do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: fast_tree
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chisato Hasegawa
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-02-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: acts_as_tree
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: fast_tree is an implementation of tree structure using nested sets model
+email:
+- chase0213@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/fast_tree.rb
+- lib/fast_tree/model.rb
+- lib/fast_tree/version.rb
+- lib/generators/active_record/fast_tree_generator.rb
+- lib/generators/active_record/templates/migration.rb
+- lib/generators/active_record/templates/migration_existing.rb
+- lib/generators/fast_tree/fast_tree_generator.rb
+- lib/generators/fast_tree/orm_helpers.rb
+- lib/tasks/fast_tree_tasks.rake
+homepage: https://github.com/chase0213/fast_tree
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: '["Rails plugin for Fast Tree Structure", "fast_tree is an implementation
+  of tree structure using nested sets model", "MIT"]'
+test_files: []