attribute-filters 1.3.2 → 1.4.0

data/lib/attribute-filters/common_filters/join.rb

@@ -0,0 +1,98 @@
+# encoding: utf-8
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2012 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:LGPL-LICENSE GNU Lesser General Public License} or {file:COPYING Ruby License}.
+# 
+# This file contains ActiveModel::AttributeFilters::Common::Join module
+# containing ready-to-use filtering method.
+
+# @abstract This namespace is shared with ActveModel.
+module ActiveModel
+  module AttributeFilters
+    # This module contains common, ready-to-use filtering methods.
+    module Common
+      # Joins attributes.
+      module Join
+        extend CommonFilter
+
+        # Joins attributes and writes the results into other attribute.
+        # 
+        # The attrubutes to be destination for joins are taken from the attribute set
+        # called +should_be_joined+.
+        # 
+        # The pattern used to join a string and the optional separator argument
+        # should be set using the model's class method +join_attribute+.
+        def join_attributes
+          filter_attrs_from_set(:should_be_joined, :process_all, :process_blank) do |atr_val, atr_name, set_obj|
+            from, compact = set_obj.annotation(atr_name, :join_from, :join_compact)
+            if from.blank?
+              next atr_val if !atr_val.is_a?(Array)
+              from = [ atr_name ]
+            elsif !from.is_a?(Array)
+              from = [ from ]
+            end
+            vals = AttributeSet::Query.new(from, self).values
+            separator = set_obj.has_annotation?(atr_name, :join_separator) ?
+                        set_obj.annotation(atr_name, :join_separator) : " "
+            if compact && vals.respond_to?(:compact)
+              vals.compact.join(separator)
+            elsif vals.respond_to?(:join)
+              vals.join(separator)
+            else
+              vals
+            end
+          end
+        end
+
+        # This submodule contains class methods needed to describe
+        # attribute joining.
+        module ClassMethods
+          # This method parametrizes joining operation for an attribute of the given name.
+          # It uses attribute set annotations to register parameters used when joining.
+          # 
+          # @param atr_name [String,Symbol] attribute name
+          # @param parameters [Hash] parameters hash # fixme: add YARD parameters explained
+          # @return [void]
+          def join_attribute(atr_name, parameters = nil)
+            atr_name.is_a?(Hash) and return atr_name.each_pair { |k, v| join_attribute(k, v) }
+            if atr_name.is_a?(Array)
+              if parameters.is_a?(Symbol) || parameters.is_a?(String)
+                return join_attribute(parameters, atr_name)
+              elsif parameters.is_a?(Hash)
+                dst = parameters.delete(:into) || parameters.delete(:in) || parameters.delete(:destination)
+                if dst.nil?
+                  raise ArgumentError, "you have to specify destination attribute using :into => 'attribute_name'"
+                end
+                parameters[:from] = atr_name
+                return join_attribute(dst, parameters)
+              end
+            end
+            parameters = { :from => parameters } unless parameters.is_a?(Hash)
+            the_attribute(atr_name, :should_be_joined)
+            a = {}
+            if parameters.key?(:with)
+              a[:join_separator] = parameters[:with]
+            elsif parameters.key?(:separator)
+              a[:join_separator] = parameters[:separator]
+            elsif parameters.key?(:join_separator)
+              a[:join_separator] = parameters[:join_separator]
+            end
+            from    = parameters[:from] || parameters[:source] || parameters[:sources] || parameters[:join_from]
+            compact = parameters.key?(:compact) ? !!parameters[:compact] : !!parameters[:join_compact]
+            a.merge!({ :join_compact => compact, :join_from => from })
+            annotate_attributes_that(:should_be_joined, atr_name => a)
+          end
+          alias_method :join_attributes,      :join_attribute
+          alias_method :joint_attribute,      :join_attribute
+          alias_method :joint_attributes,     :join_attribute
+          alias_method :join_attributes_to,   :join_attribute
+          alias_method :join_attributes_into, :join_attribute
+        end # module ClassMethods
+      end # module Join
+
+      include Join
+
+    end # module Common
+  end # module AttributeFilters
+end # module ActiveModel

data/lib/attribute-filters/common_filters/split.rb

@@ -0,0 +1,130 @@
+# encoding: utf-8
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2012 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:LGPL-LICENSE GNU Lesser General Public License} or {file:COPYING Ruby License}.
+# 
+# This file contains ActiveModel::AttributeFilters::Common::Split module
+# containing ready-to-use filtering method.
+
+# @abstract This namespace is shared with ActveModel.
+module ActiveModel
+  module AttributeFilters
+    # This module contains common, ready-to-use filtering methods.
+    module Common
+      # Splits attributes.
+      module Split
+        extend CommonFilter
+        # Splits attributes and writes the results into other attributes.
+        # 
+        # The attrubutes to be splitted are taken from the attribute set
+        # called +should_be_splitted+. This method is safe to be
+        # used with multibyte strings (containing diacritics).
+        # 
+        # The pattern used to split a string and the optional limit argument
+        # should be set using the model's class method +split_attribute+
+        # or directly with annotations.
+        def split_attributes
+          for_each_attr_from_set(:should_be_splitted) do |atr_val, atr_name, set_obj|
+            pattern, limit, flatten, into = set_obj.annotation(atr_name,  :split_pattern, :split_limit,
+                                                                          :split_flatten, :split_into)
+            if limit.nil?
+              r = AttributeFiltersHelpers.each_element(atr_val, String) do |v|
+                v.mb_chars.split(pattern)
+              end
+            else
+              r = AttributeFiltersHelpers.each_element(atr_val, String) do |v|
+                v.mb_chars.split(pattern, limit)
+              end
+            end
+            r = [ r ] unless r.is_a?(Array)
+            r.flatten! if flatten
+
+            # writing collected slices
+            if into.blank?
+              public_send("#{atr_name}=", r)
+            else
+              into.each_with_index { |dst_atr, i| public_send("#{dst_atr}=", r[i]) }
+            end
+          end
+        end
+
+        # This submodule contains class methods needed to describe
+        # attribute splitting.
+        module ClassMethods
+          # This method parametrizes splitting operation for an attribute of the given name.
+          # It uses attribute set annotations to register parameters used when splitting.
+          # 
+          # If the separator is not specified and the source attribute is a kind of +String+ then the default
+          # separator is applied, which is a whitespace character. You can change that by explicitly setting
+          # the separator to +nil+. In such case the split will occuch for each character. If there are more
+          # resulting parts then destination attributes then the redundant elements are ignored. If there is
+          # a limit given and there are more array elements than attributes then the filter behaves like
+          # puts leaves the redundant (unsplittable) and puts it into the last destination attribute.
+          # 
+          # If the source attribute is an array then the filter will put each element of that array into each
+          # destination attribute. If there are more array elements than attributes then the reduntant elements
+          # are ignored.
+          # 
+          # If the destination attributes are not given then the split filter will generate an array and replace
+          # currently processed attribute with an array.
+          # 
+          # The pattern parameter (+:pattern+ when using +split_attributes+ class method or +:split_pattern+ when directly
+          # annotating attribute in a set) should be a string. If you would like to separate each character
+          # you have to set it to +nil+.
+          # 
+          # @example
+          #   class User < ActiveRecord::Base
+          #     include ActiveModel::AttributeFilters::Common::Split
+          #   
+          #     attr_virtual      :real_name
+          #     attr_accessible   :real_name
+          #     split_attributes  :real_name, :limit => 2, :into => [ :first_name, :last_name ], :pattern => ' '
+          #     before_validation :split_attributes
+          #   end
+          #   
+          # @example
+          #   class User < ActiveRecord::Base
+          #     include ActiveModel::AttributeFilters::Common::Split
+          #   
+          #     attr_virtual      :real_name
+          #     attr_accessible   :real_name
+          #     attributes_that   :should_be_splitted =>  { :real_name =>
+          #                                                   { :limit => 2,
+          #                                                     :into => [ :first_name, :last_name ],
+          #                                                     :pattern => ' ' } }
+          #     before_validation :split_attributes
+          #   end
+          # 
+          # @param atr_name [String,Symbol] attribute name
+          # @param parameters [Hash] parameters hash # fixme: add YARD parameters explained
+          # @return [void]
+          def split_attribute(atr_name, parameters = nil)
+            atr_name.is_a?(Hash) and return atr_name.each_pair { |k, v| split_attribute(k, v) }
+            parameters = { :into => parameters } unless parameters.is_a?(Hash)
+            the_attribute(atr_name, :should_be_splitted)
+            pattern = parameters[:with]   || parameters[:pattern] || parameters[:split_pattern]
+            into    = parameters[:into]   || parameters[:to]      || parameters[:split_into]
+            limit   = parameters[:limit]  || parameters[:split_limit]
+            limit   = limit.to_i unless limit.blank?
+            flatten = parameters[:flatten] || parameters[:split_flatten]
+            if into.blank?
+              into = nil
+            elsif !into.is_a?(Array)
+              into = into.respond_to?(:to_a) ? into.to_a : [ into ]
+            end
+            annotate_attributes_that(:should_be_splitted, atr_name => {
+                                     :split_flatten => flatten,
+                                     :split_pattern => pattern,
+                                     :split_limit => limit,
+                                     :split_into => into})
+          end
+          alias_method :split_attributes, :split_attribute
+        end # module ClassMethods
+      end # module Split
+
+    include Split
+
+    end # module Common
+  end # module AttributeFilters
+end # module ActiveModel

data/lib/attribute-filters/common_filters/squeeze.rb

@@ -0,0 +1,75 @@
+# encoding: utf-8
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2012 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:LGPL-LICENSE GNU Lesser General Public License} or {file:COPYING Ruby License}.
+# 
+# This file contains ActiveModel::AttributeFilters::Common::Squeeze module
+# containing ready-to-use filtering method.
+
+# @abstract This namespace is shared with ActveModel.
+module ActiveModel
+  module AttributeFilters
+    # This module contains common, ready-to-use filtering methods.
+    module Common
+      # Squeezes white characters in attributes.
+      module Squeeze
+        extend CommonFilter
+        # Squeezes white characters in attributes.
+        # 
+        # The attrubutes to be squeezed are taken from the attribute set
+        # called +should_be_squeezed+. This method is safe to be
+        # used with multibyte strings (containing diacritics).
+        # 
+        # @note If a value of currently processed attribute is an array
+        #  then any element of the array is changed.
+        # 
+        # @return [void]
+        def squeeze_attributes
+          filter_attrs_from_set(:should_be_squeezed) do |atr|
+            AttributeFiltersHelpers.each_element(atr, String) do |v|
+              v.mb_chars.squeeze.to_s
+            end
+          end
+        end
+        # This submodule contains class methods used to easily define filter.
+        module ClassMethods
+          # Registers attributes that should be squeezed.
+          def squeeze_attributes(*args)
+            attributes_that(:should_be_squeezed, args)
+          end
+          alias_method :squeeze_attribute, :squeeze_attributes
+        end # module ClassMethods
+
+        # Squeezes white characters in attributes, removes leading and trailing spaces and newlines.
+        # 
+        # The attrubutes to be squished are taken from the attribute set
+        # called +should_be_squished+. This method is safe to be
+        # used with multibyte strings (containing diacritics).
+        # 
+        # @note If a value of currently processed attribute is an array
+        #  then any element of the array is changed.
+        # 
+        # @return [void]
+        def squish_attributes
+          filter_attrs_from_set(:should_be_squished) do |atr|
+            AttributeFiltersHelpers.each_element(atr, String) do |v|
+              v.mb_chars.squish.to_s
+            end
+          end
+        end
+        # This submodule contains class methods used to easily define filter.
+        module ClassMethods
+          # Registers attributes that should be squished.
+          def squish_attributes(*args)
+            attributes_that(:should_be_squished, args)
+          end
+          alias_method :squish_attribute, :squish_attributes
+        end # module ClassMethods
+      end # module Squeeze
+
+    include Squeeze
+
+    end # module Common
+  end # module AttributeFilters
+end # module ActiveModel

data/lib/attribute-filters/common_filters/strip.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2012 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:LGPL-LICENSE GNU Lesser General Public License} or {file:COPYING Ruby License}.
+# 
+# This file contains ActiveModel::AttributeFilters::Common::Strip module
+# containing ready-to-use filtering method.
+
+# @abstract This namespace is shared with ActveModel.
+module ActiveModel
+  module AttributeFilters
+    # This module contains common, ready-to-use filtering methods.
+    module Common
+      # Strips attributes from leading and trailing spaces.
+      module Strip
+        extend CommonFilter
+        # Strips attributes from leading and trailing spaces.
+        # 
+        # The attrubutes to be stripped are taken from the attribute set called
+        # +should_be_stripped+. It operates directly on attribute's contents.
+        # 
+        # @note If a value of currently processed attribute is an array
+        #  then any element of the array is changed.
+        # 
+        # @return [void]
+        def strip_attributes
+          filter_attrs_from_set(:should_be_stripped) do |atr|
+            AttributeFiltersHelpers.each_element(atr, String) { |v| v.strip }
+          end
+        end
+        # This submodule contains class methods used to easily define filter.
+        module ClassMethods
+          # Registers attributes that should be stripped.
+          def strip_attributes(*args)
+            attributes_that(:should_be_stripped, args)
+          end
+          alias_method :strip_attribute, :strip_attributes
+        end # module ClassMethods
+      end # module Strip
+
+      include Strip
+
+    end # module Common
+  end # module AttributeFilters
+end # module ActiveModel

data/lib/attribute-filters/dsl_attr_virtual.rb

@@ -0,0 +1,50 @@
+# encoding: utf-8
+#
+# Author::    Paweł Wilk (mailto:pw@gnu.org)
+# Copyright:: (c) 2012 by Paweł Wilk
+# License::   This program is licensed under the terms of {file:LGPL-LICENSE GNU Lesser General Public License} or {file:COPYING Ruby License}.
+#
+# This file contains attr_virtual DSL method that sets up setter, getter,
+# and enables change tracking for vitual attrbutes.
+
+# @abstract This namespace is shared with ActveModel.
+module ActiveModel
+  module AttributeFilters
+    module ClassMethods
+
+      private
+
+      unless method_defined?(:attr_virtual)
+        # This method creates setter and getter for attributes of the given names
+        # and ensures that changes of their values are tracked.
+        # 
+        # @note Placing +attr_writer+ with the same attribute name AFTER
+        #  +attr_virtual+ will overwrite setter. Don't do that.
+        def attr_virtual(*attribute_names)
+          attribute_names.flatten.compact.uniq.each do |atr_name|
+            writer_name = "#{atr_name}="
+            atr_name = atr_name.to_sym
+            attr_reader(atr_name) unless method_defined?(atr_name)
+            attr_accessible(atr_name) if method_defined?(:attr_accessible)
+            if method_defined?(writer_name)
+              self.class_eval <<-EVAL
+                alias_method :#{atr_name}_without_change_tracking=, :#{writer_name}
+                def #{writer_name}(val)
+                  attribute_will_change!('#{atr_name}') if val != '#{atr_name}'
+                  #{atr_name}_without_change_tracking=(val)
+                end
+              EVAL
+            else
+              self.class_eval <<-EVAL
+                def #{writer_name}(val)
+                  attribute_will_change!('#{atr_name}') if val != '#{atr_name}'
+                  @#{atr_name} = val
+                end
+              EVAL
+            end
+          end
+        end # def attr_virtual
+      end # unless method_defined?(:attr_virtual)
+    end # module ClassMethods
+  end # module AttributeFilters
+end # module ActiveModel

data/lib/attribute-filters/dsl_filters.rb

@@ -13,7 +13,8 @@ module ActiveModel
     PROCESSING_FLAGS = {
       :process_blank      => false,
       :process_all        => false,
-      :no_presence_check  => false
+      :no_presence_check  => false,
+      :include_missing    => false
     }.freeze
 
     # Gets names of attributes for which filters should be applied by
@@ -23,7 +24,7 @@ module ActiveModel
     # @overload attributes_to_filter(set_name, process_all, no_presence_check)
     #   @param set_name [String,Symbol] name of a set of attributes used to get attributes
     #   @param process_all [Boolean] if set then all the attributes from the attribute set are selected,
-    #     not just attributes that has changed (defaults to +false+)
+    #     not just attributes that have changed (defaults to +false+)
     #   @param no_presence_check [Boolean] if set then the checking whether attribute exists will be
     #     disabled (matters only when +process_all+ is also set) (defaults to +false+)
     #   @return [AttributeSet] set of attributes (attribute name => previous_value)
@@ -36,9 +37,9 @@ module ActiveModel
     #     disabled (matters only when +process_all+ is also set) (defaults to +false+)
     #   @return [AttributeSet] set of attributes (attribute name => previous_value)
     def attributes_to_filter(set_name, process_all = false, no_presence_check = false)
-      atf = set_name.is_a?(::ActiveModel::AttributeSet) ? set_name : attribute_set(set_name)
+      atf = set_name.is_a?(::ActiveModel::AttributeSet) ? set_name : attribute_set_simple(set_name)
       if process_all
-        no_presence_check ? atf : atf & (__vatrf(no_presence_check) + attributes.keys)
+        no_presence_check ? atf : atf & all_attributes_simple(no_presence_check)
       else
         if self.class.filter_virtual_attributes_that_changed?
           atf & changes.keys
@@ -66,17 +67,18 @@ module ActiveModel
     #   
     #   The result of the given block is used to set a new values for processed attributes. 
     #   
-    #   @param set_name [Symbol] name of the attribute set
+    #   @param set_name [Symbol] name of the attribute set or a set object
     #   @param args [Array] optional additional arguments that will be passed to the block
     #   @param flags [Array<Symbol>] optional additional flags controlling the processing of attributes:
     #     * +:process_blank+ – tells to also process attributes that are blank (empty or +nil+)
     #     * +:process_all+ - tells to process all attributes, not just the ones that has changed
     #     * +:no_presence_check+ – tells not to check for existence of each processed attribute when processing
-    #       all attributes; increases performance but you must care about putting into set only the existing attributes
+    #       all attributes; increases performance but you must care about putting only the existing attributes into sets
     #   @yield [attribute_value, set_name, attribute_name, *args] block that will be called for each attribute
     #   @yieldparam attribute_value [Object] current attribute value that should be altered
+    #   @yieldparam attribute_name [String] a name of currently processed attribute
+    #   @yieldparam set_object [Object] currently processed set that attribute belongs to
     #   @yieldparam set_name [Symbol] a name of the processed attribute set
-    #   @yieldparam attribute_name [Object] a name of currently processed attribute
     #   @yieldparam args [Array] optional arguments passed to the method
     #   @yieldreturn [Object] the result of calling the block 
     #   @return [void]
@@ -95,7 +97,7 @@ module ActiveModel
     #     
     #     end
     def filter_attrs_from_set(set_name, *args, &block)
-       operate_on_attrs_from_set(set_name, true, *args, &block)
+      operate_on_attrs_from_set(set_name, true, *args, &block)
     end
     alias_method :attribute_filter_for_set,     :filter_attrs_from_set
     alias_method :filter_attributes_which,      :filter_attrs_from_set
@@ -131,17 +133,20 @@ module ActiveModel
     #   method in a block or explicitly assign new, calculated value to the attribute
     #   using its name (also passed to a block as one of arguments).
     #   
-    #   @param set_name [Symbol] name of the attribute set
+    #   @param set_name [Symbol] name of the attribute set or a set object
     #   @param args [Array] optional additional arguments that will be passed to a block
     #   @param flags [Array<Symbol>] optional additional flags controlling the processing of attributes:
     #     * +:process_blank+ – tells to also process attributes that are blank (empty or +nil+)
     #     * +:process_all+ - tells to process all attributes, not just the ones that has changed
     #     * +:no_presence_check+ – tells not to check for existence of each processed attribute when processing
     #       all attributes; increases performance but you must care about putting into set only the existing attributes
+    #     * +:include_missing+ – includes attributes that does not exist in a resulting iteration (their values are
+    #       always +nil+); has effect only when +process_blank+ and +no_presence_check+ are set to +true+
     #   @yield [attribute_value, set_name, attribute_name, *args] block that will be called for each attribute
     #   @yieldparam attribute_value [Object] current attribute value that should be altered
+    #   @yieldparam attribute_name [String] a name of currently processed attribute
+    #   @yieldparam set_object [Object] currently processed set that attribute belongs to
     #   @yieldparam set_name [Symbol] a name of the processed attribute set
-    #   @yieldparam attribute_name [Object] a name of currently processed attribute
     #   @yieldparam args [Array] optional arguments passed to the method
     #   @yieldreturn [Object] the result of calling the block 
     #   @return [void]
@@ -200,6 +205,7 @@ module ActiveModel
       end
       alias_method :filter_virtual_attributes_that_changed, :filter_virtual_attributes_that_have_changed
       alias_method :filter_changed_virtual_attributes,      :filter_virtual_attributes_that_have_changed
+      alias_method :virtual_attributes_are_tracked,         :filter_virtual_attributes_that_have_changed
 
       # Gets the internal flag that causes to check virtual attributes
       # for changes when selecting attributes for filtering.
@@ -220,49 +226,54 @@ module ActiveModel
 
     # Applies operations to elements from set.
     def operate_on_attrs_from_set(set_name, alter_mode, *args, &block)
+      block_given? or return enum_for(__method__, set_name, alter_mode, *args)
       flags             = AttributeFiltersHelpers.process_flags(args)
       process_all       = flags[:process_all]
       process_blank     = flags[:process_blank]
       no_presence_check = flags[:no_presence_check]
-      attrs_to_process  = attributes_to_filter(set_name, process_all, no_presence_check)
+      include_missing   = flags[:include_missing]
+      if set_name.is_a?(::ActiveModel::AttributeSet)
+        set_obj = set_name
+        set_name = nil
+      else
+        set_obj = attribute_set_simple(set_name)
+      end
+      attrs_to_process = attributes_to_filter(set_obj, process_all, no_presence_check)
       if alter_mode
         if process_blank
           # filtering without testing for blank
           attrs_to_process.each do |atr|
-            send("#{atr}=", yield(send(atr), set_name, atr, *args))
+            public_send("#{atr}=", yield(public_send(atr), atr, set_obj, set_name, *args))
           end
         else
           # filtering present only
           attrs_to_process.each do |atr|
-            v = send(atr)
-            send("#{atr}=", yield(v, set_name, atr, *args)) if v.present?
+            v = public_send(atr)
+            public_send("#{atr}=", yield(v, atr, set_obj, set_name, *args)) if v.present?
           end
         end
       else
         if process_blank
           # calling without testing for blank
-          attrs_to_process.each do |atr|
-            yield(send(atr), set_name, atr, *args)
+          if include_missing
+            # including missing attributes (changing them into nils)
+            attrs_to_process.each do |atr|
+              v = respond_to?(atr) ? public_send(atr) : nil
+              yield(v, atr, set_obj, set_name, *args)
+            end
+          else
+            attrs_to_process.each do |atr|
+              yield(public_send(atr), atr, set_obj, set_name, *args)
+            end
           end
         else
           # calling present only
           attrs_to_process.each do |atr|
-            v = send(atr)
-            yield(v, set_name, atr, *args) if v.present?
+            v = public_send(atr)
+            yield(v, atr, set_obj, set_name, *args) if v.present?
           end
         end
       end
     end
-
-    private
-
-    # Helper that collects virtual attributes that
-    # have setters and getters.
-    def __vatrf(no_presence_check = false)
-      tar = self.class.send(:__treat_as_real)
-      return tar if no_presence_check || tar.empty?
-      tar.select { |a| respond_to?(a) && respond_to?("#{a}=") }
-    end
-
   end # module AttributeFilters
 end # module ActiveModel