jumoku 0.2.4 → 0.2.5

data/lib/jumoku.rb

@@ -9,44 +9,59 @@ require 'hashery'
 require 'plexus'
 
 # Jumoku provides you with several modules and classes to build and manipulate
-# tree graphs. Two basic implementations are available: undirected trees
-# ({RawUndirectedTree}) and directed trees ({RawDirectedTree}).
+# tree-graphs.
 #
-# {Tree} is derived from the undirected flavour and sticks to the mathematical
-# tree definition. {Arborescence} is derived from the directed flavour and is
-# likely to be used as the basis to modelize hierarchy structures, such as a
-# family tree, a file browser…
+# A tree is a structure composed of branches binding nodes. Branches may be
+# directed (arcs) or undirected (edges). When a there is only one general
+# direction (flow), there is a root node, and one or several leaf nodes. A
+# directed, uni-flow tree where each node only branches in once and branches
+# out once is called a path. For more information on what a tree-graph is and
+# how you could make use of it, see the README.
 #
-# Note that a node can be any Object. There is no "node type", therefore
-# arguments which re expected to be nodes are simply labelled as "`node`"
-# within this documentation. A nice object type to use as a node may be an
-# OpenStruct or an [OpenObject](http://facets.rubyforge.org/apidoc/api/more/classes/OpenObject.html)
-# (from the Facets library), both turning nodes into versatile handlers.
+# Two basic implementations are available: undirected trees
+# ({RawUndirectedTree}) and directed trees ({RawDirectedTree}). They offer
+# limited features, so one will certainly drop to their civilized siblings:
+#
+#  * {Tree} is derived from an undirected tree and sticks to the mathematical
+# tree definition.
+#  * {Arborescence} is derived from a directed tree and is likely to be used
+# as the basis to modelize hierarchy structures, such as a family tree, a file
+# browser…
+#
+# A node can be any Object: there is no "node type". A nice object "type" to
+# use as a node may be an OpenStruct or an OpenHash (from the Facets library),
+# but really any object is valid.
+#
+# Jumoku allows you to enable some strategies when creating a new tree. For
+# instance, you may enable an edge/arc labeling strategy, which will cause
+# indexing of branches as they are added. Jumoku provides a few basic
+# strategies mixin, and one may implement custom ones.
 #
 module Jumoku
   # core implementations
-  autoload :Shared,                   'jumoku/builders/shared'
-  autoload :Extended,                 'jumoku/builders/extended'
+  autoload :Shared,                         'jumoku/builders/shared'
+  autoload :Extended,                       'jumoku/builders/extended'
 
   # branch types
-  autoload :UndirectedBranch,         'jumoku/support/branch'
-  autoload :DirectedBranch,           'jumoku/support/branch'
+  autoload :UndirectedBranch,               'jumoku/support/branch'
+  autoload :DirectedBranch,                 'jumoku/support/branch'
 
   # tree builders
-  autoload :RawUndirectedTreeBuilder, 'jumoku/builders/raw_undirected_tree'
-  autoload :RawDirectedTreeBuilder,   'jumoku/builders/raw_directed_tree'
-  autoload :TreeBuilder,              'jumoku/builders/tree'
-  autoload :ArborescenceBuilder,      'jumoku/builders/arborescence'
+  autoload :RawUndirectedTreeBuilder,       'jumoku/builders/raw_undirected_tree'
+  autoload :RawDirectedTreeBuilder,         'jumoku/builders/raw_directed_tree'
+  autoload :TreeBuilder,                    'jumoku/builders/tree'
+  autoload :ArborescenceBuilder,            'jumoku/builders/arborescence'
 
   # tree classes
-  autoload :RawDirectedTree,          'jumoku/classes/tree_classes'
-  autoload :RawUndirectedTree,        'jumoku/classes/tree_classes'
-  autoload :Tree,                     'jumoku/classes/tree_classes'
-  autoload :Arborescence,             'jumoku/classes/tree_classes'
+  autoload :RawDirectedTree,                'jumoku/classes/tree_classes'
+  autoload :RawUndirectedTree,              'jumoku/classes/tree_classes'
+  autoload :Tree,                           'jumoku/classes/tree_classes'
+  autoload :Arborescence,                   'jumoku/classes/tree_classes'
 
   # strategies
-  autoload :EdgeLabeling,             'jumoku/strategies/edge_labeling'
-  EdgeLabeling.autoload :Simple,      'jumoku/strategies/edge_labeling/simple'
+  autoload :Strategies,                     'jumoku/strategies'
+  Strategies.autoload :EdgeLabelingBackend, 'jumoku/strategies/edge_labeling'
+  Strategies.autoload :SimpleEdgeLabeling,  'jumoku/strategies/edge_labeling/simple'
 
   # support
   require 'jumoku/support/ruby_compatibility'

data/lib/jumoku/builders/arborescence.rb

@@ -4,6 +4,17 @@ module Jumoku
   # It provides a directed tree which acts as a hierarchical structure, known
   # as an arborescence.
   #
+  # By default, it is ensured that new arcs remain in the same general flow
+  # direction, based on the first arc added (binding the node known as root
+  # to its first children, known as leaf). This constraint may be relaxed by
+  # passing the `:free_flow` option to true when initializing:
+  #
+  #     Arborescence.new(:free_flow => true)
+  #
+  # This way, the tree remains directed (nodes are bound using arcs, not
+  # undirected edges), but a node may be either a pure source (only outing
+  # arcs), a pure target (only arcs pointing at it), or a mix.
+  #
   module ArborescenceBuilder
     include RawDirectedTreeBuilder
     include Extended
@@ -64,9 +75,8 @@ module Jumoku
     end
     alias parent_of parent
 
-    # Check whether a node is a parent. If another node is provided as
-    # second parameter, check whether the former node is the parent of the
-    # latter node.
+    # Check whether a node is a parent. If another node is provided as second
+    # parameter, check whether the former is the parent of the latter.
     #
     # @overload parent?(node)
     #   @param [Node] node
@@ -137,7 +147,7 @@ module Jumoku
     alias cousins neighbours
 
     # Check whether two nodes are neighbours. To include the node's siblings
-    # in the matching candidates, pass the :siblings option to true.
+    # in the matching candidates, pass the `:siblings` option to true.
     #
     # @param [Node] node1
     # @param [Node] node2

data/lib/jumoku/builders/extended.rb

@@ -298,7 +298,7 @@ module Jumoku
     end
     alias has_branches_among? branches_among?
 
-    # Number of nodes.
+    # Number of nodes. Just `#nodes.size` really.
     #
     # @return [Integer]
     #

data/lib/jumoku/builders/raw_directed_tree.rb

@@ -1,11 +1,12 @@
 module Jumoku
   # A {RawDirectedTree} relax the undirected constraint of trees as defined in
-  # Graph Theory. They remain connected and acyclic.
+  # Graph Theory. They remain connected and acyclic though.
   #
-  # It thus uses Plexus::DirectedGraphBuilder as its backend.
+  # It thus uses `Plexus::DirectedGraphBuilder` as its backend.
   #
   # It offers limited functionalities, therefore the main tree structure you'll likely to
   # use is its extended version, {Arborescence}.
+  #
   module RawDirectedTreeBuilder
     include Plexus::DirectedGraphBuilder
     include Shared
@@ -22,14 +23,8 @@ module Jumoku
     #
     def initialize(*params)
       super(*params) # Delegates to Plexus.
-      args = (params.pop if params.last.is_a? Hash) || {}
-      @_options = args
-      strategies = _extract_strategies(args)
-
-      class << self; self; end.module_eval do
-        strategies.each { |strategy| include strategy }
-        alias has_branch? has_arc?
-      end
+      @_options = (params.pop if params.last.is_a? Hash) || {}
+      _delay { alias has_branch? has_arc? }
     end
 
     # Checks whether the tree is *really* a valid tree, that is if the
@@ -39,7 +34,8 @@ module Jumoku
     # * acyclic
     # * connected
     #
-    # @return [Boolean]
+    # @return [true, false]
+    #
     def valid?
       super and directed?
     end

data/lib/jumoku/builders/raw_undirected_tree.rb

@@ -1,8 +1,10 @@
 module Jumoku
   # A {RawUndirectedTree} sticks to the standard definition of trees in Graph Theory:
+  #
   #  * undirected,
   #  * connected,
   #  * acyclic.
+  #
   # It thus uses Plexus::UndirectedGraphBuilder as its backend, which ensure the first
   # constraint.
   #
@@ -26,16 +28,8 @@ module Jumoku
     #
     def initialize(*params)
       super(*params) # Delegates to Plexus.
-      args = (params.pop if params.last.is_a? Hash) || {}
-      @_options = args
-      strategies = _extract_strategies(args)
-
-      super(*params) # Delegates to Plexus.
-
-      class << self; self; end.module_eval do
-        strategies.each { |strategy| include strategy }
-        alias has_branch? has_edge?
-      end
+      @_options = (params.pop if params.last.is_a? Hash) || {}
+      _delay { alias has_branch? has_edge? }
     end
 
     # Checks whether the tree is *really* a valid tree, that is if the

data/lib/jumoku/builders/shared.rb

@@ -1,14 +1,13 @@
 module Jumoku
   # This module provides the basic routines needed to implement the specialized
-  # builders: {UndirectedTreeBuilder} and {DirectedTreeBuilder}.
+  # builders: {RawUndirectedTreeBuilder} and {RawDirectedTreeBuilder}.
   #
   module Shared
-    STRATEGIES = [:edge_labeling, :node_labeling]
-
     def self.included(base)
       base.class_eval do
         # Late aliasing as it references methods provided by Plexus modules.
         alias has_node? has_vertex?
+        include Jumoku::Strategies
       end
     end
 
@@ -211,16 +210,10 @@ module Jumoku
       self.class.new(self)
     end
 
-    def _extract_strategies(options)
-      options = options.dup.select! { |k,v| STRATEGIES.include?(k) } || options.dup
-      options.inject([]) do |strategies, (k,v)|
-        begin
-          strategies << Jumoku.const_get(k.to_s.constantize).const_get(v.to_s.constantize)
-          strategies
-        rescue NameError # silently ignored
-          strategies
-        end
-      end
+    # Some code chunks must be module evaled at runtime.
+    #
+    def _delay
+      class << self; self; end.module_eval { yield }
     end
   end
 end

data/lib/jumoku/classes/tree_classes.rb

@@ -1,9 +1,15 @@
 module Jumoku
   # "Raw" implementations.
+
+  # See {RawUndirectedTreeBuilder}.
   class RawUndirectedTree; include RawUndirectedTreeBuilder; end
+  # See {RawDirectedTreeBuilder}.
   class RawDirectedTree;   include RawDirectedTreeBuilder;   end
 
   # "Useful" implementations.
+
+  # See {TreeBuilder}.
   class Tree;         include TreeBuilder;         end
+  # See {ArborescenceBuilder}.
   class Arborescence; include ArborescenceBuilder; end
 end

data/lib/jumoku/strategies.rb

@@ -0,0 +1,32 @@
+module Jumoku
+  # Strategies are decorators implemented as mixins which taint a tree object
+  # with new or extended features. For instance, the `SimpleEdgeLabeling`
+  # strategy alters the way new nodes and branches are added to a tree,
+  # enforcing labeling of edges with increasing integers, `Binary` enforces
+  # a tree to grow as a binary tree, etc.
+  #
+  # It is easy to develop your own decorators and `use` them.
+  #
+  module Strategies
+    # Activate a strategy.
+    #
+    # @param [#to_s, Module] strategy strategy's name, either as a module
+    #   namespace (like `Strategies::SimpleEdgeLabeling`) or a symbol (like
+    #   `:simple_edge_labeling`)
+    #
+    def use(strategy)
+      strategy = catch(:unknown_strategy) do
+        begin
+          if strategy.is_a?(Symbol) || strategy.is_a?(String)
+            strategy = Strategies.const_get(strategy.to_s.constantize)
+          end
+        rescue NameError
+          throw :unknown_strategy, nil
+        end
+        strategy
+      end
+      extend strategy unless strategy.nil?
+    end
+    alias strategy use
+  end
+end

data/lib/jumoku/strategies/edge_labeling.rb

@@ -1,6 +1,14 @@
 module Jumoku
-  module EdgeLabeling
-    module Backend
+  module Strategies
+    # Edge labeling strategies are concerned with the way edges or arcs are
+    # labeled. Simple labeling schemes are based on indexing with increasing
+    # integers, whereas some other strategies elaborate on notions such as
+    # weight or symetry.
+    #
+    # This module provides basic implementation for the common ground used
+    # by custom strategies.
+    #
+    module EdgeLabelingBackend
       # Sort edges by the provided block's logic. The block takes edge as
       # parameter, and this method delegates to Enumerable#sort_by for
       # sorting edges. Return unsorted edges list if no block is provided.

data/lib/jumoku/strategies/edge_labeling/simple.rb

@@ -1,5 +1,5 @@
 module Jumoku
-  module EdgeLabeling
+  module Strategies
     # A simple edge labeling strategy: as new nodes are added, new edges are
     # assigned increasing integers. Removed edges do not trigger reindexing,
     # so for a tree with n nodes, the labeling set is ||n|| but indexes are
@@ -8,8 +8,8 @@ module Jumoku
     # This simple strategy allows for using simple search algorithms as well
     # for simple ordering schemes.
     #
-    module Simple
-      include EdgeLabeling::Backend
+    module SimpleEdgeLabeling
+      include Strategies::EdgeLabelingBackend
 
       attr_accessor :next_simple_edge_label_number
 

data/lib/jumoku/support/branch.rb

@@ -1,11 +1,17 @@
 module Jumoku
-  # Namespacing. Useful for duck typing criteria.
+  # Used only as a namespace. Useful for duck typing criteria: both
+  # `Plexus::Edge` and `Plexus::Arc` are seen as `Branch`.
+  #
   module Branch; end
 
+  # Delegates to `Plexus::Edge`.
+  #
   class UndirectedBranch < Plexus::Edge
     include Branch
   end
 
+  # Delegates to `Plexus::Arc`.
+  #
   class DirectedBranch   < Plexus::Arc
     include Branch
   end

data/lib/jumoku/support/ruby_compatibility.rb

@@ -1,4 +1,4 @@
-module Jukomu
+module Jumoku
   if RUBY_VERSION < "1.9"
     def ruby_18
       yield

data/lib/jumoku/support/support.rb

@@ -1,8 +1,14 @@
 module Jumoku
+  # Generic error class.
   class JumokuError             < StandardError; end
+  # Generic error class for raw builders.
   class RawTreeError            < JumokuError;   end
+  # Node-related error class for raw builders.
   class RawTreeNodeError        < RawTreeError;  end
+  # Raised when a branch already exist, causing an operation to abort.
   class BranchAlreadyExistError < JumokuError;   end
+  # Raised when breaking the connexion constraint, causing an operation to abort.
   class ForbiddenCycle          < JumokuError;   end
+  # Raised when a referenced node does not exist.
   class UndefinedNode           < JumokuError;   end
 end

data/lib/jumoku/version.rb

@@ -1,6 +1,6 @@
 module Jumoku
   MAJOR = 0
   MINOR = 2
-  PATCH = 4
+  PATCH = 5
   VERSION = [MAJOR, MINOR, PATCH].join('.')
 end

data/spec/strategies/simple_edge_labeling.rb

@@ -1,8 +1,8 @@
 require 'spec_helper'
 
-describe EdgeLabeling::Simple do
-  let(:tree) { Tree.new(:edge_labeling => :simple) }
-  let(:arbo) { Arborescence.new(:edge_labeling => :simple) }
+describe Strategies::SimpleEdgeLabeling do
+  let(:tree) { Tree.new.use Strategies::SimpleEdgeLabeling }
+  let(:arbo) { Arborescence.new.use :simple_edge_labeling }
 
   describe 'a tree with simple edge labeling' do
     it "should label its edges with increasing integers when new nodes are added or removed" do

metadata

@@ -1,8 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: jumoku
 version: !ruby/object:Gem::Version 
+  hash: 29
   prerelease: 
-  version: 0.2.4
+  segments: 
+  - 0
+  - 2
+  - 5
+  version: 0.2.5
 platform: ruby
 authors: 
 - Jean-Denis Vauguet <jd@vauguet.fr>
@@ -10,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-12 00:00:00 +02:00
+date: 2011-07-14 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -21,6 +26,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id001
@@ -32,6 +40,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id002
@@ -43,6 +54,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id003
@@ -54,6 +68,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :runtime
   version_requirements: *id004
@@ -65,6 +82,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :development
   version_requirements: *id005
@@ -76,6 +96,9 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
         version: "0"
   type: :development
   version_requirements: *id006
@@ -96,7 +119,7 @@ files:
 - lib/jumoku/builders/shared.rb
 - lib/jumoku/builders/arborescence.rb
 - lib/jumoku/builders/raw_directed_tree.rb
-- lib/jumoku/raw_tree_node.rb
+- lib/jumoku/strategies.rb
 - lib/jumoku/classes/tree_classes.rb
 - lib/jumoku/strategies/edge_labeling/simple.rb
 - lib/jumoku/strategies/edge_labeling.rb
@@ -131,12 +154,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 requirements: []
 

data/lib/jumoku/raw_tree_node.rb

@@ -1,27 +0,0 @@
-module Jumoku
-  module RawTree
-    # This module describes RawTree nodes.
-    #
-    # You may also use this module as a mixin to have a class behave
-    # as a RawTree node, while customizing behaviors.
-    #
-    module Node
-      # Creates a new node.
-      #
-      # @param [#to_s, #to_sym] name a valid name, considering the :names_as options
-      #   passed to the raw tree you want to create a node for.
-      # @param [Object] data the data field type to use. Defaults to an empty OpenObject
-      # @param [Array(#to_s)] children an array of children nodes ids
-      #
-      # @return [OpenObject] the node as an OpenObject instance
-      #
-      def create name, data = OpenObject.new, children = []
-        @name = name
-        @data = data
-        @children = children
-
-        OpenObject.new(:name => @name, :data => @data, :children => @children)
-      end
-    end
-  end
-end