dagnabit 2.2.6 → 3.0.0

data/db/connection.rb

@@ -0,0 +1,3 @@
+database = ENV['DATABASE'] || 'postgresql'
+
+require File.join(File.dirname(__FILE__), %W(connections #{database} connection))

data/{test/connections/native_postgresql → db/connections/postgresql}/connection.rb

@@ -1,8 +1,9 @@
-print "Using native PostgreSQL\n"
-
+require 'active_record'
 require 'logger'
 
-ActiveRecord::Base.logger = Logger.new("debug.log")
+puts 'Using PostgreSQL adapter'
+
+ActiveRecord::Base.logger = Logger.new('debug.log')
 
 ActiveRecord::Base.configurations = {
   'ActiveRecord::Base' => {
@@ -10,8 +11,8 @@ ActiveRecord::Base.configurations = {
     :database => 'dagnabit_test',
     :username => 'dagnabit_test',
     :password => 'dagnabit_test',
-    :hostname => 'localhost'
+    :host => 'localhost'
   }
-};
+}
 
 ActiveRecord::Base.establish_connection('ActiveRecord::Base')

data/db/models/edge.rb

@@ -0,0 +1,6 @@
+class Edge < ActiveRecord::Base
+  extend Dagnabit::Edge::Activation
+
+  acts_as_edge
+  connects 'Vertex'
+end

data/db/models/other_edge.rb

@@ -0,0 +1,6 @@
+class OtherEdge < ActiveRecord::Base
+  extend Dagnabit::Edge::Activation
+
+  acts_as_edge
+  connects 'OtherVertex'
+end

data/db/models/other_vertex.rb

@@ -0,0 +1,6 @@
+class OtherVertex < ActiveRecord::Base
+  extend Dagnabit::Vertex::Activation
+
+  acts_as_vertex
+  connected_by  'OtherEdge'
+end

data/db/models/vertex.rb

@@ -0,0 +1,6 @@
+class Vertex < ActiveRecord::Base
+  extend Dagnabit::Vertex::Activation
+
+  acts_as_vertex
+  connected_by 'Edge'
+end

data/db/schema.rb

@@ -0,0 +1,32 @@
+ActiveRecord::Schema.define do
+  extend Dagnabit::Migration
+
+  execute 'DROP LANGUAGE IF EXISTS plpgsql CASCADE'
+  execute 'CREATE TRUSTED LANGUAGE plpgsql'
+
+  [:edges, :other_edges].each do |table|
+    create_table table, :force => true do |t|
+      t.references :parent, :null => false
+      t.references :child,  :null => false
+    end
+
+    add_index table, [:parent_id, :child_id], :unique => true
+
+    create_cycle_check_trigger table
+  end
+
+  create_table :vertices, :force => true do |t|
+    t.integer :datum
+  end
+
+  create_table :other_vertices, :force => true do |t|
+    t.integer :datum
+  end
+
+  [ [:vertices, :edges],
+    [:other_vertices, :other_edges]
+  ].each do |vt, et|
+    execute %Q{ALTER TABLE #{et} ADD CONSTRAINT FK_#{et}_parent_id_#{vt}_id FOREIGN KEY (parent_id) REFERENCES #{vt} ("id") MATCH FULL}
+    execute %Q{ALTER TABLE #{et} ADD CONSTRAINT FK_#{et}_child_id_#{vt}_id FOREIGN KEY (child_id) REFERENCES #{vt} ("id") MATCH FULL}
+  end
+end

data/lib/dagnabit.rb

@@ -1,19 +1,6 @@
-require 'active_record'
-
-require 'dagnabit/link/configuration'
-require 'dagnabit/link/validations'
-require 'dagnabit/link/associations'
-require 'dagnabit/link/class_methods'
-require 'dagnabit/link/cycle_prevention'
-require 'dagnabit/link/named_scopes'
-require 'dagnabit/link/transitive_closure_recalculation'
-require 'dagnabit/link/transitive_closure_link_model'
-
-require 'dagnabit/node/configuration'
-require 'dagnabit/node/class_methods'
-require 'dagnabit/node/associations'
-require 'dagnabit/node/neighbors'
-
-require 'dagnabit/activation'
-
-ActiveRecord::Base.extend(Dagnabit::Activation)
+module Dagnabit
+  autoload :Edge,       'dagnabit/edge'
+  autoload :Graph,      'dagnabit/graph'
+  autoload :Migration,  'dagnabit/migration'
+  autoload :Vertex,     'dagnabit/vertex'
+end

data/lib/dagnabit/edge.rb

@@ -0,0 +1,7 @@
+require File.join(File.dirname(__FILE__), %w(.. dagnabit))
+
+module Dagnabit::Edge
+  autoload :Activation,   'dagnabit/edge/activation'
+  autoload :Associations, 'dagnabit/edge/associations'
+  autoload :Connectivity, 'dagnabit/edge/connectivity'
+end

data/lib/dagnabit/edge/activation.rb

@@ -0,0 +1,14 @@
+require File.join(File.dirname(__FILE__), %w(.. edge))
+
+module Dagnabit::Edge
+  ##
+  # This module provides a method to set up all of the Edge modules in a class.
+  module Activation
+    ##
+    # Sets up dagnabit's edge modules in an edge class.
+    def acts_as_edge
+      extend Associations
+      extend Connectivity
+    end
+  end
+end

data/lib/dagnabit/edge/associations.rb

@@ -0,0 +1,10 @@
+require File.join(File.dirname(__FILE__), %w(.. edge))
+
+module Dagnabit::Edge
+  module Associations
+    def connects(vertex_class)
+      belongs_to :parent, :class_name => vertex_class
+      belongs_to :child,  :class_name => vertex_class
+    end
+  end
+end

data/lib/dagnabit/edge/connectivity.rb

@@ -0,0 +1,38 @@
+require File.join(File.dirname(__FILE__), %w(.. edge))
+
+module Dagnabit::Edge
+  ##
+  # Methods for querying connectivity of edges.
+  module Connectivity
+    ##
+    # Finds all edges connecting the given vertices.
+    #
+    # More specifically, finds all edges such that the edge's parent and child
+    # is one of the given vertices.
+    #
+    # This means that should vertices belong to disjoint subgraphs be selected,
+    # e.g.
+    #
+    #     (a)  (d)
+    #      |    |
+    #     (b)   e
+    #      |    |
+    #     (c)   f
+    #
+    # where () denotes a selected vertex, then only the edges for which both
+    # the parent and child vertices are present will be in the result set.  In
+    # the above example, this means that while the a->b and b->c edges will be
+    # present, the d->e edge will not.  To include the d->e edge, e would have
+    # to be in the vertex list.
+    #
+    # @param [Array<ActiveRecord::Base>] vertices the vertices to consider
+    # @return [Array<ActiveRecord::Base>] a list of edges
+    def connecting(*vertices)
+      ids = vertices.map(&:id)
+
+      find_by_sql([%Q{
+        SELECT * FROM #{table_name} WHERE parent_id IN (:ids) AND child_id IN (:ids)
+      }, { :ids => ids }])
+    end
+  end
+end

data/lib/dagnabit/graph.rb

@@ -0,0 +1,143 @@
+require File.join(File.dirname(__FILE__), %w(.. dagnabit))
+
+module Dagnabit
+  ##
+  # This class is a representation of a directed graph.  It deviates from the
+  # definition of a directed graph in a few ways; here's a couple:
+  #
+  # * It represents the vertex and edge sets using data structures more akin to
+  #   bags than sets.
+  # * It imposes restrictions on the form of vertices and edges; namely, they
+  #   must be ActiveRecord::Base subclasses that extend {Vertex::Connectivity}.
+  #
+  # Despite these flaws, it is hoped that {Graph} is still useful for
+  # performing queries on graphs built with dagnabit.
+  #
+  # {Graph} is not compatible with RGL's Graph concept.  This is because
+  # {Graph} defines {#vertices} and {#edges} as accessors, whereas RGL provides
+  # implementations of {#vertices} and {#edges} in terms of methods called
+  # `each_vertex` and `each_edge`, respectively.  Nevertheless, RGL
+  # compatibility would be nice to have, so it is a to-do item.
+  #
+  # Graphs may be constructed from a set of source nodes with {.from_vertices}.
+  class Graph
+    ##
+    # The vertices of this graph.
+    #
+    # @return [Array<ActiveRecord::Base>]
+    attr_accessor :vertices
+
+    ##
+    # The edges of this graph.
+    #
+    # @return [Array<ActiveRecord::Base>]
+    attr_accessor :edges
+
+    ##
+    # The vertex model used by this graph.
+    #
+    # This must be defined before calling {#load_descendants!}.
+    #
+    # @return [Class]
+    attr_accessor :vertex_model
+
+    ##
+    # The vertex model used by this graph.
+    #
+    # This must be defined before calling {#load_descendants!}.
+    #
+    # @return [Class]
+    attr_accessor :edge_model
+
+    ##
+    # Given a set of `vertices`, builds a subgraph from those vertices and their
+    # descendants.
+    #
+    # This method is intended to be used in the case where `vertices` contains
+    # only source vertices (vertices having indegree zero), but can be used with
+    # non-source vertices as well.
+    #
+    # If your vertices may be one of many subclasses (i.e. you're using single
+    # table inheritance in your vertices table), then you should use the base
+    # class for {#vertex_model}.
+    #
+    # @param [Array<ActiveRecord::Base>] vertices the vertices to start from
+    # @param [Class] vertex_model the model class used for representing vertices
+    # @param [Class] edge_model the model class used for representing edges
+    # @return [Graph] a subgraph
+    def self.from_vertices(vertices, vertex_model, edge_model)
+      new.tap do |g|
+        g.vertex_model = vertex_model
+        g.edge_model = edge_model
+        g.vertices = vertices
+        g.load_descendants!
+      end
+    end
+
+    def initialize
+      self.vertices = []
+      self.edges = []
+    end
+
+    ##
+    # Loads all descendants of the vertices in {#vertices}.
+    #
+    # {#vertex_model} and {#edge_model} must be set before calling this method.
+    # If either are not set, this method raises `RuntimeError`.
+    #
+    # Once vertices are loaded, load_descendants! loads all edges that connect
+    # vertices in the working vertex set.
+    #
+    # Vertices and edges that were present before a load_descendants! call will
+    # remain in {#vertices} and {#edges}, respectively.
+    #
+    # @raise [RuntimeError] if {#vertex_model} or {#edge_model} are unset
+    def load_descendants!
+      raise 'vertex_model and edge_model must be set' unless vertex_model && edge_model
+
+      self.vertices += vertex_model.descendants_of(*vertices)
+      self.edges += edge_model.connecting(*vertices)
+    end
+
+    ##
+    # Returns the source vertices in the graph.  Sources are not returned in any
+    # particular order.
+    #
+    # This method is implemented using a hash anti-join on vertex ID and edge
+    # child ID.  If a vertex is a child of some edge, then it is rejected, and
+    # thus only vertices that are not children of any edge (viz. have indegree
+    # zero and are therefore sources) remain.
+    #
+    # If this method is run on a subgraph of a larger graph, then the source
+    # determination is done relative to the subgraph.  Consider the following
+    # graph:
+    #
+    #     a   b
+    #      \ /
+    #       c
+    #       |
+    #       d
+    #
+    # When considering the vertex set `{ a, b, c, d }` and corresponding edge
+    # set, `c` is clearly not a source.  However, in the subgraph `S`
+    #
+    #     S = ({c, d}, {(c, d)})
+    #
+    # `c` _is_ a source, and if S were reified as a {Graph} instance (using, for
+    # example, {.from_vertices}), `[c]` would be the output of calling `sources`
+    # on that instance.
+    #
+    # This method expects all vertices and edges to have been persisted, and
+    # will return incorrect results if there exist unpersisted vertices or edges
+    # in the graph.  For this reason, it is advised that you ensure that all
+    # vertices and edges in a graph are saved before calling {#sources}.
+    #
+    # @return [Array<vertex_model>] an array of source vertices
+    def sources
+      ids = vertices.inject({}) { |r, v| r.update(v.id => v) }
+      children = edges.inject({}) { |r, e| r.update(e.child_id => true) }
+
+      ids.reject { |k, _| children[k] }.map { |_, v| v }
+    end
+  end
+end

data/lib/dagnabit/migration.rb

@@ -0,0 +1,98 @@
+require File.join(File.dirname(__FILE__), %w(.. dagnabit))
+
+module Dagnabit
+  ##
+  # Contains shorthand for setting up database triggers and constraints for
+  # maintaining dagnabit's invariants.  See the README for more information.
+  #
+  # This module is intended to be extended by subclasses of
+  # ActiveRecord::Migration.
+  module Migration
+    ##
+    # Instantiates a cycle check trigger on `edge_table`.  The trigger is
+    # executed on a per row basis for every insert or update.
+    #
+    # @param [Symbol, String] edge_table the table for the trigger
+    # @return [void]
+    def create_cycle_check_trigger(edge_table)
+      create_cycle_check_function(edge_table)
+
+      execute %Q{
+        CREATE TRIGGER #{trigger_name} AFTER INSERT OR UPDATE ON #{edge_table}
+          FOR EACH ROW EXECUTE PROCEDURE #{function_name}_#{edge_table}();
+      }.strip
+    end
+
+    ##
+    # Drops a trigger created by {#create_cycle_check_trigger}.
+    #
+    # @param [Symbol, String] edge_table the table owning the trigger
+    # @return [void]
+    def drop_cycle_check_trigger(edge_table)
+      execute %Q{
+        DROP TRIGGER #{trigger_name} ON #{edge_table};
+      }.strip
+
+      drop_cycle_check_function(edge_table)
+    end
+
+    ##
+    # Builds a PL/pgSQL function for performing cycle checks.
+    #
+    # If the function already exists, then calling this method will overwrite
+    # it.
+    #
+    # A `CREATE TRUSTED LANGUAGE plpgsql` declaration must have been made in the
+    # database prior to invocation of {#create_cycle_check_function}.
+    #
+    # @param [Symbol, String] edge_table the table to check
+    # @return [void]
+    def create_cycle_check_function(edge_table)
+      execute %Q{
+        CREATE OR REPLACE FUNCTION #{function_name}_#{edge_table}() RETURNS trigger AS $#{function_name}$
+          DECLARE
+            cyclic bool;
+          BEGIN
+            WITH RECURSIVE cycles(id, path, cycle) AS (
+              SELECT e.child_id, ARRAY[]::integer[], false
+                FROM #{edge_table} e WHERE e.parent_id = NEW.parent_id
+              UNION ALL
+              SELECT e.child_id, c.path || c.id, c.id = ANY(c.path)
+                FROM cycles c INNER JOIN #{edge_table} e ON e.parent_id = c.id AND NOT cycle
+            )
+            SELECT true FROM cycles WHERE cycle = true INTO cyclic;
+
+            IF cyclic = true THEN
+              RAISE EXCEPTION 'Edge (%, %) introduces a cycle', NEW.child_id, NEW.parent_id;
+            END IF;
+
+            RETURN NULL;
+          END;
+        $#{function_name}$ LANGUAGE plpgsql;
+      }.strip
+    end
+    
+    ##
+    # Drops the function created by {#create_cycle_check_function}.
+    #
+    # It is safe to call this method if the function was not previously
+    # created.
+    #
+    # @return [void]
+    def drop_cycle_check_function(edge_table)
+      execute %Q{
+        DROP FUNCTION IF EXISTS #{function_name}_#{edge_table}();
+      }.strip
+    end
+
+    private
+
+    def trigger_name
+      'dagnabit_cycle_check'
+    end
+
+    def function_name
+      'dagnabit_cycle_check'
+    end
+  end
+end

data/lib/dagnabit/version.rb

@@ -0,0 +1,3 @@
+module Dagnabit
+  VERSION = '3.0.0'
+end

data/lib/dagnabit/vertex.rb

@@ -0,0 +1,10 @@
+require File.join(File.dirname(__FILE__), %w(.. dagnabit))
+
+module Dagnabit::Vertex
+  autoload :Activation,   'dagnabit/vertex/activation'
+  autoload :Associations, 'dagnabit/vertex/associations'
+  autoload :Bonding,      'dagnabit/vertex/bonding'
+  autoload :Connectivity, 'dagnabit/vertex/connectivity'
+  autoload :Neighbors,    'dagnabit/vertex/neighbors'
+  autoload :Settings,     'dagnabit/vertex/settings'
+end