flounder 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 740168d7c1b6af4512d1fe0241aa2311ff290cc6
-  data.tar.gz: de30b4d4e04bb31f2082c9ef95fac9147ec3713f
+  metadata.gz: 9860bdc14eff074ea0e340f278593cc4e489599b
+  data.tar.gz: 830bccfe9f8204a93e9eacb9c72b3b53191f82fb
 SHA512:
-  metadata.gz: 5a11bd2ebf80f5af077325f58ea96045bc2e61a3f4c8db4ba82020a143eb29f669b614df8b4155d54df20ce602e37c264b7547af75bece93181a43ef67db4f70
-  data.tar.gz: f4591506a011b6857a5b84c628cac7e6ef7220e1f996a72b40d4f1c08ae01d36bb8230c40903e87a3590f0819b5b83905dc3e8cad6ce2c777cdbd6d40858dcf6
+  metadata.gz: 2c93426c7de1ac2a10368dcf8f85cdd269a20d00f71229706bbd2a42ff928d2415bf157217d52167c7d2e308a6dd59cb50ad505cacf04f4425eb7210e5380d94
+  data.tar.gz: 4799ae63203ad83d6059c87efcb5c86619a054628591594e5c5cae93a10d3d1156136481b4387b4ddffb6defb0715d66d9ef31c3d01146435ecd6829973e16d0

data/Gemfile.lock

@@ -0,0 +1,33 @@
+PATH
+  remote: .
+  specs:
+    flounder (0.2.0)
+      arel (~> 5, > 5.0.1)
+      connection_pool (~> 2)
+      hashie (~> 3, >= 3.2)
+      pg (> 0.17)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ae (1.8.2)
+      ansi
+    ansi (1.4.3)
+    arel (5.0.1.20140414130214)
+    brass (1.2.1)
+    connection_pool (2.0.0)
+    facets (2.9.3)
+    hashie (3.2.0)
+    pg (0.17.1)
+    qed (2.9.1)
+      ansi
+      brass
+      facets (>= 2.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ae
+  flounder!
+  qed

data/flounder.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name     = "flounder"
-  s.version  = '0.3.0'
+  s.version  = '0.4.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/laboratory_flounder"
-  s.authors  = ['Kaspar Schiess']
+  s.authors  = ['Kaspar Schiess', 'Florian Hanke']
   
   # s.description = <<-EOF
   # EOF

data/lib/flounder/connection.rb

@@ -16,10 +16,6 @@ module Flounder
     end
 
     # ------------------------------------------------ official Connection iface
-    def schema_cache
-      self
-    end
-
     Column = Struct.new(:name, :type)
     def columns_hash table_name
       hash = {}
@@ -40,12 +36,12 @@ module Flounder
           hash[name] = Column.new(name, typesym)
         end
       end
-      
+
       hash
     end
 
     def primary_key name
-      fail
+      fail NotImplementedError
       @primary_keys[name.to_s]
     end
 
@@ -55,7 +51,7 @@ module Flounder
     end
 
     def columns name, message = nil
-      fail
+      fail NotImplementedError
       @columns[name.to_s]
     end
 
@@ -75,6 +71,39 @@ module Flounder
       # p [:quote, thing, column]
       pg.escape_literal(thing.to_s)
     end
+    
+    def objectify_result_row ent, result, row_idx
+      obj = Hashie::Mash.new
+  
+      each_field(ent, result, row_idx) do 
+        |entity, name, value, type_oid, binary, idx|
+        # TODO remove entity resolution from each_field?
+
+        entity, name = yield name if block_given?
+
+        typecast_value = typecast(type_oid, value)
+
+        # JOIN tables are available from the result using their singular
+        # names.
+        if entity
+          obj[entity.singular] ||= {}
+
+          sub_obj = obj[entity.singular]
+          sub_obj[name] = typecast_value
+        end
+
+        # The main entity and custom fields (AS something) are available on the
+        # top-level of the result. 
+        if !entity || entity == ent
+          warn "#{name.inspect} already defined in result set, aliasing occurs." \
+            if obj.has_key? name
+          obj[name] = typecast_value
+        end
+      end
+
+      return obj
+    end
+    
   private 
     include PostgresUtils
   end

data/lib/flounder/domain.rb

@@ -7,9 +7,6 @@ module Flounder
   end
 
   class Domain
-    attr_reader :connection_pool
-    attr_accessor :logger
-
     # A device that discards all logging made to it. This is used to be silent
     # by default while still allowing the logging of all queries. 
     #
@@ -27,6 +24,10 @@ module Flounder
       @oids_entity_map = {}
       @logger = Logger.new(NilDevice.new)
     end
+
+    attr_reader :connection_pool
+    attr_accessor :logger
+
     def [] name
       raise NoSuchEntity, "No such entity #{name.inspect} in this domain." \
         unless @plural.has_key?(name)
@@ -34,6 +35,12 @@ module Flounder
       @plural.fetch(name)
     end
 
+    # Returns all entities as an array. 
+    #
+    def entities
+      @plural.values
+    end
+
     # Logs sql statements that are prepared for execution. 
     #
     def log_sql sql

data/lib/flounder/entity.rb

@@ -5,6 +5,10 @@ module Flounder
 
     # Name of the entity in plural form. 
     attr_reader :name
+    
+    # Also, the name is the plural, so we'll support that as well. 
+    alias plural name
+
     # Name of the entity in singular form. 
     attr_reader :singular
 
@@ -18,6 +22,8 @@ module Flounder
       @name = plural
       @singular = singular
       @table_name = table_name
+      @columns_hash = nil
+
       @table = Arel::Table.new(table_name)
     end
 
@@ -27,24 +33,60 @@ module Flounder
       Field.new(self, name, table[name])
     end
 
-    def belongs_to entity, fk
-    end
-
     def to_s
       "entity(#{name}/#{table_name})"
     end
 
+    def query
+      Query.new(domain, self).tap { |q| 
+        yield q if block_given? 
+      }
+    end
+    
+    def insert hash
+      Insert.new(domain, self).tap { |i|
+        yield i if block_given?
+        i.insert(hash)
+      }
+    end
+    
+    def update hash
+      Update.new(domain, self).tap  { |u|
+        yield u if block_given?
+        u.update(hash)
+      }
+    end
+
+    # Temporarily creates a new entity that is available as if it was declared
+    # with the given plural and singular, but referencing to the same
+    # underlying relation.
+    #
+    def as plural, singular
+      EntityAlias.new(self, plural, singular)
+    end 
+
+    def columns_hash
+      @columns_hash ||= begin
+        domain.connection_pool.with_connection do |conn|
+          conn.columns_hash(table_name)
+        end
+      end      
+    end
+    def column_names
+      columns_hash.keys
+    end
+
     # Query initiators
-    [:where, :join, :outer_join, :project].each do |name|
+    [:where, :join, :outer_join, :project, :order_by].each do |name|
       define_method name do |*args|
-        Query.new(domain, self).tap { |q| q.send(name, *args) }
+        query { |q| q.send(name, *args) }
       end
     end
 
     # Kickers
     [:first, :all, :size].each do |name|
       define_method name do |*args|
-        q = Query.new(domain, self)
+        q = query
         q.send(name, *args)
       end
     end

data/lib/flounder/entity_alias.rb

@@ -0,0 +1,39 @@
+
+module Flounder
+  # Alias for an Entity, implementing roughly the same interface. 
+  #
+  # @see Entity
+  #
+  class EntityAlias
+    def initialize entity, plural, singular
+      @entity = entity
+      @plural = plural
+      @singular = singular
+    end
+
+    # Entity this alias refers to
+    attr_reader :entity
+
+    # Plural name of the alias
+    attr_reader :plural
+
+    # Singular name of the alias
+    attr_reader :singular
+
+    # Plural is also available as #name
+    alias name plural   
+
+    def table
+      table = entity.table 
+      table.alias(plural)
+    end
+
+    def column_names
+      entity.column_names
+    end
+
+    def [] name
+      Field.new(self, name, table[name])
+    end
+  end
+end

data/lib/flounder/exceptions.rb

@@ -0,0 +1,8 @@
+
+
+module Flounder
+  # Indicates a field reference in a chain method that cannot be resolved 
+  # to a real field on the underlying relation. 
+  #
+  class InvalidFieldReference < StandardError; end
+end

data/lib/flounder/field.rb

@@ -1,15 +1,15 @@
 module Flounder
   class Field
-    attr_reader :entity
-    attr_reader :arel_field
-    attr_reader :name
-
     def initialize entity, name, arel_field
       @entity = entity
       @name = name
       @arel_field = arel_field
     end
 
+    attr_reader :entity
+    attr_reader :arel_field
+    attr_reader :name
+
     def fully_qualified_name
       # TBD quoting? Demeter?
       entity.domain.connection_pool.with_connection do |conn|
@@ -19,6 +19,10 @@ module Flounder
       end
     end
 
+    def to_arel_field
+      arel_field
+    end
+
     include SymbolExtensions
   end
 end

data/lib/flounder/immediate.rb

@@ -0,0 +1,18 @@
+
+module Flounder
+  # An immmediate string that needs to be passed around and _not_ quoted or
+  # escaped when going to the database. 
+  #
+  # @private
+  class Immediate
+    def initialize string
+      @string = string
+    end
+
+    attr_reader :string
+
+    def to_arel_field
+      string
+    end
+  end
+end

data/lib/flounder/insert.rb

@@ -0,0 +1,73 @@
+module Flounder
+
+  # An insert.
+  #
+  class Insert
+    def initialize domain, into_entity
+      @domain = domain
+      @into_entity = into_entity
+      @engine = Engine.new(into_entity.domain.connection_pool)
+      @manager = Arel::InsertManager.new(@engine)
+
+      manager.into into_entity.table
+    end
+
+    # Domain that this insert was issued for. 
+    attr_reader :domain
+    # Entity that this insert acts on.
+    attr_reader :into_entity
+
+    # Arel SqlManager that accumulates this insert. 
+    attr_reader :manager
+    # Database engine that links Arel to Postgres.
+    attr_reader :engine
+    
+    # Add one row to the inserts.
+    #
+    def insert fields
+      manager.insert fields.map { |k, v| transform_hash_keys(k, v) }
+    end
+
+    # Kickers
+    def to_sql
+      manager.to_sql.tap { |sql|
+        domain.log_sql(sql) }
+    end
+    alias sql to_sql
+    
+    # Returns all rows of the insert result as an array. Individual rows are
+    # mapped to objects using the row mapper. 
+    #
+    def returning fields = '*'
+      inserted = []
+      engine.exec(sql + " RETURNING #{fields}") do |result|
+        inserted = Array.new(result.ntuples, nil)
+        result.ntuples.times do |row_idx|
+          inserted[row_idx] = engine.connection.
+            objectify_result_row(into_entity, result, row_idx)
+        end
+      end
+      inserted
+    end
+
+  private
+  
+    # Called on each key/value pair of an insert clause, this returns a 
+    # hash that can be passed to Arel #insert. 
+    #
+    def transform_hash_keys field, value
+      if value.kind_of? Field
+        value = value.arel_field
+      end
+
+      case field
+        when Symbol
+          [into_entity[field].arel_field, value]
+        when Flounder::Field
+          [field.arel_field, value]
+      else
+        fail "Could not transform condition part. (#{field.inspect}, #{value.inspect})"
+      end
+    end
+  end # class
+end # module Flounder

data/lib/flounder/postgres_utils.rb

@@ -4,10 +4,11 @@ require 'date'
 
 module Flounder
   module PostgresUtils
-    OID_INTEGER = 23
+    OID_BOOLEAN = 16
     OID_SMALLINT = 21
+    OID_INTEGER = 23
+    OID_TEXT = 25
     OID_VARCHAR = 1043
-    OID_BOOLEAN = 16
     OID_TIMESTAMP = 1114
     OID_DATE = 1082
     OID_TIME = 1083
@@ -25,6 +26,8 @@ module Flounder
           value.to_i
         when OID_BOOLEAN
           value == 't'
+        when OID_TEXT
+          value.to_s
       else
         value
       end
@@ -40,7 +43,7 @@ module Flounder
           :time
         when OID_INTEGER, OID_SMALLINT
           :integer
-        when OID_VARCHAR
+        when OID_VARCHAR, OID_TEXT
           :string
         when OID_BOOLEAN
           :boolean
@@ -49,8 +52,8 @@ module Flounder
       end
     end
     
-    def each_field from_entity, result, row_idx
-      domain = from_entity.domain
+    def each_field entity, result, row_idx
+      domain = entity.domain
 
       result.nfields.times do |field_idx|
         table_oid = result.ftable(field_idx)

data/lib/flounder/query.rb

@@ -1,5 +1,24 @@
 module Flounder
+
+  # A query obtained by calling any of the chain methods on an entity.
+  #
   class Query
+    def initialize domain, from_entity
+      @domain = domain
+      @from_entity = from_entity
+      @engine = Engine.new(from_entity.domain.connection_pool)
+      @manager = Arel::SelectManager.new(@engine)
+    
+      @has_projection = false
+
+      @projection_prefixes = Hash.new
+      @default_projection = []
+
+      add_fields_to_default from_entity
+
+      manager.from from_entity.table
+    end
+
     # Domain that this query was issued from. 
     attr_reader :domain
     # Entity that this query acts on.
@@ -9,17 +28,14 @@ module Flounder
     attr_reader :manager
     # Database engine that links Arel to Postgres.
     attr_reader :engine
-    
 
-    def initialize domain, from_entity
-      @domain = domain
-      @from_entity = from_entity
-      @engine = Engine.new(from_entity.domain.connection_pool)
-      @manager = Arel::SelectManager.new(@engine)
-      @has_projection = false
+    # All projected fields if no custom projection is made. Fields are encoded
+    # so that they can be traced back to the entity that contributed them. 
+    attr_reader :default_projection
 
-      manager.from from_entity.table
-    end
+    # Each projection has a unique prefix mapping to the entity that uses this
+    # prefix during this query. 
+    attr_reader :projection_prefixes
 
     def where conditions={}
       conditions.each do |k, v|
@@ -28,15 +44,38 @@ module Flounder
       self
     end    
 
-    def join entity, join_node=Arel::Nodes::InnerJoin
+    def _join join_node, entity
       @last_join = entity
 
-      manager.join(entity.table, join_node)
+      table = entity.table
+      manager.join(table, join_node)
+      add_fields_to_default(entity)
+
       self
     end
-    def outer_join entity
-      join(entity, Arel::Nodes::OuterJoin)
+    def add_fields_to_default entity
+      prefix = entity.name.to_s
+      table = entity.table
+      
+      warn "Table alias #{prefix} already used in select; field aliasing will occur!" \
+        if projection_prefixes.has_key? prefix
+
+      projection_prefixes[prefix] = entity
+
+      entity.column_names.each do |name|
+        default_projection << table[name].as("_#{prefix}_#{name}")
+      end
     end
+    
+    def inner_join *args
+      _join(Arel::Nodes::InnerJoin, *args)
+    end
+    alias join inner_join
+
+    def outer_join *args
+      _join(Arel::Nodes::OuterJoin, *args)
+    end
+
     def on join_conditions
       join_conditions.each do |k, v|
         manager.on(
@@ -49,9 +88,14 @@ module Flounder
       self
     end
 
+    # Adds a field to the projection clause of the SQL statement (the part
+    # between SELECT and FROM). Projection of '*' is the default, so you can
+    # omit this call entirely if you want that.
+    #
     def project *field_list
-      # TBD: Clean up
       @has_projection = true
+      @default_projection = {}
+
       manager.project *map_to_arel(field_list)
       self
     end
@@ -61,15 +105,9 @@ module Flounder
       self
     end
 
-    # Transforms a simple symbol into either a field of the last .join table, 
-    # or respects field values passed in. 
+    # Orders by a list of field references. 
     #
-    def join_field name
-      return name if name.kind_of? Field
-      @last_join[name]
-    end
-
-    def order *field_list
+    def order_by *field_list
       field_list.each do |field|
         field = from_entity[field] unless field.kind_of?(Field)
         manager.order field.fully_qualified_name
@@ -80,7 +118,7 @@ module Flounder
     # Kickers
     def to_sql
       prepare_kick
-
+      
       manager.to_sql.tap { |sql| 
         domain.log_sql(sql) }
     end
@@ -111,7 +149,12 @@ module Flounder
       engine.exec(sql) do |result|
         all = Array.new(result.ntuples, nil)
         result.ntuples.times do |row_idx|
-          all[row_idx] = objectify_result_row(result, row_idx)
+          all[row_idx] = engine.connection.
+            objectify_result_row(from_entity, result, row_idx) do |name|
+              unless default_projection.empty?
+                extract_source_info_from_name(name)
+              end
+            end
         end
       end
 
@@ -120,23 +163,71 @@ module Flounder
 
   private
   
-    def map_to_arel field_list
-      field_list.map { |field| 
-        if field.kind_of? Field
-          field.arel_field
-        else
-          field
-        end
+    # Transforms a simple symbol into either a field of the last .join table, 
+    # or respects field values passed in. 
+    #
+    def join_field name
+      return name if name.kind_of? Field
+      @last_join[name]
+    end
+
+    # Maps an array of field references to Flounder::Field objects. A field 
+    # reference can be: 
+    #
+    #   * a symbol, interpreted as a field name of the main enity of the 
+    #     operation
+    #   * a string, interpreted as something to be passed into the SQL statement
+    #     as is. Caution: Don't expose this to unsecure channels!
+    #   * a Flounder::Field, left alone (obtained through calling #[] on any 
+    #     entity)
+    #
+    def map_to_fields field_list
+      field_list.map { |x| 
+        map_to_field(x)
       }
     end
+    def map_to_field field_ref
+      case field_ref 
+        when Symbol
+          from_entity[field_ref]
+        when String
+          Immediate.new(field_ref)
+        when Field
+          field_ref
+      else
+        fail InvalidFieldReference, "Cannot resolve #{field_ref.inspect} to a field."
+      end
+    end
 
+    # Maps a field reference (see #fields) to an Arel::Field.
+    #
+    def map_to_arel field_list
+      map_to_fields(field_list).map(&:to_arel_field)
+    end
+
+    # Prepares a kick (aka transformation into sql/result). This should include
+    # all actions that need to be performed to validate the query. 
+    #
     def prepare_kick
       unless @has_projection
-        manager.project Arel.star
+        @has_projection = true
+
+        # Prepare the regular expression that we'll use to extract entities 
+        # from column names. 
+        @re_field = %r(
+          ^_                             # indicates one of our own 
+          (?<prefix>#{projection_prefixes.keys.join('|')})
+          _
+          (?<field_name>.*)
+          $
+        )x
+
+        manager.project *default_projection
       end
     end
 
-    # Transforms things like :a => 1 into field('a').eq(1).
+    # Called on each key/value pair of a condition clause, this returns a 
+    # condition that can be passed to Arel #where. 
     #
     def transform_hash_condition field, value
       if value.kind_of? Field
@@ -169,27 +260,15 @@ module Flounder
       end
     end
 
-    # Turns row (a hash) into something that can be treated like an object. 
-    # Also performs type coercion. 
-    #
-    def objectify_result_row result, row_idx
-      obj = Hashie::Mash.new
-
-      engine.connection.each_field(from_entity, result, row_idx) do 
-        |entity, name, value, type_oid, binary, idx|
-        
-        # p [entity.name, name, type_oid, type_name(result, idx)]
-        typecast_value = engine.connection.typecast(type_oid, value)
-
-        if entity
-          obj[entity.singular] ||= {}
-          obj[entity.singular][name] = typecast_value
-        else
-          obj[name] = typecast_value
-        end
-      end
+    def extract_source_info_from_name name
+      md = name.match(@re_field)
+      fail "ASSERTION FAILURE Source info extraction failed." unless md
+
+      entity = projection_prefixes[md[:prefix]]
+      fail "ASSERTION FAILURE entity cannot be nil" unless entity
+      name = md[:field_name]
 
-      return obj
+      return entity, name
     end
   end # class
 end # module Flounder

data/lib/flounder/update.rb

@@ -0,0 +1,114 @@
+module Flounder
+
+  # An update obtained by calling any of the chain methods on an entity.
+  #
+  class Update
+    def initialize domain, entity
+      @domain = domain
+      @entity = entity
+      @engine = Engine.new(entity.domain.connection_pool)
+      @manager = Arel::UpdateManager.new(@engine)
+
+      manager.table entity.table
+    end
+
+    # Domain that this update was issued from. 
+    attr_reader :domain
+    # Entity that this update acts on.
+    attr_reader :entity
+
+    # Arel SqlManager that accumulates this query. 
+    attr_reader :manager
+    # Database engine that links Arel to Postgres.
+    attr_reader :engine
+
+    # Add one row to the updates.
+    #
+    def update fields
+      manager.set fields.map { |k, v| transform_hash_keys(k, v) }
+    end
+
+    def where conditions={}
+      conditions.each do |k, v|
+        manager.where(transform_hash_condition(k, v))
+      end
+      self
+    end
+
+    # Kickers
+    def to_sql
+      manager.to_sql.tap { |sql| 
+        domain.log_sql(sql) }
+    end
+    alias sql to_sql
+
+    # Returns all rows of the update result as an array. Individual rows are
+    # mapped to objects using the row mapper. 
+    #
+    def returning fields = '*'
+      updated = nil
+      engine.exec(sql + " RETURNING #{fields}") do |result|
+        updated = Array.new(result.ntuples, nil)
+        result.ntuples.times do |row_idx|
+          updated[row_idx] = engine.connection.
+            objectify_result_row(entity, result, row_idx)
+        end
+      end
+      updated
+    end
+
+  private
+
+    # Called on each key/value pair of an insert clause, this returns a 
+    # hash that can be passed to Arel #insert. 
+    #
+    def transform_hash_keys field, value
+      if value.kind_of? Field
+        value = value.arel_field
+      end
+
+      case field
+        when Symbol
+          [entity[field].arel_field, value]
+        when Flounder::Field
+          [field.arel_field, value]
+      else
+        fail "Could not transform condition part. (#{field.inspect}, #{value.inspect})"
+      end
+    end
+
+    # Called on each key/value pair of a condition clause, this returns a 
+    # condition that can be passed to Arel #where. 
+    #
+    def transform_hash_condition field, value
+      if value.kind_of? Field
+        value = value.arel_field
+      end
+
+      case field
+        when Symbol
+          condition_part(entity[field].arel_field, value)
+        when Flounder::Field
+          condition_part(field.arel_field, value)
+        when Flounder::SymbolExtensions::Modifier
+          condition_part(
+            field.to_arel_field(entity), 
+            value, 
+            field.kind)
+      else
+        fail "Could not transform condition part. (#{field.inspect}, #{value.inspect})"
+      end
+    end
+    def condition_part arel_field, value, kind=:eq
+      case value
+        when Symbol
+          value_field = entity[value].arel_field
+          arel_field.send(kind, value_field)
+        when Range
+          arel_field.in(value)
+      else
+        arel_field.send(kind, value)
+      end
+    end
+  end # class
+end # module Flounder

data/lib/flounder.rb

@@ -10,8 +10,13 @@ require 'flounder/connection_pool'
 require 'flounder/domain'
 require 'flounder/engine'
 require 'flounder/entity'
+require 'flounder/entity_alias'
 require 'flounder/field'
+require 'flounder/immediate'
 require 'flounder/query'
+require 'flounder/insert'
+require 'flounder/update'
+require 'flounder/exceptions'
 
 module Flounder
 module_function

data/qed/applique/ae.rb

@@ -1 +1,7 @@
-require 'ae'
+require 'ae'
+
+def generates_sql(expected)
+  -> (given) {
+    given.sql.gsub(/^SELECT.*FROM/, 'SELECT [fields] FROM').assert == expected
+  }
+end

data/qed/applique/setup_domain.rb

@@ -0,0 +1,27 @@
+
+
+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')
+    end
+  end
+end
+
+# Allows using entities directly, without indirection via domain. (ie `users`)
+domain.entities.each do |entity|
+  define_method entity.plural do
+    entity
+  end
+end
+
+# Load the SQL fixtures.
+#
+# One fine day we will use transactional features.
+#
+File.open File.expand_path '../../qed/flounder.sql' do |file|
+  Flounder::Engine.new(domain.connection_pool).exec file.read
+end

data/qed/exceptions.md

@@ -0,0 +1,12 @@
+
+Some things are forbidden. Here's a list of those: 
+
+# Invalid Field References
+
+All of these statements raise an `InvalidFieldReference` exception.
+
+~~~ruby
+  expect Flounder::InvalidFieldReference do
+    users.project(1, 2, 3)
+  end
+~~~

data/qed/flounder.sql

@@ -1,4 +1,4 @@
--- Database fixture for these tests. Please improt into a database that 
+-- Database fixture for these tests. Please import into a database that 
 -- should also be called 'flounder'.
 
 DROP TABLE IF EXISTS "users" CASCADE;
@@ -9,6 +9,7 @@ CREATE TABLE "users" (
 
 BEGIN;
 INSERT INTO "users" (name) VALUES ('John Snow');
+INSERT INTO "users" (name) VALUES ('John Doe');
 COMMIT;
 
 DROP TABLE IF EXISTS "posts" CASCADE;
@@ -16,12 +17,13 @@ CREATE TABLE "posts" (
   "id" serial PRIMARY KEY,
   "title" varchar(100) NOT NULL,
   "text" text NOT NULL,
-  "user_id" int NOT NULL REFERENCES users("id")
+  "user_id" int NOT NULL REFERENCES users("id"), 
+  "approver_id" int REFERENCES users("id")
 );
 
 BEGIN;
-INSERT INTO "posts" (title, text, user_id) VALUES (
-  'First Light', 'This is the first post in our test system.', '1');
+INSERT INTO "posts" (title, text, user_id, approver_id) VALUES (
+  'First Light', 'This is the first post in our test system.', 1, 2);
 COMMIT;
 
 DROP TABLE IF EXISTS "comments" CASCADE;

data/qed/index.md

@@ -1,8 +1,8 @@
 
 Flounder is a simple layer between you and the database. It abstracts syntax details and removes the need for string manipulation and parsing, but it does not 'map to objects' in the traditional sense. It still returns objects from queries, though - and it certainly allows influencing the mapping, but the core of flounder is about making querying and manipulating the database look nice and be maintainable. Here are our guiding principles: 
 
-* DSL should be close to SQL; we're not imitating Enumerables. 
-* Not the multitude of chain methods, but the composability of these methods makes Flounders power. 
+* Given the choice, we'll chose the method name close to SQL. Flounder should make that domain knowledge more useful, not introduce another domain. 
+* Composability over complexity.
 
 # A simple Domain
 
@@ -20,8 +20,8 @@ Here's our domain definition. In which - yes - you specify both singular and plu
 Now very simple selects should work as expected.
 
 ~~~ruby
-  sql = domain[:users].where(id: 1).sql
-  sql.assert == %Q(SELECT * FROM "users"  WHERE "users"."id" = 1)
+  domain[:users].where(id: 1).assert generates_sql(
+    %Q(SELECT [fields] FROM "users"  WHERE "users"."id" = 1))
 ~~~
 
 The `domain[:users]` bit refers to a relation in the database and when you append another square bracket pair, you'll refer to a field in the database - everywhere, in all flounder clauses. 
@@ -33,29 +33,29 @@ The `domain[:users]` bit refers to a relation in the database and when you appen
 Also, several conditions work as one would expect from DataMapper. 
 
 ~~~ruby
-  domain[:users].where(id: 1..10).sql.assert == 
-    %Q(SELECT * FROM "users"  WHERE "users"."id" BETWEEN 1 AND 10)
-
-  domain[:users].where(:id.lt => 10).sql.assert == 
-    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" < 10"
-  domain[:users].where(:id.lteq => 10).sql.assert == 
-    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" <= 10"
-  domain[:users].where(:id.gt => 10).sql.assert == 
-    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" > 10"
-  domain[:users].where(:id.gteq => 10).sql.assert == 
-    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" >= 10"
-  domain[:users].where(:id.not_eq => 10).sql.assert == 
-    "SELECT * FROM \"users\"  WHERE \"users\".\"id\" != 10"
+  domain[:users].where(id: 1..10).assert generates_sql( 
+    %Q(SELECT [fields] FROM "users"  WHERE "users"."id" BETWEEN 1 AND 10))
+
+  domain[:users].where(:id.lt => 10).assert generates_sql( 
+    "SELECT [fields] FROM \"users\"  WHERE \"users\".\"id\" < 10")
+  domain[:users].where(:id.lteq => 10).assert generates_sql( 
+    "SELECT [fields] FROM \"users\"  WHERE \"users\".\"id\" <= 10")
+  domain[:users].where(:id.gt => 10).assert generates_sql( 
+    "SELECT [fields] FROM \"users\"  WHERE \"users\".\"id\" > 10")
+  domain[:users].where(:id.gteq => 10).assert generates_sql( 
+    "SELECT [fields] FROM \"users\"  WHERE \"users\".\"id\" >= 10")
+  domain[:users].where(:id.not_eq => 10).assert generates_sql( 
+    "SELECT [fields] FROM \"users\"  WHERE \"users\".\"id\" != 10")
 ~~~
 
 Fields can be used fully qualified by going through the entity.
 
 ~~~ruby
   domain[:users].where(domain[:users][:id] => 10).
-    sql.assert == %Q(SELECT * FROM "users"  WHERE "users"."id" = 10)
+    assert generates_sql(%Q(SELECT [fields] FROM "users"  WHERE "users"."id" = 10))
 
   domain[:users].where(domain[:users][:name].matches => 'a%').
-    sql.assert == %Q(SELECT * FROM "users"  WHERE "users"."name" LIKE 'a%')
+    assert generates_sql(%Q(SELECT [fields] FROM "users"  WHERE "users"."name" LIKE 'a%'))
 ~~~
 
 # Some JOINs
@@ -63,11 +63,11 @@ Fields can be used fully qualified by going through the entity.
 Here are some non-crazy joins that also work. 
 
 ~~~ruby
-  sql = domain[:users].join(domain[:posts]).on(:id => :user_id).sql
-  sql.assert == %Q(SELECT * FROM "users" INNER JOIN "posts" ON "users"."id" = "posts"."user_id")
+  domain[:users].join(domain[:posts]).on(:id => :user_id).
+    assert generates_sql(%Q(SELECT [fields] FROM "users" INNER JOIN "posts" ON "users"."id" = "posts"."user_id"))
 
-  sql = domain[:users].outer_join(domain[:posts]).on(:id => :user_id).sql
-  sql.assert == %Q(SELECT * FROM "users" LEFT OUTER JOIN "posts" ON "users"."id" = "posts"."user_id")
+  domain[:users].outer_join(domain[:posts]).on(:id => :user_id).
+    assert generates_sql(%Q(SELECT [fields] FROM "users" LEFT OUTER JOIN "posts" ON "users"."id" = "posts"."user_id"))
 ~~~
 
 Joining presents an interesting dilemma. There are two ways of joining things together, given three tables. The sequence A.B.C might mean to join A to B and C; it might also be interpreted to mean to join A to B and B to C. Here's how we solve this. 
@@ -76,7 +76,7 @@ Joining presents an interesting dilemma. There are two ways of joining things to
   domain[:users].
     join(domain[:posts]).on(:id => :user_id).
     join(domain[:comments]).on(:id => :post_id).
-      sql.assert == %Q(SELECT * FROM "users" INNER JOIN "posts" ON "users"."id" = "posts"."user_id" INNER JOIN "comments" ON "users"."id" = "comments"."post_id")
+      assert generates_sql(%Q(SELECT [fields] FROM "users" INNER JOIN "posts" ON "users"."id" = "posts"."user_id" INNER JOIN "comments" ON "users"."id" = "comments"."post_id"))
 ~~~
 
 So just doing `A.B.C` will give you the first of the above possibilities. Here's how to achive the second effect. 
@@ -85,7 +85,7 @@ So just doing `A.B.C` will give you the first of the above possibilities. Here's
   domain[:users].
     join(domain[:posts]).on(:id => :user_id).anchor.
     join(domain[:comments]).on(:id => :post_id).
-      sql.assert == %Q(SELECT * FROM "users" INNER JOIN "posts" ON "users"."id" = "posts"."user_id" INNER JOIN "comments" ON "posts"."id" = "comments"."post_id")
+      assert generates_sql(%Q(SELECT [fields] FROM "users" INNER JOIN "posts" ON "users"."id" = "posts"."user_id" INNER JOIN "comments" ON "posts"."id" = "comments"."post_id"))
 ~~~
 
 The call to `#anchor` anchors all further joins at that point. 
@@ -93,8 +93,11 @@ The call to `#anchor` anchors all further joins at that point.
 # ORDER BY
 
 ~~~ruby
-  domain[:users].where(id: 2013).order(domain[:users][:id]).
-    sql.assert == %Q(SELECT * FROM "users"  WHERE "users"."id" = 2013  ORDER BY "users"."id")
+  domain[:users].where(id: 2013).order_by(domain[:users][:id]).
+    assert generates_sql(%Q(SELECT [fields] FROM "users"  WHERE "users"."id" = 2013  ORDER BY "users"."id"))
+
+  domain[:users].order_by('id').
+    assert generates_sql(%Q(SELECT [fields] FROM "users"   ORDER BY "users"."id"))
 ~~~
 
 # Selective projection

data/qed/inserts.md

@@ -0,0 +1,43 @@
+An insert creates a state from which SQL can be extracted.
+
+~~~ruby
+  sql = users.insert(:name => 'Mr. Insert SQL').to_sql
+
+  sql.assert == "INSERT INTO \"users\" (\"name\") VALUES ('Mr. Insert SQL')"
+~~~
+
+Using returning will return the inserted object.
+
+~~~ruby
+  results = users.insert(:name => 'Mr. Returning Asterisk').returning
+
+  results.first.name.assert == 'Mr. Returning Asterisk'
+~~~
+
+Returning all fields is the default, but you can provide that explicitly.
+
+~~~ruby
+  results = users.insert(:name => 'Mr. Returning Asterisk').returning '*'
+
+  results.first.name.assert == 'Mr. Returning Asterisk'
+~~~
+
+Using returning with a field name will return those fields of the inserted object.
+
+~~~ruby
+  results = users.insert(:name => 'Mr. Returning').returning(:id)
+
+  id = results.first.id
+
+  users.where(:id => id).first.name.assert == 'Mr. Returning'
+~~~
+
+Flounder fields can be used as keys.
+
+~~~ruby
+  results = users.insert(users[:name] => 'Mr. Flounder Field').returning
+
+  results.first.name.assert == 'Mr. Flounder Field'
+~~~
+
+TODO It does not yet support multi-row inserts.

data/qed/results.md

@@ -0,0 +1,21 @@
+
+
+
+~~~ruby
+  post = posts.
+    join(users).on(:user_id => :id).
+    join(users.as(:approvers, :approver)).on(:approver_id => :id).
+    first
+
+  post.user.name.assert == 'John Snow' 
+  post.approver.name.assert == 'John Doe' 
+~~~
+
+# Custom Projections
+
+TBD: Describes how to do custom projections and how these results will be available in the resulting object. 
+
+
+# Aliasing
+
+TBD: Describes to join a table multiple times and how to deal with the results. 

data/qed/selects.md

@@ -3,10 +3,14 @@
 A simple domain definition.
 
 ~~~ruby  
-  connection = Flounder.connect(dbname: 'flounder')
-  domain = Flounder.domain(connection) do |dom|
-    dom.entity(:users, :user, 'users')
-  end
+  # See 'setup_domain.rb' for the domain definition. Repeated here, as a 
+  # comment: 
+  #
+  #   Flounder.domain(connection) do |dom|
+  #     dom.entity(:users, :user, 'users')
+  #     dom.entity(:posts, :post, 'posts')
+  #     dom.entity(:comments, :comment, 'comments')
+  #   end
 
   # Enable this line if you want to see all statements executed.
   # domain.logger = Logger.new(STDOUT)
@@ -22,8 +26,8 @@ And a simple use case.
 If we want to see all records, we use the `all` kicker, which has some synonyms. You best discover those by treating the domain entity as an array.  
 
 ~~~ruby
-  users = domain[:users].all 
-  users.size.assert == 1
+  users = domain[:users].all
+  users.size.assert == 6
   users.assert.kind_of? Array
 
   domain[:users].map(&:id).assert == users.map(&:id)

data/qed/updates.md

@@ -0,0 +1,68 @@
+An update creates a state from which SQL can be extracted.
+
+~~~ruby
+  post = posts.first
+  
+  sql = posts.update(:title => 'Update SQL').where(:id => post.id).to_sql
+
+  sql.assert == 'UPDATE "posts" SET "title" = \'Update SQL\' WHERE "posts"."id" = 1'
+~~~
+
+Flounder fields are ok.
+
+~~~ruby
+  post = posts.first
+  
+  sql = posts.update(posts[:title] => 'Update Flounder SQL').where(:id => post.id).to_sql
+
+  sql.assert == 'UPDATE "posts" SET "title" = \'Update Flounder SQL\' WHERE "posts"."id" = 1'
+~~~
+
+It can update a single field.
+
+~~~ruby
+  post = posts.first
+  
+  post = posts.update(:title => 'Update Field').where(:id => post.id).returning.first
+
+  post.title.assert == 'Update Field'
+~~~
+
+Flounder fields are ok here too.
+
+~~~ruby
+  post = posts.first
+  
+  post = posts.update(posts[:title] => 'Update Flounder Field').where(:id => post.id).returning.first
+
+  post.title.assert == 'Update Flounder Field'
+~~~
+
+An update can take multiple fields.
+
+~~~ruby
+  post = posts.first
+  
+  sql = posts.update(:title => 'Update SQL', :text => 'Update Multiple Fields Text').where(:id => post.id).to_sql
+
+  sql.assert == 'UPDATE "posts" SET "title" = \'Update SQL\', "text" = \'Update Multiple Fields Text\' WHERE "posts"."id" = 1'
+~~~
+
+Updating a single row is possible.
+
+~~~ruby
+  post = posts.first
+  
+  post = posts.update(:title => 'Updated Title', :text => 'Update Single Row Possible').where(:id => post.id).returning.first
+
+  post.title.assert == 'Updated Title'
+  post.text.assert == 'Update Single Row Possible'
+~~~
+
+Updating multiple rows is possible.
+
+~~~ruby
+  updated = users.update(:name => 'Update Multiple Rows').where(:name.not_eq => nil).returning
+
+  updated.map(&:name).assert == ['Update Multiple Rows']*6
+~~~

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: flounder
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Kaspar Schiess
+- Florian Hanke
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-23 00:00:00.000000000 Z
+date: 2014-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: arel
@@ -85,6 +86,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - Gemfile
+- Gemfile.lock
 - HACKING
 - LICENSE
 - README
@@ -95,15 +97,25 @@ files:
 - lib/flounder/domain.rb
 - lib/flounder/engine.rb
 - lib/flounder/entity.rb
+- lib/flounder/entity_alias.rb
+- lib/flounder/exceptions.rb
 - lib/flounder/field.rb
+- lib/flounder/immediate.rb
+- lib/flounder/insert.rb
 - lib/flounder/postgres_utils.rb
 - lib/flounder/query.rb
 - lib/flounder/symbol_extensions.rb
+- lib/flounder/update.rb
 - qed/applique/ae.rb
-- qed/applique/ahrel.rb
+- qed/applique/flounder.rb
+- qed/applique/setup_domain.rb
+- qed/exceptions.md
 - qed/flounder.sql
 - qed/index.md
+- qed/inserts.md
+- qed/results.md
 - qed/selects.md
+- qed/updates.md
 homepage: https://bitbucket.org/technologyastronauts/laboratory_flounder
 licenses: []
 metadata: {}
@@ -123,15 +135,20 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.2.0
 signing_key: 
 specification_version: 4
 summary: Flounder is a way to write SQL simply in Ruby. It deals with everything BUT
   object relational mapping.
 test_files:
 - qed/applique/ae.rb
-- qed/applique/ahrel.rb
+- qed/applique/flounder.rb
+- qed/applique/setup_domain.rb
+- qed/exceptions.md
 - qed/flounder.sql
 - qed/index.md
+- qed/inserts.md
+- qed/results.md
 - qed/selects.md
+- qed/updates.md
 has_rdoc: