arel 0.1.0

data/doc/CONVENTIONS

@@ -0,0 +1,17 @@
+This file should ultimately be replaced by a series of tests, something like a lint tool.
+
+- all describes and its should use single quotes unless they have nested quotes.
+- object instantiation in tests for all objects that are not the SUT should be manufactured in a before
+- 'should' and other counterfactuals/subjunctive forms should not be used in tests
+- no doubles should be used except for behaviorist testing
+  - behaviorist testing is desirable only when interacting with the database or the session
+- when unit testing, always demonstrate behavior by using a real world example (as in, a public use of the API), so as to provide documentation.
+- use collect rather than map
+- jargon:
+  - 'obtains' is preferred to 'returns true'
+  - 'manufactures'
+- in tests
+  - when manufacturing expected values (right-hand-side of should), avoid convenience methods -- construct it by initializing the object directly (Foo.new(...)). This ensures equality expectations in tests are rigorous.
+  - the SUT should be manufactured inline inside the test, not in a before
+  - dependencies for the SUT should be manufactured using convenience methods (or whatever is most terse).
+- group conceptually related methods in a class within an inline module; immediately include that module.

data/doc/TODO

@@ -0,0 +1,118 @@
+todo:
+- fix AR again
+- blocks for joins
+- fix sql insertions 
+- implement mnesia adapter
+
+- CLEANUP!!!!!
+- rename externalize to derived.
+- deal with table tests in algebra
+- fix grouping
+- audit unit coverage of algebra
+- data objects
+- remove all explicit aliasing
+- scoped writes
+- refactor adapter pattern
+- break out adapters into sep modules
+- projection is by definition distincting?
+- union/intersection
+- cache expiry on write
+- transactions
+
+done:
+- and/or w/ predicates
+. Relation <=> Relation -> InnerJoinOperation
+. Relation << Relation -> LeftOuterJoinOperation
+. InnerJoinOperation.on(*Predicate) -> InnerJoinRelation
+. LeftOuterJoinOperation.on(*Predicate) -> LeftOuterJoinRelation
+. Relation[Symbol] -> Attribute
+. Relation[Range] -> Relation
+. Attribute == Attribute -> EqualityPredicate
+. Attribute >= Attribute -> GreaterThanOrEqualToPredicate
+. Relation.include?(Column) -> Predicate
+. Relation.project(*Column) -> ProjectRelation
+. Relation.select(*Predicate) -> SelectionRelation
+. Relation.order(*Column) -> OrderRelation
+. #to_sql
+. Remove Builder
+. Namespace
+. Audit SqlAlchemy for missing features
+- Generalized denormalizations on any aggregation (count, yes, but also max, min, average)
+- Remove operator overloading of << and <=> for joins. Make it just foo.join(bar) and foo.outer_join(bar).
+- Remove operator overloading of == for predicates. make it a.eq(b) (note lack of question mark).
+- hookup more predicates (=, <=, =>)
+- get some basic aggregations working: users.project(user[:points].max)
+- Alias Table Names
+- When joining with any sort of aggregation, it needs to be a nested select
+- get a value select working: users.project(users[:name], addresses.select(addresses[:user_id] == users[:id]).project(addresses[:id].count))
+- Session
+- sublimate values to deal with the fact that they must be quoted per engine
+- clean-up singleton monstrosity
+- extract hashing module
+- hash custom matcher
+- make session engine stuff follow laws of demeter - currently doing some odd method chaining? rethink who is responsible for what
+  - session just calls execute, passing in a connection; by default it gets a connection from the relation.
+- #formatter is now on value, attribute and relation; you must admit it's name is confusing given that e.g., relation already has a formatter (Sql::Relation) ... should it be called predicate formatter? operand1.to_sql(operand2.predicate) maybe prefer operand1.cast(operand2) or project or in light of
+  - renamed to #format: operand1.format(operand2)
+- rename sql strategies
+- need to_sql for ranges
+  - {:conditions=>{:id=>2..3}}
+- nested orderings
+- string passthrough
+  - conditions
+  - orderings
+- relation inclusion when given an array (1,2,3,4) should quote the elements using the appropriate quoting formatter taken from the attribute
+  - descend on array, along with bind written in terms of it
+- re-evaluate bind -- does bind belong inside the relation / predicate classes or in the factory methods?
+- string passthrough:
+ :joins=>"INNER JOIN posts ON comments.post_id = posts.id"
+- finish pending tests
+- test relation, table reset
+- test Value, in particular bind.
+- test blank checks in relation.rb
+- rename active_relation to arel
+- mock out database
+- fix complex joining cases:
+- active record query adapter
+- anonymous table names
+- Explicitly model recursive structural decomposition / polymorphism
+- Explicitly model the namer/externalizer using interpreter jargon
+- All Sql Strategies should be accumulations with the top-level relation?
+- instance methodify externalize
+- test: find_attribute_given_attribute and all @attribute ||= everywhere and memoization of table class.
+- rename select to where
+- rename all ion classes
+- joining with LIMIT is like aggregations!!
+- blocks for non-joins
+- expressions should be class-based, and joins too, anything _sql should be renamed
+- implement in memory adapter
+- clean up block_given stuff
+- reorganize sql tests
+- recursive memory operations
+- reorganize memory tests
+- result sets to attr correlation too
+- implement joins in memory
+- result sets should be array relations
+- fix AR
+- insertions for in memory
+- cross-engine joins
+
+icebox:
+- #bind in Attribute and Expression should be doing a descend?
+- try to make aggegration testing in join spec to be a bit more unit-like
+- standardize quoting  
+  - use strings everywhere, not symbols ?
+- "unit" test sql strategies
+  - use real world examples, so they should be like a tutorial.
+- rename the tion (Selection) classes so that words that don't end in tion don't seem inconsistent
+- consider this code from has_many:
+  # replace the SELECT clause with COUNT(*), preserving any hints within /* ... */
+  @reflection.options[:counter_sql] = @reflection.options[:finder_sql].sub(/SELECT (\/\*.*?\*\/ )?(.*)\bFROM\b/im) { "SELECT #{$1}COUNT(*) FROM" }
+- lock
+  - SELECT suchandsuch FOR UPDATE
+- joins become subselects in writes:
+users.delete().where( 
+    addresses.c.user_id== 
+         select([users.c.id]). 
+         where(users.c.name=='jack') 
+    )

data/lib/arel.rb

@@ -0,0 +1,10 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'rubygems'
+require 'activesupport'
+require 'activerecord'
+require 'active_record/connection_adapters/abstract/quoting'
+
+require 'arel/algebra'
+require 'arel/engines'
+require 'arel/session'

data/lib/arel/algebra.rb

@@ -0,0 +1,4 @@
+require 'arel/algebra/extensions'
+require 'arel/algebra/predicates'
+require 'arel/algebra/relations'
+require 'arel/algebra/primitives'

data/lib/arel/algebra/extensions.rb

@@ -0,0 +1,4 @@
+require 'arel/algebra/extensions/object'
+require 'arel/algebra/extensions/class'
+require 'arel/algebra/extensions/symbol'
+require 'arel/algebra/extensions/hash'

data/lib/arel/algebra/extensions/class.rb

@@ -0,0 +1,32 @@
+module Arel
+  module ClassExtensions
+    def attributes(*attrs)
+      @attributes = attrs
+      attr_reader *attrs
+    end
+
+    def deriving(*methods)
+      methods.each { |m| derive m }
+    end
+
+    def derive(method_name)
+      methods = {
+        :initialize => "
+          def #{method_name}(#{@attributes.join(',')})
+            #{@attributes.collect { |a| "@#{a} = #{a}" }.join("\n")}
+          end
+        ",
+        :== => "
+          def ==(other)
+            #{name} === other &&
+            #{@attributes.collect { |a| "@#{a} == other.#{a}" }.join(" &&\n")}
+          end
+        "
+      }
+      class_eval methods[method_name], __FILE__, __LINE__
+    end
+    
+    Class.send(:include, self)
+  end
+end
+

data/lib/arel/algebra/extensions/hash.rb

@@ -0,0 +1,11 @@
+module Arel
+  module HashExtensions
+    def bind(relation)
+      inject({}) do |bound, (key, value)|
+        bound.merge(key.bind(relation) => value.bind(relation))
+      end
+    end
+    
+    Hash.send(:include, self)
+  end
+end

data/lib/arel/algebra/extensions/object.rb

@@ -0,0 +1,17 @@
+module Arel
+  module ObjectExtensions
+    def bind(relation)
+      Arel::Value.new(self, relation)
+    end
+
+    def find_correlate_in(relation)
+      bind(relation)
+    end
+
+    def let
+      yield(self)
+    end
+    
+    Object.send(:include, self)
+  end
+end

data/lib/arel/algebra/extensions/symbol.rb

@@ -0,0 +1,9 @@
+module Arel
+  module SymbolExtensions
+    def to_attribute(relation)
+      Arel::Attribute.new(relation, self)
+    end
+    
+    Symbol.send(:include, self)
+  end
+end

data/lib/arel/algebra/predicates.rb

@@ -0,0 +1,41 @@
+module Arel
+  class Predicate
+    def or(other_predicate)
+      Or.new(self, other_predicate)
+    end
+
+    def and(other_predicate)
+      And.new(self, other_predicate)
+    end
+  end
+
+  class Binary < Predicate
+    attributes :operand1, :operand2
+    deriving :initialize
+
+    def ==(other)
+      self.class === other          and
+      @operand1  ==  other.operand1 and
+      @operand2  ==  other.operand2
+    end
+
+    def bind(relation)
+      self.class.new(operand1.find_correlate_in(relation), operand2.find_correlate_in(relation))
+    end
+  end
+
+  class Equality < Binary
+    def ==(other)
+      Equality === other and
+        ((operand1 == other.operand1 and operand2 == other.operand2) or
+         (operand1 == other.operand2 and operand2 == other.operand1))
+    end
+  end
+
+  class GreaterThanOrEqualTo  < Binary; end
+  class GreaterThan           < Binary; end
+  class LessThanOrEqualTo     < Binary; end
+  class LessThan              < Binary; end
+  class Match                 < Binary; end
+  class In                    < Binary; end
+end

data/lib/arel/algebra/primitives.rb

@@ -0,0 +1,5 @@
+require 'arel/algebra/primitives/attribute'
+require 'arel/algebra/primitives/ordering'
+require 'arel/algebra/primitives/value'
+require 'arel/algebra/primitives/expression'
+

data/lib/arel/algebra/primitives/attribute.rb

@@ -0,0 +1,150 @@
+require 'set'
+
+module Arel
+  class Attribute
+    attributes :relation, :name, :alias, :ancestor
+    deriving :==
+    delegate :engine, :christener, :to => :relation
+
+    def initialize(relation, name, options = {})
+      @relation, @name, @alias, @ancestor = relation, name, options[:alias], options[:ancestor]
+    end
+
+    def named?(hypothetical_name)
+      (@alias || name).to_s == hypothetical_name.to_s
+    end
+
+    def aggregation?
+      false
+    end
+
+    def inspect
+      "<Attribute #{name}>"
+    end
+
+    module Transformations
+      def self.included(klass)
+        klass.send :alias_method, :eql?, :==
+      end
+
+      def hash
+        @hash ||= history.size + name.hash + relation.hash
+      end
+
+      def as(aliaz = nil)
+        Attribute.new(relation, name, :alias => aliaz, :ancestor => self)
+      end
+
+      def bind(new_relation)
+        relation == new_relation ? self : Attribute.new(new_relation, name, :alias => @alias, :ancestor => self)
+      end
+
+      def to_attribute(relation)
+        bind(relation)
+      end
+    end
+    include Transformations
+
+    module Congruence
+      def history
+        @history ||= [self] + (ancestor ? ancestor.history : [])
+      end
+
+      def join?
+        relation.join?
+      end
+
+      def root
+        history.last
+      end
+
+      def original_relation
+        @original_relation ||= original_attribute.relation
+      end
+
+      def original_attribute
+        @original_attribute ||= history.detect { |a| !a.join? }
+      end
+
+      def find_correlate_in(relation)
+        relation[self] || self
+      end
+
+      def descends_from?(other)
+        history.include?(other)
+      end
+
+      def /(other)
+        other ? (history & other.history).size : 0
+      end
+    end
+    include Congruence
+
+    module Predications
+      def eq(other)
+        Equality.new(self, other)
+      end
+
+      def lt(other)
+        LessThan.new(self, other)
+      end
+
+      def lteq(other)
+        LessThanOrEqualTo.new(self, other)
+      end
+
+      def gt(other)
+        GreaterThan.new(self, other)
+      end
+
+      def gteq(other)
+        GreaterThanOrEqualTo.new(self, other)
+      end
+
+      def matches(regexp)
+        Match.new(self, regexp)
+      end
+
+      def in(array)
+        In.new(self, array)
+      end
+    end
+    include Predications
+
+    module Expressions
+      def count(distinct = false)
+        distinct ?  Distinct.new(self).count :  Count.new(self)
+      end
+
+      def sum
+        Sum.new(self)
+      end
+
+      def maximum
+        Maximum.new(self)
+      end
+
+      def minimum
+        Minimum.new(self)
+      end
+
+      def average
+        Average.new(self)
+      end
+    end
+    include Expressions
+
+    module Orderings
+      def asc
+        Ascending.new(self)
+      end
+
+      def desc
+        Descending.new(self)
+      end
+
+      alias_method :to_ordering, :asc
+    end
+    include Orderings
+  end
+end

data/lib/arel/algebra/primitives/expression.rb

@@ -0,0 +1,43 @@
+module Arel
+  class Expression < Attribute
+    attributes :attribute, :alias, :ancestor
+    deriving :==
+    delegate :relation, :to => :attribute
+    alias_method :name, :alias
+
+    def initialize(attribute, aliaz = nil, ancestor = nil)
+      @attribute, @alias, @ancestor = attribute, aliaz, ancestor
+    end
+
+    def aggregation?
+      true
+    end
+
+    def inspect
+      "<#{self.class.name} #{attribute.inspect}>"
+    end
+
+    module Transformations
+      def as(aliaz)
+        self.class.new(attribute, aliaz, self)
+      end
+
+      def bind(new_relation)
+        new_relation == relation ? self : self.class.new(attribute.bind(new_relation), @alias, self)
+      end
+
+      def to_attribute(relation)
+        Attribute.new(relation, @alias, :ancestor => self)
+      end
+    end
+    include Transformations
+  end
+
+  class Count    < Expression; end
+  class Distinct < Expression; end
+  class Sum      < Expression; end
+  class Maximum  < Expression; end
+  class Minimum  < Expression; end
+  class Average  < Expression; end
+end
+