flounder 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f116f6520c4017a543634696a1d98c17cf3208d9
-  data.tar.gz: 9471a11ee88f27827a3c6ac3ecdeea6218c5b0b2
+  metadata.gz: f1df582c917b24ed0beb74e4fdd6b15d0f7792ba
+  data.tar.gz: f5ef57ba73986e7ebb89e475289f177baf0c1602
 SHA512:
-  metadata.gz: 2746df8286f4a3d5068e482321e556581778fb96acba83d1c89cae63dfa76846f8e7abcbadd43e2d59b6b5edc8a44e144a2b439176e4d8c484eb00e7c20e7f1f
-  data.tar.gz: 45eb6fa78492db34ed608b1f45a9490a626dda10c4912366fd1dd1420f7f515d5c7bc4902e35c03432470d8ddc7607714c98e1ae188ba017239539fefeea5e51
+  metadata.gz: 964433279a3fcd0bb1035dc5062fb075560518ccf411462ad79af281264b1abc41f22b02019d753620cb39caf53583d2e3a56d67be3be39a5560c7f8056bdc1f
+  data.tar.gz: 08eded169bd82e3468af1e673fb199f14a0e59352707f068b76f7ed96d5d3af5ac5af7ccd673070bc3124eaf96e75c8713e0c48fcc42cbe02b6e4054beb4f982

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    flounder (0.12.1)
+    flounder (0.15.1)
       aggregate (~> 0.2, >= 0.2.2)
       arel (~> 5, > 5.0.1)
       connection_pool (~> 2)

data/HISTORY

@@ -1,3 +1,5 @@
+# 0.16 
+  + DRY joins using #connect - one declaration of relationships, many uses. 
 
 # 0.15
   + Condition piece generator - use this to create OR expressions: Entity#cond

data/README

@@ -6,10 +6,16 @@ SYNOPSIS
 
   require 'flounder'
   d = Flounder.domain do |dom|
-    dom.entity(:users, 'users')
+    dom.entity(:users, :user, 'users') do |user|
+      user.has_many :giraffes, :id => :user_id
+    end
+    dom.entity(:giraffes, :giraffe, 'all_giraffes') do |giraffe|
+      giraffe.belongs_to :user, :user_id => :id
+    end
   end
 
   d[:users].where(:id.lt => 10).to_a
+  d[:users].connect(:giraffes)
 
 STATUS
 

data/flounder.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name     = "flounder"
-  s.version  = '0.15.1'
+  s.version  = '0.16.0'
   s.summary  = "Flounder is a way to write SQL simply in Ruby. It deals with everything BUT object relational mapping. "
   s.email    = "kaspar.schiess@technologyastronauts.ch"
   s.homepage = "https://bitbucket.org/technologyastronauts/oss_flounder"

data/lib/flounder/entity.rb

@@ -1,5 +1,7 @@
 require 'forwardable'
 
+require 'flounder/relation'
+
 module Flounder
 
   # An entity corresponds to a table in the database. On top of its table 
@@ -28,6 +30,7 @@ module Flounder
       @singular = singular
       @table_name = table_name
       @columns_hash = nil
+      @relations = {} # name -> relation
 
       @table = Arel::Table.new(table_name)
     end
@@ -49,6 +52,9 @@ module Flounder
     # @return [String] Name of the table that underlies this entity. 
     attr_reader :table_name
 
+    # @return [Array] relations that this entity has to other entities
+    attr_accessor :relations
+
     extend Forwardable
     def_delegators :domain, :transaction, :with_connection
 
@@ -66,6 +72,42 @@ module Flounder
     end
     alias to_s inspect
 
+    # Relations to other entities
+    
+    # Adds a relationship where many records on the other entity correspond to
+    # this one.
+    #
+    def has_many *a
+      add_relationship :has_many, *a
+    end
+
+    # Adds a relationship where one record on the other entity corresponds to
+    # possibly many on our side.
+    #
+    # Example: 
+    #   domain.entity :foos, :foo, 'foo' do |foo|
+    #     foo.belongs_to :bar, :bar_id => :id
+    #   end
+    #
+    # You can also explicitly name the relationship instead of going through 
+    # the singular name of the other entity: 
+    #
+    # Example: 
+    #   domain.entity :foos, :foo, 'foo' do |foo|
+    #     foo.belongs_to :bar_stuff, :bar, :bar_id => :id
+    #   end
+    #
+    def belongs_to *a
+      add_relationship :belongs_to, *a
+    end
+
+    def add_relationship type, name, entity_ref=nil, **join_conditions
+      raise ArgumentError, "Must have join conditions." if join_conditions.empty?
+      
+      relations[name] = Relation.new(
+        domain, type, name, entity_ref||name, join_conditions)
+    end
+
     # Builds a condition part or a general SQL expression. 
     # 
     #   entity.cond(a: 1)
@@ -123,7 +165,7 @@ module Flounder
     # Query initiators
     [:where, :join, :outer_join, :project,
       :order_by, :group_by, 
-      :limit, :offset].each do |name|
+      :limit, :offset, :connect].each do |name|
       define_method name do |*args|
         select { |q| q.send(name, *args) }
       end

data/lib/flounder/helpers/entity.rb

@@ -0,0 +1,18 @@
+module Flounder::Helpers
+  module Entity
+    def entity_like? something
+      something.kind_of?(Flounder::Entity) ||
+        something.kind_of?(Symbol) && domain.has_entity?(something)
+    end
+    def convert_to_entity something
+      case something
+        when Flounder::Entity, Flounder::EntityAlias
+          return something
+        when Symbol
+          return domain[something]
+      else
+        fail "Not entity-like - yet! (#{something.inspect})"
+      end
+    end
+  end
+end

data/lib/flounder/query/base.rb

@@ -1,6 +1,9 @@
 
 require 'pg_hstore'
 require 'benchmark'
+require 'set'
+
+require 'flounder/helpers/entity'
 
 module Flounder::Query
   class Base
@@ -211,6 +214,8 @@ module Flounder::Query
         # covers: :field => (1..100)
         when Range
           arel_field.in(value)
+        when Set
+          arel_field.in(value.to_a)
       else
         arel_field.send(kind, value)
       end
@@ -241,19 +246,6 @@ module Flounder::Query
       end
     end
 
-    def entity_like? something
-      something.kind_of?(Flounder::Entity) ||
-        something.kind_of?(Symbol) && domain.has_entity?(something)
-    end
-    def convert_to_entity something
-      case something
-        when Flounder::Entity, Flounder::EntityAlias
-          return something
-        when Symbol
-          return domain[something]
-      else
-        fail "Not entity-like - yet! (#{something.inspect})"
-      end
-    end
+    include Flounder::Helpers::Entity
   end
 end

data/lib/flounder/query/select.rb

@@ -153,8 +153,46 @@ module Flounder::Query
       all.first.count
     end
 
+    # Follows relationships on the currently anchored entity. This is like 
+    # an explicit join, but allows to eliminate repetition. 
+    #
+    def connect *connect_spec
+      connect_spec.each do |spec_part|
+        follow_relation_spec(join_entity, spec_part)
+      end
+
+      self
+    end
+
   private
 
+    # Follows a given relationship spec. Does NOT change anchoring.
+    #
+    def follow_relation_spec entity, spec
+      old_join_entity = join_entity
+
+      case spec
+        when Symbol
+          relation = entity.relations[spec]
+          relation.apply(self)
+        when Hash
+          spec.each do |k, v|
+            follow_relation_spec(join_entity, k)
+            self.anchor
+
+            follow_relation_spec(join_entity, v)
+          end
+        when Array
+          spec.each do |v|
+            follow_relation_spec(join_entity, v)
+          end
+      else
+        raise ArgumentError, "#{spec.inspect} not allowed in #connect."
+      end
+
+      @join_entity = old_join_entity
+    end
+
     def column_name_to_entity name
       unless default_projection.empty?
         extract_source_info_from_name(name)

data/lib/flounder/relation.rb

@@ -0,0 +1,30 @@
+require 'flounder/helpers/entity'
+
+module Flounder
+  class Relation
+    attr_accessor :domain, :type
+    attr_accessor :name, :entity_ref, :join_conditions
+
+    def initialize domain, type, name, entity_ref, join_conditions
+      @domain, @type, @name, @entity_ref, @join_conditions = 
+        domain, type, name, entity_ref, join_conditions
+    end
+
+    def apply query
+      entity = convert_to_entity(entity_ref)
+
+      if name != entity_ref
+        # TODO maybe using name for both singular and plural is not a good idea.
+        # Maybe it is.
+        entity = entity.as(name, name)
+      end
+
+      query.
+        join(entity).
+        on(join_conditions)
+    end    
+
+  private
+    include Flounder::Helpers::Entity
+  end
+end

data/qed/applique/setup_domain.rb

@@ -4,9 +4,21 @@ def domain
   @domain ||= begin
     connection = Flounder.connect(dbname: 'flounder')
     Flounder.domain(connection) do |dom|
-      dom.entity(:users, :user, 'users')
-      dom.entity(:posts, :post, 'posts')
-      dom.entity(:comments, :comment, 'comments')
+      dom.entity(:users, :user, 'users') do |user|
+        user.has_many :posts, :id => :author_id
+        user.has_many :approved_posts, :posts, :id => :author_id
+        user.has_many :comments, :id => :author_id
+      end
+      dom.entity(:posts, :post, 'posts') do |post|
+        post.belongs_to :user, :author_id => :id
+        post.belongs_to :approver, :users, :author_id => :id
+
+        post.has_many :comments, :id => :post_id
+      end
+      dom.entity(:comments, :comment, 'comments') do |comment|
+        comment.belongs_to :post, :post_id => :id
+        comment.belongs_to :author, :author_id => :id
+      end
     end
   end
 end

data/qed/expressions.md

@@ -21,4 +21,4 @@ These condition pieces can be used in a WHERE-clause directly.
 ~~~ruby
   users.where(users.cond(id: 1)).
    assert generates_sql("SELECT [fields] FROM \"users\"  WHERE (\"users\".\"id\" = 1)") 
-~~~
+~~~

data/qed/index.md

@@ -72,5 +72,16 @@ By default, symbols are interpreted as field names in the entity that you start
     assert generates_sql("SELECT [fields] FROM \"users\"  WHERE \"posts\".\"id\" = 1")
 ~~~
 
+Sets are queried for using the `IN` operator.
+
+~~~ruby
+  require 'set'
+  s = Set.new([1,2,3])
+  users.where(:posts, :id.in => s).
+    assert generates_sql("SELECT [fields] FROM \"users\"  WHERE \"posts\".\"id\" IN (1, 2, 3)")
+  users.where(:posts, :id => s).
+    assert generates_sql("SELECT [fields] FROM \"users\"  WHERE \"posts\".\"id\" IN (1, 2, 3)")
+~~~
+
 TODO links to other documentation
 

data/qed/joins.md

@@ -1,4 +1,5 @@
 
+# Basic JOINs
 Joins are correctly created.
 
 ~~~ruby
@@ -83,3 +84,32 @@ Results should also be correct:
   row = query.first
   row.other_comment.assert == row.comment
 ~~~
+
+
+# Joining using `#connect`
+
+You can also store joins in the entity definition (see `#belongs_to` and `#has_many` on the Entity) and then navigate through your models using those names.
+
+A simple example for a connect: 
+
+~~~ruby
+  # Query for users, joining posts and joining comments from posts (anchor)
+  query = users.connect(:posts).where(id: 1)
+
+  users.
+    join(:posts).on(:id => :author_id).
+    where(id: 1).to_sql.assert == query.to_sql
+~~~
+
+Or a more complicated example, using hashes and arrays in the join specification.
+
+~~~ruby
+  # Query for users, joining posts and joining comments from posts (anchor)
+  query = users.connect(:posts => [:comments, :approver])
+
+  users.
+    join(:posts).on(:id => :author_id).anchor.
+    join(:comments).on(:id => :post_id).
+    join(users.as(:approver, :approver)).on(:author_id => :id).to_sql.assert == query.to_sql
+~~~
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flounder
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.0
 platform: ruby
 authors:
 - Kaspar Schiess
@@ -9,114 +9,114 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-13 00:00:00.000000000 Z
+date: 2014-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: arel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '5'
-    - - '>'
+    - - ">"
       - !ruby/object:Gem::Version
         version: 5.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '5'
-    - - '>'
+    - - ">"
       - !ruby/object:Gem::Version
         version: 5.0.1
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.17'
 - !ruby/object:Gem::Dependency
   name: hashie
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.2'
 - !ruby/object:Gem::Dependency
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
 - !ruby/object:Gem::Dependency
   name: pg-hstore
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 1.2.0
 - !ruby/object:Gem::Dependency
   name: aggregate
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.2'
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.2
 description: "    Flounder is the missing piece between the database and your Ruby
@@ -127,11 +127,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- flounder.gemspec
 - Gemfile
 - Gemfile.lock
 - HACKING
 - HISTORY
+- LICENSE
+- README
+- flounder.gemspec
+- lib/flounder.rb
 - lib/flounder/connection.rb
 - lib/flounder/connection_pool.rb
 - lib/flounder/domain.rb
@@ -141,6 +144,7 @@ files:
 - lib/flounder/exceptions.rb
 - lib/flounder/expression.rb
 - lib/flounder/field.rb
+- lib/flounder/helpers/entity.rb
 - lib/flounder/immediate.rb
 - lib/flounder/postgres_utils.rb
 - lib/flounder/query/base.rb
@@ -149,9 +153,8 @@ files:
 - lib/flounder/query/returning.rb
 - lib/flounder/query/select.rb
 - lib/flounder/query/update.rb
+- lib/flounder/relation.rb
 - lib/flounder/symbol_extensions.rb
-- lib/flounder.rb
-- LICENSE
 - qed/applique/ae.rb
 - qed/applique/flounder.rb
 - qed/applique/setup_domain.rb
@@ -170,7 +173,6 @@ files:
 - qed/projection.md
 - qed/selects.md
 - qed/updates.md
-- README
 homepage: https://bitbucket.org/technologyastronauts/oss_flounder
 licenses:
 - MIT
@@ -181,17 +183,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Flounder is a way to write SQL simply in Ruby. It deals with everything BUT