dagnabit 2.2.1

data/init.rb

@@ -0,0 +1 @@
+require 'dagnabit'

data/lib/dagnabit.rb

@@ -0,0 +1,17 @@
+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)

data/lib/dagnabit/activation.rb

@@ -0,0 +1,60 @@
+module Dagnabit
+  #
+  # Class methods for mixing in ("activating") dag functionality.
+  #
+  module Activation
+    # 
+    # Marks an ActiveRecord model as a link model.
+    #
+    # == Supported options
+    #
+    # [:ancestor_id_column]
+    #   Name of the column in the link tables that will hold the ID of the
+    #   ancestor object.  Defaults to +ancestor_id+.
+    # [:descendant_id_column]
+    #   Name of the column in the link tables that will hold the ID of the
+    #   descendant object.  Defaults to +descendant_id+.
+    # [:transitive_closure_table_name]
+    #   Name of the table that will hold the tuples comprising the transitive
+    #   closure of the dag.  Defaults to the edge model's table name affixed by
+    #   "<tt>_transitive_closure_tuples</tt>".
+    # [:transitive_closure_class_name]
+    #   Name of the generated class that will represent tuples in the transitive
+    #   closure tuple table.  This class is created inside the link model class.
+    #   Defaults to +TransitiveClosureLink+.
+    #
+    def acts_as_dag_link(options = {})
+      extend Dagnabit::Link::Configuration
+      configure_acts_as_dag_link(options)
+
+      extend Dagnabit::Link::TransitiveClosureLinkModel
+      generate_transitive_closure_link_model(options)
+
+      extend Dagnabit::Link::ClassMethods
+      extend Dagnabit::Link::Associations
+      extend Dagnabit::Link::NamedScopes
+      extend Dagnabit::Link::Validations
+      include Dagnabit::Link::CyclePrevention
+      include Dagnabit::Link::TransitiveClosureRecalculation
+    end
+
+    #
+    # Adds convenience methods to dag nodes.
+    #
+    # Strictly speaking, it's not necessary to call this method inside classes
+    # you want to act as nodes.  +acts_as_dag_node_linked_by+ merely provides
+    # convenience methods for finding and traversing links from/to this node.
+    #
+    # The +link_class_name+ parameter determines the the link model to be used
+    # for nodes of this type.
+    #
+    def acts_as_dag_node_linked_by(link_class_name)
+      extend Dagnabit::Node::Configuration
+      configure_acts_as_dag_node(link_class_name)
+
+      extend Dagnabit::Node::ClassMethods
+      extend Dagnabit::Node::Associations
+      include Dagnabit::Node::Neighbors
+    end
+  end
+end

data/lib/dagnabit/link/associations.rb

@@ -0,0 +1,18 @@
+module Dagnabit
+  module Link
+    #
+    # Adds associations useful for link classes.
+    #
+    # This module mixes in the following associations to link classes:
+    #
+    # * +ancestor+: the source of this link, or where this link begins
+    # * +descendant+: the target of this link, or where this link ends
+    #
+    module Associations
+      def self.extended(base)
+        base.send(:belongs_to, :ancestor, :polymorphic => true, :foreign_key => base.ancestor_id_column)
+        base.send(:belongs_to, :descendant, :polymorphic => true, :foreign_key => base.descendant_id_column)
+      end
+    end
+  end
+end

data/lib/dagnabit/link/class_methods.rb

@@ -0,0 +1,43 @@
+module Dagnabit
+  module Link
+    #
+    # Handy class methods for creating and querying paths.
+    #
+    module ClassMethods
+      #
+      # Constructs a new edge.  The direction of the edge runs from +from+ to +to+.
+      #
+      def build_edge(from, to, attributes = {})
+        new(attributes.merge(:ancestor => from, :descendant => to))
+      end
+
+      #
+      # Like +build_edge+, but saves the edge after it is instantiated.
+      # Returns true if the endpoints could be connected, false otherwise.
+      #
+      # See Dagnabit::Link::Validations for more information on built-in link
+      # validations.
+      #
+      def connect(from, to, attributes = {})
+        build_edge(from, to, attributes).save
+      end
+
+      # 
+      # Returns true if there is a path from +a+ to +b+, false otherwise.
+      # 
+      def path?(a, b)
+        paths(a, b).count > 0
+      end
+
+      #
+      # Returns all paths from +a+ to +b+.
+      #
+      # These paths are returned as transitive closure links, which aren't
+      # guaranteed to have the same methods as your link class.
+      #
+      def paths(a, b)
+        transitive_closure_class.linking(a, b)
+      end
+    end
+  end
+end

data/lib/dagnabit/link/configuration.rb

@@ -0,0 +1,40 @@
+module Dagnabit
+  module Link
+    #
+    # Dagnabit::Edge::Configuration - dag edge configuration
+    #
+    module Configuration
+      attr_accessor :ancestor_id_column
+      attr_accessor :descendant_id_column
+      attr_writer :transitive_closure_table_name
+      attr_accessor :transitive_closure_class_name
+
+      #
+      # Configure an ActiveRecord model as a dag link. See Dagnabit::Activation
+      # for options description.
+      #
+      def configure_acts_as_dag_link(options)
+        self.ancestor_id_column = options[:ancestor_id_column] || 'ancestor_id'
+        self.descendant_id_column = options[:descendant_id_column] || 'descendant_id'
+        self.transitive_closure_table_name = options[:transitive_closure_table_name] || table_name + '_transitive_closure_tuples'
+        self.transitive_closure_class_name = options[:transitive_closure_class_name] || 'TransitiveClosureLink'
+      end
+
+      def transitive_closure_table_name
+        connection.quote_table_name(unquoted_transitive_closure_table_name)
+      end
+
+      def unquoted_transitive_closure_table_name
+        @transitive_closure_table_name
+      end
+
+      def ancestor_type_column
+        'ancestor_type'
+      end
+
+      def descendant_type_column
+        'descendant_type'
+      end
+    end
+  end
+end

data/lib/dagnabit/link/cycle_prevention.rb

@@ -0,0 +1,31 @@
+module Dagnabit
+  module Link
+    #
+    # Installs a callback into the link model to check for cycles.  If a cycle
+    # would be created by the addition of this link, prevents the link from
+    # being saved.
+    #
+    module CyclePrevention
+      #
+      # Performs cycle detection.
+      #
+      # Given an edge (A, B), insertion of that edge will create a cycle if
+      #
+      # * there is a path (B, A), or
+      # * A == B
+      #
+      def before_save
+        super
+        check_for_cycles 
+      end
+
+      private
+
+      def check_for_cycles
+        if ancestor && descendant
+          false if self.class.path?(descendant, ancestor) || descendant == ancestor
+        end
+      end
+    end
+  end
+end

data/lib/dagnabit/link/named_scopes.rb

@@ -0,0 +1,65 @@
+module Dagnabit
+  module Link
+    #
+    # Adds named scopes to Link models.
+    #
+    # This module provides two named scopes for finding links scoped by
+    # ancestor and descendant type.  They were designed as support for node
+    # neighbor queries such as ancestors_of_type and descendants_as_type, but
+    # can be used on their own.
+    #
+    # These links are imported into the generated transitive closure link model.
+    # See Dagnabit::Link::TransitiveClosureLinkModel for more information.
+    #
+    # == Supplied scopes
+    #
+    # [ancestor_type]
+    #   Returns all links having a specified ancestor type.
+    #
+    # [descendant_type]
+    #   Returns all links having a specified descendant type.
+    #
+    # == A note on type matching
+    #
+    # Types are stored in links using ActiveRecord's polymorphic association
+    # typing logic, and are matched using string matching.  Therefore, subclass
+    # matching and namespacing aren't provided.
+    #
+    # To elaborate on this, let's say you have the following model structure:
+    #
+    #   class Link < ActiveRecord::Base
+    #     acts_as_dag_link
+    #   end
+    #
+    #   module Foo
+    #     class Bar < ActiveRecord::Base
+    #       ...
+    #     end
+    #   end
+    #
+    # A link linking Foo::Bars will record Foo::Bar as ancestor or descendant
+    # type, not just 'Bar'.  The following will therefore not work:
+    #
+    #   Link.ancestor_type('Bar')
+    #
+    # You have to do:
+    #
+    #   Link.ancestor_type('Foo::Bar')
+    #
+    # or, if you'd like to hide the details of deriving a full class name:
+    #
+    #   Link.ancestor_type(Bar.name)
+    #
+    module NamedScopes
+      def self.extended(base)
+        base.send(:named_scope,
+                  :ancestor_type,
+                  lambda { |type| { :conditions => { :ancestor_type => type } } })
+
+        base.send(:named_scope,
+                  :descendant_type,
+                  lambda { |type| { :conditions => { :descendant_type => type } } })
+      end
+    end
+  end
+end

data/lib/dagnabit/link/transitive_closure_link_model.rb

@@ -0,0 +1,86 @@
+module Dagnabit
+  module Link
+    #
+    # Builds a model for transitive closure tuples.
+    #
+    # The transitive closure model is generated inside the link class.
+    # Therefore, if your link model class was called Link, the transitive
+    # closure model would be named Link::(class name here).  The name of the
+    # transitive closure model class is determined when the link class model is
+    # activated; see Dagnabit::Activation#acts_as_dag_link for more information.
+    #
+    # == Model class details
+    # 
+    # === Construction details
+    #
+    # The transitive closure model is constructed as a subclass of
+    # ActiveRecord::Base, _not_ as a subclass of your link model class.  The
+    # transitive closure model also acts as a dag link (via
+    # Dagnabit::Activation#acts_as_dag_link) and is configured using the same
+    # configuration options as your link model class.
+    #
+    # This means:
+    #
+    # * The transitive closure tuple table and your link table must have the
+    #   same column names for ancestor id/type and descendant id/type.
+    # * You will not be able to use any methods defined on your link model on
+    #   the transitive closure model.
+    #
+    # === Available methods
+    #
+    # The following class methods are available on transitive closure link
+    # models:
+    #
+    # [linking(a, b)]
+    #   Returns all links (direct or indirect) linking +a+ and +b+.  
+    # [ancestor_type(type)]
+    #   Behaves identically to the ancestor_type named scope defined in
+    #   Dagnabit::Link::NamedScopes.
+    # [descendant_type(type)]
+    #   Behaves identically to the descendant_type named scope defined in
+    #   Dagnabit::Link::NamedScopes.
+    #
+    # The following instance methods are available on transitive closure link
+    # models:
+    #
+    # [ancestor]
+    #   Returns the ancestor of this link.  Behaves identically to the
+    #   ancestor association defined in Dagnabit::Link::Associations.
+    # [descendant]
+    #   Returns the descendant of this link.  Behaves identically to the
+    #   descendant association defined in Dagnabit::Link::Associations.
+    #
+    module TransitiveClosureLinkModel
+      attr_reader :transitive_closure_class
+
+      private
+
+      #
+      # Generates the transitive closure model.
+      #
+      def generate_transitive_closure_link_model(options)
+        original_class = self
+
+        klass = Class.new(ActiveRecord::Base) do
+          extend Dagnabit::Link::Configuration
+
+          configure_acts_as_dag_link(options)
+          set_table_name original_class.unquoted_transitive_closure_table_name
+        end
+
+        @transitive_closure_class = const_set(transitive_closure_class_name, klass)
+
+        # reflections and named scopes aren't properly created in anonymous
+        # models, so we need to do that work after the model has been named
+        @transitive_closure_class.extend(Dagnabit::Link::Associations)
+        @transitive_closure_class.extend(Dagnabit::Link::NamedScopes)
+        @transitive_closure_class.named_scope :linking, lambda { |from, to|
+            { :conditions => { ancestor_id_column => from.id,
+                               ancestor_type_column => from.class.name,
+                               descendant_id_column => to.id,
+                               descendant_type_column => to.class.name } }
+        }
+      end
+    end
+  end
+end

data/lib/dagnabit/link/transitive_closure_recalculation.rb

@@ -0,0 +1,17 @@
+require 'dagnabit/link/transitive_closure_recalculation/on_create'
+require 'dagnabit/link/transitive_closure_recalculation/on_destroy'
+require 'dagnabit/link/transitive_closure_recalculation/on_update'
+
+module Dagnabit
+  module Link
+    #
+    # Code to do the heavy lifting of maintaining the transitive closure of the
+    # dag after edge create, destroy, and update.
+    # 
+    module TransitiveClosureRecalculation
+      include OnCreate
+      include OnDestroy
+      include OnUpdate
+    end
+  end
+end

data/lib/dagnabit/link/transitive_closure_recalculation/on_create.rb

@@ -0,0 +1,104 @@
+require 'dagnabit/link/transitive_closure_recalculation/utilities'
+
+module Dagnabit
+  module Link
+    module TransitiveClosureRecalculation
+      module OnCreate
+        include Utilities
+
+        def after_create
+          super
+          update_transitive_closure_for_create
+        end
+
+        private
+
+        def update_transitive_closure_for_create
+          tc = self.class.transitive_closure_table_name
+          tc_aid, tc_did, tc_atype, tc_dtype = quoted_dag_link_column_names
+          aid, did, atype, dtype = quoted_dag_link_values
+          all_columns = all_quoted_column_names.join(',')
+          all_values = all_quoted_column_values.join(',')
+
+          with_temporary_edge_tables('new', 'delta') do |new, delta|
+            extend_connected_paths(new, tc_aid, tc_did, tc_atype, tc_dtype, tc, aid, did, atype, dtype)
+            append_created_edge(new, all_columns, all_values)
+            synchronize_transitive_closure(new, delta, all_columns, tc, tc_aid, tc_did, tc_atype, tc_dtype)
+          end
+        end
+
+        #
+        # determine:
+        # * all paths constructed by adding (a, b) to the back of paths
+        #   ending at a (first subselect)
+        # * all paths constructed by adding (a, b) to the front of paths
+        #   starting at b (second subselect)
+        # * all paths constructed by adding (a, b) in the middle of paths
+        #   starting at a and ending at b (third subselect)
+        #
+        def extend_connected_paths(new, tc_aid, tc_did, tc_atype, tc_dtype, tc, aid, did, atype, dtype)
+          connection.execute <<-END
+            INSERT INTO #{new} (#{tc_aid}, #{tc_did}, #{tc_atype}, #{tc_dtype})
+              SELECT * FROM (
+                SELECT
+                  TC.#{tc_aid}, #{did}, TC.#{tc_atype}, #{dtype}
+                  FROM
+                    #{tc} AS TC
+                  WHERE
+                    TC.#{tc_did} = #{aid} AND TC.#{tc_dtype} = #{atype}
+                UNION
+                SELECT
+                  #{aid}, TC.#{tc_did}, #{atype}, TC.#{tc_dtype}
+                  FROM
+                    #{tc} AS TC
+                  WHERE
+                    TC.#{tc_aid} = #{did} AND TC.#{tc_atype} = #{dtype}
+                UNION
+                SELECT
+                  TC1.#{tc_aid}, TC2.#{tc_did}, TC1.#{tc_atype}, TC2.#{tc_dtype}
+                  FROM
+                    #{tc} AS TC1, #{tc} AS TC2
+                  WHERE
+                    TC1.#{tc_did} = #{aid} AND TC1.#{tc_dtype} = #{atype}
+                    AND
+                    TC2.#{tc_aid} = #{did} AND TC2.#{tc_atype} = #{dtype}
+              ) AS tmp0
+          END
+        end
+
+        def append_created_edge(new, all_columns, all_values)
+          connection.execute <<-END
+            INSERT INTO #{new} (#{all_columns}) VALUES (#{all_values})
+          END
+        end
+
+        def synchronize_transitive_closure(new, delta, all_columns, tc, tc_aid, tc_did, tc_atype, tc_dtype)
+          #
+          # ...filter out duplicates...
+          #
+          connection.execute <<-END
+            INSERT INTO #{delta}
+            SELECT * FROM #{new} AS T
+              WHERE NOT EXISTS (
+                SELECT *
+                  FROM
+                    #{tc} AS TC
+                  WHERE
+                    TC.#{tc_aid} = T.#{tc_aid} AND TC.#{tc_did} = T.#{tc_did}
+                    AND
+                    TC.#{tc_atype} = T.#{tc_atype} AND TC.#{tc_dtype} = T.#{tc_dtype}
+              )
+          END
+
+          #
+          # ...and update the transitive closure table
+          #
+          connection.execute <<-END
+            INSERT INTO #{tc} (#{all_columns})
+              SELECT * FROM #{delta}
+          END
+        end
+      end
+    end
+  end
+end