meta_search_hub 1.1.3

data/lib/meta_search/method.rb

@@ -0,0 +1,129 @@
+require 'meta_search/utility'
+
+module MetaSearch
+  # MetaSearch can be given access to any class method on your model to extend its search capabilities.
+  # The only rule is that the method must return an ActiveRecord::Relation so that MetaSearch can
+  # continue to extend the search with other attributes. Conveniently, scopes (formerly "named scopes")
+  # do this already.
+  #
+  # Consider the following model:
+  #
+  #   class Company < ActiveRecord::Base
+  #     has_many :slackers, :class_name => "Developer", :conditions => {:slacker => true}
+  #     scope :backwards_name, lambda {|name| where(:name => name.reverse)}
+  #     scope :with_slackers_by_name_and_salary_range,
+  #       lambda {|name, low, high|
+  #         joins(:slackers).where(:developers => {:name => name, :salary => low..high})
+  #       }
+  #   end
+  #
+  # To allow MetaSearch access to a model method, including a named scope, just use
+  # <tt>search_methods</tt> in the model:
+  #
+  #   search_methods :backwards_name
+  #
+  # This will allow you to add a text field named :backwards_name to your search form, and
+  # it will behave as you might expect.
+  #
+  # In the case of the second scope, we have multiple parameters to pass in, of different
+  # types. We can pass the following to <tt>search_methods</tt>:
+  #
+  #   search_methods :with_slackers_by_name_and_salary_range,
+  #     :splat_param => true, :type => [:string, :integer, :integer]
+  #
+  # MetaSearch needs us to tell it that we don't want to keep the array supplied to it as-is, but
+  # "splat" it when passing it to the model method. And in this case, ActiveRecord would have been
+  # smart enough to handle the typecasting for us, but I wanted to demonstrate how we can tell
+  # MetaSearch that a given parameter is of a specific database "column type." This is just a hint
+  # MetaSearch uses in the same way it does when casting "Where" params based on the DB column
+  # being searched. It's also important so that things like dates get handled properly by FormBuilder.
+  #
+  # _NOTE_: If you do supply an array, rather than a single type value, to <tt>:type</tt>, MetaSearch
+  # will enforce that any array supplied for input by your forms has the correct number of elements
+  # for your eventual method.
+  #
+  # Besides <tt>:splat_param</tt> and <tt>:type</tt>, search_methods accept the same <tt>:formatter</tt>
+  # and <tt>:validator</tt> options that you would use when adding a new MetaSearch::Where:
+  #
+  # <tt>formatter</tt> is the Proc that will do any formatting to the variable passed to your method.
+  # The default proc is <tt>{|param| param}</tt>, which doesn't really do anything. If you pass a
+  # string, it will be +eval+ed in the context of this Proc.
+  #
+  # If your method will do a LIKE search against its parameter, you might want to pass:
+  #
+  #   :formatter => '"%#{param}%"'
+  #
+  # Be sure to single-quote the string, so that variables aren't interpolated until later. If in doubt,
+  # just use a Proc, like so:
+  #
+  #   :formatter => Proc.new {|param| "%#{param}%"}
+  #
+  # <tt>validator</tt> is the Proc that will be used to check whether a parameter supplied to the
+  # method is valid. If it is not valid, it won't be used in the query. The default is
+  # <tt>{|param| !param.blank?}</tt>, so that empty parameters aren't added to the search, but you
+  # can get more complex if you desire. Validations are run after typecasting, so you can check
+  # the class of your parameters, for instance.
+  class Method
+    include Utility
+
+    attr_reader :name, :formatter, :validator, :type
+
+    def initialize(name, opts ={})
+      raise ArgumentError, "Name parameter required" if name.blank?
+      @name = name
+      @type = opts[:type] || :string
+      @splat_param = opts[:splat_param] || false
+      @formatter = opts[:formatter] || Proc.new {|param| param}
+      if @formatter.is_a?(String)
+        formatter = @formatter
+        @formatter = Proc.new {|param| eval formatter}
+      end
+      unless @formatter.respond_to?(:call)
+        raise ArgumentError, "Invalid formatter for #{name}, should be a Proc or String."
+      end
+      @validator = opts[:validator] || Proc.new {|param| !param.blank?}
+      unless @validator.respond_to?(:call)
+        raise ArgumentError, "Invalid validator for #{name}, should be a Proc."
+      end
+    end
+
+    # Cast the parameter to the type specified in the Method's <tt>type</tt>
+    def cast_param(param)
+      if type.is_a?(Array)
+        unless param.is_a?(Array) && param.size == type.size
+          num_params = param.is_a?(Array) ? param.size : 1
+          raise ArgumentError, "Parameters supplied to #{name} could not be type cast -- #{num_params} values supplied, #{type.size} expected"
+        end
+        type.each_with_index do |t, i|
+          param[i] = cast_attributes(t, param[i])
+        end
+        param
+      else
+        cast_attributes(type, param)
+      end
+    end
+
+    # Evaluate the method in the context of the supplied relation and parameter
+    def evaluate(relation, param)
+      if splat_param?
+        relation.send(name, *format_param(param))
+      else
+        relation.send(name, format_param(param))
+      end
+    end
+
+    def splat_param?
+      !!@splat_param
+    end
+
+    # Format a parameter for searching using the Method's defined formatter.
+    def format_param(param)
+      formatter.call(param)
+    end
+
+    # Validate the parameter for use in a search using the Method's defined validator.
+    def validate(param)
+      validator.call(param)
+    end
+  end
+end

data/lib/meta_search/model_compatibility.rb

@@ -0,0 +1,75 @@
+require 'meta_search/utility'
+
+module MetaSearch
+
+  module ModelCompatibility
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    def persisted?
+      false
+    end
+
+    def to_key
+      nil
+    end
+
+    def to_param
+      nil
+    end
+
+    def to_model
+      self
+    end
+  end
+
+  class Name < String
+    attr_reader :singular, :plural, :element, :collection, :partial_path, :human, :param_key, :route_key, :i18n_key
+    alias_method :cache_key, :collection
+
+    def initialize
+      super("Search")
+      @singular = "search".freeze
+      @plural = "searches".freeze
+      @element = "search".freeze
+      @human = "Search".freeze
+      @collection = "meta_search/searches".freeze
+      @partial_path = "#{@collection}/#{@element}".freeze
+      @param_key = "search".freeze
+      @route_key = "searches".freeze
+      @i18n_key = :meta_search
+    end
+  end
+
+  module ClassMethods
+    include Utility
+
+    def model_name
+      @_model_name ||= Name.new
+    end
+
+    def human_attribute_name(attribute, options = {})
+      method_name = preferred_method_name(attribute)
+
+      defaults = [:"meta_search.attributes.#{klass.model_name.i18n_key}.#{method_name || attribute}"]
+
+      if method_name
+        predicate = Where.get(method_name)[:name]
+        predicate_attribute = method_name.sub(/_#{predicate}=?$/, '')
+        predicate_attributes = predicate_attribute.split(/_or_/).map { |att|
+          klass.human_attribute_name(att)
+        }.join(" #{I18n.translate(:"meta_search.or", :default => 'or')} ")
+        defaults << :"meta_search.predicates.#{predicate}"
+      end
+
+      defaults << options.delete(:default) if options[:default]
+      defaults << attribute.to_s.humanize
+
+      options.reverse_merge! :count => 1, :default => defaults, :attribute => predicate_attributes || klass.human_attribute_name(attribute)
+      I18n.translate(defaults.shift, options)
+    end
+  end
+
+end

data/lib/meta_search/searches/active_record.rb

@@ -0,0 +1,203 @@
+require 'active_support/concern'
+require 'meta_search/method'
+require 'meta_search/builder'
+
+module MetaSearch
+  module Searches
+
+    module ActiveRecord
+
+      def self.included(base)
+        base.extend ClassMethods
+
+        base.class_eval do
+          class_attribute :_metasearch_include_attributes, :_metasearch_exclude_attributes
+          class_attribute :_metasearch_include_associations, :_metasearch_exclude_associations
+          class_attribute :_metasearch_methods
+          self._metasearch_include_attributes =
+            self._metasearch_exclude_attributes =
+            self._metasearch_exclude_associations =
+            self._metasearch_include_associations = {}
+          self._metasearch_methods = {}
+        end
+      end
+
+      module ClassMethods
+        # Prepares the search to run against your model. Returns an instance of
+        # MetaSearch::Builder, which behaves pretty much like an ActiveRecord::Relation,
+        # in that it doesn't actually query the database until you do something that
+        # requires it to do so.
+        #
+        # Options:
+        #
+        # * +params+ - a hash of valid searches with keys that are valid according to
+        #   the docs in MetaSearch::Where.
+        # * +opts+ - A hash of additional information that will be passed through to
+        #   the search's Builder object. +search_key+, if present, will override the
+        #   default param name, 'search', in any sort_links generated by this Builder.
+        #   All other keys are passed untouched to the builder, and available from the
+        #   Builder's +options+ reader for use in :if blocks supplied to attr_searchable
+        #   and friends.
+        def metasearch(params = nil, opts = nil)
+          builder = Searches.for(self).new(self, opts || {})
+          builder.build(params || {})
+        end
+
+        alias_method :search, :metasearch unless respond_to?(:search)
+
+        def _metasearch_method_authorized?(name, metasearch_object)
+          name = name.to_s
+          meth = self._metasearch_methods[name]
+          meth && (meth[:if] ? meth[:if].call(metasearch_object) : true)
+        end
+
+        def _metasearch_attribute_authorized?(name, metasearch_object)
+          name = name.to_s
+          if self._metasearch_include_attributes.empty?
+            !_metasearch_excludes_attribute?(name, metasearch_object)
+          else
+            _metasearch_includes_attribute?(name, metasearch_object)
+          end
+        end
+
+        def _metasearch_association_authorized?(name, metasearch_object)
+          name = name.to_s
+          if self._metasearch_include_associations.empty?
+            !_metasearch_excludes_association?(name, metasearch_object)
+          else
+            _metasearch_includes_association?(name, metasearch_object)
+          end
+        end
+
+        private
+
+        # Excludes model attributes from searchability. This means that searches can't be created against
+        # these columns, whether the search is based on this model, or the model's attributes are being
+        # searched by association from another model. If a Comment <tt>belongs_to :article</tt> but declares
+        # <tt>attr_unsearchable :user_id</tt> then <tt>Comment.search</tt> won't accept parameters
+        # like <tt>:user_id_equals</tt>, nor will an Article.search accept the parameter
+        # <tt>:comments_user_id_equals</tt>.
+        def attr_unsearchable(*args)
+          if table_exists?
+            opts = args.extract_options!
+            args.flatten.each do |attr|
+              attr = attr.to_s
+              raise(ArgumentError, "No persisted attribute (column) named #{attr} in #{self}") unless self.columns_hash.has_key?(attr)
+              self._metasearch_exclude_attributes = self._metasearch_exclude_attributes.merge(
+                attr => {
+                  :if => opts[:if]
+                }
+              )
+            end
+          end
+        end
+
+        # Like <tt>attr_unsearchable</tt>, but operates as a whitelist rather than blacklist. If both
+        # <tt>attr_searchable</tt> and <tt>attr_unsearchable</tt> are present, the latter
+        # is ignored.
+        def attr_searchable(*args)
+          if table_exists?
+            opts = args.extract_options!
+            args.flatten.each do |attr|
+              attr = attr.to_s
+              raise(ArgumentError, "No persisted attribute (column) named #{attr} in #{self}") unless self.columns_hash.has_key?(attr)
+              self._metasearch_include_attributes = self._metasearch_include_attributes.merge(
+                attr => {
+                  :if => opts[:if]
+                }
+              )
+            end
+          end
+        end
+
+        # Excludes model associations from searchability. This mean that searches can't be created against
+        # these associations. An article that <tt>has_many :comments</tt> but excludes comments from
+        # searching by declaring <tt>assoc_unsearchable :comments</tt> won't make any of the
+        # <tt>comments_*</tt> methods available.
+        def assoc_unsearchable(*args)
+          opts = args.extract_options!
+          args.flatten.each do |assoc|
+            assoc = assoc.to_s
+            raise(ArgumentError, "No such association #{assoc} in #{self}") unless self.reflect_on_all_associations.map {|a| a.name.to_s}.include?(assoc)
+            self._metasearch_exclude_associations = self._metasearch_exclude_associations.merge(
+              assoc => {
+                :if => opts[:if]
+              }
+            )
+          end
+        end
+
+        # As with <tt>attr_searchable</tt> this is the whitelist version of
+        # <tt>assoc_unsearchable</tt>
+        def assoc_searchable(*args)
+          opts = args.extract_options!
+          args.flatten.each do |assoc|
+            assoc = assoc.to_s
+            raise(ArgumentError, "No such association #{assoc} in #{self}") unless self.reflect_on_all_associations.map {|a| a.name.to_s}.include?(assoc)
+            self._metasearch_include_associations = self._metasearch_include_associations.merge(
+              assoc => {
+                :if => opts[:if]
+              }
+            )
+          end
+        end
+
+        def search_methods(*args)
+          opts = args.extract_options!
+          authorizer = opts.delete(:if)
+          args.flatten.map(&:to_s).each do |arg|
+            self._metasearch_methods = self._metasearch_methods.merge(
+              arg => {
+                :method => MetaSearch::Method.new(arg, opts),
+                :if => authorizer
+              }
+            )
+          end
+        end
+
+        alias_method :search_method, :search_methods
+
+        def _metasearch_includes_attribute?(name, metasearch_object)
+          attr = self._metasearch_include_attributes[name]
+          attr && (attr[:if] ? attr[:if].call(metasearch_object) : true)
+        end
+
+        def _metasearch_excludes_attribute?(name, metasearch_object)
+          attr = self._metasearch_exclude_attributes[name]
+          attr && (attr[:if] ? attr[:if].call(metasearch_object) : true)
+        end
+
+        def _metasearch_includes_association?(name, metasearch_object)
+          assoc = self._metasearch_include_associations[name]
+          assoc && (assoc[:if] ? assoc[:if].call(metasearch_object) : true)
+        end
+
+        def _metasearch_excludes_association?(name, metasearch_object)
+          assoc = self._metasearch_exclude_associations[name]
+          assoc && (assoc[:if] ? assoc[:if].call(metasearch_object) : true)
+        end
+
+      end
+    end
+
+    def self.for(klass)
+      DISPATCH[klass.name]
+    end
+
+    private
+
+    DISPATCH = Hash.new do |hash, klass_name|
+      class_name = klass_name.gsub('::', '_')
+      hash[klass_name] = module_eval <<-RUBY_EVAL
+        class #{class_name} < MetaSearch::Builder
+          def self.klass
+            ::#{klass_name}
+          end
+        end
+
+        #{class_name}
+      RUBY_EVAL
+    end
+
+  end
+end

data/lib/meta_search/utility.rb

@@ -0,0 +1,110 @@
+require 'meta_search/exceptions'
+
+module MetaSearch
+  module Utility #:nodoc:
+
+    TRUE_VALUES = [true, 1, '1', 't', 'T', 'true', 'TRUE'].to_set
+    FALSE_VALUES = [false, 0, '0', 'f', 'F', 'false', 'FALSE'].to_set
+
+    private
+
+    def preferred_method_name(method_id)
+      method_name = method_id.to_s
+      where = Where.new(method_name) rescue nil
+      return nil unless where
+      where.aliases.each do |a|
+        break if method_name.sub!(/#{a}(=?)$/, "#{where.name}\\1")
+      end
+      method_name
+    end
+
+    def array_of_strings?(o)
+      o.is_a?(Array) && o.all?{|obj| obj.is_a?(String)}
+    end
+
+    def array_of_arrays?(vals)
+      vals.is_a?(Array) && vals.first.is_a?(Array)
+    end
+
+    def array_of_dates?(vals)
+      vals.is_a?(Array) && vals.first.respond_to?(:to_time)
+    end
+
+    def cast_attributes(type, vals)
+      if array_of_arrays?(vals)
+        vals.map! {|v| cast_attributes(type, v)}
+      # Need to make sure not to kill multiparam dates/times
+      elsif vals.is_a?(Array) && (array_of_dates?(vals) || !(DATES+TIMES).include?(type))
+        vals.map! {|v| cast_attribute(type, v)}
+      else
+        cast_attribute(type, vals)
+      end
+    end
+
+    def cast_attribute(type, val)
+      case type
+      when *STRINGS
+        val.respond_to?(:to_s) ? val.to_s : String.new(val)
+      when *DATES
+        if val.respond_to?(:to_date)
+          val.to_date rescue nil
+        else
+          y, m, d = *[val].flatten
+          m ||= 1
+          d ||= 1
+          Date.new(y,m,d) rescue nil
+        end
+      when *TIMES
+        if val.is_a?(Array)
+          y, m, d, hh, mm, ss = *[val].flatten
+          Time.zone.local(y, m, d, hh, mm, ss) rescue nil
+        else
+          unless val.acts_like?(:time)
+            val = val.is_a?(String) ? Time.zone.parse(val) : val.to_time rescue val
+          end
+          val.in_time_zone rescue nil
+        end
+      when *BOOLEANS
+        if val.is_a?(String) && val.blank?
+          nil
+        else
+          TRUE_VALUES.include?(val)
+        end
+      when :integer
+        val.blank? ? nil : val.to_i
+      when :float
+        val.blank? ? nil : val.to_f
+      when :decimal
+        if val.blank?
+          nil
+        elsif val.class == BigDecimal
+          val
+        elsif val.respond_to?(:to_d)
+          val.to_d
+        else
+          val.to_s.to_d
+        end
+      else
+        raise TypeCastError, "Unable to cast columns of type #{type}"
+      end
+    end
+
+    def collapse_multiparameter_options(opts)
+      opts.keys.each do |k|
+        if k.include?("(")
+          real_attribute, position = k.split(/\(|\)/)
+          cast = %w(a s i).include?(position.last) ? position.last : nil
+          position = position.to_i - 1
+          value = opts.delete(k)
+          opts[real_attribute] ||= []
+          opts[real_attribute][position] = if cast
+            (value.blank? && cast == 'i') ? nil : value.send("to_#{cast}")
+          else
+            value
+          end
+        end
+      end
+      opts
+    end
+  end
+end