tangle 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8eb75fcbb95f4ed4a3dd8f24c2142d9a6ddda1cafaf4dfbbb8e6ef60cab9131
-  data.tar.gz: dd3823ce25297ddc173e6bf7867d8c61e6d795157f99655b54f7297ac960744c
+  metadata.gz: ecbc32a01243a5579254a7beca7175df838759511ca5af297668ec54ab245ff2
+  data.tar.gz: b437ade2b5f953312b845a3d9fd5679d6e40b7c98a437b5ce6677f866824de9f
 SHA512:
-  metadata.gz: b55e6aa75a2f1225cbcbda72050f3d374222453dfd4a75221bb01d8b9aa452f96832a38ac7b960a3edbe8913135127e72db0b94a96024138e5b29bddd0bd81b5
-  data.tar.gz: d580c9be8c1559c0055d0a3f59b2cde590c5e7b0b42e821f4cbba1ac3bbd85e43616f43fd652c362de979a3d0bcdd8e43b94aff61dd29ad2d684038cce63197e
+  metadata.gz: f8af8b8acc6f0400e03eb760a3baffe12987b5f797bd952cf9a271312163433b1129670056991dd5febe959c74fa894e99a048e22e470c48241f140eff1b4836
+  data.tar.gz: c455890c8be488f6d38d83f003f731a5db70426464f14c85107344d277297446c73225e8ca615d556e8bacf079934bd5ff9724a60716a7212485dcbae870e2f8

data/README.md

@@ -2,19 +2,21 @@
 
 # Tangle
 
-Tangle aims to untangle your graphs, by providing a set of classes for managing different types of graphs, and mixins for adding specific feature sets, like coloring or graphviz export.
+Tangle aims to untangle your graphs, by providing a set of classes for managing different types of graphs, and mixins for adding specific feature sets.
 
 **Graph types**:
  * SimpleGraph
  * MultiGraph
  * DiGraph
- * ~~DAG~~
+ * DAG
  * ~~Tree~~
 
 **Feature mixins**:
  * Connectedness
  * Ancestry
+ * ~~Vertex ordering~~
  * ~~Coloring~~
+ * ~~GraphViz~~
 
 ## Installation
 
@@ -51,6 +53,34 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
+### Mixin API
+
+A mixin is a module with optional submodules for each of the classes
+`Graph`, `Vertex`, and `Edge`. If the mixin needs initial state it
+should provide a keyword initializer `#initialize_kwarg_KEYWORD(argument)`,
+that will be called when the object is `#initalize`d with a matching kwarg.
+
+Example:
+```ruby
+module WeightedEdges
+	module Edge
+		def initialize_kwarg_weight(weight)
+			@weight = weight
+		end
+
+		def weight
+			@weight
+		end
+
+		def weight=(new_weight)
+			@weight = new_weight
+		end
+	end
+end
+
+Tangle::Graph.new(mixins: [WeightedEdges])
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/notCalle/tangle. Pull requests should be rebased to HEAD of `master` before submitting, and all commits must be signed with valid GPG key. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/lib/tangle/directed/edge.rb

@@ -6,11 +6,6 @@ module Tangle
     # An edge in a directed graph
     #
     class Edge < Tangle::Edge
-      def initialize(vertex1, vertex2 = vertex1, graph: nil)
-        @child, @parent = @vertices = [vertex1, vertex2]
-        super
-      end
-
       def parent?(vertex)
         @parent == vertex
       end
@@ -26,6 +21,13 @@ module Tangle
       def child(_vertex = nil)
         @child
       end
+
+      protected
+
+      def with_vertices(vertex1, vertex2 = vertex1)
+        @child, @parent = @vertices = [vertex1, vertex2]
+        self
+      end
     end
   end
 end

data/lib/tangle/directed/graph.rb

@@ -8,10 +8,6 @@ module Tangle
     class Graph < Tangle::Graph
       Edge = Tangle::Directed::Edge
       DEFAULT_MIXINS = [Tangle::Mixin::Ancestry].freeze
-
-      def initialize(mixins: DEFAULT_MIXINS, **kvargs)
-        super
-      end
     end
   end
 end

data/lib/tangle/edge.rb

@@ -16,11 +16,11 @@ module Tangle
     #
     # End users should probably use Graph#add_edge instead.
     #
-    def initialize(vertex1, vertex2 = vertex1, graph: nil)
-      @vertices ||= Set[vertex1, vertex2]
-      @graph = graph
+    def initialize(vertex1, vertex2 = vertex1, graph: nil, **kwargs)
+      with_graph(graph)
+      with_vertices(vertex1, vertex2)
 
-      initialize_mixins
+      initialize_mixins(**kwargs)
 
       validate_edge
     end
@@ -41,22 +41,23 @@ module Tangle
       @vertices.find { |other| other != for_vertex } || for_vertex
     end
 
-    # Duplicate an edge into another graph, replacing original vertices with
+    # Clone an edge into another graph, replacing original vertices with
     # their already prepared duplicates in the other graph. Returns nil if any
     # of the vertices does not exist in the other graph.
     # End users should probably use Graph#subgraph instead.
     #
-    # dup_into(graph) => Edge or nil
+    # clone_into(graph) => Edge or nil
     #
     # Raises an ArgumentError if graph would remain the same.
     #
-    def dup_into(graph)
+    def clone_into(graph)
       raise ArgumentError if graph == @graph
 
       vertices = @vertices.map do |vertex|
         graph.get_vertex(vertex.vertex_id)
       end
-      self.class.new(*vertices, graph: graph)
+
+      clone.with_graph(graph).with_vertices(*vertices)
     rescue KeyError
       nil
     end
@@ -78,6 +79,18 @@ module Tangle
 
     def_delegators :@vertices, :include?, :hash
 
+    protected
+
+    def with_graph(graph)
+      @graph = graph
+      self
+    end
+
+    def with_vertices(vertex1, vertex2 = vertex1)
+      @vertices = Set[vertex1, vertex2]
+      self
+    end
+
     private
 
     def validate_edge

data/lib/tangle/graph.rb

@@ -1,32 +1,46 @@
 require 'tangle/mixin'
 require 'tangle/vertex'
 require 'tangle/edge'
+require 'tangle/graph_private'
+require 'tangle/graph_protected'
 
 module Tangle
   #
   # Base class for all kinds of graphs
   #
   class Graph
+    include Tangle::GraphPrivate
+    include Tangle::GraphProtected
     include Tangle::Mixin::Initialize
     Edge = Tangle::Edge
+    DEFAULT_MIXINS = [Tangle::Mixin::Connectedness].freeze
 
-    # Initialize a new graph, optionally preloading it with vertices and edges
-    #
-    # Graph.new() => Graph
-    # Graph.new(vertices: +array_or_hash+) => Graph
-    # Graph.new(vertices: +array_or_hash+, edges: +array_or_hash+) => Graph
-    # Graph.new(mixins: [MixinModule, ...], ...) => Graph
+    # Initialize a new graph, preloading it with vertices and edges
     #
-    # When +array_or_hash+ is a hash, it contains the objects as values and
-    # their names as keys. When +array_or_hash+ is an array the objects will
-    # get assigned unique names (within the graph).
+    # Graph[+vertices+] => Graph
+    # Graph[+vertices+, +edges+) => Graph
     #
-    # +vertices+ can contain anything, and the Vertex object that is created
-    # will delegate all missing methods to its content.
+    # When +vertices+ is a hash, it contains initialization kwargs as
+    # values and vertex names as keys. When +vertices+ is an array of
+    # initialization kwargs, the vertices will be be anonymous.
     #
     # +edges+ can contain an array of exactly two, either names of vertices
     # or vertices.
     #
+    # Any kwarg supported by Graph.new is also allowed.
+    #
+    def self.[](vertices, edges = {}, **kwargs)
+      graph = new(**kwargs)
+      graph.add_vertices(vertices)
+      edges.each { |from, to| graph.add_edge(from, to) }
+      graph
+    end
+
+    # Initialize a new graph, optionally preloading it with vertices and edges
+    #
+    # Graph.new() => Graph
+    # Graph.new(mixins: [MixinModule, ...], ...) => Graph
+    #
     # +mixins+ is an array of modules that can be mixed into the various
     # classes that makes up a graph. Initialization of a Graph, Vertex or Edge
     # looks for submodules in each mixin, with the same name and extends
@@ -35,15 +49,10 @@ module Tangle
     # Any subclass of Graph should also subclass Edge to manage its unique
     # constraints.
     #
-    def initialize(vertices: nil, edges: nil,
-                   mixins: [Tangle::Mixin::Connectedness])
-      @vertices_by_id = {}
-      @vertices_by_name = {}
-      @edges ||= []
-
-      initialize_mixins(mixins)
-      initialize_vertices(vertices)
-      initialize_edges(edges)
+    def initialize(mixins: self.class::DEFAULT_MIXINS, **kwargs)
+      initialize_mixins(mixins, **kwargs)
+      initialize_vertices
+      initialize_edges
     end
 
     # Get all edges.
@@ -85,12 +94,20 @@ module Tangle
     #
     # Optional named arguments:
     #   name: unique name or label for vertex
-    #   contents: delegate object for missing methods
     #
     def add_vertex(**kvargs)
       insert_vertex(Vertex.new(graph: self, **kvargs))
     end
 
+    def add_vertices(vertices)
+      case vertices
+      when Hash
+        vertices.each { |name, kwargs| add_vertex(name: name, **kwargs) }
+      else
+        vertices.each { |kwargs| add_vertex(**kwargs) }
+      end
+    end
+
     def get_vertex(name_or_vertex)
       case name_or_vertex
       when Vertex
@@ -109,81 +126,9 @@ module Tangle
     # Unless a selector is provided, the subgraph contains the entire graph.
     #
     def subgraph(&selector)
-      graph = self.class.new
-
-      dup_vertices_into(graph, &selector)
-      dup_edges_into(graph)
-
-      graph
+      clone.with_vertices(vertices(&selector)).with_edges(edges)
     end
-    alias dup subgraph
 
     attr_reader :mixins
-
-    protected
-
-    # Insert a prepared vertex into the graph
-    #
-    def insert_vertex(vertex)
-      raise ArgumentError unless vertex.graph.eql?(self)
-
-      @vertices_by_name[vertex.name] = vertex unless vertex.name.nil?
-      @vertices_by_id[vertex.vertex_id] = vertex
-    end
-
-    # Insert a prepared edge into the graph
-    #
-    def insert_edge(edge)
-      raise ArgumentError unless edge.graph.eql?(self)
-
-      @edges << edge
-      edge
-    end
-
-    private
-
-    def initialize_vertices(vertices)
-      return if vertices.nil?
-
-      case vertices
-      when Hash
-        initialize_named_vertices(vertices)
-      else
-        initialize_anonymous_vertices(vertices)
-      end
-    end
-
-    def initialize_named_vertices(vertices)
-      vertices.each do |name, delegate|
-        add_vertex(name: name, delegate: delegate)
-      end
-    end
-
-    def initialize_anonymous_vertices(vertices)
-      vertices.each do |delegate|
-        add_vertex(delegate: delegate)
-      end
-    end
-
-    def initialize_edges(edges)
-      return if edges.nil?
-
-      edges.each do |vertices|
-        add_edge(*vertices)
-      end
-    end
-
-    def dup_vertices_into(graph, &selector)
-      vertices(&selector).each do |vertex|
-        graph.insert_vertex(vertex.dup_into(graph))
-      end
-    end
-
-    def dup_edges_into(graph)
-      edges.each do |edge|
-        new_edge = edge.dup_into(graph)
-        graph.insert_edge(new_edge) unless new_edge.nil?
-      end
-    end
   end
 end

data/lib/tangle/graph_private.rb

@@ -0,0 +1,30 @@
+module Tangle
+  #
+  # The private bits of Graph
+  #
+  module GraphPrivate
+    private
+
+    def initialize_vertices
+      @vertices_by_id = {}
+      @vertices_by_name = {}
+    end
+
+    def initialize_edges
+      @edges = []
+    end
+
+    def clone_vertices_into(graph, &selector)
+      vertices(&selector).each do |vertex|
+        graph.insert_vertex(vertex.clone_into(graph))
+      end
+    end
+
+    def clone_edges_into(graph)
+      edges.each do |edge|
+        new_edge = edge.clone_into(graph)
+        graph.insert_edge(new_edge) unless new_edge.nil?
+      end
+    end
+  end
+end

data/lib/tangle/graph_protected.rb

@@ -0,0 +1,45 @@
+module Tangle
+  #
+  # The protected bits of Graph
+  #
+  module GraphProtected
+    protected
+
+    # Insert a prepared vertex into the graph
+    #
+    def insert_vertex(vertex)
+      raise ArgumentError unless vertex.graph.eql?(self)
+
+      @vertices_by_name[vertex.name] = vertex unless vertex.name.nil?
+      @vertices_by_id[vertex.vertex_id] = vertex
+    end
+
+    # Insert a prepared edge into the graph
+    #
+    def insert_edge(edge)
+      raise ArgumentError unless edge.graph.eql?(self)
+
+      @edges << edge
+      edge
+    end
+
+    def with_vertices(vertices = [])
+      initialize_vertices
+
+      vertices.each do |vertex|
+        insert_vertex(vertex.clone_into(self))
+      end
+      self
+    end
+
+    def with_edges(edges = [])
+      initialize_edges
+
+      edges.each do |edge|
+        new_edge = edge.clone_into(self)
+        insert_edge(new_edge) unless new_edge.nil?
+      end
+      self
+    end
+  end
+end

data/lib/tangle/mixin.rb

@@ -9,7 +9,7 @@ module Tangle
     module Initialize
       private
 
-      def initialize_mixins(mixins = nil)
+      def initialize_mixins(mixins = nil, **kwargs)
         case klass = self.class.name[/[^:]+$/].to_sym
         when :Graph
           @mixins = mixins
@@ -18,6 +18,7 @@ module Tangle
         end
 
         extend_with_mixins(klass, mixins) unless mixins.nil?
+        initialize_kwargs(**kwargs) unless kwargs.empty?
       end
 
       def extend_with_mixins(klass, mixins)
@@ -25,6 +26,15 @@ module Tangle
           extend(mixin.const_get(klass)) if mixin.const_defined?(klass)
         end
       end
+
+      def initialize_kwargs(**kwargs)
+        kwargs.each do |keyword, argument|
+          initializer = "initialize_kwarg_#{keyword}".to_sym
+          can_init = respond_to?(initializer)
+          raise ArgumentError, "unknown keyword: #{keyword}" unless can_init
+          send initializer, argument
+        end
+      end
     end
   end
 end

data/lib/tangle/simple/graph.rb

@@ -8,9 +8,10 @@ module Tangle
     class Graph < Tangle::Graph
       Edge = Tangle::Simple::Edge
 
-      def initialize(**kvargs)
-        @edges ||= Set[]
-        super
+      private
+
+      def initialize_edges
+        @edges = Set[]
       end
     end
   end

data/lib/tangle/vertex.rb

@@ -6,8 +6,7 @@ module Tangle
   #
   # A named vertex in a graph
   #
-  class Vertex < SimpleDelegator
-    include PP::ObjectMixin
+  class Vertex
     include Tangle::Mixin::Initialize
 
     # Create a new vertex
@@ -17,38 +16,29 @@ module Tangle
     # Named arguments:
     #   graph: a Graph or nil for an orphaned vertex
     #   name: anything that's hashable and unique within the graph
-    #   delegate: delegate object for missing methods
     #
     def initialize(graph: nil,
                    name: nil,
-                   delegate: nil,
-                   vertex_id: object_id)
-      super(delegate) unless delegate.nil?
-
+                   vertex_id: object_id,
+                   **kwargs)
       @graph = graph
       @name = name
-      @delegate = delegate
       @vertex_id = vertex_id
 
-      initialize_mixins
+      initialize_mixins(**kwargs)
     end
 
-    # Duplicate a vertex in a new graph, keeping all other contained attributes
-    # End users should probably use Graph#subgrap instead.
+    # Clone a vertex in a new graph, keeping all other contained attributes
+    # End users should probably use Graph#subgraph instead.
     #
-    # dup_into(new_graph) => Vertex
+    # clone_into(new_graph) => Vertex
     #
     # Raises an ArgumentError if graph would remain the same.
     #
-    def dup_into(graph)
+    def clone_into(graph)
       raise ArgumentError if graph == @graph
 
-      Vertex.new(
-        graph:     graph,
-        name:      @name,
-        delegate:  @delegate,
-        vertex_id: @vertex_id
-      )
+      clone.with_graph(graph)
     end
 
     # Return all edges that touch this vertex
@@ -92,7 +82,13 @@ module Tangle
 
     attr_reader :graph
     attr_reader :name
-    attr_reader :delegate
     attr_reader :vertex_id
+
+    protected
+
+    def with_graph(graph)
+      @graph = graph
+      self
+    end
   end
 end

data/tangle.gemspec

@@ -1,5 +1,5 @@
 
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'tangle/version'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tangle
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Calle Englund
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-20 00:00:00.000000000 Z
+date: 2018-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: git-version-bump
@@ -106,6 +106,8 @@ files:
 - lib/tangle/edge.rb
 - lib/tangle/errors.rb
 - lib/tangle/graph.rb
+- lib/tangle/graph_private.rb
+- lib/tangle/graph_protected.rb
 - lib/tangle/mixin.rb
 - lib/tangle/mixin/ancestry.rb
 - lib/tangle/mixin/connectedness.rb