chronic_tree 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b52c7d90e61d2f6f2c147ed874baa5c1d67f312c
+  data.tar.gz: b29cf0a5b4c9299a098902e61a3e0dba30f7f38a
+SHA512:
+  metadata.gz: 79595c974dc69193490703f08de4f2f9c099ad755d71839955c3cb734f4ea35c463649f74cf97dd07b5fb940a4a691445ac83e012a62b858af948402a74a70d1
+  data.tar.gz: e4b7b047332da17ba9b988ddbad31aac9b9671b55e60a56741269105f49247be197943e96befae32780022d8a40e7a6c5a4ef95bcb5fc5b54c48ecbf62398899

data/.gitignore

@@ -0,0 +1,19 @@
+*.rbc
+.rspec
+/tmp
+/coverage/
+/spec/tmp
+**.orig
+/pkg/*
+
+## Environment normalisation:
+/.bundle
+
+# these should all be checked in to normalise the environment:
+# Gemfile.lock, .ruby-version, .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+/*.sublime-project
+/*.sublime-workspace

data/.ruby-version

@@ -0,0 +1 @@
+2.1.1@chronic_tree

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.1.2
+  - 2.1.1
+  - 2.0.0
+env:
+  - CODECLIMATE_REPO_TOKEN=c2536dff5fa10e3c3cccd9b8dfe4b5caa73584f59c5e3ea56181cd6092dda7bc

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,87 @@
+PATH
+  remote: .
+  specs:
+    chronic_tree (1.0.0)
+      activerecord (>= 4.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (4.1.1)
+      activesupport (= 4.1.1)
+      builder (~> 3.1)
+    activerecord (4.1.1)
+      activemodel (= 4.1.1)
+      activesupport (= 4.1.1)
+      arel (~> 5.0.0)
+    activesupport (4.1.1)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    arel (5.0.1.20140414130214)
+    builder (3.2.2)
+    codeclimate-test-reporter (0.3.0)
+      simplecov (>= 0.7.1, < 1.0.0)
+    coderay (1.1.0)
+    coveralls (0.7.0)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    i18n (0.6.9)
+    json (1.8.1)
+    method_source (0.8.2)
+    mime-types (2.3)
+    minitest (5.3.4)
+    multi_json (1.10.1)
+    pry (0.10.0)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rake (10.3.2)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec (3.0.0)
+      rspec-core (~> 3.0.0)
+      rspec-expectations (~> 3.0.0)
+      rspec-mocks (~> 3.0.0)
+    rspec-core (3.0.1)
+      rspec-support (~> 3.0.0)
+    rspec-expectations (3.0.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.0.0)
+    rspec-mocks (3.0.1)
+      rspec-support (~> 3.0.0)
+    rspec-support (3.0.0)
+    simplecov (0.8.2)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    slop (3.5.0)
+    sqlite3 (1.3.9)
+    term-ansicolor (1.3.0)
+      tins (~> 1.0)
+    thor (0.19.1)
+    thread_safe (0.3.4)
+    tins (1.3.0)
+    tzinfo (1.2.1)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  chronic_tree!
+  codeclimate-test-reporter
+  coveralls
+  pry
+  rake
+  rspec (~> 3.0.0)
+  sqlite3

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Xiang Li
+
+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,278 @@
+# Chronic Tree
+
+[![GitHub version](https://badge.fury.io/gh/bigxiang%2Fchronic_tree.svg)](http://badge.fury.io/gh/bigxiang%2Fchronic_tree)
+[![Build Status](https://travis-ci.org/bigxiang/chronic_tree.svg?branch=master)](https://travis-ci.org/bigxiang/chronic_tree)
+[![Code Climate](https://codeclimate.com/github/bigxiang/chronic_tree.png)](https://codeclimate.com/github/bigxiang/chronic_tree)
+[![Coverage Status](https://coveralls.io/repos/bigxiang/chronic_tree/badge.png)](https://coveralls.io/r/bigxiang/chronic_tree)
+
+Build a tree with historical versions and multiple scopes by one model class.
+
+There are some gems for tree structures, for example: [acts_as_tree](https://github.com/amerine/acts_as_tree). They are simple and easy to use.
+
+But in some applications, we are facing more complicated cases. We probably need to build multiple trees using one model and track their histories. For example, organization tree in an ERP or CRM application. Multiple organization trees in these apps usually are created and tracked. So we can’t solve this problem only by using a ‘parent_id’. It’s why this gem has been created.
+
+This gem is compatible with Ruby 2.0+ and Rails 4.0+.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'chronic_tree'
+
+And then execute:
+
+    $ bundle
+
+Execute the installation script:
+
+    $ rails g chronic_tree:install
+
+Execute the rake command:
+
+    $ rake db:migrate
+
+## Quick Start
+
+Add a tree to your model:
+
+```ruby
+class Org < ActiveRecord::Base
+  chronic_tree
+end
+```
+
+Before travelling in the tree, using `as_tree` to initialize the tree arguments is highly recommended however the methods below would call `as_tree` implicitly if the arguments aren't set. It's somewhat dup, I am trying to simplify it, but it's the safest way to get the correct version of the tree now.
+
+```ruby
+# init a tree with current timestamp and default scope
+@org.as_tree
+
+# init a tree with the timestamp at 10 minutes ago and default scope
+@org.as_tree(10.minutes.ago)
+
+# init a tree with the timestamp at 10 minutes ago and special scope
+@org.as_tree(10.minutes.ago, 'special')
+```
+
+####Add root
+
+This method creates a root node for an empty tree.
+```ruby
+@org.add_as_root
+```
+
+####Add children
+
+This method adds a child object under itself.
+
+Create this structure:
+```ruby
+# root
+#   -- child_org
+#     -- another_child_org
+@org.add_child(@child_org)
+@child_org.add_child(@another_child_org)
+
+@org.as_tree.descendants # => [[@child_org], [@another_child_org]]
+```
+
+####Change parent
+
+You can change the parent node with another node existing in the tree.
+```ruby
+@org.as_tree.parent # => @parent
+@org.change_parent(@another_parent)
+@org.as_tree.parent # => @another_parent
+```
+
+####Remove descendants
+
+It destroys all descendant nodes.
+```ruby
+@org.remove_descendants
+```
+
+####Remove self
+
+It destroys self node and its descendant nodes.
+```ruby
+@org.remove_self
+```
+
+####Replace self by another object
+
+It’s replaced by another object. This behavior doesn't affect other tree nodes.
+```ruby
+# before replacing
+# org
+#   -- child
+
+@child.as_tree.parent # => @org
+@org.replace_by(@another_org)
+@child.as_tree.parent # => @another_org
+
+# after replacing
+# another_org
+#   -- child
+```
+
+####Get children
+
+Get all direct child objects of itself.
+```ruby
+@org.as_tree.children.each do |child_org|
+  # actions...
+  # each child org has called as_tree automatically
+  # so you can use tree traversal directly
+
+  ...
+  child_org.children
+  child_org.parent
+  child_org.root
+  ...
+end
+```
+
+####Get parent
+
+Get parent object, return nil if the parent doesn't exist.
+```ruby
+@org.as_tree.parent  # => @parent_org
+@org.as_tree.parent  # => nil if parent doesn't exist
+@org.as_tree.parent? # => alias of parent method
+```
+
+####Get root
+
+Get root object, return nil if the parent doesn't exist.
+```ruby
+@org.as_tree.root  # => @root_org
+@org.as_tree.root  # => nil if the tree is empty
+```
+
+####Get ancestors
+
+It returns a list of all parent objects of itself and order by distance to it.
+```ruby
+@org.as_tree.ancestors # => [<parent_org>, <root_org>]
+```
+
+####Get descendants
+
+It returns a list of levels. Each level is an array too and contains all objects of this level.
+```ruby
+@org.as_tree.descendants # => [[<first_level_children>], [<second_level_children>], ...]
+```
+
+It returns all descendants as a flat array at once.
+```ruby
+@org.as_tree.flat_descendants # => [<all_descendants>]
+```
+
+####Utils
+
+```ruby
+@org.tree_empty?     # => Return true if the tree is empty.
+@org.tree_empty?(10.minutes.ago, 'special')
+@org.existed_in_tree?   # => Return true if @org exists in the tree.
+@org.existed_in_tree?(10.minutes.ago, 'special')
+```
+These two methods wouldn't call `as_tree`.
+
+## Advanced
+
+The most important part of this gem is playing with historical versions and multiple scopes in one tree.
+
+####Play with history
+
+If you had a tree 1 day ago:
+
+```
+root
+  -- child1
+    -- child1.1
+  -- child2
+    -- child2.1
+```
+
+And change to this version now:
+
+```
+root
+  -- child1
+  -- child2
+    -- child2.1
+      -- child2.1.1
+```
+
+You can easily get the correct version of the tree at any time.
+
+```ruby
+root.as_tree.children # => [child1, child2]
+child1.as_tree.children # => []
+child2.as_tree.flat_descendants # =? [child2.1, child2.1.1]
+
+root.as_tree(1.days.ago).children # => [child1, child2]
+child1.as_tree(1.days.ago).children # => [child1.1]
+child2.as_tree(1.days.ago).flat_descendants # =? [child2.1]
+```
+
+####Play with multiple scopes
+
+If you have two scopes in one tree at the same time:
+
+```
+default scope:
+root
+  -- child1
+  -- child2
+    -- child2.1
+
+special scope:
+another_root
+  -- child2
+    -- child2.1
+    -- child2.2
+  -- child3
+```
+
+You can switch between two scopes:
+
+```ruby
+child2.as_tree.parent # => root
+child2.as_tree.children # => [child2.1]
+
+child2.as_tree('special').parent # => another_root
+child2.as_tree('special').children # => [child2.1, child2.2]
+```
+
+
+####Using low-level relations
+
+They usually don't need to be used. All tree traversal methods are based on these relations, they just return ActiveRecord::Relation for chronic_tree_elements table, so you can chain the method as you want.
+
+You must pass timestamp and scope name explicitly in these relations.
+
+```ruby
+# Return children elements
+root.children_relation(Time.now, 'default')
+
+# Return parent elements
+root.parent_relation(Time.now, 'default')
+
+# Return descendant elements
+root.descendants_relation(Time.now, 'default')
+
+# Return ancestor elements
+root.ancestors_relation(Time.now, 'default')
+```
+
+## Contributing
+
+Any feedback or improvement is appreciated!
+
+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

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/chronic_tree.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'chronic_tree/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "chronic_tree"
+  spec.version       = ChronicTree::VERSION
+  spec.authors       = ["bigxiang"]
+  spec.email         = ["bigxiang@gmail.com"]
+  spec.description   = %q{Build a tree with multiple versions and scopes by one model class.}
+  spec.summary       = %q{Build a tree with multiple versions and scopes by one model class.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 3.0.0"
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "codeclimate-test-reporter"
+  spec.add_development_dependency "coveralls"
+
+  spec.add_dependency "activerecord", ">= 4.0.0"
+end