mwmitchell-rsolr-ext 0.8.0 → 0.9.5

data/README.rdoc

@@ -1,7 +1,66 @@
 =RSolr::Ext
 A set of helper methods/modules to assist in building Solr queries and handling responses when using the RSolr library.
 
-==Request Example
+==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:
+  solr.luke['index']
+  solr.luke['fields']
+  solr.luke['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.
+=====Examples
+* :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.
+=====Examples
+* :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.
+=====Examples
+* :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.
+=====Examples
+* :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.
+=====Examples
+* :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,
@@ -12,31 +71,37 @@ A set of helper methods/modules to assist in building Solr queries and handling
     :facets=>{:fields=>['cat', 'blah']}
   }
   
-  rsolr = RSolr::Ext.connect
-  
   response = rsolr.find(solr_params)
 
-==Response Example
-  rsolr = RSolr::Ext.connect
+==Responses
+RSolr::Ext decorates the normal output hash from RSolr and adds some helpful methods.
+
+===Examples
+  solr = RSolr::Ext.connect
   
-  response = rsolr.find :q=>'*:*'
+  response = solr.find :q=>'*:*'
   
   response.ok?
   response.params
   response.docs
   response.docs.previous_page
   response.docs.next_page
-  response.facets
+  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.
 
-===Doc Pagination
+===Documents/Pagination
 If you wanna paginate, just throw the collection into the WillPaginate view helper.
   <%= will_paginate response.docs %>
 
-===The "Model" Module
+==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)

data/lib/rsolr-ext.rb

@@ -21,7 +21,7 @@ module RSolr
   
   module Ext
     
-    VERSION = '0.8.0'
+    VERSION = '0.9.5'
     
     autoload :Connection, 'rsolr-ext/connection.rb'
     autoload :Doc, 'rsolr-ext/doc.rb'

data/lib/rsolr-ext/connection.rb

@@ -1,91 +1,38 @@
-# RSolr::Ext.connect() does this for you.
-# Ext::Connection makes querying solr easier by providing a simple #find method.
-#
-# The #find method behaves differently depending on what you send in.
-#
-# The first argument can be either a symbol (:all, :first)
-# OR
-# a solr params hash
-# OR
-# a string that will be used for the query.
-#
-# If the first argument is a symbol, the second is used for solr params or the query.
-# 
-# If the first argument is :first, then only a single document is returns (:rows=>0)
-# If the first argument is :all, then all documents are returned
-# 
-# If a hash is used for solr params, all of the normal RSolr::Ext::Request::Standard
-# mappings are available (everything else gets passed to solr).
-# 
-# If a string is used, it's set to the :q param.
-#
-# The last argument (after the query or solr params) is used for finding options.
-# The following opts are allowed:
-# :include_response - false is default - whether or not to return the whole solr response or just the doc(s)
-# :handler  - nil is default - the request path (/select or /search etc.)
 module RSolr::Ext::Connection
   
-  # Examples:
-  # find 'jefferson' # q=jefferson - all docs
-  # find :first, 'jefferson' # q=jefferson&rows=1 - first doc only
-  # find 'jefferson', :phrase_filters=>{:type=>'book'} # q=jefferson&fq=type:"book" - all docs
-  # find {:q=>'something'}, :include_response=>true # q=something -- the entire response
-  def find *args, &blk
-    mode, solr_params, opts = extract_find_opts!(*args)
-    
-    opts[:include_response] ||= true
-    
-    solr_params[:rows] = 1 if mode == :first
-    valid_solr_params = RSolr::Ext::Request.map(solr_params)
-    
-    response = opts[:handler] ? send_request(opts[:handler], valid_solr_params) : select(valid_solr_params)
-    return response if response.is_a?(String)
-    
-    response = RSolr::Ext::Response::Base.new(response)
-    
-    if opts[:include_response] == true
-      response
-    else
-      if mode == :first
-        # return only one doc
-        response['response']['docs'].first
-      else
-        # return all docs
-        response['response']['docs']
-      end
-    end
+  # 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
+    path = args.first.is_a?(String) ? args.shift : '/select'
+    params = args.pop || {}
+    response = self.request path, RSolr::Ext::Request.map(params)
+    RSolr::Ext::Response::Base.new(response)
   end
   
-  # find_by_id(10, :handler=>'catalog')
-  # find_by_id(:id=>10)
-  def find_by_id(id, solr_params={}, opts={}, &blk)
-    if id.respond_to?(:each_pair)
-      solr_params = id
-    else
-      solr_params[:phrases] ||= {}
-      solr_params[:phrases][:id] = id.to_s
-    end
-    self.find(:first, solr_params, opts, &blk)
-  end
-  
-  protected
-  
-  def extract_find_opts!(*args)
-    mode = :all
-    valid_modes = [:all, :first]
-    if args[0].is_a?(Symbol)
-      mode = valid_modes.include?(args[0]) ? args.shift : raise("Invalid find mode; should be :first or :all")
-    end
-    # extract solr params
-    solr_params = args.shift
-    # if solr_params is NOT a hash like object
-    # force it into a string for the :q param
-    unless solr_params.respond_to?(:each_pair)
-      solr_params = {:q=>solr_params.to_s}
-    end
-    # extract options
-    opts = args.shift || {}
-    [mode, solr_params, opts]
+  # 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/request.rb

@@ -24,8 +24,8 @@ module RSolr::Ext::Request
       if filters = input.delete(:filters)
         output[:fq] = append_to_param output[:fq], build_query(filters), false
       end
-      if pfilters = input.delete(:phrase_filters)
-        output[:fq] = append_to_param output[:fq], build_query(pfilters, true), false
+      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

data/lib/rsolr-ext/response.rb

@@ -6,8 +6,11 @@ module RSolr::Ext::Response
   
   class Base < Mash
     
-    def initialize *args
-      super *args
+    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']
@@ -26,6 +29,10 @@ module RSolr::Ext::Response
       header['status'] == 0
     end
     
+    def method_missing *args, &blk
+      self.original_hash.send *args, &blk
+    end
+    
   end
   
   module Response

data/rsolr-ext.gemspec

@@ -1,33 +1,33 @@
 Gem::Specification.new do |s|
-	s.name = "rsolr-ext"
-	s.version = "0.8.0"
-	s.date = "2009-07-31"
-	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 = [
-    
+  s.name = "rsolr-ext"
+  s.version = "0.9.5"
+  s.date = "2009-09-04"
+  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"
@@ -42,4 +42,6 @@ Gem::Specification.new do |s|
 	
 	s.extra_rdoc_files = %w(LICENSE README.rdoc)
 	
+	s.add_dependency("mwmitchell-rsolr", [">= 0.9.5"])
+	
 end

data/test/connection_test.rb

@@ -4,9 +4,36 @@ require 'helper'
 
 class RSolrExtConnectionTest < Test::Unit::TestCase
   
-  test 'RSolr::connect' do
+  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?
+  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/request_test.rb

@@ -1,14 +1,6 @@
 require 'test_unit_test_case'
 require File.join(File.dirname(__FILE__), '..', 'lib', 'rsolr-ext')
 
-class Symbol
-  
-  def method_missing n,&b
-    [self, n].join('.').to_sym
-  end
-  
-end
-
 class RSolrExtRequestTest < Test::Unit::TestCase
   
   test 'standard request' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mwmitchell-rsolr-ext
 version: !ruby/object:Gem::Version 
-  version: 0.8.0
+  version: 0.9.5
 platform: ruby
 authors: 
 - Matt Mitchell
@@ -9,10 +9,19 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-31 00:00:00 -07:00
+date: 2009-09-04 00:00:00 -07:00
 default_executable: 
-dependencies: []
-
+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.5
+    version: 
 description: An extension lib for RSolr
 email: goodieboy@gmail.com
 executables: []