filter_matcher 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Jakub Godawa
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,122 @@
+filter_matcher - filter your collections
+===
+
+How to install?
+==
+
+    gem install filter_matcher
+
+What it does?
+==
+
+It filters a collection with defined filters. Launches the filters one by one on the collection until it finds a single result. When the result is found a final action is invoked.
+
+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:
+
+    def name_filter(collection, name)
+      collection.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}
+    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 }
+    end
+
+Now, in order to run them all on the collection, we run the filter_and_match method:
+
+    @input.each do |input|
+      collection = @db
+
+      filter_and_match collection, {
+        :by_name => input[:name],
+        :by_age  => input[:age],
+        :by_homepage => input[:homepage]
+      }
+    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 elemnt_matched method will be triggered. In this example we just change the entry's flag:
+
+  def element_matched(element)
+    element[:matched] = true
+  end
+
+Full PeopleMatcher class example, that is responsible only for the matching is shown below:
+
+    class PeopleMatcher
+      include FilterMatcher
+
+      attr_reader :db
+
+      def initialize(db, input)
+        @db, @input = db, input
+      end
+
+      def match
+        @input.each do |input|
+          collection = @db
+
+          filter_and_match collection, {
+            :by_name => input[:name],
+            :by_age  => input[:age],
+            :by_homepage => input[:homepage]
+          }
+        end
+      end
+
+      private
+
+      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
+
+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.

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/filter_matcher.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "filter_matcher/version"
+
+Gem::Specification.new do |s|
+  s.name        = "filter_matcher"
+  s.version     = FilterMatcher::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Jakub Godawa"]
+  s.email       = ["jakub.godawa@gmail.com"]
+  s.homepage    = "http://github.com/vysogot/filter_matcher"
+  s.summary     = %q{FilterMatcher makes it easy to find a match in a collection}
+  s.description = %q{FilterMatcher is helpful when it comes to find a single match in the collection
+  by a group of filters. Every filter is can be easly defined and chained with others. Filters narrow the
+  collection sequantially.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/filter_matcher/filter_matcher.rb

@@ -0,0 +1,23 @@
+module FilterMatcher
+
+  #
+  # define filter in a class that uses this module
+  # named like:
+  #   - name_filter
+  #   - age_filter
+  #
+  # they should a filtered array
+  #
+
+  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
+      end
+    end
+  end
+end

data/lib/filter_matcher/people_matcher.rb

@@ -0,0 +1,71 @@
+#
+# 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

data/lib/filter_matcher/version.rb

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

data/lib/filter_matcher.rb

@@ -0,0 +1 @@
+require 'filter_matcher/filter_matcher'

data/test/people_matcher_test.rb

@@ -0,0 +1,81 @@
+require 'bundler/setup'
+require 'test/unit'
+require 'filter_matcher/people_matcher'
+
+class PeopleMatcherTest < Test::Unit::TestCase
+  def setup
+    @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 }
+    ]
+  end
+
+  def test_filters_by_name
+    input = [
+      { :name => "John" },
+      { :name => "Johny" }
+    ]
+
+    assert_matched(input, [1, 3])
+  end
+
+  def test_filters_by_name_and_then_by_age
+    input = [
+      { :name => "Dan", :age => 40 }
+    ]
+
+    assert_matched(input, [6])
+  end
+
+  def test_filters_by_name_and_then_by_age_and_then_by_homepage
+    input = [
+      { :name => "Mike", :age => 30, :homepage => "www.realmike.com" },
+      { :name => "Dan", :homepage => "www.danny.com" }
+    ]
+
+    assert_matched(input, [4, 5])
+  end
+
+  def test_filters_by_age_and_then_by_homepage_name_not_given
+    input = [
+      { :age => 25, :homepage => "www.johny.com" }
+    ]
+
+    assert_matched(input, [3])
+  end
+
+  def test_doesnt_match_if_nothing_matched
+    input = [
+      { :name => "George" }
+    ]
+
+    assert_matched(input, [])
+  end
+
+  def test_doesnt_match_if_many_matched
+    input = [
+      { :name => "Mike", :age => 30 }
+    ]
+
+    assert_matched(input, [])
+  end
+
+  private
+
+  def assert_matched(input, matched)
+    matcher = PeopleMatcher.new(@db, input)
+    matcher.match
+
+    matcher.db.select {|x| matched.include?(x[:id]) }.each do |entry|
+      assert(entry[:matched], "Matched expected: #{entry.inspect}")
+    end
+
+    matcher.db.reject {|x| matched.include?(x[:id]) }.each do |entry|
+      assert(!entry[:matched], "Not matched expected: #{entry.inspect}")
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: filter_matcher
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Jakub Godawa
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-16 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: |-
+  FilterMatcher is helpful when it comes to find a single match in the collection
+    by a group of filters. Every filter is can be easly defined and chained with others. Filters narrow the
+    collection sequantially.
+email: 
+- jakub.godawa@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- 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_test.rb
+has_rdoc: true
+homepage: http://github.com/vysogot/filter_matcher
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: FilterMatcher makes it easy to find a match in a collection
+test_files: 
+- test/people_matcher_test.rb