fuzzy_set 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b8ca0bdbe55c19972e9df5c589d606a81b94270d
-  data.tar.gz: da1885c2d00aa8ba8043f72294cbad17e90bc8ec
+  metadata.gz: ea177c8ec92af90bff837cb332e1ed19878d448f
+  data.tar.gz: 15b67fc336b12cd46b9c5e109dadcc65655b7fcf
 SHA512:
-  metadata.gz: b0b987aa8cd7d0143424fe6d6fcff33f90dccf7a1c7fb60d5bb23c699fb1df229119f0e8de97405bb682cd0ecbc631beed51a19800460e67c0e8f4385f690ff0
-  data.tar.gz: 18a257eb888a1feffbfecb9065116b19add560c5354a598f75605f1660a132d861abe86fd69f6afc641b2341647cbb0e64a4128fb70de3bf6f65d28b11df6556
+  metadata.gz: 4efd199d4afc9caf35bb46099779fdc86096f17cd1a7c3f5dac4113f251c215672c57fc35a8fb1aabe3efb19a078758ba8d79579006d0f9a84ac7a73efc43c43
+  data.tar.gz: 87e9d04d3043ec1842cbca56b097fef76ff17c8859552b4b133fc4ee38c12b9758178a5076445ed9e873f45f95fb48664447c4f71dddb89a7453dee3713c0fff

data/.rspec

@@ -1,2 +1,3 @@
 --color
 --require spec_helper
+--format doc

data/.rubocop.yml

@@ -0,0 +1,3 @@
+AllCops:
+  Exclude:
+    - lib/fuzzy_set/version.rb

data/README.md

@@ -1,8 +1,24 @@
 # FuzzySet
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/fuzzy_set`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Gem Version](https://badge.fury.io/rb/fuzzy_set.svg)](http://badge.fury.io/rb/fuzzy_set)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/fuzzy_set/frames)
+[![Build Status](https://travis-ci.org/mhutter/fuzzy_set.svg)](https://travis-ci.org/mhutter/fuzzy_set)
+[![Code Climate](https://codeclimate.com/github/mhutter/fuzzy_set/badges/gpa.svg)](https://codeclimate.com/github/mhutter/fuzzy_set)
+[![Test Coverage](https://codeclimate.com/github/mhutter/fuzzy_set/badges/coverage.svg)](https://codeclimate.com/github/mhutter/fuzzy_set/coverage)
 
-TODO: Delete this and the text above, and describe your gem
+
+FuzzySet represents a set which allows searching its entries by using [Approximate string matching](https://en.wikipedia.org/wiki/Approximate_string_matching).
+
+It allows you to create a fuzzy-search!
+
+## How does it work?
+
+When `add`ing an element to the Set, it first gets indexed. This is, on a very basic level, cutting it up into ngrams and building an index with each ngram pointing to the element.
+
+If you then query the set with `get`, the query itself is also sliced into ngrams. We then select all elements in the set which share at least one common ngram with the query. The results are then ordered by their [cosine string similarity](https://github.com/mhutter/string-similarity) to the query.
+
+**TODO**:
+See [Issues labeled #feature](https://github.com/mhutter/fuzzy_set/labels/feature)
 
 ## Installation
 
@@ -24,17 +40,46 @@ Or install it yourself as:
 
 ```ruby
 require 'fuzzy_set'
-
 states = open('states.txt').read.split(/\n/)
-fs = FuzzySet.new(*states)
 
+# Create a new set and add some elements:
+fs = FuzzySet.new
+fs.add 'Some'
+fs.add 'Words'
+fs.add "or", "even", "multiple", "words!"
+
+# Or provide your elements when creating the set:
+fs = FuzzySet.new(states)
+
+# Use #exact_match to find exact matches (= the normalized query
+# matches a normalized element in the set):
 fs.exact_match('michigan!') # => "Michigan"
 fs.exact_match('mischigen') # => nil
 
+# Use #get to get all approximate matches:
 fs.get('mischigen')
 # => ["Michigan", "Wisconsin", "Mississippi", "Minnesota", "Missouri"]
+
+# With the default settings, #get will always first try to get an
+# exact match (see above), and return if there is one:
+fs.get('mississippi') # => ["Mississippi"]
+
+# set `all_matches` to true, to do a full query, even if there is
+# an exact match:
+fs = FuzzySet.new(states, all_matches: true)
+fs.get('mississippi') # => ["Mississippi", "Missouri", "Michigan", "Minnesota"]
+
+# You can configure more stuff (see below)
+fs = FuzzySet.new(states, all_matches: true, ngram_size_min: 1)
 ```
 
+### Options
+
+- `:all_matches` - If `false` and there is an exact match for `#get`, return the match immediately. If `true`, do the ngram-query to get more possible matches.
+- `:ngram_size_max` - The maximum Ngram size to use (if there is no match using the max ngram size, try again with a smaller ngran size).
+- `:ngram_size_min` - The minimum Ngram size to use.
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/fuzzy_set.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Manuel Hutter']
   spec.email         = ['manuel@hutter.io']
 
-  spec.summary       = %q{FuzzySet allows you to fuzzy-search Strings!}
-  spec.description   = %q{FuzzySet allows you to fuzzy-search Strings!}
+  spec.summary       = %q{Set which allows you to fuzzy-search Strings}
+  spec.description   = %q{FuzzySet represents a set which allows searching its entries by using [Approximate string matching](https://en.wikipedia.org/wiki/Approximate_string_matching).}
   spec.homepage      = 'https://github.com/mhutter/fuzzy_set'
   spec.license       = 'MIT'
 

data/lib/fuzzy_set.rb

@@ -1,20 +1,35 @@
 require 'string/similarity'
 
 require 'fuzzy_set/version'
-require 'core_ext/string'
 
 # FuzzySet implements a fuzzy-searchable set of strings.
 #
 # As a set, it cannot contain duplicate elements.
 class FuzzySet
-  NGRAM_SIZE = 3
+  # default options for creating new instances
+  DEFAULT_OPTS = {
+    all_matches: false,
+    ngram_size_max: 3,
+    ngram_size_min: 2
+  }
+
+  # @param items [#each,#to_s] item(s) to add
+  # @param opts [Hash] options, see {DEFAULT_OPTS}
+  # @option opts [Boolean] :all_matches
+  #   return all matches, even if an exact match is found
+  # @option opts [Fixnum] :ngram_size_max upper limit for ngram sizes
+  # @option opts [Fixnum] :ngram_size_min lower limit for ngram sizes
+  def initialize(*items, **opts)
+    opts = DEFAULT_OPTS.merge(opts)
 
-  def initialize(*items)
     @items = []
     @denormalize = {}
     @index = {}
+    @all_matches = opts[:all_matches]
+    @ngram_size_max = opts[:ngram_size_max]
+    @ngram_size_min = opts[:ngram_size_min]
 
-    add(*items)
+    add(items)
   end
 
   # Normalizes +query+, and looks up an entry by its normalized value.
@@ -29,9 +44,10 @@ class FuzzySet
   #
   # Each item will be converted into a string and indexed upon adding.
   #
-  # @param items [#to_s] item(s) to add
+  # @param items [#each,#to_s] item(s) to add
   # @return [FuzzySet] +self+
   def add(*items)
+    items = [items].flatten
     items.each do |item|
       item = item.to_s
       return self if @items.include?(item)
@@ -53,13 +69,15 @@ class FuzzySet
   # 2. check for an exact match and return, if present
   # 3. find matches based on Ngrams
   # 4. sort matches by their cosine similarity to +query+
+  #
+  # @param query [String] search query
   def get(query)
     query = normalize(query)
 
     # check for exact match
-    return [@denormalize[query]] if @denormalize[query]
+    return [@denormalize[query]] if !@all_matches && @denormalize[query]
 
-    match_ids = query.ngram(NGRAM_SIZE).map { |ng| @index[ng] }
+    match_ids = matches_for(query)
     match_ids = match_ids.flatten.compact.uniq
     matches = match_ids.map { |id| @items[id] }
 
@@ -85,6 +103,14 @@ class FuzzySet
 
   private
 
+  def matches_for(query)
+    @ngram_size_max.downto(@ngram_size_min).each do |size|
+      match_ids = ngram(query, size).map { |ng| @index[ng] }
+      return match_ids if match_ids.any?
+    end
+    []
+  end
+
   # Normalize a string by removing all non-word characters
   # except spaces and then converting it to lowercase.
   def normalize(str)
@@ -98,9 +124,25 @@ class FuzzySet
     @items.index(item)
   end
 
+  # calculate Ngrams and add them to the items
   def calculate_grams_for(string, id)
-    string.ngram(NGRAM_SIZE).each do |gram|
-      @index[gram] = (@index[gram] || []).push(id)
+    @ngram_size_max.downto(@ngram_size_min).each do |size|
+      ngram(string, size).each do |gram|
+        @index[gram] = (@index[gram] || []).push(id)
+      end
+    end
+  end
+
+  # break apart the string into strings of length `n`
+  #
+  # @example
+  #     'foobar'.ngram(3)
+  #     # => ["-fo", "foo", "oob", "oba", "bar", "ar-"]
+  def ngram(str, n)
+    fail ArgumentError, "n must be >= 1, is #{n}" if n < 1
+    str = "-#{str}-" if n > 1
+    (str.length - n + 1).times.map do |i|
+      str.slice(i, n)
     end
   end
 end

data/lib/fuzzy_set/version.rb

@@ -1,3 +1,3 @@
 class FuzzySet
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fuzzy_set
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Manuel Hutter
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-04 00:00:00.000000000 Z
+date: 2015-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: string-similarity
@@ -94,7 +94,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: FuzzySet allows you to fuzzy-search Strings!
+description: FuzzySet represents a set which allows searching its entries by using
+  [Approximate string matching](https://en.wikipedia.org/wiki/Approximate_string_matching).
 email:
 - manuel@hutter.io
 executables: []
@@ -103,6 +104,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - Gemfile
 - Guardfile
@@ -112,7 +114,6 @@ files:
 - bin/console
 - bin/setup
 - fuzzy_set.gemspec
-- lib/core_ext/string.rb
 - lib/fuzzy_set.rb
 - lib/fuzzy_set/version.rb
 homepage: https://github.com/mhutter/fuzzy_set
@@ -138,6 +139,6 @@ rubyforge_project:
 rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
-summary: FuzzySet allows you to fuzzy-search Strings!
+summary: Set which allows you to fuzzy-search Strings
 test_files: []
 has_rdoc: 

data/lib/core_ext/string.rb

@@ -1,14 +0,0 @@
-class String
-  # break apart the string into strings of length `n`
-  #
-  # @example
-  #     'foobar'.ngram(3)
-  #     # => ["-fo", "foo", "oob", "oba", "bar", "ar-"]
-  def ngram(n)
-    fail ArgumentError, "n must be > 1, is #{n}" if n < 2
-    str = "-#{self}-"
-    (str.length - n + 1).times.map do |i|
-      str.slice(i, n)
-    end
-  end
-end