rubytree 0.8.3 → 0.9.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/API-CHANGES.rdoc +51 -20
- data/Gemfile +5 -1
- data/Gemfile.lock +14 -13
- data/History.rdoc +110 -42
- data/LICENSE.md +37 -0
- data/README.md +276 -0
- data/Rakefile +53 -28
- data/TAGS +218 -0
- data/TODO.org +114 -42
- data/examples/example_basic.rb +53 -0
- data/lib/tree.rb +357 -529
- data/lib/tree/binarytree.rb +76 -36
- data/lib/tree/utils/camel_case_method_handler.rb +78 -0
- data/lib/tree/utils/json_converter.rb +125 -0
- data/lib/tree/utils/metrics_methods.rb +172 -0
- data/lib/tree/utils/tree_merge_handler.rb +118 -0
- data/lib/tree/utils/utils.rb +41 -0
- data/lib/tree/version.rb +3 -3
- data/test/test_binarytree.rb +46 -1
- data/test/test_subclassed_node.rb +70 -0
- data/test/test_thread_and_fiber.rb +88 -0
- data/test/test_tree.rb +209 -35
- metadata +85 -82
- data/.dir-locals.el +0 -5
- data/COPYING.rdoc +0 -32
- data/README.rdoc +0 -219
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: ac2fe1bd84044b1981f67b94bbf751f144d96afb
|
4
|
+
data.tar.gz: 20ed672c1300c42447b483919a47fe8128d8ad05
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: eb12ccc374632de68c78121c70a8a0c3c7e42e3c062c78a179df542d2e459928464c0404a546ab14f06394c0db8b73e5baf21818a87f2b7dcddf5e58b37a783f
|
7
|
+
data.tar.gz: 1249c16cf513a6f44e713338e7bd1eb38a8d3ee554d0584126fe093bc89013ca9efc06516be82cada869479da93d23aef84fe070f0efa94261255a5bb7525d01
|
data/API-CHANGES.rdoc
CHANGED
@@ -2,51 +2,82 @@
|
|
2
2
|
|
3
3
|
= API Changes in RubyTree
|
4
4
|
|
5
|
-
This file documents various API level changes that have been made to the
|
5
|
+
This file documents various API level changes that have been made to the
|
6
|
+
RubyTree package.
|
6
7
|
|
7
|
-
Note: API level changes are expected to reduce dramatically after the 1.x
|
8
|
-
|
8
|
+
Note: API level changes are expected to reduce dramatically after the 1.x
|
9
|
+
release. In most cases, an alternative will be provided to ensure relatively
|
10
|
+
smooth transition to the new APIs.
|
9
11
|
|
10
|
-
== Release
|
12
|
+
== Release 0.9.0 Changes
|
13
|
+
|
14
|
+
- New post-ordered traversal via the {Tree::TreeNode#postordered_each} method.
|
15
|
+
|
16
|
+
- The Binary Tree implementation now supports in-order traversal via the
|
17
|
+
{Tree::BinaryTreeNode#inordered_each} method.
|
18
|
+
|
19
|
+
- RubyTree now mixes in the {http://ruby-doc.org/core-1.8.7/Comparable.html
|
20
|
+
Comparable} module.
|
21
|
+
|
22
|
+
- The traversal methods ({Tree::TreeNode#each},
|
23
|
+
{Tree::TreeNode#preordered_each}, {Tree::TreeNode#postordered_each} and
|
24
|
+
{Tree::TreeNode#breadth_each}) now correctly return an
|
25
|
+
{http://ruby-doc.org/core-1.8.7/Enumerable.html Enumerator} as the
|
26
|
+
return value when no block is given, and return the receiver node if a block was
|
27
|
+
provided. This is consistent with how the standard Ruby collections work.
|
28
|
+
|
29
|
+
== Release 0.8.3 Changes
|
11
30
|
|
12
31
|
- {Tree::TreeNode#siblings} will now return an empty array for the root node.
|
13
32
|
|
14
33
|
== Release 0.8.0 Changes
|
15
34
|
|
16
|
-
- Added the ability to specify an optional insertion position in the
|
17
|
-
code contributed by Dirk.
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
|
35
|
+
- Added the ability to specify an optional insertion position in the
|
36
|
+
{Tree::TreeNode#add} method. Idea and original code contributed by Dirk.
|
37
|
+
|
38
|
+
- Added a new method {Tree::TreeNode#detached_subtree_copy} to allow cloning
|
39
|
+
the entire tree. This method is also aliased to {Tree::TreeNode#dup}. Idea
|
40
|
+
and original code contributed by Vincenzo Farruggia.
|
41
|
+
|
42
|
+
- Converted all CamelCase method names to the canonical ruby_method_names
|
43
|
+
(underscore separated). The CamelCase methods can still be invoked, but will
|
44
|
+
throw a Deprecated warning.
|
22
45
|
|
23
46
|
== Release 0.7.0 Changes
|
24
47
|
|
25
|
-
- Converted all exceptions thrown on invalid method arguments to from
|
26
|
-
following methods:
|
48
|
+
- Converted all exceptions thrown on invalid method arguments to from
|
49
|
+
'RuntimeError' to 'ArgumentError'. This impacts the following methods:
|
27
50
|
|
28
51
|
- {Tree::TreeNode#initialize}
|
29
52
|
- {Tree::TreeNode#add}
|
30
53
|
- {Tree::TreeNode#[]}
|
31
54
|
- {Tree::BinaryTreeNode#add}
|
32
55
|
|
33
|
-
- Added {Tree::TreeNode#level} as an alias for
|
56
|
+
- Added {Tree::Utils::TreeMetricsHandler#level Tree::TreeNode#level} as an alias for
|
57
|
+
{Tree::Utils::TreeMetricsHandler#node_depth Tree::TreeNode#node_depth}
|
34
58
|
|
35
|
-
- Added new methods {Tree::
|
59
|
+
- Added new methods {Tree::Utils::TreeMetricsHandler#in_degree
|
60
|
+
Tree::TreeNode#in_degree} and {Tree::Utils::TreeMetricsHandler#out_degree Tree::TreeNode#out_degree}
|
61
|
+
to report the node's degree stats
|
36
62
|
|
37
63
|
- {Tree::TreeNode#is_only_child?} now returns +true+ for a root node.
|
38
64
|
|
39
|
-
- {Tree::TreeNode#next_sibling} and {Tree::TreeNode#previous_sibling} now
|
65
|
+
- {Tree::TreeNode#next_sibling} and {Tree::TreeNode#previous_sibling} now
|
66
|
+
return +nil+ for a root node.
|
40
67
|
|
41
|
-
- {Tree::TreeNode#add} and {Tree::TreeNode#<<} now throw an ArgumentError
|
68
|
+
- {Tree::TreeNode#add} and {Tree::TreeNode#<<} now throw an ArgumentError
|
69
|
+
exception if a +nil+ node is passed as an argument.
|
42
70
|
|
43
|
-
- Added new methods {Tree::
|
44
|
-
|
71
|
+
- Added new methods {Tree::Utils::JSONConverter#to_json Tree::TreeNode#to_json} and
|
72
|
+
{Tree::Utils::JSONConverter::ClassMethods#json_create Tree::TreeNode#json_create} to
|
73
|
+
convert to/from the JSON format. Thanks to
|
74
|
+
Dirk[http://github.com/railsbros-dirk] for this change.
|
45
75
|
|
46
76
|
== Release 0.6.1 Changes
|
47
77
|
|
48
|
-
- Deprecated the {Tree::
|
49
|
-
|
78
|
+
- Deprecated the {Tree::Utils::TreeMetricsHandler#depth} method as it was returning an incorrect
|
79
|
+
depth value. Have introduced a new replacement method
|
80
|
+
{Tree::Utils::TreeMetricsHandler#node_depth} which returns the correct result.
|
50
81
|
|
51
82
|
# Local Variables:
|
52
83
|
# mode: rdoc
|
data/Gemfile
CHANGED
data/Gemfile.lock
CHANGED
@@ -1,28 +1,29 @@
|
|
1
1
|
PATH
|
2
2
|
remote: .
|
3
3
|
specs:
|
4
|
-
rubytree (0.
|
5
|
-
json (
|
6
|
-
structured_warnings (
|
4
|
+
rubytree (0.9.0)
|
5
|
+
json (~> 1.8)
|
6
|
+
structured_warnings (~> 0.1)
|
7
7
|
|
8
8
|
GEM
|
9
|
-
remote:
|
9
|
+
remote: https://rubygems.org/
|
10
10
|
specs:
|
11
|
-
json (1.
|
12
|
-
rake (
|
13
|
-
|
11
|
+
json (1.8.1)
|
12
|
+
rake (10.1.1)
|
13
|
+
rdoc (4.1.0)
|
14
14
|
rtags (0.98)
|
15
15
|
rtagstask (0.0.4)
|
16
16
|
rtags (> 0.0.0)
|
17
|
-
structured_warnings (0.1.
|
18
|
-
yard (0.8.
|
17
|
+
structured_warnings (0.1.4)
|
18
|
+
yard (0.8.7.3)
|
19
19
|
|
20
20
|
PLATFORMS
|
21
21
|
ruby
|
22
22
|
|
23
23
|
DEPENDENCIES
|
24
|
-
|
25
|
-
|
26
|
-
|
24
|
+
bundler (~> 1.5)
|
25
|
+
rake (~> 10.1)
|
26
|
+
rdoc (~> 4.1)
|
27
|
+
rtagstask (~> 0.0)
|
27
28
|
rubytree!
|
28
|
-
yard (
|
29
|
+
yard (~> 0.8)
|
data/History.rdoc
CHANGED
@@ -2,92 +2,155 @@
|
|
2
2
|
|
3
3
|
= History of Changes
|
4
4
|
|
5
|
-
=== 0.
|
5
|
+
=== 0.9.0 / 2013-12-31
|
6
|
+
|
7
|
+
This is a feature and bug-fix release.
|
8
|
+
|
9
|
+
==== The Features
|
10
|
+
|
11
|
+
* Rubytree now supports +postordered+ traversal via the {Tree::TreeNode#postordered_each} method. Thanks to
|
12
|
+
to {https://github.com/pdecourcel Paul de Courcel} for this.
|
13
|
+
|
14
|
+
* The Binary tree now supports +inorder+ traversal via the
|
15
|
+
{Tree::BinaryTreeNode#inordered_each} method.
|
16
|
+
|
17
|
+
* Ability to merge in another tree at a chosen node, or merge two trees to
|
18
|
+
create a third tree. Thanks to {https://github.com/dazoakley Darren Oakley}
|
19
|
+
for this ({https://github.com/evolve75/RubyTree/pull/2 pull request #2})
|
20
|
+
|
21
|
+
* RubyTree now mixes in the {http://ruby-doc.org/core-1.8.7/Comparable.html
|
22
|
+
Comparable} module.
|
23
|
+
|
24
|
+
==== The Fixes
|
25
|
+
|
26
|
+
* (Partial) fix for preventing cyclic graphs in the tree
|
27
|
+
|
28
|
+
* Refactored the {Tree::TreeNode#each} method to prevent stack errors while navigating
|
29
|
+
deep trees ({https://github.com/evolve75/RubyTree/issues/12 issue #12})
|
30
|
+
|
31
|
+
* Check to ensure that the added node's name is unique to the destination tree
|
32
|
+
({https://github.com/evolve75/RubyTree/pull/9 merge #9}). Thanks to
|
33
|
+
{https://github.com/ysf Youssef Rebahi-Gilbert} for the idea and the initial
|
34
|
+
code
|
35
|
+
|
36
|
+
* Fix for {issue 23}[https://github.com/evolve75/RubyTree/issues/23], where the
|
37
|
+
tree traversal on a binary tree would fail if the _left_ child was +nil+
|
38
|
+
|
39
|
+
* The traversal methods ({Tree::TreeNode#each},
|
40
|
+
{Tree::TreeNode#preordered_each}, {Tree::TreeNode#postordered_each} and
|
41
|
+
{Tree::TreeNode#breadth_each}) now correctly return an
|
42
|
+
{http://ruby-doc.org/core-1.8.7/Enumerable.html Enumerator} as the
|
43
|
+
return value when no block is given, and return the receiver node if a block was
|
44
|
+
provided. This is consistent with how the standard Ruby collections work.
|
45
|
+
|
46
|
+
==== Other Changes
|
47
|
+
|
48
|
+
* Structural changes in the code to refactor out the non-core functions into
|
49
|
+
modules (mostly by extracting out non-core code as mixins).
|
50
|
+
|
51
|
+
* Significant refactoring of the documentation. The {http://yardoc.org Yardoc}
|
52
|
+
tags are now extensively used.
|
53
|
+
|
54
|
+
* Basic support built-in for including example code in the Gem. This will be
|
55
|
+
fully expanded in the next release.
|
56
|
+
|
57
|
+
* Various changes to the {http://bundler.io bundler}, {https://travis-ci.org
|
58
|
+
travis-ci} and other Rakefile related changes.
|
59
|
+
|
60
|
+
=== 0.8.3 / 2012-08-21
|
6
61
|
|
7
62
|
This is a primarily a bug-fix release, with some packaging changes.
|
8
63
|
|
9
|
-
* Have removed the dependency on Hoe.
|
64
|
+
* Have removed the dependency on Hoe[https://github.com/seattlerb/hoe]. The
|
65
|
+
build is now vanilla
|
66
|
+
{gemspec}[http://guides.rubygems.org/specification-reference/] based.
|
10
67
|
|
11
68
|
* Included support for {gem-testers}[http://test.rubygems.org/].
|
12
69
|
|
13
70
|
* Included support for {Bundler}[http://gembundler.com/].
|
14
71
|
|
15
|
-
* Implemented the
|
72
|
+
* Implemented the {Tree::Utils::JSONConverter#as_json} method to support Rails' JSON encoding,
|
16
73
|
by pulling in the changes by Eric Cline (https://github.com/escline).
|
17
74
|
|
18
75
|
* Partial fix for {Github Bug
|
19
|
-
#5}[https://github.com/evolve75/RubyTree/issues/5].
|
76
|
+
#5}[https://github.com/evolve75/RubyTree/issues/5]. This is to
|
20
77
|
prevent infinite looping is an existing node is added again
|
21
78
|
elsewhere in the tree.
|
22
79
|
|
23
80
|
* Fixed the issue with using +integers+ as node names, and its
|
24
|
-
interaction with the +TreeNode#[]+ access method {Github Bug
|
81
|
+
interaction with the +Tree::TreeNode#[]+ access method as documented in {Github Bug
|
25
82
|
#6}[https://github.com/evolve75/RubyTree/issues/6].
|
26
83
|
|
27
84
|
* Clarified the need to have unique node names {Github Bug
|
28
85
|
#7}[https://github.com/evolve75/RubyTree/issues/7] (documentation).
|
29
86
|
|
30
|
-
* Fixed
|
87
|
+
* Fixed {Tree::TreeNode#siblings} method to return an empty array for the root node as
|
31
88
|
well (it returned +nil+ earlier).
|
32
89
|
|
33
90
|
=== 0.8.2 / 2011-12-15
|
34
91
|
|
35
|
-
* Minor bug-fix release to address bug #1215 (Tree::TreeNode#to_s
|
36
|
-
breaks if
|
92
|
+
* Minor bug-fix release to address bug #1215 ({Tree::TreeNode#to_s}
|
93
|
+
breaks if +@content+ or +@parent.name+ is not a string).
|
37
94
|
|
38
95
|
=== 0.8.1 / 2010-10-02
|
39
96
|
|
40
|
-
* This is the public release of R0.8.0
|
41
|
-
Note that R0.8.0 will not be released separately as a publicly
|
42
|
-
available Rubygem. All changes as listed for R0.8.0 are available in
|
97
|
+
* This is the public release of +R0.8.0+, with additional bug-fixes.
|
98
|
+
Note that +R0.8.0+ will not be released separately as a publicly
|
99
|
+
available Rubygem. All changes as listed for +R0.8.0+ are available in
|
43
100
|
this release.
|
44
101
|
|
45
|
-
* The main change in R0.8.0
|
46
|
-
method names to snake_case.
|
102
|
+
* The main change in +R0.8.0+/+R0.8.1+ is conversion of all CamelCase
|
103
|
+
method names to snake_case. The old CamelCase method names will
|
47
104
|
still work (to ensure backwards compatibility), but will also
|
48
105
|
display a warning.
|
49
106
|
|
50
|
-
* The TreeNode#add method now accepts an optional child insertion
|
107
|
+
* The {Tree::TreeNode#add} method now accepts an optional child insertion
|
51
108
|
point.
|
52
109
|
|
53
110
|
* The subtree from the current node can now be cloned in its entirety
|
54
|
-
using the
|
111
|
+
using the {Tree::TreeNode#detached_subtree_copy} method.
|
55
112
|
|
56
|
-
* A major bug-fix for bug #28613 which impacted the Binarytree
|
57
|
-
implementation. See
|
58
|
-
http://rubyforge.org/tracker/index.php?func=detail&aid=28613&group_id=1215&atid=4793
|
59
|
-
for details.
|
113
|
+
* A major bug-fix for {bug #28613}[http://rubyforge.org/tracker/index.php?func=detail&aid=28613&group_id=1215&atid=4793] which impacted the Binarytree implementation.
|
60
114
|
|
61
|
-
* Minor code re-factoring driven by the code-smell checks using reek.
|
115
|
+
* Minor code re-factoring driven by the code-smell checks using {reek}[https://github.com/troessner/reek].
|
62
116
|
|
63
|
-
* Inclusion of the
|
117
|
+
* Inclusion of the +reek+ code-smell detection tool in the Rakefile.
|
64
118
|
|
65
119
|
=== 0.8.0 / 2010-05-04
|
66
120
|
|
67
|
-
* Updated the
|
121
|
+
* Updated the {Tree::TreeNode#add} method to allow the optional specification of an insertion
|
122
|
+
position in the child array.
|
68
123
|
|
69
|
-
* Added a new method
|
124
|
+
* Added a new method {Tree::TreeNode#detached_subtree_copy} to allow cloning the entire tree
|
125
|
+
(this method is also aliased as +dup+).
|
70
126
|
|
71
|
-
* Converted all CamelCase method names to the canonical ruby_method_names
|
72
|
-
|
73
|
-
|
127
|
+
* Converted all +CamelCase+ method names to the canonical +ruby_method_names+
|
128
|
+
(underscore separated). The +CamelCase+ methods _can still_ be invoked, but will
|
129
|
+
throw a {http://rug-b.rubyforge.org/structured_warnings/rdoc/ Deprecated warning}. The support for old CamelCase methods will go away
|
130
|
+
some time in the future, so the user is advised to convert all current method
|
131
|
+
invocations to the new names.
|
74
132
|
|
75
133
|
=== 0.7.0 / 2010-05-03
|
76
134
|
|
77
135
|
* Added new methods to report the degree statistics of a node.
|
78
136
|
|
79
|
-
* Added a convenience method alias
|
137
|
+
* Added a convenience method alias {Tree::Utils::TreeMetricsHandler#level Tree::TreeNode#level} to +nodeDepth+.
|
80
138
|
|
81
|
-
* Converted the exceptions thrown on invalid arguments to
|
139
|
+
* Converted the exceptions thrown on invalid arguments to
|
140
|
+
{http://www.ruby-doc.org/core-2.0.0/ArgumentError.html ArgumentError}
|
141
|
+
instead of {http://www.ruby-doc.org/core-2.0.0/RuntimeError.html RuntimeError}.
|
82
142
|
|
83
|
-
* Converted the documentation to Yard format.
|
143
|
+
* Converted the documentation to {http://yardoc.org Yard} format.
|
84
144
|
|
85
|
-
* Added new methods for converting from/to JSON formats.
|
86
|
-
|
145
|
+
* Added new methods for converting from/to {http://www.json.org JSON} formats. Thanks to Dirk
|
146
|
+
Breuer[http://github.com/railsbros-dirk] for this
|
147
|
+
fork[http://github.com/galaxycats/].
|
87
148
|
|
88
|
-
* Added a separate API-CHANGES documentation file.
|
149
|
+
* Added a separate {file:API-CHANGES.rdoc} documentation file.
|
89
150
|
|
90
|
-
* Added fixes for root related edge conditions to
|
151
|
+
* Added fixes for root related edge conditions to {Tree::TreeNode#is_only_child?
|
152
|
+
isOnlyChild?}, {Tree::TreeNode#next_sibling nextSibling},
|
153
|
+
{Tree::TreeNode#previous_sibling previousSibling} and {Tree::TreeNode#remove! remove!} methods.
|
91
154
|
|
92
155
|
* Removed the 'ChangeLog' file as this can now be generated from the git logs.
|
93
156
|
|
@@ -99,17 +162,21 @@ This is a primarily a bug-fix release, with some packaging changes.
|
|
99
162
|
|
100
163
|
=== 0.6.1 / 2010-01-04
|
101
164
|
|
102
|
-
* Changed the hard-dependency on the 'structured_warnings' RubyGem to a
|
103
|
-
|
104
|
-
|
105
|
-
|
165
|
+
* Changed the hard-dependency on the 'structured_warnings' RubyGem to a
|
166
|
+
soft-dependency - which lets Rubytree still work if this RubyGem is not
|
167
|
+
available. The rationale for this is that we should not require the user to
|
168
|
+
install a separate library just for one single edge-case function (in this
|
169
|
+
case, to indicate a deprecated method). However, if the library _is_ available
|
170
|
+
on the user's system, then it will get used.
|
106
171
|
|
107
172
|
=== 0.6.0 / 2010-01-03
|
108
173
|
|
109
|
-
* Fixed the
|
110
|
-
|
174
|
+
* Fixed the
|
175
|
+
bug#22535[http://rubyforge.org/tracker/index.php?func=detail&aid=22535&group_id=1215&atid=4793]
|
176
|
+
where the {Tree::Utils::TreeMetricsHandler#depth Tree::TreeNode#depth} method was actually returning height+1 (not the depth).
|
111
177
|
|
112
|
-
* Marked the Tree::TreeNode#depth method as *deprecated* (and introduced the
|
178
|
+
* Marked the {Tree::Utils::TreeMetricsHandler#depth Tree::TreeNode#depth} method as *deprecated* (and introduced the
|
179
|
+
run-time dependency on
|
113
180
|
structured-warnings[http://github.com/schmidt/structured_warnings] gem).
|
114
181
|
|
115
182
|
=== 0.5.3 / 2009-12-31
|
@@ -120,7 +187,7 @@ This is a primarily a bug-fix release, with some packaging changes.
|
|
120
187
|
|
121
188
|
=== 0.5.2 / 2007-12-21
|
122
189
|
|
123
|
-
* Added more test cases and enabled ZenTest compatibility for the test case
|
190
|
+
* Added more test cases and enabled {https://github.com/seattlerb/zentest ZenTest} compatibility for the test case
|
124
191
|
names.
|
125
192
|
|
126
193
|
=== 0.5.1 / 2007-12-20
|
@@ -133,7 +200,8 @@ This is a primarily a bug-fix release, with some packaging changes.
|
|
133
200
|
|
134
201
|
=== 0.4.3 / 2007-10-09
|
135
202
|
|
136
|
-
* Changes to the build mechanism (now uses
|
203
|
+
* Changes to the build mechanism (now uses
|
204
|
+
{http://www.zenspider.com/projects/hoe.html Hoe}).
|
137
205
|
|
138
206
|
=== 0.4.2 / 2007-10-01
|
139
207
|
|
data/LICENSE.md
ADDED
@@ -0,0 +1,37 @@
|
|
1
|
+
[RubyTree][] is licensed under the [BSD][] license.
|
2
|
+
|
3
|
+
Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014
|
4
|
+
Anupam Sengupta (<anupamsg@gmail.com>).
|
5
|
+
|
6
|
+
All rights reserved.
|
7
|
+
|
8
|
+
Redistribution and use in source and binary forms, with or without
|
9
|
+
modification, are permitted provided that the following conditions are met:
|
10
|
+
|
11
|
+
- Redistributions of source code must retain the above copyright notice, this
|
12
|
+
list of conditions and the following disclaimer.
|
13
|
+
|
14
|
+
- Redistributions in binary form must reproduce the above copyright notice,
|
15
|
+
this list of conditions and the following disclaimer in the documentation
|
16
|
+
and/or other materials provided with the distribution.
|
17
|
+
|
18
|
+
- Neither the name of the organization nor the names of its contributors may be
|
19
|
+
used to endorse or promote products derived from this software without
|
20
|
+
specific prior written permission.
|
21
|
+
|
22
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
23
|
+
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
24
|
+
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
25
|
+
A PARTICULAR PURPOSE ARE DISCLAIMED.
|
26
|
+
|
27
|
+
IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
|
28
|
+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
29
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
|
30
|
+
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
31
|
+
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
|
32
|
+
IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
|
33
|
+
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
|
34
|
+
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
35
|
+
|
36
|
+
[BSD]: http://opensource.org/licenses/bsd-license.php "BSD License"
|
37
|
+
[RubyTree]: http://rubytree.rubyforge.org/ "RubyTree Home Page"
|
data/README.md
ADDED
@@ -0,0 +1,276 @@
|
|
1
|
+
<!--
|
2
|
+
README.md
|
3
|
+
|
4
|
+
Copyright (C) 2014 Anupam Sengupta (anupamsg@gmail.com)
|
5
|
+
|
6
|
+
-->
|
7
|
+
# **RubyTree** #
|
8
|
+
|
9
|
+
[![Gem Version](https://badge.fury.io/rb/rubytree.png)](http://badge.fury.io/rb/rubytree)
|
10
|
+
[![Travis Build Status](https://secure.travis-ci.org/evolve75/RubyTree.png)](http://travis-ci.org/evolve75/rubytree)
|
11
|
+
[![Dependency Status](https://gemnasium.com/evolve75/RubyTree.png)](https://gemnasium.com/evolve75/RubyTree)
|
12
|
+
[![Code Climate](https://codeclimate.com/github/evolve75/RubyTree.png)](https://codeclimate.com/github/evolve75/RubyTree)
|
13
|
+
[![Coverage Status](https://coveralls.io/repos/evolve75/RubyTree/badge.png)](https://coveralls.io/r/evolve75/RubyTree)
|
14
|
+
[![githalytics.com alpha](https://cruel-carlota.pagodabox.com/473b881f1075bf9f255f0181dde6068f)](http://githalytics.com/evolve75/RubyTree)
|
15
|
+
|
16
|
+
## DESCRIPTION: ##
|
17
|
+
|
18
|
+
**RubyTree** is a pure Ruby implementation of the generic
|
19
|
+
[tree data structure][tree_data_structure]. It provides a node-based model to
|
20
|
+
store named nodes in the tree, and provides simple APIs to access, modify and
|
21
|
+
traverse the structure.
|
22
|
+
|
23
|
+
The implementation is *node-centric*, where individual nodes in the tree are the
|
24
|
+
primary structural elements. All common tree-traversal methods ([pre-order][],
|
25
|
+
[post-order][], and [breadth-first][]) are supported.
|
26
|
+
|
27
|
+
The library mixes in the [Enumerable][] and [Comparable][] modules to allow access
|
28
|
+
to the tree as a standard collection (iteration, comparison, etc.).
|
29
|
+
|
30
|
+
A [Binary tree][] is also provided, which provides the [in-order][] traversal in
|
31
|
+
addition to the other methods.
|
32
|
+
|
33
|
+
**RubyTree** supports importing from, and exporting to [JSON][], and also supports
|
34
|
+
the Ruby's standard object [marshaling][].
|
35
|
+
|
36
|
+
This is a [BSD licensed][BSD] open source project, and is hosted at
|
37
|
+
[github.com/evolve75/RubyTree][rt@github], and is available as a standard gem from
|
38
|
+
[rubygems.org/gems/rubytree][rt_gem].
|
39
|
+
|
40
|
+
The home page for **RubyTree** is at [rubytree.rubyforge.org][rt_site].
|
41
|
+
|
42
|
+
## WHAT'S NEW: ##
|
43
|
+
|
44
|
+
See [History](./History.rdoc) for the detailed Changelog.
|
45
|
+
|
46
|
+
See [API-CHANGES](./API-CHANGES.rdoc) for the detailed description of
|
47
|
+
API level changes.
|
48
|
+
|
49
|
+
## GETTING STARTED: ##
|
50
|
+
|
51
|
+
This is a basic usage example of the library to create and manipulate a tree.
|
52
|
+
See the [API][rt_doc] documentation for more details.
|
53
|
+
|
54
|
+
```ruby
|
55
|
+
#!/usr/bin/env ruby
|
56
|
+
#
|
57
|
+
# example_basic.rb:: Basic usage of the tree library.
|
58
|
+
#
|
59
|
+
# Author: Anupam Sengupta
|
60
|
+
# Time-stamp: <2013-12-28 12:14:20 anupam>
|
61
|
+
# Copyright (C) 2013 Anupam Sengupta <anupamsg@gmail.com>
|
62
|
+
#
|
63
|
+
# The following example implements this tree structure:
|
64
|
+
#
|
65
|
+
# +------------+
|
66
|
+
# | ROOT |
|
67
|
+
# +-----+------+
|
68
|
+
# +-------------+------------+
|
69
|
+
# | |
|
70
|
+
# +-------+-------+ +-------+-------+
|
71
|
+
# | CHILD 1 | | CHILD 2 |
|
72
|
+
# +-------+-------+ +---------------+
|
73
|
+
# |
|
74
|
+
# |
|
75
|
+
# +-------+-------+
|
76
|
+
# | GRANDCHILD 1 |
|
77
|
+
# +---------------+
|
78
|
+
|
79
|
+
# ..... Example starts.
|
80
|
+
require 'tree' # Load the library
|
81
|
+
|
82
|
+
# ..... Create the root node first. Note that every node has a name and an optional content payload.
|
83
|
+
root_node = Tree::TreeNode.new("ROOT", "Root Content")
|
84
|
+
root_node.print_tree
|
85
|
+
|
86
|
+
# ..... Now insert the child nodes. Note that you can "chain" the child insertions for a given path to any depth.
|
87
|
+
root_node << Tree::TreeNode.new("CHILD1", "Child1 Content") << Tree::TreeNode.new("GRANDCHILD1", "GrandChild1 Content")
|
88
|
+
root_node << Tree::TreeNode.new("CHILD2", "Child2 Content")
|
89
|
+
|
90
|
+
# ..... Lets print the representation to stdout. This is primarily used for debugging purposes.
|
91
|
+
root_node.print_tree
|
92
|
+
|
93
|
+
# ..... Lets directly access children and grandchildren of the root. The can be "chained" for a given path to any depth.
|
94
|
+
child1 = root_node["CHILD1"]
|
95
|
+
grand_child1 = root_node["CHILD1"]["GRANDCHILD1"]
|
96
|
+
|
97
|
+
# ..... Now lets retrieve siblings of the current node as an array.
|
98
|
+
siblings_of_child1 = child1.siblings
|
99
|
+
|
100
|
+
# ..... Lets retrieve immediate children of the root node as an array.
|
101
|
+
children_of_root = root_node.children
|
102
|
+
|
103
|
+
# ..... This is a depth-first and L-to-R pre-ordered traversal.
|
104
|
+
root_node.each { |node| node.content.reverse }
|
105
|
+
|
106
|
+
# ..... Lets remove a child node from the root node.
|
107
|
+
root_node.remove!(child1)
|
108
|
+
```
|
109
|
+
|
110
|
+
This example can also be found at
|
111
|
+
[examples/example_basic.rb](examples/example_basic.rb).
|
112
|
+
|
113
|
+
## REQUIREMENTS: ##
|
114
|
+
|
115
|
+
* [Ruby][] 1.8.x, 1.9.x, 2.0.x, or 2.1.0x.
|
116
|
+
|
117
|
+
|
118
|
+
* Run-time Dependencies:
|
119
|
+
* [structured_warnings][]
|
120
|
+
* [JSON][] for converting to/from the JSON format
|
121
|
+
|
122
|
+
|
123
|
+
* Development dependencies (not required for installing the gem):
|
124
|
+
* [Bundler][] for creating the stable build environment
|
125
|
+
* [Rake][] for building the package
|
126
|
+
* [Yard][] for the documentation
|
127
|
+
|
128
|
+
## INSTALL: ##
|
129
|
+
|
130
|
+
To install the [gem][rt_gem], run this command from a terminal/shell:
|
131
|
+
|
132
|
+
$ gem install rubytree
|
133
|
+
|
134
|
+
This should install the gem file for **RubyTree**. Note that you might need to have
|
135
|
+
super-user privileges (root/sudo) to successfully install the gem.
|
136
|
+
|
137
|
+
### Installing from the tgz/zip file ###
|
138
|
+
|
139
|
+
**RubyTree** also be downloaded as a `tar/zip` file (or as a `gem`) from:
|
140
|
+
|
141
|
+
[rubyforge.org/frs/?group_id=1215&release_id=8817][rt@rubyforge]
|
142
|
+
|
143
|
+
The file-name is one of:
|
144
|
+
|
145
|
+
* `rubytree-<VERSION>.gem` - The rubygem
|
146
|
+
|
147
|
+
* `rubytree-<VERSION>.tgz` - GZipped source files
|
148
|
+
|
149
|
+
* `rubytree-<VERSION>.zip` - Zipped source files
|
150
|
+
|
151
|
+
Download the appropriate file-type for your system.
|
152
|
+
|
153
|
+
Extract the archive file (`tgz` or `zip`) and run the following command from the
|
154
|
+
top-level source directory:
|
155
|
+
|
156
|
+
$ ruby ./setup.rb
|
157
|
+
|
158
|
+
You may need administrator/super-user privileges to complete the setup using
|
159
|
+
this method. Note that the source code contains the `Rakefile` for building
|
160
|
+
using [Rake][], which might an easier mechanism for building and installing the
|
161
|
+
gem.
|
162
|
+
|
163
|
+
## DOCUMENTATION: ##
|
164
|
+
|
165
|
+
The primary class **RubyTree** is {Tree::TreeNode}. See the class
|
166
|
+
documentation for an example of using the library.
|
167
|
+
|
168
|
+
If the *ri* documentation was generated during install, you can use this
|
169
|
+
command at the terminal to view the text mode ri documentation:
|
170
|
+
|
171
|
+
$ ri Tree::TreeNode
|
172
|
+
|
173
|
+
Documentation for the latest released version is available at:
|
174
|
+
|
175
|
+
[rubytree.rubyforge.org/rdoc][rt_doc]
|
176
|
+
|
177
|
+
Documentation for the latest git HEAD is available at:
|
178
|
+
|
179
|
+
[rdoc.info/projects/evolve75/RubyTree][rt_doc@head]
|
180
|
+
|
181
|
+
Note that the documentation is formatted using [Yard][].
|
182
|
+
|
183
|
+
## DEVELOPERS: ##
|
184
|
+
|
185
|
+
This section is only for modifying **RubyTree** itself. It is not required for using
|
186
|
+
the library!
|
187
|
+
|
188
|
+
You can download the latest released source code as a tar or zip file, as
|
189
|
+
mentioned above in the installation section.
|
190
|
+
|
191
|
+
Alternatively, you can checkout the latest commit/revision from the Version
|
192
|
+
Control System. Note that **RubyTree**'s primary [SCM][] is [git][] and is hosted on
|
193
|
+
[github.com][rt@github].
|
194
|
+
|
195
|
+
### Using the git Repository ###
|
196
|
+
|
197
|
+
The git repository is available at [github.com/evolve75/RubyTree][rt@github].
|
198
|
+
|
199
|
+
For cloning the git repository, use one of the following commands:
|
200
|
+
|
201
|
+
$ git clone git://github.com/evolve75/RubyTree.git
|
202
|
+
|
203
|
+
or
|
204
|
+
|
205
|
+
$ git clone http://github.com/evolve75/RubyTree.git
|
206
|
+
|
207
|
+
### Setting up the Development Environment ###
|
208
|
+
|
209
|
+
**RubyTree** uses [Bundler][] to manage its dependencies. This allows for a
|
210
|
+
simplified dependency management, for both run-time as well as during build.
|
211
|
+
|
212
|
+
After checking out the source, run:
|
213
|
+
|
214
|
+
$ gem install bundler
|
215
|
+
$ bundle install
|
216
|
+
$ rake test
|
217
|
+
$ rake doc:yard
|
218
|
+
$ rake gem:package
|
219
|
+
|
220
|
+
These steps will install any missing dependencies, run the tests/specs,
|
221
|
+
generate the documentation, and finally generate the gem file.
|
222
|
+
|
223
|
+
Note that the documentation uses [Yard][], which will be
|
224
|
+
downloaded and installed automatically by [Bundler][].
|
225
|
+
|
226
|
+
## ACKNOWLEDGMENTS: ##
|
227
|
+
|
228
|
+
A big thanks to the following contributors for helping improve **RubyTree**:
|
229
|
+
|
230
|
+
1. [Dirk Breuer](http://github.com/railsbros-dirk) for contributing the JSON
|
231
|
+
conversion code.
|
232
|
+
2. Vincenzo Farruggia for contributing the (sub)tree cloning code.
|
233
|
+
3. [Eric Cline](https://github.com/escline) for the Rails JSON encoding fix.
|
234
|
+
4. [Darren Oakley](https://github.com/dazoakley) for the tree merge methods.
|
235
|
+
5. [Youssef Rebahi-Gilbert](https://github.com/ysf) for the code to check
|
236
|
+
duplicate node names in the tree (globally unique names).
|
237
|
+
6. [Paul de Courcel](https://github.com/pdecourcel) for adding the
|
238
|
+
`postordered_each` method.
|
239
|
+
|
240
|
+
## LICENSE: ##
|
241
|
+
|
242
|
+
**RubyTree** is licensed under the terms of the [BSD][] license. See
|
243
|
+
[LICENSE.md](./LICENSE.md) for details.
|
244
|
+
|
245
|
+
{include:file:LICENSE.md}
|
246
|
+
__ _ _
|
247
|
+
/__\_ _| |__ _ _| |_ _ __ ___ ___
|
248
|
+
/ \// | | | '_ \| | | | __| '__/ _ \/ _ \
|
249
|
+
/ _ \ |_| | |_) | |_| | |_| | | __/ __/
|
250
|
+
\/ \_/\__,_|_.__/ \__, |\__|_| \___|\___|
|
251
|
+
|___/
|
252
|
+
|
253
|
+
[BSD]: http://opensource.org/licenses/bsd-license.php "BSD License"
|
254
|
+
[Binary tree]: http://en.wikipedia.org/wiki/Binary_tree "Binary Tree Data Structure"
|
255
|
+
[Bundler]: http://bundler.io "Bundler"
|
256
|
+
[Comparable]: http://ruby-doc.org/core-1.8.7/Comparable.html "Comparable mix-in"
|
257
|
+
[Enumerable]: http://ruby-doc.org/core-1.9.3/Enumerable.html "Enumerable mix-in"
|
258
|
+
[JSON]: http://flori.github.com/json "JSON"
|
259
|
+
[Rake]: http://rake.rubyforge.org "Rake"
|
260
|
+
[Ruby]: http://www.ruby-lang.org "Ruby Programming Language"
|
261
|
+
[SCM]: http://en.wikipedia.org/wiki/Source_Code_Management "Source Code Management"
|
262
|
+
[Yard]: http://yardoc.org "Yard Document Generator"
|
263
|
+
[breadth-first]: http://en.wikipedia.org/wiki/Breadth-first_search "Breadth-first (level-first) Traversal"
|
264
|
+
[git]: http://git-scm.com "Git SCM"
|
265
|
+
[in-order]: http://en.wikipedia.org/wiki/Tree_traversal#In-order "In-order (symmetric) Traversal"
|
266
|
+
[marshaling]: http://ruby-doc.org/core-1.8.7/Marshal.html "Marshaling in Ruby"
|
267
|
+
[post-order]: http://en.wikipedia.org/wiki/Tree_traversal#Post-order "Post-ordered Traversal"
|
268
|
+
[pre-order]: http://en.wikipedia.org/wiki/Tree_traversal#Pre-order "Pre-ordered Traversal"
|
269
|
+
[rt@github]: http://github.com/evolve75/RubyTree "RubyTree Project Page on Github"
|
270
|
+
[rt@rubyforge]: http://rubyforge.org/frs/?group_id=1215&release_id=8817 "RubyTree at Rubyforge"
|
271
|
+
[rt_doc@head]: http://rdoc.info/projects/evolve75/RubyTree "RubyTree Documentation for VCS Head"
|
272
|
+
[rt_doc]: http://rubytree.rubyforge.org/rdoc "RubyTree Documentation"
|
273
|
+
[rt_gem]: http://rubygems.org/gems/rubytree "RubyTree Gem"
|
274
|
+
[rt_site]: http://rubytree.rubyforge.org "RubyTree Site"
|
275
|
+
[structured_warnings]: http://github.com/schmidt/structured_warnings "structured_warnings"
|
276
|
+
[tree_data_structure]: http://en.wikipedia.org/wiki/Tree_data_structure "Tree Data Structure"
|