rsolr-ext 0.9.6.3

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2008-2009 Matt Mitchell
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.rdoc

@@ -0,0 +1,119 @@
+=RSolr::Ext
+A set of helper methods/modules to assist in building Solr queries and handling responses when using the RSolr library.
+
+==Related Resources & Projects
+* {RSolr}[http://github.com/mwmitchell/rsolr]
+
+==Requests
+To use the RSolr::Ext connection instead of the normal RSolr connection:
+  solr = RSolr::Ext.connect
+
+RSolr::Ext adds a #find and a #luke_admin method to the connection object.
+
+===#luke
+The #luke method returns a Hash/Mash result of a /admin/luke?numTerms=0 request:
+  luke_response = solr.luke
+  luke_response['index']
+  luke_response['fields']
+  luke_response['info']
+
+
+===#find
+The #find method listens for certain keys. All other keys are ignored, allowing the ability to mix-and-match special keys with normal Solr param keys. The recognized keys are describe below.
+
+
+:page - This maps to the Solr "start" param. The current "page" in the results set. RSolr::Ext handles the page-to-rows math for you.
+
+
+:per_page - This maps to the Solr "rows" param. How many "pages" in the result.
+
+
+:queries - This key maps to the Solr "q" param. Accepts a string, array or hash. When an array is used, each value is joined by a space. When a hash is used, the keys are used as Solr fields.
+
+* :queries => 'normal' BECOMES ?q=normal
+* :queries => ['one', 'two'] BECOMES ?q=one two
+* :queries => {:title=>'one'} BECOMES ?q=title:(one)
+* :queries => ['red', {:title=>'one'}] BECOMES ?q=red title:(one)
+
+
+:phrases - This value is mapped to the Solr "q" param. When this key is used, the value will become double-quoted, creating a Solr "phrase" based query.
+
+* :phrases => 'normal' BECOMES ?q="normal"
+* :phrases => ['one', 'two'] BECOMES ?q="one" "two"
+* :phrases => {:title=>'one'} BECOMES ?q=title:("one")
+* :phrases => ['red', {:title=>'one'}] BECOMES ?q="red" title:("one") 
+
+
+:filters - The :filters key maps to the Solr :fq param. This has the same behavior as the :queries key, except it's for the :fq param.
+
+* :filters => 'normal' BECOMES ?fq=normal
+* :filters => ['one', 'two'] BECOMES ?fq=one two
+* :filters => {:title=>'one'} BECOMES ?fq=title:(one)
+* :filters => ['red', {:title=>'one'}] BECOMES ?fq=red title:(one)
+ 
+
+:phrase_filters - The :phrase_filters key maps to the Solr :fq param. This has the same behavior as the :phrases key, except it's for the :fq param.
+
+* :phrase_filters => 'normal' BECOMES ?fq="normal"
+* :phrase_filters => ['one', 'two'] BECOMES ?fq="one" "two"
+* :phrase_filters => {:title=>'one'} BECOMES ?fq=title:("one")
+* :phrase_filters => ['red', {:title=>'one'}] BECOMES ?fq="red" title:("one")
+ 
+
+:facets - The :facets does a few different things. First, it sets the Solr param facet=true. It accepts a hash with a single key called :fields. This should be an array of field names to facet on.
+
+* :facets=>{:fields=>['cat', 'blah']} BECOMES ?facet=true&facet.field=cat&facet.field=blah
+
+
+
+==Request Example
+  solr = RSolr::Ext.connect
+  solr_params = {
+    :page=>2,
+    :per_page=>10,
+    :phrases=>{:name=>'This is a phrase'},
+    :filters=>['test', {:price=>(1..10)}],
+    :phrase_filters=>{:manu=>['Apple']},
+    :queries=>'ipod',
+    :facets=>{:fields=>['cat', 'blah']},
+    :echoParams => 'EXPLICIT'
+  }
+  response = rsolr.find solr_params
+
+==Responses
+RSolr::Ext decorates the normal output hash from RSolr and adds some helpful methods.
+  
+  solr = RSolr::Ext.connect
+  
+  response = solr.find :q=>'*:*'
+  
+  response.ok?
+  response.params
+  response.docs
+  response.docs.previous_page
+  response.docs.next_page
+  response.facets.each do |facet|
+    puts facet.name
+    facet.items.each do |item|
+      puts "#{facet.name}::#{item.value} (#{item.hits})"
+    end
+  end
+
+You can access values in the response hash using symbols or strings.
+
+===Documents/Pagination
+If you wanna paginate, just throw the collection into the WillPaginate view helper.
+  <%= will_paginate response.docs %>
+
+==The "Model" Module
+You can create your own <read-only> "models" using RSolr::Ext::Model
+  
+  class Book
+    include RSolr::Ext::Model
+    def self.find_by_author(author)
+        find(:fq=>'object_type:"book"', :rows=>10, :phrase_filters=>{:author=>author})
+    end
+  end
+  
+  all_books = Book.find('*:*')
+  hawk_books = Book.find_by_author('hawk')

data/lib/mash.rb

@@ -0,0 +1,143 @@
+# This class has dubious semantics and we only have it so that people can write
+# params[:key] instead of params['key'].
+class Mash < Hash
+
+  # @param constructor<Object>
+  #   The default value for the mash. Defaults to an empty hash.
+  #
+  # @details [Alternatives]
+  #   If constructor is a Hash, a new mash will be created based on the keys of
+  #   the hash and no default value will be set.
+  def initialize(constructor = {})
+    if constructor.is_a?(Hash) 
+      super() 
+      update(constructor) 
+    else 
+      super(constructor) 
+    end 
+  end
+
+  # @param key<Object> The default value for the mash. Defaults to nil.
+  #
+  # @details [Alternatives]
+  #   If key is a Symbol and it is a key in the mash, then the default value will
+  #   be set to the value matching the key.
+  def default(key = nil) 
+    if key.is_a?(Symbol) && include?(key = key.to_s) 
+      self[key] 
+    else 
+      super 
+    end 
+  end 
+ 
+  alias_method :regular_writer, :[]= unless method_defined?(:regular_writer) 
+  alias_method :regular_update, :update unless method_defined?(:regular_update)
+
+  # @param key<Object> The key to set.
+  # @param value<Object>
+  #   The value to set the key to.
+  #
+  # @see Mash#convert_key
+  # @see Mash#convert_value
+  def []=(key, value) 
+    regular_writer(convert_key(key), convert_value(value)) 
+  end
+
+  # @param other_hash<Hash>
+  #   A hash to update values in the mash with. The keys and the values will be
+  #   converted to Mash format.
+  #
+  # @return <Mash> The updated mash.
+  def update(other_hash) 
+    other_hash.each_pair { |key, value| regular_writer(convert_key(key), convert_value(value)) } 
+    self 
+  end 
+ 
+  alias_method :merge!, :update
+
+  # @param key<Object> The key to check for. This will be run through convert_key.
+  #
+  # @return <TrueClass, FalseClass> True if the key exists in the mash.
+  def key?(key) 
+    super(convert_key(key)) 
+  end 
+
+  # def include? def has_key? def member?
+  alias_method :include?, :key?
+  alias_method :has_key?, :key?
+  alias_method :member?, :key?
+
+  # @param key<Object> The key to fetch. This will be run through convert_key.
+  # @param *extras<Array> Default value.
+  #
+  # @return <Object> The value at key or the default value.
+  def fetch(key, *extras) 
+    super(convert_key(key), *extras) 
+  end
+
+  # @param *indices<Array>
+  #   The keys to retrieve values for. These will be run through +convert_key+.
+  #
+  # @return <Array> The values at each of the provided keys
+  def values_at(*indices) 
+    indices.collect {|key| self[convert_key(key)]} 
+  end
+
+  # @return <Mash> A duplicate of this mash.
+  def dup 
+    Mash.new(self) 
+  end
+
+  # @param hash<Hash> The hash to merge with the mash.
+  #
+  # @return <Mash> A new mash with the hash values merged in.
+  def merge(hash) 
+    self.dup.update(hash) 
+  end
+
+  # @param key<Object>
+  #   The key to delete from the mash.\
+  def delete(key) 
+    super(convert_key(key)) 
+  end
+
+  # Used to provide the same interface as Hash.
+  #
+  # @return <Mash> This mash unchanged.
+  def stringify_keys!; self end
+ 
+  # @return <Hash> The mash as a Hash with string keys.
+  def to_hash 
+    Hash.new(default).merge(self) 
+  end 
+ 
+  protected
+  # @param key<Object> The key to convert.
+  #
+  # @param <Object>
+  #   The converted key. If the key was a symbol, it will be converted to a
+  #   string.
+  #
+  # @api private
+  def convert_key(key) 
+    key.kind_of?(Symbol) ? key.to_s : key 
+  end
+
+  # @param value<Object> The value to convert.
+  #
+  # @return <Object>
+  #   The converted value. A Hash or an Array of hashes, will be converted to
+  #   their Mash equivalents.
+  #
+  # @api private
+  def convert_value(value) 
+    case value 
+    when Hash 
+      value.to_mash 
+    when Array 
+      value.collect { |e| convert_value(e) } 
+    else 
+      value 
+    end 
+  end
+end

data/lib/rsolr-ext/connection.rb

@@ -0,0 +1,41 @@
+module RSolr::Ext::Connection
+  
+  # TWO modes of arguments:
+  #
+  # <request-handler-path>, <solr-params-hash>
+  # OR
+  # <solr-params-hash>
+  #
+  # The default request-handler-path is /select
+  # 
+  # If a hash is used for solr params, all of the normal RSolr::Ext::Request
+  # mappings are available (everything else gets passed to solr).
+  # Returns a new RSolr::Ext::Response::Base object.
+  def find *args
+    # remove the handler arg - the first, if it is a string OR set default
+    path = args.first.is_a?(String) ? args.shift : '/select'
+    # remove the params - the first, if it is a Hash OR set default
+    params = args.first.kind_of?(Hash) ? args.shift : {}
+    # send path, map params and send the rest of the args along
+    response = self.request path, RSolr::Ext::Request.map(params), *args
+    RSolr::Ext::Response::Base.new(response)
+  end
+  
+  # TWO modes of arguments:
+  #
+  # <request-handler-path>, <solr-params-hash>
+  # OR
+  # <solr-params-hash>
+  #
+  # The default request-handler-path is /admin/luke
+  # The default params are numTerms=0
+  #
+  # Returns a new Mash object.
+  def luke *args
+    path = args.first.is_a?(String) ? args.shift : '/admin/luke'
+    params = args.pop || {}
+    params['numTerms'] ||= 0
+    self.request(path, params).to_mash
+  end
+  
+end

data/lib/rsolr-ext/doc.rb

@@ -0,0 +1,44 @@
+module RSolr::Ext::Doc
+  
+  # for easy access to the solr id (route helpers etc..)
+  def id
+    self['id']
+  end
+  
+  # Helper method to check if value/multi-values exist for a given key.
+  # The value can be a string, or a RegExp
+  # Multiple "values" can be given; only one needs to match.
+  # 
+  # Example:
+  # doc.has?(:location_facet)
+  # doc.has?(:location_facet, 'Clemons')
+  # doc.has?(:id, 'h009', /^u/i)
+  def has?(k, *values)
+    return if self[k].nil?
+    return true if self.key?(k) and values.empty?
+    target = self[k]
+    if target.is_a?(Array)
+      values.each do |val|
+        return target.any?{|tv| val.is_a?(Regexp) ? (tv =~ val) : (tv==val)}
+      end
+    else
+      return values.any? {|val| val.is_a?(Regexp) ? (target =~ val) : (target == val)}
+    end
+  end
+
+  # helper
+  # key is the name of the field
+  # opts is a hash with the following valid keys:
+  #  - :sep - a string used for joining multivalued field values
+  #  - :default - a value to return when the key doesn't exist
+  # if :sep is nil and the field is a multivalued field, the array is returned
+  def get key, opts={:sep=>', ', :default=>nil}
+    if self.key? key
+      val = self[key]
+      (val.is_a?(Array) and opts[:sep]) ? val.join(opts[:sep]) : val
+    else
+      opts[:default]
+    end
+  end
+
+end

data/lib/rsolr-ext/model.rb

@@ -0,0 +1,99 @@
+# include this module into a plain ruby class:
+# class Book
+#   include RSolr::Ext::Model
+#   connection = RSolr::Ext.connect
+#   default_params = {:phrase_filters=>'type:book'}
+# end
+# 
+# Then:
+# number_10 = Book.find_by_id(10)
+#
+module RSolr::Ext::Model
+
+  # Class level methods for altering object instances
+  module Callbacks
+    
+    # method that only accepts a block
+    # The block is executed when an object is created via #new -> SolrDoc.new
+    # The blocks scope is the instance of the object.
+    def after_initialize(&blk)
+      hooks << blk
+    end
+    
+    # Removes the current set of after_initialize blocks.
+    # You would use this if you wanted to open a class back up,
+    # but clear out the previously defined blocks.
+    def clear_after_initialize_blocks!
+      @hooks = []
+    end
+    
+    # creates the @hooks container ("hooks" are blocks or procs).
+    # returns an array
+    def hooks
+      @hooks ||= []
+    end
+    
+  end
+
+  #
+  # Findable is a module that gets mixed into the SolrDocument class object.
+  # These methods will be available through the class like: SolrDocument.find and SolrDocument.find_by_id
+  #
+  module Findable
+  
+    attr_accessor :connection, :default_params
+    
+    def connection
+      @connection ||= RSolr::Ext.connect
+    end
+    
+    # this method decorates the connection find method
+    # and then creates new instance of the class that uses this module.
+    def find(*args)
+      decorate_response_docs connection.find(*args)
+    end
+    
+    # this method decorates the connection find_by_id method
+    # and then creates new instance of the class that uses this module.
+    def find_by_id(id, solr_params={}, opts={})
+      decorate_response_docs connection.find_by_id(id, solr_params, opts)
+    end
+  
+    protected
+  
+    def decorate_response_docs response
+      response['response']['docs'].map!{|d| self.new d }
+      response
+    end
+  
+  end
+  
+  # Called by Ruby Module API
+  # extends this *class* object
+  def self.included(base)
+    base.extend Callbacks
+    base.extend Findable
+    base.send :include, RSolr::Ext::Doc
+  end
+  
+  # The original object passed in to the #new method
+  attr :_source
+  
+  # Constructor **for the class that is getting this module included**
+  # source_doc should be a hash or something similar
+  # calls each of after_initialize blocks
+  def initialize(source_doc={})
+    @_source = source_doc.to_mash
+    self.class.hooks.each do |h|
+      instance_eval &h
+    end
+  end
+  
+  # the wrapper method to the @_source object.
+  # If a method is missing, it gets sent to @_source
+  # with all of the original params and block
+  def method_missing(m, *args, &b)
+    @_source.send(m, *args, &b)
+  end
+  
+end

data/lib/rsolr-ext/request.rb

@@ -0,0 +1,101 @@
+module RSolr::Ext::Request
+  
+  module Params
+    
+    def map input
+      output = {}
+      if input[:per_page]
+        output[:rows] = input.delete :per_page
+      end
+      
+      if page = input.delete(:page)
+        raise ':per_page must be set when using :page' unless output[:rows]
+        page = page.to_s.to_i-1
+        page = page < 1 ? 0 : page
+        output[:start] = page * output[:rows]
+      end
+      
+      if queries = input.delete(:queries)
+        output[:q] = append_to_param output[:q], build_query(queries, false)
+      end
+      if phrases = input.delete(:phrases)
+        output[:q] = append_to_param output[:q], build_query(phrases, true)
+      end
+      if filters = input.delete(:filters)
+        output[:fq] = append_to_param output[:fq], build_query(filters), false
+      end
+      if phrase_filters = input.delete(:phrase_filters)
+        output[:fq] = append_to_param output[:fq], build_query(phrase_filters, true), false
+      end
+      if facets = input.delete(:facets)
+        output[:facet] = true
+        output['facet.field'] = append_to_param output['facet.field'], build_query(facets.values), false
+      end
+      output.merge input
+    end
+    
+  end
+  
+  module QueryHelpers
+    
+    # Wraps a string around double quotes
+    def quote(value)
+      %("#{value}")
+    end
+
+    # builds a solr range query from a Range object
+    def build_range(r)
+      "[#{r.min} TO #{r.max}]"
+    end
+
+    # builds a solr query fragment
+    # if "quote_string" is true, the values will be quoted.
+    # if "value" is a string/symbol, the #to_s method is called
+    # if the "value" is an array, each item in the array is 
+    # send to build_query (recursive)
+    # if the "value" is a Hash, a fielded query is built
+    # where the keys are used as the field names and
+    # the values are either processed as a Range or
+    # passed back into build_query (recursive)
+    def build_query(value, quote_string=false)
+      case value
+      when String,Symbol
+        quote_string ? quote(value.to_s) : value.to_s
+      when Array
+        value.collect do |v|
+          build_query(v, quote_string)
+        end.flatten
+      when Hash
+        return value.collect do |(k,v)|
+          if v.is_a?(Range)
+            "#{k}:#{build_range(v)}"
+          # If the value is an array, we want the same param, multiple times (not a query join)
+          elsif v.is_a?(Array)
+            v.collect do |vv|
+              "#{k}:#{build_query(vv, quote_string)}"
+            end
+          else
+            "#{k}:#{build_query(v, quote_string)}"
+          end
+        end.flatten
+      end
+    end
+
+    # creates an array where the "existing_value" param is first
+    # and the "new_value" is the last.
+    # All empty/nil items are removed.
+    # the return result is either the result of the
+    # array being joined on a space, or the array itself.
+    # "auto_join" should be true or false.
+    def append_to_param(existing_value, new_value, auto_join=true)
+      values = [existing_value, new_value]
+      values.delete_if{|v|v.nil?}
+      auto_join ? values.join(' ') : values.flatten
+    end
+    
+  end
+  
+  extend QueryHelpers
+  extend Params
+  
+end

data/lib/rsolr-ext/response/docs.rb

@@ -0,0 +1,56 @@
+module RSolr::Ext::Response::Docs
+  
+  module Pageable
+    
+    attr_accessor :start, :per_page, :total
+    
+    # Returns the current page calculated from 'rows' and 'start'
+    # WillPaginate hook
+    def current_page
+      return 1 if start < 1
+      per_page_normalized = per_page < 1 ? 1 : per_page
+      @current_page ||= (start / per_page_normalized).ceil + 1
+    end
+    
+    # Calcuates the total pages from 'numFound' and 'rows'
+    # WillPaginate hook
+    def total_pages
+      @total_pages ||= per_page > 0 ? (total / per_page.to_f).ceil : 1
+    end
+    
+    # returns the previous page number or 1
+    # WillPaginate hook
+    def previous_page
+      @previous_page ||= (current_page > 1) ? current_page - 1 : 1
+    end
+    
+    # returns the next page number or the last
+    # WillPaginate hook
+    def next_page
+      @next_page ||= (current_page == total_pages) ? total_pages : current_page+1
+    end
+    
+    def has_next?
+      current_page < total_pages
+    end
+    
+    def has_previous?
+      current_page > 1
+    end
+    
+  end
+  
+  def self.extended(base)
+    d = base['response']['docs']
+    d.each{|doc| doc.extend RSolr::Ext::Doc }
+    d.extend Pageable
+    d.per_page = base['responseHeader']['params']['rows'].to_s.to_i
+    d.start = base['response']['start'].to_s.to_i
+    d.total = base['response']['numFound'].to_s.to_i
+  end
+  
+  def docs
+    response['docs']
+  end
+  
+end

data/lib/rsolr-ext/response/facets.rb

@@ -0,0 +1,62 @@
+module RSolr::Ext::Response::Facets
+  
+  # represents a facet value; which is a field value and its hit count
+  FacetItem = Struct.new :value,:hits
+  
+  # represents a facet; which is a field and its values
+  FacetField = Struct.new :name, :items do
+    def items; @items ||= [] end
+  end
+  
+  # @response.facets.each do |facet|
+  #   facet.field
+  # end
+  # "caches" the result in the @facets instance var
+  def facets
+    # memoize!
+    @facets ||= (
+      all = facet_fields.collect do |(facet_field_name,values_and_hits_list)|
+        facet = FacetField.new(facet_field_name)
+        # the values_and_hits_list is an array where a value is immediately followed by it's hit count
+        # so we shift off an item (the value)
+        while value = values_and_hits_list.shift
+          # and then shift off the next to get the hit value
+          facet.items << FacetItem.new(value, values_and_hits_list.shift)
+          # repeat until there are no more pairs in the values_and_hits_list array
+        end
+        facet
+      end
+      #all.extend RSolr::Ext::Response::Docs::Pageable
+      #all.start = header['params']['facet.offset'].to_s.to_i
+      #all.per_page = header['params']['facet.limit'].to_s.to_i - 1
+      #all.total = -1
+      ## override the has_next? method -- when paging through facets,
+      ## it's not possible to know how many "pages" there are
+      #all.instance_eval "def has_next?; #{all.size == all.per_page+1} end"
+      all
+    )
+  end
+  
+  # pass in a facet field name and get back a Facet instance
+  def facet_by_field_name(name)
+    @facets_by_field_name ||= {}
+    @facets_by_field_name[name] ||= (
+      facets.detect{|facet|facet.name.to_s == name.to_s}
+    )
+  end
+  
+  def facet_counts
+    @facet_counts ||= self['facet_counts'] || {}
+  end
+
+  # Returns the hash of all the facet_fields (ie: {'instock_b' => ['true', 123, 'false', 20]}
+  def facet_fields
+    @facet_fields ||= facet_counts['facet_fields'] || {}
+  end
+
+  # Returns all of the facet queries
+  def facet_queries
+    @facet_queries ||= facet_counts['facet_queries'] || {}
+  end
+  
+end # end Facets

data/lib/rsolr-ext/response/spelling.rb

@@ -0,0 +1,65 @@
+# A mixin for making access to the spellcheck component data easy.
+#
+# response.spelling.words
+#
+module RSolr::Ext::Response::Spelling
+  
+  def spelling
+    @spelling ||= Base.new(self)
+  end
+  
+  class Base
+    
+    attr :response
+    
+    def initialize(response)
+      @response = response
+    end
+    
+    # returns an array of spelling suggestion for specific query words, 
+    # as provided in the solr response.  Only includes words with higher
+    # frequency of occurrence than word in original query.
+    # can't do a full query suggestion because we only get info for each word;  
+    # combination of words may not have results.
+    # Thanks to Naomi Dushay!
+    def words
+      @words ||= (
+        word_suggestions = []
+        spellcheck = self.response[:spellcheck]
+        if spellcheck && spellcheck[:suggestions]
+          suggestions = spellcheck[:suggestions]
+          unless suggestions.nil?
+            # suggestions is an array: 
+            #    (query term)
+            #    (hash of term info and term suggestion) 
+            #    ...
+            #    (query term)
+            #    (hash of term info and term suggestion) 
+            #    'correctlySpelled'
+            #    true/false
+            #    collation
+            #    (suggestion for collation)
+            i_stop = suggestions.index("correctlySpelled")
+            # step through array in 2s to get info for each term
+            0.step(i_stop-1, 2) do |i| 
+              term = suggestions[i]
+              term_info = suggestions[i+1]
+              # term_info is a hash:
+              #   numFound =>
+              #   startOffset =>
+              #   endOffset =>
+              #   origFreq =>
+              #   suggestion =>  { frequency =>, word => }
+              origFreq = term_info['origFreq']
+              suggFreq = term_info['suggestion']['frequency'] 
+              word_suggestions << term_info['suggestion']['word'] if suggFreq > origFreq
+            end
+          end
+        end
+        word_suggestions.uniq
+      )
+    end
+    
+  end
+  
+end

data/lib/rsolr-ext/response.rb

@@ -0,0 +1,51 @@
+module RSolr::Ext::Response
+  
+  autoload :Docs, 'rsolr-ext/response/docs'
+  autoload :Facets, 'rsolr-ext/response/facets'
+  autoload :Spelling, 'rsolr-ext/response/spelling'
+  
+  class Base < Mash
+    
+    attr :original_hash
+    
+    def initialize hash
+      super hash
+      @original_hash = hash
+      extend Response# if self['response']
+      extend Docs# if self['response'] and self['response']['docs']
+      extend Facets# if self['facet_counts']
+      extend Spelling# if self['spellcheck']
+    end
+    
+    def header
+      self['responseHeader']
+    end
+    
+    def params
+      header['params']
+    end
+    
+    def ok?
+      header['status'] == 0
+    end
+    
+    def method_missing *args, &blk
+      self.original_hash.send *args, &blk
+    end
+    
+  end
+  
+  module Response
+    
+    def response
+      self[:response]
+    end
+    
+    # short cut to response['numFound']
+    def total
+      response[:numFound]
+    end
+    
+  end
+  
+end

data/lib/rsolr-ext.rb

@@ -0,0 +1,42 @@
+# add this directory to the load path if it hasn't already been added
+
+lambda { |base|
+  $: << base unless $:.include?(base) || $:.include?(File.expand_path(base))
+}.call(File.dirname(__FILE__))
+
+require 'mash' unless defined?(Mash)
+
+unless Hash.respond_to?(:to_mash)
+  class Hash
+    def to_mash
+      Mash.new(self)
+    end
+  end
+end
+
+require 'rubygems'
+require 'rsolr'
+
+module RSolr
+  
+  module Ext
+    
+    VERSION = '0.9.5'
+    
+    autoload :Connection, 'rsolr-ext/connection.rb'
+    autoload :Doc, 'rsolr-ext/doc.rb'
+    autoload :Request, 'rsolr-ext/request.rb'
+    autoload :Response, 'rsolr-ext/response.rb'
+    autoload :Model, 'rsolr-ext/model.rb'
+    
+    # c = RSolr::Ext.connect
+    # c.find(:q=>'*:*').docs.size
+    def self.connect(*args)
+      connection = RSolr.connect(*args)
+      connection.extend RSolr::Ext::Connection
+      connection
+    end
+    
+  end
+  
+end

data/rsolr-ext.gemspec

@@ -0,0 +1,39 @@
+Gem::Specification.new do |s|
+  s.name = "rsolr-ext"
+  s.version = "0.9.6.3"
+  s.date = "2009-09-30"
+  
+  s.summary = "An extension lib for RSolr"
+  s.email = "goodieboy@gmail.com"
+  s.homepage = "http://github.com/mwmitchell/rsolr-ext"
+  s.description = "An extension lib for RSolr"
+  s.has_rdoc = true
+  s.authors = ["Matt Mitchell"]
+  s.files = [
+    "lib/mash.rb",
+    "lib/rsolr-ext/connection.rb",
+    "lib/rsolr-ext/doc.rb",
+    "lib/rsolr-ext/model.rb",
+    "lib/rsolr-ext/request.rb",
+    "lib/rsolr-ext/response/docs.rb",
+    "lib/rsolr-ext/response/facets.rb",
+    "lib/rsolr-ext/response/spelling.rb",
+    "lib/rsolr-ext/response.rb",
+    "lib/rsolr-ext.rb",
+    "LICENSE",
+    "README.rdoc",
+    "rsolr-ext.gemspec"
+	]
+	s.test_files = [
+	  'test/connection_test.rb',
+	  'test/request_test.rb',
+	  'test/response_test.rb',
+	  'test/test_unit_test_case.rb',
+	  'test/helper.rb'
+	]
+	
+	s.extra_rdoc_files = %w(LICENSE README.rdoc)
+	
+	s.add_dependency("mwmitchell-rsolr", [">= 0.9.6"])
+	
+end

data/test/connection_test.rb

@@ -0,0 +1,40 @@
+require 'test_unit_test_case'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'rsolr-ext')
+require 'helper'
+
+class RSolrExtConnectionTest < Test::Unit::TestCase
+  
+  test 'the #connect method' do
+    connection = RSolr::Ext.connect
+    assert connection.respond_to?(:find)
+  end
+  
+  test 'the #find method' do
+    connection = RSolr::Ext.connect
+    response = connection.find :q=>'*:*'
+    assert response.kind_of?(Mash)
+  end
+  
+  test 'the #find method with a custom request handler' do
+    connection = RSolr::Ext.connect
+    response = connection.find '/select', :q=>'*:*'
+    assert response.adapter_response[:path]=~/\/select/
+  end
+  
+  test 'the response' do
+    connection = RSolr::Ext.connect
+    response = connection.find :q=>'*:*'
+    assert response.respond_to?(:ok?)
+    assert response.ok?
+    assert_equal response.docs[0][:id], response.docs[0].id
+  end
+  
+  test 'the #luke method' do
+    info = RSolr::Ext.connect.luke
+    assert info.kind_of?(Mash)
+    assert info.key?('fields')
+    assert info.key?('index')
+    assert info.key?('info')
+  end
+  
+end

data/test/helper.rb

@@ -0,0 +1,3 @@
+def mock_query_response
+  %({'responseHeader'=>{'status'=>0,'QTime'=>5,'params'=>{'facet.limit'=>'10','wt'=>'ruby','rows'=>'11','facet'=>'true','facet.field'=>['manu','cat'],'echoParams'=>'EXPLICIT','q'=>'*:*','facet.sort'=>'true'}},'response'=>{'numFound'=>26,'start'=>0,'docs'=>[{'id'=>'SP2514N','inStock'=>true,'manu'=>'Samsung Electronics Co. Ltd.','name'=>'Samsung SpinPoint P120 SP2514N - hard drive - 250 GB - ATA-133','popularity'=>6,'price'=>92.0,'sku'=>'SP2514N','timestamp'=>'2009-03-20T14:42:49.795Z','cat'=>['electronics','hard drive'],'spell'=>['Samsung SpinPoint P120 SP2514N - hard drive - 250 GB - ATA-133'],'features'=>['7200RPM, 8MB cache, IDE Ultra ATA-133','NoiseGuard, SilentSeek technology, Fluid Dynamic Bearing (FDB) motor']},{'id'=>'6H500F0','inStock'=>true,'manu'=>'Maxtor Corp.','name'=>'Maxtor DiamondMax 11 - hard drive - 500 GB - SATA-300','popularity'=>6,'price'=>350.0,'sku'=>'6H500F0','timestamp'=>'2009-03-20T14:42:49.877Z','cat'=>['electronics','hard drive'],'spell'=>['Maxtor DiamondMax 11 - hard drive - 500 GB - SATA-300'],'features'=>['SATA 3.0Gb/s, NCQ','8.5ms seek','16MB cache']},{'id'=>'F8V7067-APL-KIT','inStock'=>false,'manu'=>'Belkin','name'=>'Belkin Mobile Power Cord for iPod w/ Dock','popularity'=>1,'price'=>19.95,'sku'=>'F8V7067-APL-KIT','timestamp'=>'2009-03-20T14:42:49.937Z','weight'=>4.0,'cat'=>['electronics','connector'],'spell'=>['Belkin Mobile Power Cord for iPod w/ Dock'],'features'=>['car power adapter, white']},{'id'=>'IW-02','inStock'=>false,'manu'=>'Belkin','name'=>'iPod & iPod Mini USB 2.0 Cable','popularity'=>1,'price'=>11.5,'sku'=>'IW-02','timestamp'=>'2009-03-20T14:42:49.944Z','weight'=>2.0,'cat'=>['electronics','connector'],'spell'=>['iPod & iPod Mini USB 2.0 Cable'],'features'=>['car power adapter for iPod, white']},{'id'=>'MA147LL/A','inStock'=>true,'includes'=>'earbud headphones, USB cable','manu'=>'Apple Computer Inc.','name'=>'Apple 60 GB iPod with Video Playback Black','popularity'=>10,'price'=>399.0,'sku'=>'MA147LL/A','timestamp'=>'2009-03-20T14:42:49.962Z','weight'=>5.5,'cat'=>['electronics','music'],'spell'=>['Apple 60 GB iPod with Video Playback Black'],'features'=>['iTunes, Podcasts, Audiobooks','Stores up to 15,000 songs, 25,000 photos, or 150 hours of video','2.5-inch, 320x240 color TFT LCD display with LED backlight','Up to 20 hours of battery life','Plays AAC, MP3, WAV, AIFF, Audible, Apple Lossless, H.264 video','Notes, Calendar, Phone book, Hold button, Date display, Photo wallet, Built-in games, JPEG photo playback, Upgradeable firmware, USB 2.0 compatibility, Playback speed control, Rechargeable capability, Battery level indication']},{'id'=>'TWINX2048-3200PRO','inStock'=>true,'manu'=>'Corsair Microsystems Inc.','name'=>'CORSAIR  XMS 2GB (2 x 1GB) 184-Pin DDR SDRAM Unbuffered DDR 400 (PC 3200) Dual Channel Kit System Memory - Retail','popularity'=>5,'price'=>185.0,'sku'=>'TWINX2048-3200PRO','timestamp'=>'2009-03-20T14:42:49.99Z','cat'=>['electronics','memory'],'spell'=>['CORSAIR  XMS 2GB (2 x 1GB) 184-Pin DDR SDRAM Unbuffered DDR 400 (PC 3200) Dual Channel Kit System Memory - Retail'],'features'=>['CAS latency 2,	2-3-3-6 timing, 2.75v, unbuffered, heat-spreader']},{'id'=>'VS1GB400C3','inStock'=>true,'manu'=>'Corsair Microsystems Inc.','name'=>'CORSAIR ValueSelect 1GB 184-Pin DDR SDRAM Unbuffered DDR 400 (PC 3200) System Memory - Retail','popularity'=>7,'price'=>74.99,'sku'=>'VS1GB400C3','timestamp'=>'2009-03-20T14:42:50Z','cat'=>['electronics','memory'],'spell'=>['CORSAIR ValueSelect 1GB 184-Pin DDR SDRAM Unbuffered DDR 400 (PC 3200) System Memory - Retail']},{'id'=>'VDBDB1A16','inStock'=>true,'manu'=>'A-DATA Technology Inc.','name'=>'A-DATA V-Series 1GB 184-Pin DDR SDRAM Unbuffered DDR 400 (PC 3200) System Memory - OEM','popularity'=>5,'sku'=>'VDBDB1A16','timestamp'=>'2009-03-20T14:42:50.004Z','cat'=>['electronics','memory'],'spell'=>['A-DATA V-Series 1GB 184-Pin DDR SDRAM Unbuffered DDR 400 (PC 3200) System Memory - OEM'],'features'=>['CAS latency 3,	 2.7v']},{'id'=>'3007WFP','inStock'=>true,'includes'=>'USB cable','manu'=>'Dell, Inc.','name'=>'Dell Widescreen UltraSharp 3007WFP','popularity'=>6,'price'=>2199.0,'sku'=>'3007WFP','timestamp'=>'2009-03-20T14:42:50.017Z','weight'=>401.6,'cat'=>['electronics','monitor'],'spell'=>['Dell Widescreen UltraSharp 3007WFP'],'features'=>['30" TFT active matrix LCD, 2560 x 1600, .25mm dot pitch, 700:1 contrast']},{'id'=>'VA902B','inStock'=>true,'manu'=>'ViewSonic Corp.','name'=>'ViewSonic VA902B - flat panel display - TFT - 19"','popularity'=>6,'price'=>279.95,'sku'=>'VA902B','timestamp'=>'2009-03-20T14:42:50.034Z','weight'=>190.4,'cat'=>['electronics','monitor'],'spell'=>['ViewSonic VA902B - flat panel display - TFT - 19"'],'features'=>['19" TFT active matrix LCD, 8ms response time, 1280 x 1024 native resolution']},{'id'=>'0579B002','inStock'=>true,'manu'=>'Canon Inc.','name'=>'Canon PIXMA MP500 All-In-One Photo Printer','popularity'=>6,'price'=>179.99,'sku'=>'0579B002','timestamp'=>'2009-03-20T14:42:50.062Z','weight'=>352.0,'cat'=>['electronics','multifunction printer','printer','scanner','copier'],'spell'=>['Canon PIXMA MP500 All-In-One Photo Printer'],'features'=>['Multifunction ink-jet color photo printer','Flatbed scanner, optical scan resolution of 1,200 x 2,400 dpi','2.5" color LCD preview screen','Duplex Copying','Printing speed up to 29ppm black, 19ppm color','Hi-Speed USB','memory card: CompactFlash, Micro Drive, SmartMedia, Memory Stick, Memory Stick Pro, SD Card, and MultiMediaCard']}]},'facet_counts'=>{'facet_queries'=>{},'facet_fields'=>{'manu'=>['inc',8,'apach',2,'belkin',2,'canon',2,'comput',2,'corp',2,'corsair',2,'foundat',2,'microsystem',2,'softwar',2],'cat'=>['electronics',14,'memory',3,'card',2,'connector',2,'drive',2,'graphics',2,'hard',2,'monitor',2,'search',2,'software',2]},'facet_dates'=>{}}})
+end

data/test/request_test.rb

@@ -0,0 +1,33 @@
+require 'test_unit_test_case'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'rsolr-ext')
+
+class RSolrExtRequestTest < Test::Unit::TestCase
+  
+  test 'standard request' do
+    solr_params = RSolr::Ext::Request.map(
+      :page=>2,
+      :per_page=>10,
+      :phrases=>{:name=>'This is a phrase'},
+      :filters=>['test', {:price=>(1..10)}],
+      :phrase_filters=>{:manu=>['Apple']},
+      :queries=>'ipod',
+      :facets=>{:fields=>['cat', 'blah']},
+      :spellcheck => true
+    )
+    assert_equal ["test", "price:[1 TO 10]", "manu:\"Apple\""], solr_params[:fq]
+    assert_equal 10, solr_params[:start]
+    assert_equal 10, solr_params[:rows]
+    assert_equal "ipod name:\"This is a phrase\"", solr_params[:q]
+    assert_equal ['cat', 'blah'], solr_params['facet.field']
+    assert_equal true, solr_params[:facet]
+  end
+  
+  test 'fq param using the phrase_filters mapping' do
+    solr_params = RSolr::Ext::Request.map(
+      :phrase_filters=>{:manu=>['Apple', 'ASG'], :color=>['red', 'blue']}
+    )
+    expected = {:fq=>["color:\"red\"", "color:\"blue\"", "manu:\"Apple\"", "manu:\"ASG\""]}
+    assert expected, solr_params
+  end
+  
+end

data/test/response_test.rb

@@ -0,0 +1,105 @@
+require 'test_unit_test_case'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'rsolr-ext')
+require 'helper'
+
+class RSolrExtResponseTest < Test::Unit::TestCase
+  
+  test 'base response class' do
+    raw_response = eval(mock_query_response)
+    r = RSolr::Ext::Response::Base.new(raw_response)
+    assert r.respond_to?(:header)
+    assert r.ok?
+  end
+  
+  test 'standard response class' do
+    raw_response = eval(mock_query_response)
+    r = RSolr::Ext::Response::Base.new(raw_response)
+    assert r.respond_to?(:response)
+    assert r.ok?
+    assert_equal 11, r.docs.size
+    assert_equal 'EXPLICIT', r.params[:echoParams]
+    assert_equal 1, r.docs.previous_page
+    assert_equal 2, r.docs.next_page
+    #
+    assert r.kind_of?(RSolr::Ext::Response::Docs)
+    assert r.kind_of?(RSolr::Ext::Response::Facets)
+  end
+  
+  test 'standard response doc ext methods' do
+    raw_response = eval(mock_query_response)
+    r = RSolr::Ext::Response::Base.new(raw_response)
+    doc = r.docs.first
+    assert doc.has?(:cat, /^elec/)
+    assert ! doc.has?(:cat, 'elec')
+    assert doc.has?(:cat, 'electronics')
+    
+    assert 'electronics', doc.get(:cat)
+    assert_nil doc.get(:xyz)
+    assert_equal 'def', doc.get(:xyz, :default=>'def')
+  end
+  
+  test 'Response::Standard facets' do
+    raw_response = eval(mock_query_response)
+    r = RSolr::Ext::Response::Base.new(raw_response)
+    assert_equal 2, r.facets.size
+    
+    field_names = r.facets.collect{|facet|facet.name}
+    assert field_names.include?('cat')
+    assert field_names.include?('manu')
+    
+    first_facet = r.facets.first
+    assert_equal 'cat', first_facet.name
+    assert_equal 10, first_facet.items.size
+    
+    expected = first_facet.items.collect do |item|
+      item.value + ' - ' + item.hits.to_s
+    end.join(', ')
+    assert_equal "electronics - 14, memory - 3, card - 2, connector - 2, drive - 2, graphics - 2, hard - 2, monitor - 2, search - 2, software - 2", expected
+    
+    r.facets.each do |facet|
+      assert facet.respond_to?(:name)
+      facet.items.each do |item|
+        assert item.respond_to?(:value)
+        assert item.respond_to?(:hits)
+      end
+    end
+    
+  end
+  
+  test 'response::standard facet_by_field_name' do
+    raw_response = eval(mock_query_response)
+    r = RSolr::Ext::Response::Base.new(raw_response)
+    facet = r.facet_by_field_name('cat')
+    assert_equal 'cat', facet.name
+  end
+  
+=begin
+  
+  # pagination for facets has been commented out in the response/facets module.
+  # ...need to think more about how this can be handled
+  
+  test 'response::standard facets.paginate' do
+    raw_response = eval(mock_query_response)
+    raw_response['responseHeader']['params']['facet.offset'] = 1
+    raw_response['responseHeader']['params']['facet.limit'] = 2
+    
+    r = RSolr::Ext::Response::Standard.new(raw_response)
+    
+    assert_equal 2, r.facets.current_page
+    
+    # always 1 less than facet.limit
+    assert_equal 1, r.facets.per_page
+    
+    assert_equal 3, r.facets.next_page
+    
+    assert_equal 1, r.facets.previous_page
+    
+    # can't know how many pages there are with facets.... so we set it to -1
+    assert_equal -1, r.facets.total_pages
+    
+    assert r.facets.has_next?
+    assert r.facets.has_previous?
+  end
+=end
+  
+end

data/test/test_unit_test_case.rb

@@ -0,0 +1,18 @@
+require 'test/unit'
+
+class Test::Unit::TestCase
+  
+  def self.test(name, &block)
+    test_name = "test_#{name.gsub(/\s+/,'_')}".to_sym
+    defined = instance_method(test_name) rescue false
+    raise "#{test_name} is already defined in #{self}" if defined
+    if block_given?
+      define_method(test_name, &block)
+    else
+      define_method(test_name) do
+        flunk "No implementation provided for #{name}"
+      end
+    end
+  end
+  
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: rsolr-ext
+version: !ruby/object:Gem::Version 
+  version: 0.9.6.3
+platform: ruby
+authors: 
+- Matt Mitchell
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-30 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mwmitchell-rsolr
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.9.6
+    version: 
+description: An extension lib for RSolr
+email: goodieboy@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- lib/mash.rb
+- lib/rsolr-ext/connection.rb
+- lib/rsolr-ext/doc.rb
+- lib/rsolr-ext/model.rb
+- lib/rsolr-ext/request.rb
+- lib/rsolr-ext/response/docs.rb
+- lib/rsolr-ext/response/facets.rb
+- lib/rsolr-ext/response/spelling.rb
+- lib/rsolr-ext/response.rb
+- lib/rsolr-ext.rb
+- LICENSE
+- README.rdoc
+- rsolr-ext.gemspec
+has_rdoc: true
+homepage: http://github.com/mwmitchell/rsolr-ext
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: An extension lib for RSolr
+test_files: 
+- test/connection_test.rb
+- test/request_test.rb
+- test/response_test.rb
+- test/test_unit_test_case.rb
+- test/helper.rb