property 0.9.1 → 1.0.0

data/.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 coverage
 *.gem
+log/test.log

data/History.txt

@@ -1,6 +1,22 @@
+== 1.0.0 2010-05-27
+
+* Major enhancements
+  * Added StoredRole class to store role definitions in the database.
+  * Validates with legacy but invalid properties if value is unchanged.
+  * Added the notion of used roles.
+  * Renamed Behavior to Role.
+  * Added support for index definition in stored column.
+  * Added support for :with option in index_reader.
+
+* 2 minor enhancements
+  * Created Property::Base module for inclusion without callbacks.
+  * Raises an exception if we try to define a property that would hide a superclass method.
+  * Fixed multiple column declarations in one go.
+  * Fixed bug when adding role as class to sub-class.
+
 == 0.9.1 2010-03-20
 
-* 1 major enhancement
+* 2 major enhancements
   * Added support for custom indexer classes.
   * Removed after_commit dependency (no need for an after_commit).
 
@@ -24,13 +40,13 @@
 == 0.8.1 2010-02-14
 
 * 2 major enhancement
-  * Enabled behavior method definitions.
+  * Enabled role method definitions.
   * Enabled external storage with 'store_properties_in' method.
 
 == 0.8.0 2010-02-11
 
 * 3 major enhancements
-  * Enabled Behaviors that can be added on an instance.
+  * Enabled Roles that can be added on an instance.
   * Enabled non-DB types.
   * 100% test coverage.
 

data/README.rdoc

@@ -47,12 +47,12 @@ And set them with:
   @contact.prop['name'] = 'Gandhi'
   @contact.name = 'Gandhi'
 
-== Behaviors
+== Roles
 
 Properties would not be really fun if you could not add new properties to your instances depending
-on some flags. First define the behaviors:
+on what the object does. First define the roles:
 
-  @picture = Property::Behavior.new do |p|
+  @picture = Property::Role.new do |p|
     p.integer :width,  :default => :get_width
     p.integer :height, :default => :get_height
     p.string  'camera'
@@ -76,16 +76,21 @@ on some flags. First define the behaviors:
     end
   end
 
-And then, either when creating new pictures or updating them, you need to include the behavior:
+And then, either when creating new pictures or updating them, you need to include the role:
 
-  @model.behave_like @picture
+  @model.has_role @picture
 
 The model now has the picture's properties defined, with accessors like @model.camera, methods like
 @model.image, get_with, etc and default values will be fetched on save.
 
-Note that you do not need to include a behavior just to read the data as long as you use the 'prop'
+Note that you do not need to include a role just to read the data as long as you use the 'prop'
 accessor.
 
+== StoredRole
+
+The dynamic nature of the Property gem goes to the point where you can store your property definitions
+in the database by using the StoredRole and StoredColumn modules.
+
 == External storage
 
 You might need to define properties in a model but store them in another model (versioning). In this
@@ -102,3 +107,43 @@ case you can simply use 'store_properties_in' class method:
 
 Doing so will not touch the storage class. All property definitions, validations and method
 definitions are executed on the 'Contact' class.
+
+== Indexing support
+
+The property gem lets you very easily export content from the packed data to any kind of external table. Using
+a key/value tables:
+
+  class Contact < ActiveRecord::Base
+    include Property
+    property do |p|
+      p.string 'name', :indexed => true
+      p.string 'first_name', :index => Proc.new {|rec| { 'fullname' => rec.fullname }}
+
+      p.index(:string) do |record|
+        {
+          'fulltext' => "name:#{record.name} first_name:#{record.first_name}",
+          "name_#{record.lang}" => record.name
+        }
+      end
+    end
+  end
+
+Using a custom indexer, you can group indexed values together in a single record. This can be interesting if you have
+some legacy code or queries that need direct access to some values:
+
+  class Contact < ActiveRecord::Base
+    include Property
+    property do |p|
+      p.string 'name'
+      p.string 'first_name'
+
+      p.index(ContactIndexer) do |record|
+        {
+          'name'       => record.name,
+          'first_name' => record.first_name,
+        }
+      end
+    end
+  end
+
+Please read the docs for details: http://zenadmin.org/635

data/lib/property.rb

@@ -2,16 +2,18 @@ require 'property/attribute'
 require 'property/dirty'
 require 'property/properties'
 require 'property/column'
-require 'property/behavior'
+require 'property/role'
+require 'property/stored_role'
 require 'property/schema'
 require 'property/declaration'
 require 'property/db'
 require 'property/index'
 require 'property/serialization/json'
 require 'property/core_ext/time'
+require 'property/base'
 
 module Property
-  VERSION = '0.9.1'
+  VERSION = '1.0.0'
 
   def self.included(base)
     base.class_eval do

data/lib/property/attribute.rb

@@ -11,18 +11,25 @@ module Property
   # them apart.
   #
   module Attribute
-
     def self.included(base)
-      base.extend ClassMethods
-
       base.class_eval do
-        include InstanceMethods
+        include Base
+        after_validation   :dump_properties
+        alias_method_chain :attributes=,  :properties
+      end
+    end
 
-        store_properties_in self
+    # This is just a helper module that includes necessary code for property access, but without
+    # the validation/save hooks.
+    module Base
+      def self.included(base)
+        base.extend ClassMethods
 
-        after_validation   :dump_properties
+        base.class_eval do
+          include InstanceMethods
 
-        alias_method_chain :attributes=,  :properties
+          store_properties_in self
+        end
       end
     end
 

data/lib/property/base.rb

@@ -0,0 +1,16 @@
+module Property
+
+  # This module is used when we need to access the properties in the properties storage model (to
+  # compare versions for example). Including this module has the same effect as including 'Property'
+  # but without the hooks (validation, save, etc).
+  module Base
+    def self.included(base)
+      base.class_eval do
+        include Attribute::Base
+        include Serialization::JSON
+        include Declaration::Base
+        include Dirty
+      end
+    end
+  end
+end

data/lib/property/column.rb

@@ -12,11 +12,11 @@ module Property
 
     def initialize(name, default, type, options={})
       name = name.to_s
-      extract_property_options(options)
       if type.kind_of?(Class)
         @klass = type
       end
       super(name, default, type, options)
+      extract_property_options(options)
     end
 
     def validate(value, errors)
@@ -48,6 +48,9 @@ module Property
       @klass || super
     end
 
+    # Property type used instead of 'type' when column is stored
+    alias ptype type
+
     def type_cast(value)
       if type == :string
         value = value.to_s
@@ -62,6 +65,15 @@ module Property
     private
       def extract_property_options(options)
         @index = options.delete(:index) || options.delete(:indexed)
+        if @index == true
+          @index = ptype
+        end
+
+        if @index.blank?
+          @index = nil
+        elsif @index.kind_of?(Symbol)
+          @index = @index.to_s
+        end
       end
 
       def extract_default(default)

data/lib/property/declaration.rb

@@ -3,39 +3,50 @@ module Property
   # Property::Declaration module is used to declare property definitions in a Class. The module
   # also manages property inheritence in sub-classes.
   module Declaration
-
     def self.included(base)
       base.class_eval do
-        extend  ClassMethods
-        include InstanceMethods
+        include Base
+        validate :properties_validation, :if => :properties
+      end
+    end
 
-        class << self
-          attr_accessor :schema
+    module Base
+      def self.included(base)
+        base.class_eval do
+          extend  ClassMethods
+          include InstanceMethods
 
-          def schema
-            @schema ||= make_schema
-          end
+          class << self
+            attr_accessor :schema
 
-          private
-            def make_schema
-              schema = Property::Schema.new(self.to_s, self)
-              if superclass.respond_to?(:schema)
-                schema.behave_like superclass
-              end
-              schema
+            def schema
+              @schema ||= make_schema
             end
-        end
 
-        validate :properties_validation, :if => :properties
+            private
+              def make_schema
+                schema = Property::Schema.new(self.to_s, self)
+                if superclass.respond_to?(:schema)
+                  schema.has_role superclass
+                end
+                schema
+              end
+          end
+        end
       end
     end
 
     module ClassMethods
 
-      # Include a new set of property definitions (Behavior) into the current class schema.
+      # Include a new set of property definitions (Role) into the current class schema.
       # You can also provide a class to simulate multiple inheritance.
-      def behave_like(behavior)
-        schema.behave_like behavior
+      def has_role(role)
+        schema.has_role role
+      end
+
+      # Return true if the current object has all the roles of the given object, class or role.
+      def has_role?(role)
+        schema.has_role? role
       end
 
       # Use this class method to declare properties and indices that will be used in your models.
@@ -52,21 +63,32 @@ module Property
       #    end
       #  end
       def property(&block)
-        schema.behavior.property(&block)
+        schema.role.property(&block)
       end
     end # ClassMethods
 
     module InstanceMethods
-      # Instance's schema (can be different from the instance's class schema if behaviors have been
+      # Instance's schema (can be different from the instance's class schema if roles have been
       # added to the instance.
       def schema
         @own_schema || self.class.schema
       end
 
-      # Include a new set of property definitions (Behavior) into the current instance's schema.
+      # Include a new set of property definitions (Role) into the current instance's schema.
       # You can also provide a class to simulate multiple inheritance.
-      def behave_like(behavior)
-        own_schema.behave_like behavior
+      def has_role(role)
+        own_schema.has_role role
+      end
+
+      # Return the list of active roles. The active roles are all the Roles included
+      # in the current object for which properties have been defined (not blank).
+      def used_roles
+        own_schema.used_roles_in(self)
+      end
+
+      # Return true if the current object has all the roles of the given object, class or role.
+      def has_role?(role)
+        own_schema.has_role? role
       end
 
       protected
@@ -81,7 +103,7 @@ module Property
         def make_own_schema
           this = class << self; self; end
           schema = Property::Schema.new(nil, this)
-          schema.behave_like self.class
+          schema.has_role self.class
           schema
         end
     end # InsanceMethods

data/lib/property/error.rb

@@ -0,0 +1,4 @@
+module Property
+  class Error < Exception
+  end
+end

data/lib/property/index.rb

@@ -23,37 +23,120 @@ module Property
         def get_indices(group_name)
           return {} if new_record?
           res = {}
-          Property::Db.fetch_attributes(['key', 'value'], index_table_name(group_name), index_reader_sql).each do |row|
+          Property::Db.fetch_attributes(['key', 'value'], index_table_name(group_name), index_reader_sql(group_name)).each do |row|
             res[row['key']] = row['value']
           end
           res
         end
 
-        def index_reader_sql
-          index_reader.map {|k, v| "#{k} = #{self.class.connection.quote(v)}"}.join(' AND ')
+        def index_reader_sql(group_name)
+          index_reader(group_name).map do |k, v|
+            if k == :with
+              v.map do |subk, subv|
+                if subv.kind_of?(Array)
+                  "`#{subk}` IN (#{subv.map {|ssubv| connection.quote(ssubv)}.join(',')})"
+                else
+                  "`#{subk}` = #{self.class.connection.quote(subv)}"
+                end
+              end.join(' AND ')
+            else
+              "`#{k}` = #{self.class.connection.quote(v)}"
+            end
+          end.join(' AND ')
         end
 
-        def index_reader
+        def index_reader(group_name)
           {index_foreign_key => self.id}
         end
 
-        alias index_writer index_reader
+        def index_writer(group_name)
+          index_reader(group_name)
+        end
 
         def index_table_name(group_name)
           "i_#{group_name}_#{self.class.table_name}"
         end
 
         def index_foreign_key
-          self.class.table_name.singularize.foreign_key
+          @index_foreign_key ||=self.class.table_name.singularize.foreign_key
+        end
+
+        # Create a list of index entries
+        def create_indices(group_name, new_keys, cur_indices)
+          # Build insert_many query
+          writer       = index_writer(group_name)
+          foreign_keys = index_foreign_keys(writer)
+
+          Property::Db.insert_many(
+            index_table_name(group_name),
+            foreign_keys + %w{key value},
+            map_index_values(new_keys, cur_indices, foreign_keys, writer)
+          )
+        end
+
+        def index_foreign_keys(writer)
+          if with = writer[:with]
+            writer.keys - [:with] + with.keys
+          else
+            writer.keys
+          end
+        end
+
+        def map_index_values(new_keys, cur_indices, index_foreign_keys, index_writer)
+          if with = index_writer[:with]
+            foreign_values = explode_list(index_foreign_keys.map {|k| index_writer[k] || with[k]})
+          else
+            foreign_values = [index_foreign_keys.map {|k| index_writer[k]}]
+          end
+
+          values = new_keys.map do |key|
+            [connection.quote(key), connection.quote(cur_indices[key])]
+          end
+
+          res = []
+          foreign_values.each do |list|
+            list = list.map {|k| connection.quote(k)}
+            values.each do |value|
+              res << (list + value)
+            end
+          end
+          res
+        end
+
+        # Takes a mixed array and explodes it
+        # [x, ['en','fr'], y, [a,b]] ==> [[x,'en',y,a], [x,'en',y',b], [x,'fr',y,a], [x,'fr',y,b]]
+        def explode_list(list)
+          res = [[]]
+          list.each do |key|
+            if key.kind_of?(Array)
+              res_bak = res
+              res = []
+              key.each do |k|
+                res_bak.each do |list|
+                  res << (list + [k])
+                end
+              end
+            else
+              res.each do |list|
+                list << key
+              end
+            end
+          end
+          res
+        end
+
+        # Update an index entry
+        def update_index(group_name, key, value)
+          self.class.connection.execute "UPDATE #{index_table_name(group_name)} SET `value` = #{connection.quote(value)} WHERE #{index_reader_sql(group_name)} AND `key` = #{connection.quote(key)}"
+        end
+
+        # Delete a list of indices (value became blank).
+        def delete_indices(group_name, keys)
+          self.class.connection.execute "DELETE FROM #{index_table_name(group_name)} WHERE #{index_reader_sql(group_name)} AND `key` IN (#{keys.map{|key| connection.quote(key)}.join(',')})"
         end
 
         # This method prepares the index
         def property_index
-          connection     = self.class.connection
-          reader_sql     = index_reader_sql
-          foreign_keys   = nil
-          foreign_values = nil
-
           schema.index_groups.each do |group_name, definitions|
             cur_indices = {}
             definitions.each do |key, proc|
@@ -61,12 +144,16 @@ module Property
                 value = prop[key]
                 if !value.blank?
                   if proc
+                    # Get value(s) to index through proc
                     cur_indices.merge!(proc.call(self))
                   else
+                    # Set current value from prop
                     cur_indices[key] = value
                   end
                 end
               else
+                # No key: group index generated with
+                # p.index(group_name) do |record| ...
                 cur_indices.merge!(proc.call(self))
               end
             end
@@ -74,7 +161,7 @@ module Property
             if group_name.kind_of?(Class)
               # Use a custom indexer
               group_name.set_property_index(self, cur_indices)
-            else
+            elsif index_reader(group_name)
               # Add key/value pairs to the default tables
               old_indices = get_indices(group_name)
 
@@ -85,34 +172,22 @@ module Property
               del_keys = old_keys - cur_keys
               upd_keys = cur_keys & old_keys
 
-              table_name  = index_table_name(group_name)
-
               upd_keys.each do |key|
                 value = cur_indices[key]
                 if value.blank?
                   del_keys << key
-                else
-                  connection.execute "UPDATE #{table_name} SET value = #{connection.quote(cur_indices[key])} WHERE #{reader_sql} AND key = #{connection.quote(key)}"
+                elsif value != old_indices[key]
+                  update_index(group_name, key, value)
                 end
               end
 
               if !del_keys.empty?
-                connection.execute "DELETE FROM #{table_name} WHERE #{reader_sql} AND key IN (#{del_keys.map{|key| connection.quote(key)}.join(',')})"
+                delete_indices(group_name, del_keys)
               end
 
               new_keys.reject! {|k| cur_indices[k].blank? }
               if !new_keys.empty?
-                # we evaluate this now to have the id on record creation
-                foreign_keys   ||= index_writer.keys
-                foreign_values ||= foreign_keys.map {|k| index_writer[k]}
-
-                Property::Db.insert_many(
-                  table_name,
-                  foreign_keys + ['key', 'value'],
-                  new_keys.map do |key|
-                    foreign_values + [connection.quote(key), connection.quote(cur_indices[key])]
-                  end
-                )
+                create_indices(group_name, new_keys, cur_indices)
               end
             end
           end
@@ -127,7 +202,7 @@ module Property
             if group_name.kind_of?(Class)
               group_name.delete_property_index(self)
             else
-              connection.execute "DELETE FROM #{index_table_name(group_name)} WHERE #{foreign_key} = #{current_id}"
+              connection.execute "DELETE FROM #{index_table_name(group_name)} WHERE `#{foreign_key}` = #{current_id}"
             end
           end
         end