filter_matcher 0.2.0 → 0.2.1

data/Gemfile

@@ -2,3 +2,4 @@ source "http://rubygems.org"
 
 # Specify your gem's dependencies in filter_matcher.gemspec
 gemspec
+gem 'rake'

data/README.md

@@ -1,142 +1,78 @@
-filter_matcher - filter your collections
-===
+# filter_matcher
 
-How to install?
-==
+filter your collection with ease
 
-    gem install filter_matcher
+## How to install?
 
-What it does?
-==
+    gem install filter_matcher
 
-It filters a collection with defined filters. Launches the filters one by one on the collection until it finds a result. When the result is found a final action is invoked.
+## What it does?
 
-Example
-==
+Invokes a method on filtered elements from a collection.
 
-This example describes SingleMatcher.
+## Example
 
 Lets say we have following data about people:
 
-    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 => false },
-      { :id => 5, :name => "Dan",   :age => 25, :homepage => "www.danny.com",     :matched => false },
-      { :id => 6, :name => "Dan",   :age => 40, :homepage => "www.fakedanny.com", :matched => false }
-    ]
-
-And we want to set the matched flag to true (or run any other more complicated action), only for the entries that match the input data. Lets say that input is:
-
-    input = [
-      { :name => "Mike", :age => 30, :homepage => "www.realmike.com" },
-      { :name => "Dan", :homepage => "www.danny.com" }
-    ]
-
-First we need to specify how we want to filter our data to find the best match. As the filters run sequentially the order matters.
-
-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:
-
+```ruby
+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 => false },
+  { :id => 5, :name => "Dan",   :age => 25, :homepage => "www.danny.com",     :matched => false },
+  { :id => 6, :name => "Dan",   :age => 40, :homepage => "www.fakedanny.com", :matched => false }
+]
+```
+
+And we want to match them with the following input:
+
+```ruby
+input = [
+  { :name => "Mike", :age => 30, :homepage => "www.realmike.com" },
+  { :name => "Dan", :homepage => "www.danny.com" }
+]
+```
+
+We specifiy filters in order of importance and the method to be invoked on matched element(s):
+
+```ruby
+input.each do |input|
+  matcher(db, :single) do |m|
     m.filter do |col|
-      col.select { |element| element[:name] == name }
+      col.select { |element| element[:name] == input[:name] }
     end
 
-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.
-
     m.filter do |col|
-      col.select { |element| element[:age] == age}
+      col.select { |element| element[:age] == input[:age]}
     end
 
-Simple and very similar to the previous one. Filters can have any logic you need. Lets define the last one - homepage filter.
-
     m.filter do |col|
-      col.select { |element| element[:homepage] == homepage }
+      col.select { |element| element[:homepage] == input[:homepage] }
     end
 
-Now, in order to run them all on the collection, we run the matcher method:
-
-    @input.each do |input|
-      collection = @db
-
-      matcher(collection, :single) 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
+  end
+end
+```
 
 The expected result is the db matched like:
 
-    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}
-    ]
+```ruby
+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 could look like that:
+## Visual examples
 
-    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
-
-Visual examples
-==
 Filtering a collection with SingleMatcher
 
     [1,2,3] --first_filter--> [2,3] ---second_filter--> [2] -> match
@@ -162,18 +98,52 @@ Filtering a collection with FirstFromTopMatcher
     [1,2,3] --first_filter--> [1,2,3] --second_filter--> [2,3] --third_filter--> [2,3] -> matches 2
 
 
-Filtering real data by SQL or JS
-==
+## Filtering class example
+
+Full PeopleMatcher class example, that is responsible only for the matching could look like that:
+
+```ruby
+class PeopleMatcher
+  include FilterMatcher
+
+  attr_reader :db
+
+  def initialize(db, input)
+    @db, @input = db, input
+  end
+
+  def match
+    @input.each do |input|
+      collection = @db
+
+     matcher(collection, :filter_type) do |m|
+        m.filter do |col|
+          # filtering code
+        end
+
+        m.filter do |col|
+          # filtering code
+        end
+
+        m.match do |element|
+          # match code
+        end
+      end
+    end
+  end
+end
+```
+
+## Usecases
 
-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.
+Matching JSON, csv or hash data. Helpful to apply any filter that cannot be applied on DB level.
 
-Feel free to contribute or give any feedback
-==
+## Contribution
 
-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.
+Did you find it usefull anyhow?
+Please let me know, and if you want to improve it just send me an email or pull request.
 
-Contributors
-==
+Contributors:
 
 [Albert Llop](https://github.com/mrsimo),
 [Sebastian Röbke](https://github.com/boosty)

data/Rakefile

@@ -1,2 +1,12 @@
 require 'bundler'
-Bundler::GemHelper.install_tasks
+#require 'bundler/gem_tasks'
+require 'rake'
+require 'rake/testtask'
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << '.'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end

data/lib/filter_matcher/filter_matcher.rb

@@ -12,7 +12,7 @@ module FilterMatcher
       end
 
       @collection = collection
-      @matcher = get_matcher(matcher_type)
+      @matcher = self.class.get_matcher(matcher_type)
     end
 
     def filter(&block)
@@ -29,62 +29,61 @@ module FilterMatcher
 
     private
 
-    def get_matcher(symbol)
+    def self.get_matcher(symbol)
       klass_name = symbol.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
       klass_name << "Matcher"
-      klass = Object.const_get(klass_name)
+      klass = self.const_get(klass_name)
       klass.new
     end
-  end
 
-  # matches only when filters can narrow collection to one element
-  class SingleMatcher
-    attr_accessor :filters
+    # matches only when filters can narrow collection to one element
+    class SingleMatcher
+      attr_accessor :filters
 
-    def initialize
-      @filters = []
-    end
+      def initialize
+        @filters = []
+      end
 
-    def run(collection, match)
-      @filters.each do |filter|
-        filtered = filter.call(collection)
-        collection = filtered.empty? ? collection : filtered
+      def run(collection, match)
+        @filters.each do |filter|
+          filtered = filter.call(collection)
+          collection = filtered.empty? ? collection : filtered
 
-        if collection.size == 1
-          match.call(collection.first)
-          break
+          if collection.size == 1
+            match.call(collection.first)
+            break
+          end
         end
       end
     end
-  end
 
-  # matches the result from the top of the filtered collection
-  # does not match only when filtered didn't filtered anything
-  class FirstFromTopMatcher
-    attr_accessor :filters
+    # matches the result from the top of the filtered collection
+    # does not match only when filtered didn't filtered anything
+    class FirstFromTopMatcher
+      attr_accessor :filters
 
-    def initialize
-      @filters = []
-    end
+      def initialize
+        @filters = []
+      end
 
-    def run(collection, match)
-      last_filter_index = @filters.size - 1
-      collection_init_size = collection.size
-      @filters.each_with_index do |filter, index|
-        filtered = filter.call(collection)
-        collection = filtered.empty? ? collection : filtered
+      def run(collection, match)
+        last_filter_index = @filters.size - 1
+        collection_init_size = collection.size
+        @filters.each_with_index do |filter, index|
+          filtered = filter.call(collection)
+          collection = filtered.empty? ? collection : filtered
 
-        if (collection.size == 1) ||
-          ((last_filter_index == index) && (collection_init_size != collection.size))
+          if (collection.size == 1) ||
+            ((last_filter_index == index) && (collection_init_size != collection.size))
 
-          match.call(collection.first)
-          break
+            match.call(collection.first)
+            break
+          end
         end
       end
     end
   end
 
-
   def matcher(collection, matcher_type)
     matcher = Matcher.new(collection, matcher_type)
     yield matcher

data/lib/filter_matcher/version.rb

@@ -1,3 +1,3 @@
 module FilterMatcher
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -2,7 +2,7 @@
 name: filter_matcher
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Jakub Godawa
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-21 00:00:00 +02:00
+date: 2011-08-11 00:00:00 +02:00
 default_executable: 
 dependencies: []