linkage 0.0.2 → 0.0.3

data/Gemfile

@@ -5,7 +5,6 @@ gem "sequel"
 group :development do
   gem "bundler", "~> 1.0.0"
   gem "jeweler", "~> 1.6.4"
-  gem "rcov", ">= 0"
   gem "test-unit", "2.3.2"
   gem "mocha"
   gem "sqlite3"
@@ -15,4 +14,6 @@ group :development do
   gem "mysql2"
   gem 'pry'
   gem 'rdiscount'
+  gem 'guard-test'
+  gem 'guard-yard'
 end

data/Gemfile.lock

@@ -3,7 +3,17 @@ GEM
   specs:
     blockenspiel (0.4.3)
     coderay (0.9.8)
+    ffi (1.0.11)
     git (1.2.5)
+    guard (1.0.0)
+      ffi (>= 0.5.0)
+      thor (~> 0.14.6)
+    guard-test (0.4.3)
+      guard (>= 0.4)
+      test-unit (~> 2.2)
+    guard-yard (1.0.2)
+      guard (>= 0.2.2)
+      yard (>= 0.7.0)
     jeweler (1.6.4)
       bundler (~> 1.0)
       git (>= 1.2.5)
@@ -11,39 +21,40 @@ GEM
     metaclass (0.0.1)
     method_source (0.6.7)
       ruby_parser (>= 2.3.1)
-    mocha (0.10.0)
+    mocha (0.10.3)
       metaclass (~> 0.0.1)
-    mysql2 (0.3.10)
+    mysql2 (0.3.11)
     pry (0.9.7.4)
       coderay (~> 0.9.8)
       method_source (~> 0.6.7)
       ruby_parser (>= 2.3.1)
       slop (~> 2.1.0)
     rake (0.9.2.2)
-    rcov (0.9.11)
     rdiscount (1.6.8)
     ruby_parser (2.3.1)
       sexp_processor (~> 3.0)
-    sequel (3.29.0)
-    sexp_processor (3.0.8)
+    sequel (3.31.0)
+    sexp_processor (3.0.10)
     slop (2.1.0)
-    sqlite3 (1.3.4)
+    sqlite3 (1.3.5)
     test-unit (2.3.2)
+    thor (0.14.6)
     versionomy (0.4.1)
       blockenspiel (>= 0.4.1)
-    yard (0.7.3)
+    yard (0.7.4)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.0.0)
+  guard-test
+  guard-yard
   jeweler (~> 1.6.4)
   mocha
   mysql2
   pry
   rake
-  rcov
   rdiscount
   sequel
   sqlite3

data/README.markdown

@@ -19,6 +19,8 @@ To describe a linkage, you use the `Dataset#link_with` method.
       lhs[:last_name].must == rhs[:parent_last_name]
       lhs[:last_name].must_not == "Smith"  # exclude parents with the last
                                            # name "Smith"
+
+      save_results_in('sqlite://results.db') # see below
     end
 
 Note that the datasets don't have to be in the same database, or even on
@@ -27,13 +29,14 @@ the same machine.
 To run a linkage, use a Runner with the resulting configuration from
 `Dataset#link_with`:
 
-    runner = Linkage::SingleThreadedRunner.new(config, 'sqlite://results.db')
+    runner = Linkage::SingleThreadedRunner.new(config)
     runner.execute
 
-The runner needs a database URI, since it stores its results in two
-database tables: `groups` and `groups_records`. The `groups` table contains
-all of the unique combinations of values in your datasets, and
-`groups_records` maps records to groups.
+The runner saves results in a database that you specify in the configuration
+(via the `save_results_in` method). It stores its results in two database
+tables: `groups` and `groups_records`. The `groups` table contains all of the
+unique combinations of values in your datasets, and `groups_records` maps
+records to groups.
 
 You can also link a dataset to itself:
 

data/Rakefile

@@ -32,14 +32,6 @@ Rake::TestTask.new(:test) do |test|
   test.verbose = true
 end
 
-require 'rcov/rcovtask'
-Rcov::RcovTask.new do |test|
-  test.libs << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-  test.rcov_opts << '--exclude "gems/*"'
-end
-
 task :default => :test
 
 require 'rdoc/task'

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/lib/linkage/configuration.rb

@@ -1,188 +1,286 @@
 module Linkage
-  # {Configuration} is used to configure linkages. When you call
-  # {Dataset#link_with}, the block you supply gets called in the context of
-  # an instance of {Configuration}.
-  #
-  # @example
-  #   dataset_1 = Linkage::Dataset.new("mysql://example.com/database_name", "table_1")
-  #   dataset_2 = Linkage::Dataset.new("mysql://example.com/database_name", "table_2")
-  #   dataset_1.link_with(dataset_2) do
-  #     # this gets run inside of a Configuration instance
-  #   end
-  #
-  # @see Dataset#link_with
   class Configuration
-    # @private
-    class ExpectationWrapper
-      def initialize(type, data, config)
-        @type = type
-        @data = data
-        @config = config
-        @side = nil
-        @forced_kind = nil
-      end
+    class DSL
+      class ExpectationWrapper
+        VALID_OPERATORS = [:==, :>, :<, :>=, :<=]
+        OPERATOR_OPPOSITES = {
+          :==   => :'!=',
+          :>    => :<=,
+          :<=   => :>,
+          :<    => :>=,
+          :>=   => :<
+        }
+
+        attr_reader :kind, :side, :lhs, :rhs
+
+        def initialize(dsl, type, lhs)
+          @dsl = dsl
+          @type = type
+          @lhs = lhs
+          @rhs = nil
+          @side = nil
+          @kind = nil
+        end
+
+        VALID_OPERATORS.each do |operator|
+          define_method(operator) do |rhs|
+            # NOTE: lhs is always a DataWrapper
+
+            @rhs = rhs
+            if !@rhs.is_a?(DataWrapper) || @lhs.static? || @rhs.static? || @lhs.side == @rhs.side
+              @side = @lhs.side
+              @side = @rhs.side if @side.nil? && @rhs.is_a?(DataWrapper)
+              @kind = :filter
+            elsif @lhs.same_except_side?(@rhs)
+              @kind = :self
+            elsif @lhs.dataset == @rhs.dataset
+              @kind = :cross
+            else
+              @kind = :dual
+            end
+            @operator = @type == :must_not ? OPERATOR_OPPOSITES[operator] : operator
+            @dsl.add_expectation(self)
+          end
+        end
+
+        def merged_field
+          @merged_field ||= @lhs.data.merge(@rhs.data)
+        end
+
+        def filter_expr
+          if @filter_expr.nil? && @kind == :filter
+            if @lhs.is_a?(DataWrapper) && !@lhs.static?
+              target = @lhs
+              other = @rhs
+            elsif @rhs.is_a?(DataWrapper) && !@rhs.static?
+              target = @rhs
+              other = @lhs
+            else
+              raise "Wonky filter"
+            end
 
-      Linkage::Expectation::VALID_OPERATORS.each do |op|
-        define_method(op) do |other|
-          case other
-          when DataWrapper
-            @other = other.data
-            if @other.static? || other.side == @data.side
-              @forced_kind = :filter
-              @side = @data.side
+            arg1 = target.data.to_expr
+            arg2 = other.is_a?(DataWrapper) ? other.data.to_expr : other
+            @filter_expr =
+              case @operator
+              when :==
+                { arg1 => arg2 }
+              when :'!='
+                ~{ arg1 => arg2 }
+              else
+                arg1 = Sequel::SQL::Identifier.new(arg1)
+                arg2 = arg2.is_a?(Symbol) ? Sequel::SQL::Identifier.new(arg2) : arg2
+                Sequel::SQL::BooleanExpression.new(@operator, arg1, arg2)
+              end
+          end
+          @filter_expr
+        end
+
+        def apply_to(dataset, side)
+          if @kind == :filter
+            if @side == side
+              return dataset.filter(filter_expr)
+            else
+              # Doesn't apply
+              return dataset
             end
+          end
+
+          if @lhs.is_a?(DataWrapper) && @lhs.side == side
+            target = @lhs
+          elsif @rhs.is_a?(DataWrapper) && @rhs.side == side
+            target = @rhs
           else
-            @other = other
-            @side = @data.side
+            raise "Wonky expectation"
+          end
+
+          expr = target.data.to_expr
+          aliased_expr = expr
+          if expr != merged_field.name
+            aliased_expr = expr.as(merged_field.name)
           end
-          add_expectation(op)
+
+          dataset.order_more(expr).select_more(aliased_expr)
+        end
+
+        def same_filter?(other)
+          kind == :filter && other.kind == :filter && filter_expr == other.filter_expr
         end
       end
 
-      private
+      class DataWrapper
+        attr_reader :side, :dataset
 
-      def add_expectation(operator)
-        klass = Expectation.get(@type)
-        exp = klass.new(operator, @data.data, @other, @forced_kind)
-        @config.add_expectation(exp, @side)
+        [:must, :must_not].each do |type|
+          define_method(type) do
+            ExpectationWrapper.new(@dsl, type, self)
+          end
+        end
       end
-    end
 
-    # @private
-    class DataWrapper
-      attr_reader :data, :side
+      class FieldWrapper < DataWrapper
+        attr_reader :name
 
-      def must
-        ExpectationWrapper.new(:must, self, @config)
-      end
+        def initialize(dsl, side, dataset, name)
+          @dsl = dsl
+          @side = side
+          @dataset = dataset
+          @name = name
+        end
 
-      def must_not
-        ExpectationWrapper.new(:must_not, self, @config)
-      end
+        def static?
+          false
+        end
+
+        def same_except_side?(other)
+          other.is_a?(FieldWrapper) && name == other.name
+        end
 
-      def static?
-        false
+        def data
+          @dataset.field_set[@name]
+        end
       end
-    end
 
-    # @private
-    class FunctionWrapper < DataWrapper
-      def initialize(klass, args, config)
-        @klass = klass
-        @args = args
-        @config = config
+      class FunctionWrapper < DataWrapper
+        attr_reader :klass, :args
+
+        def initialize(dsl, klass, args)
+          @dsl = dsl
+          @klass = klass
+          @args = args
+          @side = nil
+          @static = true
+          args.each do |arg|
+            if arg.kind_of?(DataWrapper)
+              raise "conflicting sides" if @side && @side != arg.side
+              @side = arg.side
+              @static &&= arg.static?
+            end
+          end
+        end
 
-        @side = args.inject(nil) do |side, arg|
-          if arg.kind_of?(DataWrapper)
-            raise "conflicting sides" if side && side != arg.side
-            arg.side
-          else
-            side
+        def data
+          @data ||= @klass.new(*@args.collect { |arg| arg.kind_of?(DataWrapper) ? arg.data : arg })
+        end
+
+        def name
+          data.name
+        end
+
+        def static?
+          @static
+        end
+
+        def same_except_side?(other)
+          if other.is_a?(FunctionWrapper) && klass == other.klass
+            args.each_with_index do |arg, i|
+              other_arg = other.args[i]
+              if arg.is_a?(DataWrapper) && other_arg.is_a?(DataWrapper)
+                if !arg.same_except_side?(other_arg)
+                  return false
+                end
+              else
+                if arg != other_arg
+                  return false
+                end
+              end
+            end
+            return true
           end
+          false
         end
       end
 
-      def data
-        @klass.new(*@args.collect { |arg| arg.kind_of?(DataWrapper) ? arg.data : arg })
+      class DatasetWrapper
+        def initialize(dsl, side, dataset)
+          @dsl = dsl
+          @dataset = dataset
+          @side = side
+        end
+
+        def [](field_name)
+          if @dataset.field_set.has_key?(field_name)
+            FieldWrapper.new(@dsl, @side, @dataset, field_name)
+          else
+            raise ArgumentError, "The '#{field_name}' field doesn't exist for the #{@side} dataset!"
+          end
+        end
       end
-    end
 
-    # @private
-    class FieldWrapper < DataWrapper
-      def initialize(field, side, config)
-        @data = field
-        @side = side
+      def initialize(config, &block)
         @config = config
+        @lhs_filters = []
+        @rhs_filters = []
+        instance_eval(&block)
       end
-    end
 
-    # @private
-    class DatasetWrapper
-      def initialize(dataset, side, config)
-        @dataset = dataset
-        @side = side
-        @config = config
+      def lhs
+        DatasetWrapper.new(self, :lhs, @config.dataset_1)
       end
 
-      def [](field_name)
-        field = @dataset.fields[field_name]
-        if field.nil?
-          raise ArgumentError, "The '#{field_name}' field doesn't exist for that dataset!"
-        end
-        FieldWrapper.new(field, @side, @config)
+      def rhs
+        DatasetWrapper.new(self, :rhs, @config.dataset_2)
       end
-    end
 
-    include Utils
+      def save_results_in(uri, options = {})
+        @config.results_uri = uri
+        @config.results_uri_options = options
+      end
 
-    # @return [Symbol] :self, :dual, or :cross
-    attr_reader :linkage_type
+      def add_expectation(expectation)
+        @config.expectations << expectation
+
+        if @config.linkage_type == :self
+          case expectation.kind
+          when :cross
+            @config.linkage_type = :cross
+          when :filter
+            # If there different filters on both 'sides' of a self-linkage,
+            # it turns into a cross linkage.
+            these_filters, other_filters =
+              case expectation.side
+              when :lhs
+                [@lhs_filters, @rhs_filters]
+              when :rhs
+                [@rhs_filters, @lhs_filters]
+              end
 
-    # @return [Array<Linkage::Expectation>]
-    attr_reader :expectations
+            these_filters << expectation
+            other_filters.each do |other|
+              if !expectation.same_filter?(other)
+                @config.linkage_type = :cross
+                break
+              end
+            end
+          end
+        end
+      end
 
-    # @return [Linkage::Dataset]
-    attr_reader :dataset_1
+      # For handling functions
+      def method_missing(name, *args, &block)
+        klass = Function[name.to_s]
+        if klass
+          FunctionWrapper.new(self, klass, args)
+        else
+          super
+        end
+      end
+    end
 
-    # @return [Linkage::Dataset]
-    attr_reader :dataset_2
+    attr_reader :dataset_1, :dataset_2, :expectations
+    attr_accessor :linkage_type, :results_uri, :results_uri_options
 
     def initialize(dataset_1, dataset_2)
-      @dataset_1 = dataset_1.clone
-      @dataset_2 = dataset_2.clone
+      @dataset_1 = dataset_1
+      @dataset_2 = dataset_2
       @expectations = []
       @linkage_type = dataset_1 == dataset_2 ? :self : :dual
-      @lhs_filters = []
-      @rhs_filters = []
-    end
-
-    def lhs
-      @lhs ||= DatasetWrapper.new(@dataset_1, :lhs, self)
     end
 
-    def rhs
-      @rhs ||= DatasetWrapper.new(@dataset_2, :rhs, self)
+    def configure(&block)
+      DSL.new(self, &block)
     end
 
-    # @private
-    def add_expectation(expectation, side = nil)
-      # If the expectation created turns the linkage type from a self to a
-      # cross, then the dataset gets a new id. This is so that
-      # Expectation#apply does the right thing.
-
-      @expectations << expectation
-      if @linkage_type == :self
-        cross = false
-
-        case expectation.kind
-        when :cross
-          cross = true
-        when :filter
-          # If there different filters on both 'sides' of a self-linkage,
-          # it turns into a cross linkage.
-          these_filters, other_filters =
-            case side
-            when :lhs
-              [@lhs_filters, @rhs_filters]
-            when :rhs
-              [@rhs_filters, @lhs_filters]
-            end
-
-          if !other_filters.empty? && !other_filters.include?(expectation)
-            cross = true
-          else
-            these_filters << expectation
-          end
-        end
-
-        if cross
-          @linkage_type = :cross
-          @dataset_2.send(:set_new_id)
-        end
-      end
-    end
-
-    # @private
     def groups_table_schema
       schema = []
 
@@ -193,26 +291,16 @@ module Linkage
       @expectations.each do |exp|
         next  if exp.kind == :filter
 
-        merged_type = exp.merged_field.ruby_type
-        schema << [exp.name, merged_type[:type], merged_type[:opts] || {}]
+        merged_field = exp.merged_field
+        merged_type = merged_field.ruby_type
+        schema << [merged_field.name, merged_type[:type], merged_type[:opts] || {}]
       end
 
       schema
     end
 
-    # @private
-    def inspect
-      to_s
-    end
-
-    # For handling functions
-    def method_missing(name, *args, &block)
-      klass = Function[name.to_s]
-      if klass
-        FunctionWrapper.new(klass, args, self)
-      else
-        super
-      end
+    def result_set
+      @result_set ||= ResultSet.new(self)
     end
   end
 end

data/lib/linkage/data.rb

@@ -28,10 +28,6 @@ module Linkage
       raise NotImplementedError
     end
 
-    def dataset
-      raise NotImplementedError
-    end
-
     def to_expr
       raise NotImplementedError
     end
@@ -126,26 +122,6 @@ module Linkage
       Field.new(name, nil, result)
     end
 
-    # Returns true if this data's name and dataset match the other's name
-    # and dataset (using {Dataset#==})
-    def ==(other)
-      if !other.is_a?(self.class)
-        super
-      elsif equal?(other)
-        true
-      else
-        self.name == other.name && self.dataset == other.dataset
-      end
-    end
-
-    # Returns true if this data source's dataset is equal to the given dataset
-    # (using Dataset#id).
-    #
-    # @param [Linkage::Dataset]
-    def belongs_to?(dataset)
-      self.dataset.id == dataset.id
-    end
-
     private
 
     def first_common_type(type_1, type_2)