suggester 0.1.0

data/lib/suggester/handlers.rb

@@ -0,0 +1,15 @@
+# Defines the module for the basic handle namespace
+#
+# Author::      Jeff Ching
+# Copyright::   Copyright (c) 2010
+# License::     Distributes under the same terms as Ruby
+module Suggester
+  module Handlers
+  end
+end
+
+# require all the provided base handlers
+list = Dir.glob(File.expand_path(File.dirname(__FILE__) + "/handlers/*.rb")).sort
+list.each do |f|
+  require f
+end

data/lib/suggester/handlers/active_record.rb

@@ -0,0 +1,51 @@
+require File.expand_path(File.dirname(__FILE__) + '/base')
+
+module Suggester
+  module Handlers
+    class ActiveRecord < Base
+
+      def initialize(params = {})
+        @klass      = params[:class]      || raise("must specify a class")
+        @klass = @klass.constantize if @klass.is_a?(String)
+        @id_field   = params[:id_field]   || :id
+        @name_field = params[:name_field] || :name
+        @conditions = params[:conditions] || {}
+        @include    = params[:include]   || {}
+        super(params)
+      end
+
+      protected
+
+      def all_records
+        @klass.find(:all, :include => @include, :conditions => @conditions)
+      end
+
+      def build_cache
+        cache = []
+        all_records.each do |entry|
+          cache << build_entry(entry)
+        end
+        cache.sort{|x,y| x[:search_term] <=> y[:search_term]}
+      end
+
+      def build_entry(record)
+        {
+          :search_term => search_term(record),
+          :data => entry_data(record)
+        }
+      end
+
+      def search_term(record)
+        record.send(@name_field).downcase
+      end
+
+      def entry_data(record)
+        {
+          @unique_field_name  =>  record.send(@name_field),
+          :id                 =>  record.send(@id_field),
+        }
+      end
+
+    end
+  end
+end

data/lib/suggester/handlers/base.rb

@@ -0,0 +1,107 @@
+# Base abstract class for the handlers.  Provides basic functionality allowing
+# the caches to be searched.  Provides basic functionality allowing the
+# cache to be refreshed.
+#
+# Author::    Jeff Ching
+# Copyright:: Copyright (c) 2010
+# License::   Distributes under the same terms as Ruby
+require 'suggester/handlers/helpers/refresh'
+
+module Suggester
+  module Handlers
+    class Base
+      # name of the field in the data hash that should be unique
+      attr_accessor :unique_field_name
+
+      include Suggester::Handlers::Helpers::Refresh
+      def initialize(params = {})
+        @unique_field_name = params[:unique_field_name] || :display_string
+        @refresh_interval = params.delete(:refresh_interval)
+        @last_refreshed_at = Time.now
+        @cache = build_cache
+      end
+
+      # Returns an array of hashes with the following format:
+      #   [
+      #     :search_term    =>  <string>,
+      #     :data           =>  {
+      #       <unique_field_name> =>  <anything>
+      #       ...other data to be returned
+      #     }
+      #   ]
+      # NOTE: must be sorted by :search_term
+      def cache
+        @cache
+      end
+
+      # Returns an array of data hashes that are an exact match for params[:query]
+      def match(params)
+        query = params[:query].downcase
+        limit = params[:limit]
+        limit = limit.to_i unless limit.nil?
+        results = find_exact_matches(query, limit, params)
+      end
+
+      # Returns an array of data hashes that begin with params[:query]
+      def find(params)
+        query = params[:query].downcase
+        limit = params[:limit]
+        limit = limit.to_i unless limit.nil?
+        results = find_begin_matches(query, limit, params)
+      end
+
+    protected
+
+      # Build a copy of the cache (needs to be specified by subclasses)
+      def build_cache
+        []
+      end
+
+      # do a binary search through the cache to find the lowest index
+      def find_lower_bound(string)
+        @cache.bsearch_lower_boundary {|x| x[:search_term] <=> string}
+      end
+
+      # returns an array of begins with matches as:
+      #   [ 
+      #     {
+      #       <unique_field_name> => <anything>
+      #       ...other data
+      #     }
+      #   ]
+      def find_begin_matches(search_string, limit, params)
+        results = []
+        lower_bound = find_lower_bound(search_string)
+
+        for i in lower_bound...@cache.length
+          # stop looking if we are no longer matching OR we have found enough matches
+          break if @cache[i][:search_term].index(search_string) != 0 || (limit && results.length >= limit)
+          results << @cache[i]
+        end
+
+        results.map{|r| r[:data]}
+      end
+
+      # returns an array of exact matches as:
+      #   [ 
+      #     {
+      #       <unique_field_name> => <anything>
+      #       ...other data
+      #     }
+      #   ]
+      def find_exact_matches(search_string, limit, params)
+        results = []
+        lower_bound = find_lower_bound(search_string)
+
+        for i in lower_bound...@cache.length
+          # stop looking if we are no longer matching OR we have found enough matches
+          break if @cache[i][:search_term] != search_string || (limit && results.length >= limit)
+          results << @cache[i]
+        end
+
+        results.map{|r| r[:data]}
+      end
+
+    end
+  end
+end

data/lib/suggester/handlers/helpers/normalization.rb

@@ -0,0 +1,3 @@
+module Suggester::Handlers::Helpers::Normalization
+
+end

data/lib/suggester/handlers/helpers/refresh.rb

@@ -0,0 +1,37 @@
+module Suggester
+  module Handlers
+    module Helpers
+      module Refresh
+
+        def refresh!
+          # assumption: assignment is atomic in ruby
+          @cache = build_cache
+          @last_refreshed_at = Time.now
+        end
+
+        def force_refresh!
+          @last_refreshed_at = nil
+        end
+
+        def needs_refresh?
+          return true if last_refreshed_at.nil?
+          refresh_interval && last_refreshed_at + refresh_interval.minutes < Time.now
+        end
+
+        def refresh_interval
+          @refresh_interval
+        end
+
+        def refresh_interval=(value)
+          @refresh_interval = value
+          @refresh_interval = @refresh_interval.to_i unless value.nil?
+        end
+
+        def last_refreshed_at
+          @last_refreshed_at
+        end
+
+      end
+    end
+  end
+end

data/lib/suggester/handlers/marshal.rb

@@ -0,0 +1,22 @@
+require File.expand_path(File.dirname(__FILE__) + '/base')
+
+module Suggester
+  module Handlers
+    class Marshal < Base
+
+      def initialize(params = {})
+        @file = params.delete(:file) || raise("must specify a file")
+        super(params)
+      end
+
+    protected
+
+      def build_cache()
+        io = open(@file)
+        cache = ::Marshal.load(io.read)
+        cache.sort{|x,y| x[:search_term] <=> y[:search_term]}
+      end
+
+    end
+  end
+end

data/lib/suggester/handlers/yaml.rb

@@ -0,0 +1,22 @@
+require File.expand_path(File.dirname(__FILE__) + '/base')
+
+module Suggester
+  module Handlers
+    class Yaml < Base
+      def initialize(params = {})
+        @file = params.delete(:file) || raise("must specify a file")
+        super(params)
+      end
+
+    protected
+
+      def build_cache()
+        io = open(@file)
+        cache = YAML::load(io.read)
+        cache.sort{|x,y| x[:search_term] <=> y[:search_term]}
+      end
+    end
+  end
+end
+
+

data/lib/suggester/server.rb

@@ -0,0 +1,130 @@
+# This is the core server for the Suggester gem.  It extends the basic sinatra server
+# and provides a basic interface to browse and query the server.
+#
+# The server supports output in HTML, YAML, JSON, and Marshal output
+#
+# Author::    Jeff Ching
+# Copyright:: Copyright(c) 2010
+# License::   Distribues under the same terms as Ruby
+require 'sinatra/base'
+require 'yaml'
+require 'json'
+require 'open-uri'
+require 'array_bsearch'
+require File.expand_path(File.join(File.dirname(__FILE__), 'handlers.rb'))
+
+module Suggester
+  # Core server class
+  class Server < Sinatra::Base
+
+    # Create an instance of the server. At this time, we spawn a separate thread
+    # that will reload handlers as needed to prevent locking the server thread.
+    def initialize(*args)
+      super(*args)
+      spawn_refresh_thread!
+    end
+
+    # list all handlers currently registered
+    get "/" do
+      output = "<html><body><h1>Suggester Handlers</h1>"
+      output << self.class.handlers.keys.sort.map{|n| "<a href='/#{n}/dump.html'>#{n} (#{self.class.handler(n).cache.size})</a>"}.join('<br/>')
+      output << "</body></html>"
+    end
+
+    # dump out the contents of the handler's cache
+    get "/:handler/dump.:format" do
+      format = params.delete("format")
+      handler = params.delete("handler")
+
+      data = self.class.handler(handler).cache
+      case(format)
+      when 'yml'
+        data.to_yaml
+      when 'json'
+        data.to_json
+      when 'marshal'
+        Marshal.dump(data)
+      when 'html'
+        output = "<html><body>"
+        output << data.map{|r| r.inspect}.join('<br/>')
+        output << "</body></html>"
+      else
+        "BAD FORMAT"
+      end
+    end
+
+    # find exact matches for the query string
+    get "/:handler/match/:query.:format" do
+      format = params.delete("format")
+      handler = params.delete("handler")
+      matches = self.class.handler(handler).match(params)
+      case(format)
+      when 'yml'
+        matches.to_yaml
+      when 'json'
+        matches.to_json
+      else
+        matches.inspect
+      end
+    end
+
+    # find matches that begin with the query string
+    get "/:handler/find/:query.:format" do
+      format = params.delete("format")
+      handler = params.delete("handler")
+      matches = self.class.handler(handler).find(params)
+      case(format)
+      when 'yml'
+        matches.to_yaml
+      when 'json'
+        matches.to_json
+      else
+        matches.inspect
+      end
+    end
+
+    # force a refresh of the specified handler
+    get "/:handler/refresh" do
+      handler = params.delete("handler")
+
+      if current_handler = self.class.handler(handler)
+        current_handler.force_refresh!
+        "OK"
+      else
+        "FAIL"
+      end
+    end
+
+    # Returns the hash of all handler names to their instances
+    def self.handlers
+      @handlers
+    end
+
+    # Returns the handler instance given the handler name
+    def self.handler(name)
+      @handlers ||= {}
+      @handlers[name]
+    end
+
+    # Register a handler instance to its handler name
+    def self.add_handler(name, handler)
+      @handlers ||= {}
+      @handlers[name] = handler
+    end
+
+    private
+
+    def spawn_refresh_thread! #:nodoc:
+      Thread.new do
+        loop do
+          sleep(10)
+          self.class.handlers.each do |name, handler|
+            handler.refresh! if handler.needs_refresh?
+          end
+        end
+      end
+    end
+
+  end
+end
+

data/suggester.gemspec

@@ -0,0 +1,92 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{suggester}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jeff Ching"]
+  s.date = %q{2010-12-09}
+  s.default_executable = %q{suggester_server}
+  s.description = %q{Extensible, cache-based auto-suggest server for ruby. Includes refresh and replication support out of the box.}
+  s.email = %q{ching.jeff@gmail.com}
+  s.executables = ["suggester_server"]
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    "Gemfile",
+    "Gemfile.lock",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "bin/suggester_server",
+    "config/database.yml.example",
+    "lib/array_bsearch.rb",
+    "lib/suggester.rb",
+    "lib/suggester/client.rb",
+    "lib/suggester/handlers.rb",
+    "lib/suggester/handlers/active_record.rb",
+    "lib/suggester/handlers/base.rb",
+    "lib/suggester/handlers/helpers/normalization.rb",
+    "lib/suggester/handlers/helpers/refresh.rb",
+    "lib/suggester/handlers/marshal.rb",
+    "lib/suggester/handlers/yaml.rb",
+    "lib/suggester/server.rb",
+    "pkg/suggester-0.0.1.gem",
+    "pkg/suggester-0.0.2.gem",
+    "suggester.gemspec",
+    "test/fixtures/books.sql",
+    "test/fixtures/marshal.marshal",
+    "test/fixtures/yaml.yml",
+    "test/functional/basic_test.rb",
+    "test/test_helper.rb",
+    "test/unit/active_record_handler_test.rb",
+    "test/unit/marshal_handler_test.rb",
+    "test/unit/yaml_handler_test.rb"
+  ]
+  s.homepage = %q{http://github.com/chingor13/suggester}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Extensible, cache-based auto-suggest server for ruby.}
+  s.test_files = [
+    "test/functional/basic_test.rb",
+    "test/test_helper.rb",
+    "test/unit/active_record_handler_test.rb",
+    "test/unit/marshal_handler_test.rb",
+    "test/unit/yaml_handler_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<sinatra>, [">= 0"])
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+      s.add_runtime_dependency(%q<vegas>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+    else
+      s.add_dependency(%q<sinatra>, [">= 0"])
+      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<vegas>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<sinatra>, [">= 0"])
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<vegas>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.1"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+  end
+end
+