activerecord-postgres-hstore 0.0.2 → 0.0.3

data/README.textile

@@ -116,7 +116,11 @@ or...
 
 And finally, if you need to delete keys in many rows, you can:
 
+@Person.delete_key(:data, :foo)@
 
+and with many keys:
+
+@Person.delete_keys(:data, :foo, :bar)@
 
 Have fun.
 

data/VERSION

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

data/lib/activerecord-postgres-hstore.rb

@@ -1,17 +1,29 @@
-#raise ActiveRecord::ConnectionAdapters::Column.inspect
 require 'rails'
 require 'rails/generators'
 require 'rails/generators/migration'
-class Railtie < Rails::Railtie
+
+# = Hstore Railtie
+#
+# Creates a new railtie for 2 reasons:
+#
+# * Initialize ActiveRecord properly
+# * Add hstore:setup generator 
+class Hstore < Rails::Railtie
+
   initializer 'activerecord-postgres-hstore' do
     ActiveSupport.on_load :active_record do
       require "activerecord-postgres-hstore/activerecord"
     end
   end
-  #rake_tasks do
-  #  load "lib/tasks/hstore.rake"
-  #end
-  class HstoreGenerator < Rails::Generators::Base
+
+  # Creates the hstore:setup generator. This generator creates a migration that
+  # adds hstore support for your database. If fact, it's just the sql from the
+  # contrib inside a migration. But it' s handy, isn't it?
+  #
+  # To use your generator, simply run it in your project:
+  #
+  #   rails g hstore:setup
+  class Setup < Rails::Generators::Base
     include Rails::Generators::Migration
 
     def self.source_root
@@ -32,11 +44,5 @@ class Railtie < Rails::Railtie
 
   end
 end
-
-
-
-
-
-require "activerecord-postgres-hstore/hstore"
 require "activerecord-postgres-hstore/string"
-require "activerecord-postgres-hstore/hash"
+require "activerecord-postgres-hstore/hash"

data/lib/activerecord-postgres-hstore/activerecord.rb

@@ -1,36 +1,53 @@
-# ActiveRecord::ConnectionAdapters::PostgreSQLColumn.new('data','','hstore').type
+# Extends AR to add Hstore functionality.
 module ActiveRecord
+
+  # Adds methods for deleting keys in your hstore columns
   class Base
+
+    # Deletes all keys from a specific column in a model. E.g.
+    #   Person.delete_key(:info, :father)
+    # The SQL generated will be:
+    #   UPDATE "people" SET "info" = delete("info",'father');
     def self.delete_key attribute, key
-      #UPDATE tab SET h = delete(h, 'k1');
-      unless column_names.include?(attribute.to_s)
-        raise "invalid attribute #{attribute}"
-      end
-      update_all(["#{attribute} = delete(#{attribute},?)",key])
+      raise "invalid attribute #{attribute}" unless column_names.include?(attribute.to_s)
+      update_all([%(#{attribute} = delete("#{attribute}",?)),key])
     end
+
+    # Deletes many keys from a specific column in a model. E.g.
+    #   Person.delete_key(:info, :father, :mother)
+    # The SQL generated will be:
+    #   UPDATE "people" SET "info" = delete(delete("info",'father'),'mother');
     def self.delete_keys attribute, *keys
-      unless column_names.include?(attribute.to_s)
-        raise "invalid attribute #{attribute}"
-      end
+      raise "invalid attribute #{attribute}" unless column_names.include?(attribute.to_s)
       delete_str = "delete(#{attribute},?)"
-      (keys.count-1).times do
-        delete_str = "delete(#{delete_str},?)"
-      end
+      (keys.count-1).times{ delete_str = "delete(#{delete_str},?)" }
       update_all(["#{attribute} = #{delete_str}", *keys])
     end
-    
+
+    # Deletes a key in a record. E.g.
+    #   witt = Person.find_by_name("Ludwig Wittgenstein")
+    #   witt.destroy_key(:info, :father)
+    # It does not save the record, so you'll have to do it.
     def destroy_key attribute, key
-      unless self.class.column_names.include?(attribute.to_s)
-        raise "invalid attribute #{attribute}"
-      end
+      raise "invalid attribute #{attribute}" unless self.class.column_names.include?(attribute.to_s)
       new_value = send(attribute)
       new_value.delete(key.to_s)
       send("#{attribute}=", new_value)
       self
     end
+
+    # Deletes a key in a record. E.g.
+    #   witt = Person.find_by_name("Ludwig Wittgenstein")
+    #   witt.destroy_key(:info, :father)
+    # It does save the record.
     def destroy_key! attribute, key
       destroy_key(attribute, key).save
     end
+
+    # Deletes many keys in a record. E.g.
+    #   witt = Person.find_by_name("Ludwig Wittgenstein")
+    #   witt.destroy_keys(:info, :father, :mother)
+    # It does not save the record, so you'll have to do it.
     def destroy_keys attribute, *keys
       for key in keys
         new_value = send(attribute)
@@ -39,23 +56,27 @@ module ActiveRecord
       end
       self
     end
+
+    # Deletes many keys in a record. E.g.
+    #   witt = Person.find_by_name("Ludwig Wittgenstein")
+    #   witt.destroy_keys!(:info, :father, :mother)
+    # It does save the record.
     def destroy_keys! attribute, *keys
-      unless self.class.column_names.include?(attribute.to_s)
-        raise "invalid attribute #{attribute}"
-      end
+      raise "invalid attribute #{attribute}" unless self.class.column_names.include?(attribute.to_s)
       destroy_keys(attribute, *keys).save
     end
 
-    # For Rails 3 compat :D
-    #alias :old_arel_attributes_values :arel_attributes_values
+    # This method is replaced for Rails 3 compatibility.
+    # All I do is add the condition when the field is a hash that converts the value
+    # to hstore format.
+    # IMHO this should be delegated to the column, so it won't be necessary to rewrite all
+    # this method.
     def arel_attributes_values(include_primary_key = true, include_readonly_attributes = true, attribute_names = @attributes.keys)
       attrs = {}
       attribute_names.each do |name|
         if (column = column_for_attribute(name)) && (include_primary_key || !column.primary)
-
           if include_readonly_attributes || (!include_readonly_attributes && !self.class.readonly_attributes.include?(name))
             value = read_attribute(name)
-
             if value && ((self.class.serialized_attributes.has_key?(name) && (value.acts_like?(:date) || value.acts_like?(:time))) || value.is_a?(Hash) || value.is_a?(Array))
               if self.class.columns_hash[name].type == :hstore
                 value = value.to_hstore # Done!
@@ -69,45 +90,62 @@ module ActiveRecord
       end
       attrs
     end
+
   end
+
+  # This erro class is used when the user passes a wrong value to a hstore column.
+  # Hstore columns accepts hashes or hstore valid strings. It is validated with
+  # String#valid_hstore? method.
   class HstoreTypeMismatch < ActiveRecord::ActiveRecordError
   end
+
   module ConnectionAdapters
-  
+
     class TableDefinition
-      # Adds hstore type for migrations
+
+      # Adds hstore type for migrations. So you can add columns to a table like:
+      #   create_table :people do |t|
+      #     ...
+      #     t.hstore :info
+      #     ...
+      #   end
       def hstore(*args)
         options = args.extract_options!
         column_names = args
         column_names.each { |name| column(name, 'hstore', options) }
       end
+
     end
 
     class PostgreSQLColumn < Column
       alias :old_type_cast_code :type_cast_code
       alias :old_simplified_type :simplified_type
-      alias :old_klass :klass
+
+      # Does the type casting from hstore columns using String#from_hstore or Hash#from_hstore.
       def type_cast_code(var_name)
         type == :hstore ? "#{var_name}.from_hstore" : old_type_cast_code(var_name)
       end
+
+      # Adds the hstore type for the column.
       def simplified_type(field_type)
         field_type =~ /^hstore$/ ? :hstore : old_simplified_type(field_type)
       end
-      def klass
-        type == :hstore ? Hstore : old_klass   
-      end
+
     end
+
     class PostgreSQLAdapter < AbstractAdapter
+
       alias :old_quote :quote
+      alias :old_columns :columns
+
+      # Quotes correctly a hstore column value.
       def quote(value, column = nil)
         if value && column && column.sql_type =~ /^hstore$/
-          if ! value.kind_of?(Hash) and ! value.valid_hstore?
-            raise HstoreTypeMismatch, "#{column.name} must have a Hash or a valid hstore value (#{value})"
-          end
+          raise HstoreTypeMismatch, "#{column.name} must have a Hash or a valid hstore value (#{value})" unless value.kind_of?(Hash) || value.valid_hstore?          
           return value.to_hstore
         end
         old_quote(value,column)
       end
     end
   end
-end
+end

data/lib/activerecord-postgres-hstore/hash.rb

@@ -1,11 +1,14 @@
 class Hash
 
+  # Generates a single quoted hstore string format. This is the format used
+  # to insert or update stuff in the database.
   def to_hstore
     return "''" if empty?
     #@todo DIOGO! Check security issues with this quoting pleaz
     map{|idx,val| "('#{idx}'=>'#{val.to_s.gsub(/'/,"''")}')"  }.join(' || ')
   end
 
+  # If the method from_hstore is called in a Hash, it just returns self.
   def from_hstore
     self
   end

data/lib/activerecord-postgres-hstore/string.rb

@@ -1,9 +1,15 @@
 class String
 
+  # If the value os a column is already a String and it calls to_hstore, it
+  # just returns self. Validation occurs afterwards.
   def to_hstore
     self
   end
 
+  # Validates the hstore format. Valid formats are:
+  # * An empty string
+  # * A string like %("foo"=>"bar"). I'll call it a "double quoted hstore format".
+  # * A string like %('foo'=>'bar'). I'll call it a "single quoted hstore format".
   def valid_hstore?
     return true if empty? || self == "''"
     # This is what comes from the database
@@ -16,6 +22,8 @@ class String
     self.match(dbl_quotes_re) || self.match(sngl_quotes_re)
   end
 
+  # Creates a hash from a valid double quoted hstore format, 'cause this is the format
+  # that postgresql spits out.
   def from_hstore
     Hash[ scan(/"([^"]+)"=>"([^"]+)"/) ]
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: activerecord-postgres-hstore
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Juan Maiz
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-09 00:00:00 -03:00
+date: 2010-09-12 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -52,7 +52,6 @@ files:
 - lib/activerecord-postgres-hstore.rb
 - lib/activerecord-postgres-hstore/activerecord.rb
 - lib/activerecord-postgres-hstore/hash.rb
-- lib/activerecord-postgres-hstore/hstore.rb
 - lib/activerecord-postgres-hstore/string.rb
 - lib/templates/setup_hstore.rb
 - spec/activerecord-postgres-hstore_spec.rb

data/lib/activerecord-postgres-hstore/hstore.rb

@@ -1,2 +0,0 @@
-class Hstore < Hash
-end