linkage 0.0.0

data/lib/linkage/dataset.rb

@@ -0,0 +1,205 @@
+module Linkage
+  # Wrapper for a Sequel dataset
+  class Dataset
+    @@next_id = 1 # Internal ID used for expectations
+    @@next_id_mutex = Mutex.new
+
+    # @private
+    def self.next_id
+      result = nil
+      @@next_id_mutex.synchronize do
+        result = @@next_id
+        @@next_id += 1
+      end
+      result
+    end
+
+    # @return [Array] Schema information about the dataset's primary key
+    attr_reader :primary_key
+
+    # @return [Array] Schema information for this dataset
+    attr_reader :schema
+
+    # @return [String] Database URI
+    attr_reader :uri
+
+    # @return [Symbol] Database table name
+    attr_reader :table
+
+    # @return [Array<Linkage::Field>] List of {Linkage::Field}'s
+    attr_reader :fields
+
+    # @private
+    attr_reader :id
+
+    # @param [String] uri Sequel-style database URI
+    # @param [String, Symbol] table Database table name
+    # @param [Hash] options Options to pass to Sequel.connect
+    # @see http://sequel.rubyforge.org/rdoc/files/doc/opening_databases_rdoc.html Sequel: Connecting to a database
+    def initialize(uri, table, options = {})
+      @id = self.class.next_id
+      @uri = uri
+      @table = table.to_sym
+      @options = options
+      schema = nil
+      database { |db| schema = db.schema(@table) }
+      @schema = schema
+      @order = []
+      @select = []
+      @filter = []
+      create_fields
+    end
+
+    # Setup a linkage with another dataset
+    #
+    # @return [Linkage::Configuration]
+    def link_with(dataset, &block)
+      conf = Configuration.new(self, dataset)
+      conf.instance_eval(&block)
+      conf
+    end
+
+    # Compare URI and database table name
+    #
+    # @return [Boolean]
+    def ==(other)
+      if !other.is_a?(Dataset)
+        super
+      else
+        uri == other.uri && table == other.table
+      end
+    end
+
+    # Create a copy of this instance of Dataset, using {Dataset#initialize}.
+    #
+    # @return [Linkage::Dataset]
+    def dup
+      self.class.new(uri, table)
+    end
+
+    # Clone the dataset and its associated {Linkage::Field}'s (without hitting
+    # the database).
+    #
+    # @return [Linkage::Dataset]
+    def clone
+      other = self.class.allocate
+      other.send(:initialize_copy, self, {
+        :order => @order.clone, :select => @select.clone,
+        :filter => @filter.clone, :options => @options.clone
+      })
+    end
+
+    # Add a field to use for ordering the dataset.
+    #
+    # @param [Linkage::Field] field
+    # @param [nil, Symbol] desc nil or :desc (for descending order)
+    def add_order(field, desc = nil)
+      expr = desc == :desc ? field.name.desc : field.name
+      unless @order.include?(expr)
+        @order << expr
+      end
+    end
+
+    # Add a field to be selected on the dataset. If you don't add any
+    # selects, all fields will be selected. The primary key is always
+    # selected in either case.
+    #
+    # @param [Linkage::Field] field
+    # @param [Symbol] as Optional field alias
+    def add_select(field, as = nil)
+      expr = as ? field.name.as(as) : field.name
+      unless @select.include?(expr)
+        @select << expr
+      end
+    end
+
+    # Add a filter (SQL WHERE) condition to the dataset.
+    #
+    # @param [Linkage::Field] field
+    # @param [Symbol] operator
+    # @param [Linkage::Field, Object] other
+    def add_filter(field, operator, other)
+      arg1 = field.name
+      arg2 = other.is_a?(Field) ? other.name : other
+      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
+      @filter << expr
+    end
+
+    # Yield each row of the dataset in a block.
+    #
+    # @yield [row] A Hash of two elements, :pk and :values, where row[:pk] is
+    #   the row's primary key value, and row[:values] is an array of all
+    #   selected values (except the primary key).
+    def each
+      database do |db|
+        ds = db[@table]
+
+        pk = @primary_key.name
+        if !@select.empty?
+          ds = ds.select(pk, *@select)
+        end
+        if !@order.empty?
+          ds = ds.order(*@order)
+        end
+        if !@filter.empty?
+          ds = ds.filter(*@filter)
+        end
+        ds.each do |row|
+          yield({:pk => row.delete(pk), :values => row})
+        end
+      end
+    end
+
+    private
+
+    def initialize_copy(dataset, options = {})
+      @id = dataset.id
+      @uri = dataset.uri
+      @table = dataset.table
+      @schema = dataset.schema
+      @options = options[:options]
+      @order = options[:order]
+      @select = options[:select]
+      @filter = options[:filter]
+      @fields = dataset.fields.inject({}) do |hsh, (name, field)|
+        new_field = field.clone
+        new_field.dataset = self
+        hsh[name] = new_field
+        hsh
+      end
+      @primary_key = @fields[dataset.primary_key.name]
+      self
+    end
+
+    def database(&block)
+      Sequel.connect(uri, @options, &block)
+    end
+
+    def create_fields
+      @fields = {}
+      @schema.each do |(name, column_schema)|
+        f = Field.new(name, column_schema)
+        f.dataset = self
+        @fields[name] = f
+
+        if @primary_key.nil? && column_schema[:primary_key]
+          @primary_key = f
+        end
+      end
+    end
+
+    def set_new_id
+      @id = self.class.next_id
+    end
+  end
+end

data/lib/linkage/expectation.rb

@@ -0,0 +1,138 @@
+module Linkage
+  class Expectation
+    VALID_OPERATORS = [:==, :>, :<, :>=, :<=, :'!=']
+
+    def self.get(type)
+      TYPES[type]
+    end
+
+    attr_reader :operator, :field_1, :field_2
+
+    # @param [Symbol] operator Currently, only :==
+    # @param [Linkage::Field, Object] field_1
+    # @param [Linkage::Field, Object] field_2
+    # @param [Symbol] force_kind Manually set type of expectation (useful for
+    #   a filter between two fields)
+    def initialize(operator, field_1, field_2, force_kind = nil)
+      if !(field_1.is_a?(Field) || field_2.is_a?(Field))
+        raise ArgumentError, "You must have at least one Linkage::Field"
+      end
+
+      if !VALID_OPERATORS.include?(operator)
+        raise ArgumentError, "Invalid operator: #{operator.inspect}"
+      end
+
+      @operator = operator
+      @field_1 = field_1
+      @field_2 = field_2
+      @kind = force_kind
+
+      if kind == :filter
+        if @field_1.is_a?(Field)
+          @filter_field = @field_1
+          @filter_value = @field_2
+        else
+          @filter_field = @field_2
+          @filter_value = @field_1
+        end
+      elsif @operator != :==
+        raise ArgumentError, "Inequality operators are not allowed for non-filter expectations"
+      end
+    end
+
+    def ==(other)
+      if other.is_a?(Expectation)
+        @operator == other.operator && @field_1 == other.field_1 &&
+          @field_2 == other.field_2
+      else
+        super
+      end
+    end
+
+    # @return [Symbol] :self, :dual, :cross, or :filter
+    def kind
+      @kind ||=
+        if !(@field_1.is_a?(Field) && @field_2.is_a?(Field))
+          :filter
+        elsif @field_1 == @field_2
+          :self
+        elsif @field_1.dataset == @field_2.dataset
+          :cross
+        else
+          :dual
+        end
+    end
+
+    # @return [Symbol] name of the merged field type
+    def name
+      merged_field.name
+    end
+
+    # @return [Linkage::Field] result of Field#merge between the two fields
+    def merged_field
+      @merged_field ||= @field_1.merge(@field_2)
+    end
+
+    # @return [Boolean] Whether or not this expectation involves a field in
+    #   the given dataset (Only useful for :filter expressions)
+    def applies_to?(dataset)
+      if kind == :filter
+        @filter_field.belongs_to?(dataset)
+      else
+        @field_1.belongs_to?(dataset) || @field_2.belongs_to?(dataset)
+      end
+    end
+
+    # Apply changes to a dataset based on the expectation, such as calling
+    # {Dataset#add_order}, {Dataset#add_select}, and {Dataset#add_filter}
+    # with the appropriate arguments.
+    def apply_to(dataset)
+      case kind
+      when :filter
+        if @filter_field.belongs_to?(dataset)
+          dataset.add_filter(@filter_field, @operator, @filter_value)
+        end
+      else
+        as =
+          if kind == :self
+            nil
+          else
+            name != @field_1.name ? name : nil
+          end
+
+        if @field_1.belongs_to?(dataset)
+          dataset.add_order(@field_1)
+          dataset.add_select(@field_1, as)
+        end
+        if @field_2.belongs_to?(dataset)
+          dataset.add_order(@field_2)
+          dataset.add_select(@field_2, as)
+        end
+      end
+    end
+  end
+
+  class MustExpectation < Expectation
+  end
+
+  class MustNotExpectation < Expectation
+    OPERATOR_OPPOSITES = {
+      :==   => :'!=',
+      :'!=' => :==,
+      :>    => :<=,
+      :<=   => :>,
+      :<    => :>=,
+      :>=   => :<
+    }
+
+    # Same as Expectation, except it negates the operator.
+    def initialize(operator, field_1, field_2, force_kind = nil)
+      super(OPERATOR_OPPOSITES[operator], field_1, field_2, force_kind)
+    end
+  end
+
+  Expectation::TYPES = {
+    :must => MustExpectation,
+    :must_not => MustNotExpectation
+  }
+end

data/lib/linkage/field.rb

@@ -0,0 +1,227 @@
+module Linkage
+  # This class is for holding information about a particular field in a
+  # dataset.
+  class Field
+    # A "tree" used to find compatible types.
+    TYPE_CONVERSION_TREE = {
+      TrueClass => [Integer],
+      Integer => [Bignum, Float],
+      Bignum => [BigDecimal],
+      Float => [BigDecimal],
+      BigDecimal => [String],
+      String => nil,
+      DateTime => nil,
+      Date => nil,
+      Time => nil,
+      File => nil
+    }
+
+    # @return [Symbol] This field's name
+    attr_reader :name
+
+    # @return [Symbol] This field's schema information
+    attr_reader :schema
+
+    # @attr [Linkage::Dataset] This field's associated dataset
+    attr_accessor :dataset
+
+    # Create a new instance of Field.
+    #
+    # @param [Symbol] name The field's name
+    # @param [Hash] schema The field's schema information
+    # @param [Hash] ruby_type The field's ruby type
+    def initialize(name, schema, ruby_type = nil)
+      @name = name
+      @schema = schema
+      @ruby_type = ruby_type
+    end
+
+    # Convert the column schema information to a hash of column options, one of
+    # which must be :type. The other options added should modify that type
+    # (e.g. :size). If a database type is not recognized, return it as a String
+    # type.
+    #
+    # @note This method comes more or less straight from Sequel
+    #   (lib/sequel/extensions/schema_dumper.rb).
+    def ruby_type
+      unless @ruby_type
+        hsh =
+          case t = @schema[:db_type].downcase
+          when /\A(?:medium|small)?int(?:eger)?(?:\((?:\d+)\))?(?: unsigned)?\z/o
+            {:type=>Integer}
+          when /\Atinyint(?:\((\d+)\))?\z/o
+            {:type =>@schema[:type] == :boolean ? TrueClass : Integer}
+          when /\Abigint(?:\((?:\d+)\))?(?: unsigned)?\z/o
+            {:type=>Bignum}
+          when /\A(?:real|float|double(?: precision)?)\z/o
+            {:type=>Float}
+          when 'boolean'
+            {:type=>TrueClass}
+          when /\A(?:(?:tiny|medium|long|n)?text|clob)\z/o
+            {:type=>String, :text=>true}
+          when 'date'
+            {:type=>Date}
+          when /\A(?:small)?datetime\z/o
+            {:type=>DateTime}
+          when /\Atimestamp(?:\((\d+)\))?(?: with(?:out)? time zone)?\z/o
+            {:type=>DateTime, :size=>($1.to_i if $1)}
+          when /\Atime(?: with(?:out)? time zone)?\z/o
+            {:type=>Time, :only_time=>true}
+          when /\An?char(?:acter)?(?:\((\d+)\))?\z/o
+            {:type=>String, :size=>($1.to_i if $1), :fixed=>true}
+          when /\A(?:n?varchar|character varying|bpchar|string)(?:\((\d+)\))?\z/o
+            {:type=>String, :size=>($1.to_i if $1)}
+          when /\A(?:small)?money\z/o
+            {:type=>BigDecimal, :size=>[19,2]}
+          when /\A(?:decimal|numeric|number)(?:\((\d+)(?:,\s*(\d+))?\))?\z/o
+            s = [($1.to_i if $1), ($2.to_i if $2)].compact
+            {:type=>BigDecimal, :size=>(s.empty? ? nil : s)}
+          when /\A(?:bytea|(?:tiny|medium|long)?blob|(?:var)?binary)(?:\((\d+)\))?\z/o
+            {:type=>File, :size=>($1.to_i if $1)}
+          when 'year'
+            {:type=>Integer}
+          else
+            {:type=>String}
+          end
+        hsh.delete_if { |k, v| v.nil? }
+        @ruby_type = {:type => hsh.delete(:type)}
+        @ruby_type[:opts] = hsh if !hsh.empty?
+      end
+      @ruby_type
+    end
+
+    # Create a field that can hold data from two other fields. If the fields
+    # have different types, the resulting type is determined via a
+    # type-conversion tree.
+    #
+    # @param [Linkage::Field] other
+    # @return [Linkage::Field]
+    def merge(other, new_name = nil)
+      schema_1 = self.ruby_type
+      schema_2 = other.ruby_type
+      if schema_1 == schema_2
+        result = schema_1
+      else
+        type_1 = schema_1[:type]
+        opts_1 = schema_1[:opts] || {}
+        type_2 = schema_2[:type]
+        opts_2 = schema_2[:opts] || {}
+        result_type = type_1
+        result_opts = schema_1[:opts] ? schema_1[:opts].dup : {}
+
+        # type
+        if type_1 != type_2
+          result_type = first_common_type(type_1, type_2)
+        end
+
+        # text
+        if opts_1[:text] != opts_2[:text]
+          # This can only be of type String.
+          result_opts[:text] = true
+          result_opts.delete(:size)
+        end
+
+        # size
+        if !result_opts[:text] && opts_1[:size] != opts_2[:size]
+          types = [type_1, type_2].uniq
+          if types.length == 1 && types[0] == BigDecimal
+            # Two decimals
+            if opts_1.has_key?(:size) && opts_2.has_key?(:size)
+              s_1 = opts_1[:size]
+              s_2 = opts_2[:size]
+              result_opts[:size] = [ s_1[0] > s_2[0] ? s_1[0] : s_2[0] ]
+
+              if s_1[1] && s_2[1]
+                result_opts[:size][1] = s_1[1] > s_2[1] ? s_1[1] : s_2[1]
+              else
+                result_opts[:size][1] = s_1[1] ? s_1[1] : s_2[1]
+              end
+            else
+              result_opts[:size] = opts_1.has_key?(:size) ? opts_1[:size] : opts_2[:size]
+            end
+          elsif types.include?(String) && types.include?(BigDecimal)
+            # Add one to the precision of the BigDecimal (for the dot)
+            if opts_1.has_key?(:size) && opts_2.has_key?(:size)
+              s_1 = opts_1[:size].is_a?(Array) ? opts_1[:size][0] + 1 : opts_1[:size]
+              s_2 = opts_2[:size].is_a?(Array) ? opts_2[:size][0] + 1 : opts_2[:size]
+              result_opts[:size] = s_1 > s_2 ? s_1 : s_2
+            elsif opts_1.has_key?(:size)
+              result_opts[:size] = opts_1[:size].is_a?(Array) ? opts_1[:size][0] + 1 : opts_1[:size]
+            elsif opts_2.has_key?(:size)
+              result_opts[:size] = opts_2[:size].is_a?(Array) ? opts_2[:size][0] + 1 : opts_2[:size]
+            end
+          else
+            # Treat as two strings
+            if opts_1.has_key?(:size) && opts_2.has_key?(:size)
+              result_opts[:size] = opts_1[:size] > opts_2[:size] ? opts_1[:size] : opts_2[:size]
+            elsif opts_1.has_key?(:size)
+              result_opts[:size] = opts_1[:size]
+            else
+              result_opts[:size] = opts_2[:size]
+            end
+          end
+        end
+
+        # fixed
+        if opts_1[:fixed] != opts_2[:fixed]
+          # This can only be of type String.
+          result_opts[:fixed] = true
+        end
+
+        result = {:type => result_type}
+        result[:opts] = result_opts  unless result_opts.empty?
+      end
+
+      if new_name
+        name = new_name.to_sym
+      else
+        name = self.name == other.name ? self.name : :"#{self.name}_#{other.name}"
+      end
+      Field.new(name, nil, result)
+    end
+
+    # Returns true if this field's name and dataset match the other's name
+    # and dataset (using {Dataset#==})
+    def ==(other)
+      if !other.is_a?(Field)
+        super
+      else
+        self.name == other.name && self.dataset == other.dataset
+      end
+    end
+
+    # Returns true if this field's dataset is equal to the given dataset
+    # (using Dataset#id).
+    #
+    # @param [Linkage::Dataset]
+    def belongs_to?(dataset)
+      self.dataset.id == dataset.id
+    end
+
+    def primary_key?
+      schema && schema[:primary_key]
+    end
+
+    private
+
+    def first_common_type(type_1, type_2)
+      types_1 = [type_1] + get_types(type_1)
+      types_2 = [type_2] + get_types(type_2)
+      (types_1 & types_2).first
+    end
+
+    # Get all types that the specified type can be converted to. Order
+    # matters.
+    def get_types(type)
+      result = []
+      types = TYPE_CONVERSION_TREE[type]
+      if types
+        result += types
+        types.each do |t|
+          result |= get_types(t)
+        end
+      end
+      result
+    end
+  end
+end