attribute-filters 1.4.0 → 2.0.0

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

@@ -44,6 +44,7 @@ module ActiveModel
             end
           end
         end
+        filtering_method :join_attributes, :should_be_joined
 
         # This submodule contains class methods needed to describe
         # attribute joining.
@@ -52,42 +53,48 @@ module ActiveModel
           # 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
+          # @param parameters [Hash] parameters hash
+          # @option parameters :separator [String] separator passed to +join+ method call
+          # @option parameters :join_separator [String] separator passed to +join+ method call (alternative name)
+          # @option parameters :with [String] separator passed to +join+ method call (alternative name)
+          # @option parameters :from [String,Array<String>] names of source attributes used to join
+          # @option parameters :join_from [String,Array<String>] names of source attributes used to join (alternative name)
+          # @option parameters :source [String,Array<String>] names of source attributes used to join (alternative name)
+          # @option parameters :sources [String,Array<String>] names of source attributes used to join (alternative name)
+          # @option parameters :compact [Boolean] flag that causes sources to be compacted before joining
+          # @option parameters :join_compact [Boolean] flag that causes sources to be compacted before joining (alternative name)
           # @return [void]
-          def join_attribute(atr_name, parameters = nil)
+          def join_attributes(atr_name, parameters = nil)
             atr_name.is_a?(Hash) and return atr_name.each_pair { |k, v| join_attribute(k, v) }
+            # process reversed notation
+            p = parameters
             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)
+              if p.is_a?(Hash)
+                p = p.dup
+                dst = [:into, :in, :destination, :join_into].find { |k| p.key?(k) }
+                dst.nil? and raise ArgumentError, "you must specify destination attribute using :into => 'attribute_name'"
+                p[:from] = atr_name
+                return join_attribute(p.delete(dst), p)
+              else
+                return join_attribute(p, atr_name)
               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)
+            # setup attribute set
+            setup_attributes_that :should_be_joined, { atr_name => p },
+              {
+                :join_separator   => [ :with, :separator, :join_separator ],
+                :join_from        => [ :from, :source, :sources, :join_from ],
+                :join_compact     => [ :compact, :join_compact ]
+              }, :join_from
           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
+          alias_method :join_attribute,         :join_attributes
+          alias_method :joint_attribute,        :join_attributes
+          alias_method :joint_attributes,       :join_attributes
+          alias_method :join_attributes_to,     :join_attributes
+          alias_method :join_attributes_into,   :join_attributes
+          alias_method :joins_attribute,        :join_attributes
+          alias_method :joins_attributes_to,    :join_attributes
+          alias_method :joins_attributes_into,  :join_attributes
         end # module ClassMethods
       end # module Join
 

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

@@ -0,0 +1,105 @@
+# 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::Order 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
+
+      # This module contains attribute filters responsible for manipulating order of attribute values.
+      module Order
+        extend CommonFilter
+        # Inverses order of attribute contents.
+        # 
+        # The attrubutes are taken from the attribute set
+        # called +should_be_reversed+.
+        # 
+        # @note If a value of currently processed attribute is an array
+        #  then any element of the array is changed. The same with hash (its values are changed).
+        # 
+        # @return [void]
+        def reverse_attributes
+          filter_attrs_from_set(:should_be_reversed) do |atr_val, atr_name, set_obj|
+            if set_obj.annotation(atr_name, :reverse_enumerable)
+              atr_val.respond_to?(:reverse) ? atr_val.reverse : atr_val
+            else
+              AFHelpers.each_element(atr_val) do |v|
+                v.respond_to?(:reverse) ? v.reverse : v
+              end
+            end
+          end
+        end
+        filtering_method :reverse_attributes, :should_be_reversed
+
+        # This submodule contains class methods used to easily define filter.
+        module ClassMethods
+          # Registers attributes that should be filled with some values.
+          def reverse_attributes(*args)
+            setup_attributes_that :should_be_reversed, args,
+              :reverse_enumerable => [:enum, :enums, :whole_enums, :reverse_enums, :reverse_enumerable]
+          end
+          alias_method :reverse_attribute,    :reverse_attributes
+          alias_method :reverses_attribute,   :reverse_attributes
+          alias_method :reverses_attributes,  :reverse_attributes
+        end # module ClassMethods
+      end # module Order
+
+      # Randomizes order of attribute contents.
+      # 
+      # The attrubutes are taken from the attribute set
+      # called +should_be_shuffled+.
+      # 
+      # @note If a value of currently processed attribute is an array
+      #  then any element of the array is changed. The same with hash (its values are changed).
+      # 
+      # @return [void]
+      def shuffle_attributes
+        filter_attrs_from_set(:should_be_shuffled) do |atr_val, atr_name, set_obj|
+          shuffle_enum, rng = set_obj.annotation(atr_name, :shuffle_enumerable, :shuffle_generator)
+          rng = { :random => rng }
+          if shuffle_enum
+            if atr_val.is_a?(String)
+              atr_val.mb_chars.split("").shuffle(rng).join
+            else
+              atr_val.respond_to?(:shuffle) ? atr_val.shuffle(rng) : atr_val
+            end
+          else
+            AFHelpers.each_element(atr_val) do |v|
+              if v.is_a?(String)
+                v.mb_chars.split("").shuffle(rng).join
+              else
+                v.respond_to?(:shuffle) ? v.shuffle(rng) : v
+              end
+            end
+          end
+        end
+      end
+      filtering_method :shuffle_attributes, :should_be_shuffled
+
+      # This submodule contains class methods used to easily define filter.
+      module ClassMethods
+        # Registers attributes that should be shuffled.
+        def shuffle_attributes(*args)
+          setup_attributes_that :should_be_shuffled, args,
+            {
+              :shuffle_enumerable => [:enum, :enums, :whole_enums, :shuffle_enums, :shuffle_enumerable],
+              :shuffle_generator  => [:random_generator, :generator, :rnd, :rng, :shuffle_generator]
+            }, :shuffle_generator
+        end
+        alias_method :shuffle_attribute,    :shuffle_attributes
+        alias_method :shuffles_attribute,   :shuffle_attributes
+        alias_method :shuffles_attributes,  :shuffle_attributes
+      end # module ClassMethods
+
+      include Order
+
+    end # module Common
+  end # module AttributeFilters
+end # module ActiveModel

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

@@ -0,0 +1,90 @@
+# 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::Pick 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
+      # Picks attributes from leading and trailing spaces.
+      module Pick
+        extend CommonFilter
+        
+        def pick_attributes_core(val, from, to, range, step)
+          from  ||= 0
+          to    ||= val.size - 1
+          step  ||= 1
+          range ||= from..to
+          range.step(step).map { |n| val[n] }
+        end
+        private :pick_attributes_core
+
+        # Picks attributes from leading and trailing spaces.
+        # 
+        # The attrubutes to be picked are taken from the attribute set called
+        # +should_be_picked+. 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. The same with hash (its values are changed).
+        # 
+        # @return [void]
+        def pick_attributes
+          filter_attrs_from_set(:should_be_picked) do |atr_val, atr_name, set_obj|
+            pick_enum, step, from, to, range, sep, jnt = set_obj.annotation(atr_name, :pick_enumerable, :pick_step,
+                                                                                      :pick_from, :pick_to, :pick_range,
+                                                                                      :pick_separator, :pick_join)
+            if pick_enum
+              if atr_val.is_a?(String)
+                sep ||= ""
+                jnt ||= sep.is_a?(String) ? sep : nil
+                pick_attributes_core(atr_val.mb_chars.split(sep), from, to, range, step).join(jnt)
+              elsif atr_val.is_a?(Array)
+                pick_attributes_core(atr_val, from, to, range, step)
+              elsif atr_val.is_a?(Hash)
+                Hash[pick_attributes_core(atr_val.to_a, from, to, range, step)]
+              else
+                atr_val
+              end
+            else
+              sep ||= ""
+              jnt ||= sep.is_a?(String) ? sep : nil
+              AFHelpers.each_element(atr_val, String) do |v|
+                pick_attributes_core(v.mb_chars.split(sep), from, to, range, step).join(jnt)
+              end
+            end
+          end
+        end 
+        filtering_method :pick_attributes, :should_be_picked
+
+        # This submodule contains class methods used to easily define filter.
+        module ClassMethods
+          # Registers attributes that should be picked.
+          def pick_attributes(*args)
+            setup_attributes_that :should_be_picked, args,
+              {
+                :pick_enumerable  => [:enum, :enums, :whole_enums, :shuffle_enums, :pick_enumerable],
+                :pick_step        => [:step, :with_step, :each, :pick_step],
+                :pick_from        => [:from, :head, :take, :first, :pick_first, :pick_head, :pick_from],
+                :pick_to          => [:to, :tail, :last, :pick_last, :pick_tail, :pick_to],
+                :pick_range       => [:range, :pick_range],
+                :pick_separator   => [:separator, :regex, :split_with, :split_separator, :pick_separator],
+                :pick_join        => [:joiner, :join, :join_with, :pick_join]
+              }, :pick_separator
+          end
+          alias_method :pick_attribute,   :pick_attributes
+          alias_method :picks_attribute,  :pick_attributes
+          alias_method :picks_attributes, :pick_attributes
+        end # module ClassMethods
+      end # module Pick
+
+      include Pick
+
+    end # module Common
+  end # module AttributeFilters
+end # module ActiveModel

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

@@ -0,0 +1,70 @@
+# 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::Presence 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   
+
+      # This module contains attribute filters responsible for manipulating presence of attribute values.
+      module Presence
+        extend CommonFilter
+        # Presences-up attributes that are blank with +nil+ or the given values.
+        # 
+        # The attrubutes are taken from the attribute set
+        # called +should_be_filled+.
+        # 
+        # @note If a value of currently processed attribute is an array
+        #  then any element of the array is changed. The same with hash (its values are changed).
+        # 
+        # @return [void]
+        def fill_attributes
+          filter_attrs_from_set(:should_be_filled, :process_blank) do |atr_val, atr_name, set_obj|
+            if set_obj.annotation(atr_name, :fill_enumerable)
+              if atr_val.blank? || set_obj.annotation(atr_name, :fill_any)
+                set_obj.annotation(atr_name, :fill_value)
+              else
+                atr_val
+              end
+            else
+              AFHelpers.each_element(atr_val) do |v|
+                if v.blank? || set_obj.annotation(atr_name, :fill_any)
+                  set_obj.annotation(atr_name, :fill_value)
+                else
+                  v
+                end
+              end
+            end
+          end
+        end
+        filtering_method :fill_attributes, :should_be_filled
+
+        # This submodule contains class methods used to easily define filter.
+        module ClassMethods
+          # Registers attributes that should be filled with some values.
+          def fill_attributes(*args)
+            setup_attributes_that :should_be_filled, args,
+              {
+                :fill_value      => [:with, :fill_with, :fill, :value, :content, :default, :fill_value],
+                :fill_any        => [:all, :any, :fill_always, :always_fill, :always, :fill_present, :fill_all, :fill_any],
+                :fill_enumerable => [:replace_enumerable, :replace_enums, :enums, :whole_enums, :fill_enums, :fill_enumerable]
+              }, :fill_value
+          end
+          alias_method :fill_attribute,   :fill_attributes
+          alias_method :fills_attribute,  :fill_attributes
+          alias_method :fills_attributes, :fill_attributes
+        end # module ClassMethods
+      end # module Presence
+
+      include Presence
+
+    end # module Common
+  end # module AttributeFilters
+end # module ActiveModel

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

@@ -29,11 +29,11 @@ module ActiveModel
             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|
+              r = AFHelpers.each_element(atr_val, String) do |v|
                 v.mb_chars.split(pattern)
               end
             else
-              r = AttributeFiltersHelpers.each_element(atr_val, String) do |v|
+              r = AFHelpers.each_element(atr_val, String) do |v|
                 v.mb_chars.split(pattern, limit)
               end
             end
@@ -48,6 +48,7 @@ module ActiveModel
             end
           end
         end
+        filtering_method :split_attributes, :should_be_splitted
 
         # This submodule contains class methods needed to describe
         # attribute splitting.
@@ -97,29 +98,44 @@ module ActiveModel
           #   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]
+          # @param parameters [Hash] parameters hash
+          # @option parameters :pattern [String] pattern passed to +split+ method call
+          # @option parameters :split_pattern [String] pattern passed to +split+ method call (alternative name)
+          # @option parameters :with [String] pattern passed to +split+ method call (alternative name)
+          # @option parameters :limit [Fixnum] limit parameter passed to +split+ method call
+          # @option parameters :split_limit [Fixnum] limit parameter passed to +split+ method call (alternative name)
+          # @option parameters :into [String,Symbol,Array<String,Symbol>] names of attributes that results should be written to
+          # @option parameters :to [String,Symbol,Array<String,Symbol>] names of attributes that results should be written to (alternative name)
+          # @option parameters :split_into [String,Symbol,Array<String,Symbol>] names of attributes that results should be written to (alternative name)
+          # @option parameters :destination [String,Symbol,Array<String,Symbol>] names of attributes that results should be written to (alternative name)
+          # @option parameters :flatten [Boolean] flag that causes the resulting, intermediate array to be flattened
+          # @option parameters :split_flatten [Boolean] flag that causes the resulting, intermediate array to be flattened (alternative name)
+          # @return [nil]
+          def split_attributes(atr_name, parameters = nil)
+            if atr_name.is_a?(Hash)
+              atr_name.each_pair { |k, v| split_attribute(k, v) }
+              return nil
+            end
+            setup_attributes_that :should_be_splitted, { atr_name => parameters },
+              {
+                :split_pattern  => [ :with, :pattern, :split_pattern ],
+                :split_into     => [ :into, :to, :destination, :split_into ],
+                :split_limit    => [ :limit, :split_limit ],
+                :split_flatten  => [ :flatten, :split_flatten ]
+              }, :split_into
+            # write some defaults
+            limit, into = attribute_set(:should_be_splitted).get_annotations(atr_name, :split_limit, :split_into)
+            annotate_attribute_set(:should_be_splitted, atr_name, :split_limit, limit.to_i) unless limit.blank?
             if into.blank?
-              into = nil
+              annotate_attribute_set(:should_be_splitted, atr_name,:split_into, nil)
             elsif !into.is_a?(Array)
-              into = into.respond_to?(:to_a) ? into.to_a : [ into ]
+              annotate_attributes_that(:should_be_splitted, :split_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})
+            nil
           end
-          alias_method :split_attributes, :split_attribute
+          alias_method :split_attribute,    :split_attributes
+          alias_method :splits_attribute,   :split_attributes
+          alias_method :splits_attributes,  :split_attributes
         end # module ClassMethods
       end # module Split
 

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

@@ -22,23 +22,38 @@ module ActiveModel
         # 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.
+        #  then any element of the array is changed. The same with hash (its values are 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
+          filter_attrs_from_set(:should_be_squeezed) do |atr_val, atr_name, set_obj|
+            other_str = set_obj.annotation(atr_name, :squeeze_other_str)
+            if other_str.nil?
+              AFHelpers.each_element(atr_val, String) do |v|
+                v.mb_chars.squeeze.to_s
+              end
+            else
+              AFHelpers.each_element(atr_val, String) do |v|
+                v.mb_chars.squeeze(other_str).to_s
+              end
             end
           end
         end
+        filtering_method :squeeze_attributes, :should_be_squeezed
+
         # 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)
+            setup_attributes_that :should_be_squeezed, args,
+              {
+                :squeeze_other_str => [:squeeze_other_str, :other_str, :string, :with_string,
+                                       :with_characters, :with_character, :characters]
+              }, :squeeze_other_str
           end
-          alias_method :squeeze_attribute, :squeeze_attributes
+          alias_method :squeeze_attribute,    :squeeze_attributes
+          alias_method :squeezes_attribute,   :squeeze_attributes
+          alias_method :squeezes_attributes,  :squeeze_attributes
         end # module ClassMethods
 
         # Squeezes white characters in attributes, removes leading and trailing spaces and newlines.
@@ -48,23 +63,27 @@ module ActiveModel
         # 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.
+        #  then any element of the array is changed. The same with hash (its values are changed).
         # 
         # @return [void]
         def squish_attributes
           filter_attrs_from_set(:should_be_squished) do |atr|
-            AttributeFiltersHelpers.each_element(atr, String) do |v|
+            AFHelpers.each_element(atr, String) do |v|
               v.mb_chars.squish.to_s
             end
           end
         end
+        filtering_method :squish_attributes, :should_be_squished
+
         # 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
+          alias_method :squish_attribute,     :squish_attributes
+          alias_method :squishes_attribute,   :squish_attributes
+          alias_method :squishes_attributes,  :squish_attributes
         end # module ClassMethods
       end # module Squeeze