filter_matcher 0.0.1 → 0.1.0

data/README.md

@@ -36,43 +36,63 @@ First we need to specify how we want to filter our data to find the best match.
 
 Lets say the most important is the name. If name filter finds a single result then this is a match. We can define the filter like:
 
-    def name_filter(collection, name)
-      collection.select { |element| element[:name] == name }
+    m.filter do |col|
+      col.select { |element| element[:name] == name }
     end
 
-The filter has to be named in the convention: <what_it_filters>_filter
-
 If this is not sufficient we run another filter on the result of the previous one. Lets define another filter, saying that the second most important thing to find a match is age.
 
-    def age_filter(collection, age)
-      collection.select { |element| element[:age] == age}
+    m.filter do |col|
+      col.select { |element| element[:age] == age}
     end
 
 Simple and very similar to the previous one. Filters can have any logic you need. Lets define the last one - homepage filter.
 
-    def homepage_filter(collection, homepage)
-      collection.select { |element| element[:homepage] == homepage }
+    m.filter do |col|
+      col.select { |element| element[:homepage] == homepage }
     end
 
-Now, in order to run them all on the collection, we run the filter_and_match method:
+Now, in order to run them all on the collection, we run the matcher method:
 
     @input.each do |input|
       collection = @db
 
-      filter_and_match collection, {
-        :by_name => input[:name],
-        :by_age  => input[:age],
-        :by_homepage => input[:homepage]
-      }
+      matcher(collection) do |m|
+        m.filter do |col|
+          col.select { |element| element[:name] == input[:name] }
+        end
+
+        m.filter do |col|
+          col.select { |element| element[:age] == input[:age]}
+        end
+
+        m.filter do |col|
+          col.select { |element| element[:homepage] == input[:homepage] }
+        end
+
+        m.match do |element|
+          element[:matched] = true
+        end
+      end
     end
 
 If any filter returns an empty result then next filter is given the collection of the last not empty result or the original data itself.
+If a single result will be found the match block will be triggered. In this example we just change the entry's flag:
+
+    m.match do |element|
+      element[:matched] = true
+    end
 
-If a single result will be found the elemnt_matched method will be triggered. In this example we just change the entry's flag:
+The expected result is the db matched like:
 
-  def element_matched(element)
-    element[:matched] = true
-  end
+    db == [
+      {:id => 1, :name => "John",  :age => 33, :homepage => "www.johny.com",     :matched => false}
+      {:id => 2, :name => "Mike",  :age => 30, :homepage => "www.mikes.com",     :matched => false}
+      {:id => 3, :name => "Johny", :age => 25, :homepage => "www.johny.com",     :matched => false}
+      {:id => 4, :name => "Mike",  :age => 30, :homepage => "www.realmike.com",  :matched => true}
+      {:id => 5, :name => "Dan",   :age => 25, :homepage => "www.danny.com",     :matched => true}
+      {:id => 6, :name => "Dan",   :age => 40, :homepage => "www.fakedanny.com", :matched => false}
+    ]
 
 Full PeopleMatcher class example, that is responsible only for the matching is shown below:
 
@@ -85,38 +105,60 @@ Full PeopleMatcher class example, that is responsible only for the matching is s
         @db, @input = db, input
       end
 
+      #
+      # run filters on all data for every input element
+      #
       def match
         @input.each do |input|
           collection = @db
 
-          filter_and_match collection, {
-            :by_name => input[:name],
-            :by_age  => input[:age],
-            :by_homepage => input[:homepage]
-          }
+         matcher(collection) do |m|
+            m.filter do |col|
+              col.select { |element| element[:name] == input[:name] }
+            end
+
+            m.filter do |col|
+              col.select { |element| element[:age] == input[:age]}
+            end
+
+            m.filter do |col|
+              col.select { |element| element[:homepage] == input[:homepage] }
+            end
+
+            m.match do |element|
+              element[:matched] = true
+            end
+          end
         end
       end
+    end
 
-      private
+Visual example
+==
+Filtering a collection
 
-      def name_filter(collection, name)
-        collection.select { |element| element[:name] == name }
-      end
+    [1,2,3] --first_filter--> [2,3] ---second_filter--> [2] -> match
 
-      def age_filter(collection, age)
-        collection.select { |element| element[:age] == age}
-      end
+    [1,2,3] --first_filter--> [] --> [1,2,3] --second_filter--> [3] -> match
 
-      def homepage_filter(collection, homepage)
-        collection.select { |element| element[:homepage] == homepage }
-      end
+    [1,2,3] --first_filter--> [1,2] --second_filter--> [1,2] --third_filter--> [1] -> match
 
-      def element_matched(element)
-        element[:matched] = true
-      end
-    end
+    [1,2,3] --first_filter--> [] --> [1,2,3] --second_filter--> [] --> [1,2,3] --third_filter--> [] -> no match
+
+    [1,2,3] --first_filter--> [1,2,3] --second_filter--> [2,3] --third_filter--> [2,3] -> no match
+
+Filtering real data by SQL or JS
+==
+
+Remeber that often you can filter your data much more efficient with DB languages. This filtering method should be used when the filtering logic is highly application-dependent. Good SQL query (or smart map reduce) before application filter-matching is always a better approach.
 
 Feel free to contribute or give any feedback
 ==
 
 Did you find it usefull any how? Please let me know, and if you can want to improve it just send me a pull request.
+
+Contributors
+==
+
+[Albert Llop](https://github.com/mrsimo)
+[Sebastian Röbke](https://github.com/boosty)

data/lib/filter_matcher/filter_matcher.rb

@@ -1,23 +1,35 @@
 module FilterMatcher
+  class Filterer
+    def initialize(collection)
+      @collection = collection
+      @filters = []
+    end
+
+    def filter(&block)
+      @filters << block
+    end
+
+    def match(&block)
+      @match = block
+    end
 
-  #
-  # define filter in a class that uses this module
-  # named like:
-  #   - name_filter
-  #   - age_filter
-  #
-  # they should a filtered array
-  #
+    def process
+      @filters.each do |filter|
+        filtered = filter.call(@collection)
+        @collection = filtered.empty? ? @collection : filtered
 
-  def filter_and_match(collection, filters)
-    filters.each do |key, param|
-      method_name = key.to_s.tr('by_', '') + "_filter"
-      filtered = send(method_name.to_sym, collection, param)
-      collection = filtered.empty? ? collection : filtered
-      if collection.size == 1
-        element_matched(collection.first)
-        break
+        if @collection.size == 1
+          @match.call(@collection.first)
+          break
+        end
       end
     end
   end
+
+  def matcher(collection)
+    filterer = Filterer.new(collection)
+    yield filterer
+
+    filterer.process
+  end
 end

data/lib/filter_matcher/version.rb

@@ -1,3 +1,3 @@
 module FilterMatcher
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/test/people_matcher.rb

@@ -0,0 +1,49 @@
+#
+# example class that uses filter matcher module
+#
+# @db:
+# represents data from which machter tries to filter
+# a single result
+#
+# @input:
+# criteria for maching
+#
+
+require 'filter_matcher'
+
+class PeopleMatcher
+  include FilterMatcher
+
+  attr_reader :db
+
+  def initialize(db, input)
+    @db, @input = db, input
+  end
+
+  #
+  # run filters on all data for every input element
+  #
+  def match
+    @input.each do |input|
+      collection = @db
+
+     matcher(collection) do |m|
+        m.filter do |col|
+          col.select { |element| element[:name] == input[:name] }
+        end
+
+        m.filter do |col|
+          col.select { |element| element[:age] == input[:age]}
+        end
+
+        m.filter do |col|
+          col.select { |element| element[:homepage] == input[:homepage] }
+        end
+
+        m.match do |element|
+          element[:matched] = true
+        end
+      end
+    end
+  end
+end

data/test/people_matcher_test.rb

@@ -1,6 +1,6 @@
 require 'bundler/setup'
 require 'test/unit'
-require 'filter_matcher/people_matcher'
+require File.expand_path(File.dirname(__FILE__) + '/people_matcher')
 
 class PeopleMatcherTest < Test::Unit::TestCase
   def setup

metadata

@@ -2,7 +2,7 @@
 name: filter_matcher
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors: 
 - Jakub Godawa
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-16 00:00:00 +02:00
+date: 2011-07-19 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -35,8 +35,8 @@ files:
 - filter_matcher.gemspec
 - lib/filter_matcher.rb
 - lib/filter_matcher/filter_matcher.rb
-- lib/filter_matcher/people_matcher.rb
 - lib/filter_matcher/version.rb
+- test/people_matcher.rb
 - test/people_matcher_test.rb
 has_rdoc: true
 homepage: http://github.com/vysogot/filter_matcher
@@ -67,4 +67,5 @@ signing_key:
 specification_version: 3
 summary: FilterMatcher makes it easy to find a match in a collection
 test_files: 
+- test/people_matcher.rb
 - test/people_matcher_test.rb

data/lib/filter_matcher/people_matcher.rb

@@ -1,71 +0,0 @@
-#
-# example class that uses filter matcher module
-#
-# @db:
-# represents data from which machter tries to filter
-# a single result
-#
-# @input:
-# criteria for maching
-#
-
-require 'filter_matcher'
-
-class PeopleMatcher
-  include FilterMatcher
-
-  attr_reader :db
-
-  def initialize(db, input)
-    @db, @input = db, input
-  end
-
-  #
-  # run filters on all data for every input element
-  #
-  def match
-    @input.each do |input|
-      collection = @db
-
-      #
-      # filters are run sequentially until they find
-      # a single result
-      #
-      # they are called by the following convention:
-      # :by_<what_it_filters => paramters of <what_it_filters>_filter method
-      #
-      # when one of the filters reveal a single result
-      # next filters are not run for current input
-      #
-      filter_and_match collection, {
-        :by_name => input[:name],
-        :by_age  => input[:age],
-        :by_homepage => input[:homepage]
-      }
-    end
-  end
-
-  private
-
-  #
-  # filters are named by the following convention:
-  # <what_it_filters>_filter
-  #
-  # every filter should return a filtered result
-  #
-  def name_filter(collection, name)
-    collection.select { |element| element[:name] == name }
-  end
-
-  def age_filter(collection, age)
-    collection.select { |element| element[:age] == age}
-  end
-
-  def homepage_filter(collection, homepage)
-    collection.select { |element| element[:homepage] == homepage }
-  end
-
-  def element_matched(element)
-    element[:matched] = true
-  end
-end