simple_solr 0.4.1 → 0.5.0

data/CHANGELOG.rdoc

@@ -1,8 +1,15 @@
-== 0.4.0 (Aug 16, 2011)
+== 0.5.0 (Aug 17, 2011)
+
+- Added simple_search method to retrieve results
+- Added DEVELOPMENT.rdoc
 
-- First release as a gem, indexing works
 
 == 0.4.1
 
 - Spec that missing master_solr config falls back to solr config
-- add http:// to the solr uris
+- add http:// to the solr uris
+
+
+== 0.4.0 (Aug 16, 2011)
+
+- First release as a gem, indexing works

data/DEVELOPMENT.rdoc

@@ -0,0 +1,11 @@
+= Working on SimpleSolr
+
+I appreciate the effort! GitHub offers excellent tools for collaborating
+on projects, and the basic fork/branch/pull request style is just fine.
+
+To get started, also no surprises:
+
+1. gem install bundler (if you haven't already)
+2. bundle
+3. cp spec/db/database.yml.example spec/db/database.yml
+4. rake

data/README.rdoc

@@ -2,11 +2,17 @@ Extremely lightweight adapter between Rails and Solr.
 
 SimpleSolr uses the REST interface that Solr offers and makes a great number
 of assumptions. This has resulted in a very fast, very lightweight library
-almost anyone can use straight away.
+almost anyone can use straight away. It does mean you will be working with
+query strings and hashes directly, instead of with Ruby objects.
+
+SimpleSolr is ideal when the Solr you use has been provided by a third party
+and is more or less running fine without you.
+
+=== Design goals and benefits of SimpleSolr
 
 * only a few dozen lines of code
 * extremely simple DSL
-* only depends on httparty
+* only depends on httparty[https://github.com/jnunemaker/httparty]
 * can handle all common use cases
 * has support for master/slave configurations
 * does not come with a bundled Solr
@@ -14,40 +20,33 @@ almost anyone can use straight away.
 
 And my personal favorite:
 
-* <b>does nothing for unconfigured environments</b>
+* <b>no operation in unconfigured environments</b>
 
 If you have no +development+ section in the config file (see below) then
 nothing will happen at all. Your models will not be indexed, but you are
 freed from having to run a local Solr instance as well.
 
-Naturally there are downsides as well.
-
-* assumes an +id+ field present
-* makes Solr commit after every change
-* does not come with a bundled Solr
-* no rake tasks included
-
-This gem is not really suitable for use outside Rails, as it requires both
-ActiveRecord and ActiveSupport.
-
-I owe a great deal to @outoftime's Sunspot[https://github.com/outoftime/sunspot] library. If you need a fully-packed
-solution that handles every Solr case you might have, use that instead.
+I owe a great deal to @outoftime's Sunspot[https://github.com/outoftime/sunspot] library. The
+configuration is identical, so if you come from that you will feel right at home. If you do
+need a fully-packed solution that is a good Ruby/Rails citizen and handles every Solr case you
+might have, use that instead.
 
 
 == Installation
 
-Rails 2, in config/environment.rb:
+Rails 2, in +config/environment.rb+:
 
   config.gem 'simple_solr'
   
-Rails 3, in Gemfile:
+Rails 3, in +Gemfile+:
 
   gem 'simple_solr'
   
 
 == Configuration
 
-Create a file called <tt>config/simple_solr.yml</tt>.
+Create a file called <tt>config/simple_solr.yml</tt>. (No, there is no generator. You can
+do it by hand, I believe in you.)
 
   production:
     solr:
@@ -61,9 +60,18 @@ Create a file called <tt>config/simple_solr.yml</tt>.
 
 If you have just one Solr server, leave out the master_solr section.
 
+Reasonable defaults are assumed for all these entries, so you can get away
+with just your environment and +solr+ key in there. You can leave out values
+in the +master_solr+ section, since the gem will fall back to using values from
+the +solr+ section instead.
+
 === Your models
 
-Then in your models include the following:
+<b>Note: in these examples I am using a class called Document. This is just for
+illustrative purpuses, your class will probably have a different name, like
+Post or Product. You get the idea.</b>
+
+In your models include the following:
 
   class Document < ActiveRecord::Base
     simple_solr do
@@ -72,11 +80,10 @@ Then in your models include the following:
   end
 
 Only the fields listed in the +simple_solr+ block will be sent to Solr,
-with the addition of the +id+ field which is always included. The type of
-the field is not appended; the XML sent to Solr is as bare as possible.
-
-This also means no type casting is performed on dates/times. If you need
-anything like that, use a lambda to manipulate the field to your liking.
+with the addition of the +id+ field which is always included. Every field
+is passed to Builder, which has limited type casting. If you have special
+needs with regards to date/time formats or anything like that, use a
+lambda to manipulate the field to your liking.
 
 Full example:
 
@@ -86,7 +93,7 @@ Full example:
       field :title
       field :date_creation, :created_at
       field :shared,        false
-      field :published,     "Megacorp LLC"
+      field :publisher,     "Megacorp LLC"
       field :body
     end
   end
@@ -98,6 +105,74 @@ As you can see you have a couple options with regards to the fields:
 3. Static value such as a string or boolean - which is used verbatim
 4. A lambda - for your every customization need.
 
-Use the latter form if you want to add a dynamic field to Solr. The model
-instance is passed as a parameter, so you can use every method inside
-the block, or run a calculation, or whatever.
+Use the latter if you want to add a dynamic field to Solr. The model
+instance is passed as a parameter, so Bob's your uncle and the sky's
+the limit.
+
+=== Debugging
+
+If something isn't quite working, set httparty's +debug_output+ flag
+on your model:
+
+  Document.debug_output
+
+and then save the model to see the HTTP conversation on $stdout.
+
+== Searching
+
+Use the +simple_search+ class method on your model:
+
+  Document.simple_search 'apple'
+  
+This will make a trip to Solr and return the results as a hash. That's right.
+The results are not correlated with your models. In fact, no processing is
+done at all. Simple, right? If you need to fetch model instances based on the
+results, that is up to you.
+
+You can add parameters, for example if you want to limit results using +fq+:
+
+  Document.simple_search 'apple', :fq => "category:fruit"
+  
+See the Solr documentation[http://wiki.apache.org/solr/CommonQueryParameters] for a list
+of common query parameters. Just remember that the +q+ parameter will be set already,
+although it can be overriden by the parameters you provide.
+
+The response from Solr will look something like this:
+
+  <?xml version="1.0" encoding="UTF-8"?>
+  <response>
+    <lst name="responseHeader">
+      <int name="status">0</int>
+      <int name="QTime">3</int>
+    </lst>
+    <result name="response" numFound="1" start="0" maxScore="13.722203">
+      <doc>
+        <float name="score">13.722203</float>
+        <date name="date_creation">2011-01-06T23:02:33Z</date>
+        <str name="id">969</str>
+        <str name="publisher">Widgets, Inc</str>
+        <str name="title">Golden Delicious</str>
+        <str name="category">Apples</str>
+      </doc>
+    </result>
+    <lst name="highlighting">
+      <lst name="969"/>
+    </lst>
+  </response>
+
+This response will be translated into a hash by httparty. Take a look at your
+webserver config/response headers if that does not happen.
+
+
+== Working in batches
+
+If you want to add a bunch of existing models to Solr, you can:
+
+  Document.all.each do |document|
+    document.add_to_solr
+  end
+
+
+== Helping out
+
+Interested in working on SimpleSolr? Please see DEVELOPMENT.rdoc.

data/lib/simple_solr.rb

@@ -2,12 +2,14 @@ require 'active_record'
 require 'httparty'
 require 'builder'
 
-require "simple_solr/active_record"
+require "simple_solr/update"
+require "simple_solr/search"
 require "simple_solr/configuration"
 require "simple_solr/version"
 
 if defined?(ActiveRecord::Base)
-  ActiveRecord::Base.send :include, SimpleSolr::ActiveRecord
+  ActiveRecord::Base.send :include, SimpleSolr::Update
+  ActiveRecord::Base.extend SimpleSolr::Search
 end
 
 module SimpleSolr
@@ -15,5 +17,9 @@ module SimpleSolr
     def configuration
       @configuration ||= SimpleSolr::Configuration.new
     end
+    
+    def search(query, params)
+      SimpleSolr::Search.simple_search(query, params)
+    end
   end
 end

data/lib/simple_solr/search.rb

@@ -0,0 +1,12 @@
+module SimpleSolr
+  module Search
+    # Search using the given query. Additional parameters can be added as a hash.
+    # For instance, to limit the results by using an +fq+ parameter:
+    #
+    #   Product.simple_search 'delicious', :fq => "category:fruit"
+    def simple_search(query, params={})
+      query = {:q => query}
+      get(SimpleSolr.configuration.uri + "/select", :query => query.merge(params))
+    end
+  end
+end

data/lib/simple_solr/{active_record.rb → update.rb}

@@ -1,5 +1,5 @@
 module SimpleSolr
-  module ActiveRecord
+  module Update
     def self.included(base)
       base.extend ClassMethods
     end
@@ -18,7 +18,7 @@ module SimpleSolr
         # Store the simple_solr fields for this class
         cattr_accessor :simple_solr_fields
         self.simple_solr_fields = { id: nil }
-        block.call
+        block.call if block_given?
         
         include InstanceMethods
       end

data/lib/simple_solr/version.rb

@@ -1,3 +1,3 @@
 module SimpleSolr
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/simple_solr.gemspec

@@ -7,11 +7,9 @@ Gem::Specification.new do |s|
   s.version     = SimpleSolr::VERSION
   s.authors     = ["Joost Baaij"]
   s.email       = ["joost@spacebabies.nl"]
-  s.homepage    = ""
+  s.homepage    = "https://github.com/tilsammans/simple_solr"
   s.summary     = %q{Simple Solr client}
-  s.description = %q{Rails plugins which connects to a Solr search engine with as less features as possible.}
-
-  s.rubyforge_project = "simple_solr"
+  s.description = %q{Solr client for Ruby on Rails with as few features as possible.}
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/spec/db/models.rb

@@ -1,5 +1,9 @@
 # A bunch of models with varying amounts of simple_solrism.
 
+class SparseDocument < ActiveRecord::Base
+  simple_solr
+end
+
 class SimpleDocument < ActiveRecord::Base
   simple_solr do
     field :title

data/spec/simple_solr/search_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe SimpleSolr::Search do
+  describe SimpleDocument do
+    it "responds to search" do
+      SimpleDocument.should respond_to(:simple_search)
+    end
+    
+    it "gets results" do
+      SimpleDocument.should_receive(:get).with("http://test.local:8983/solr/select", :query => {:q => 'bonanza'})
+      SimpleDocument.simple_search 'bonanza'
+    end
+
+    it "allows parameters" do
+      SimpleDocument.should_receive(:get).with("http://test.local:8983/solr/select", :query => {:q => 'bonanza', :fq => "brand_site:www.example.com"})
+      SimpleDocument.simple_search 'bonanza', :fq => "brand_site:www.example.com"
+    end
+  end
+end

data/spec/simple_solr/{active_record_spec.rb → update_spec.rb}

@@ -1,6 +1,12 @@
 require 'spec_helper'
 
-describe SimpleSolr::ActiveRecord do
+describe SimpleSolr::Update do
+  describe SparseDocument do
+    it "stores just the id field" do
+      SparseDocument.simple_solr_fields.should eq({:id => nil})
+    end
+  end
+  
   describe SimpleDocument do
     it "provides simple_solr class method" do
       SimpleDocument.should respond_to(:simple_solr)

data/spec/support/database.rb

@@ -16,7 +16,12 @@ if File.exists?(database_yml)
   end  
   
 else
-  raise "Please create #{database_yml} first to configure your database. Take a look at: #{database_yml}.example"
+  abort <<-FAIL
+  
+  Please create #{database_yml} first to configure your database.
+  Take a look at: #{database_yml}.example"
+  
+  FAIL
 end
 
 def clean_database!

metadata

@@ -1,81 +1,78 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: simple_solr
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.5.0
   prerelease: 
-  version: 0.4.1
 platform: ruby
-authors: 
+authors:
 - Joost Baaij
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-08-16 00:00:00 +02:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-08-17 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rspec
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2161392840 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "2"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :development
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: activerecord
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *2161392840
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: &2161392420 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: httparty
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: *2161392420
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: &2161391960 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: builder
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: *2161391960
+- !ruby/object:Gem::Dependency
+  name: builder
+  requirement: &2161391540 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
-  version_requirements: *id004
-description: Rails plugins which connects to a Solr search engine with as less features as possible.
-email: 
+  prerelease: false
+  version_requirements: *2161391540
+description: Solr client for Ruby on Rails with as few features as possible.
+email:
 - joost@spacebabies.nl
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .rspec
 - CHANGELOG.rdoc
+- DEVELOPMENT.rdoc
 - Gemfile
 - README.rdoc
 - Rakefile
 - lib/simple_solr.rb
-- lib/simple_solr/active_record.rb
 - lib/simple_solr/configuration.rb
+- lib/simple_solr/search.rb
+- lib/simple_solr/update.rb
 - lib/simple_solr/version.rb
 - simple_solr.gemspec
 - spec/config/master_slave.yml
@@ -83,48 +80,46 @@ files:
 - spec/db/database.yml.example
 - spec/db/models.rb
 - spec/db/schema.rb
-- spec/simple_solr/active_record_spec.rb
 - spec/simple_solr/configuration_spec.rb
+- spec/simple_solr/search_spec.rb
+- spec/simple_solr/update_spec.rb
 - spec/simple_solr_spec.rb
 - spec/spec_helper.rb
 - spec/support/database.rb
 - spec/support/rails.rb
-has_rdoc: true
-homepage: ""
+homepage: https://github.com/tilsammans/simple_solr
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
-rubyforge_project: simple_solr
-rubygems_version: 1.6.2
+rubyforge_project: 
+rubygems_version: 1.8.8
 signing_key: 
 specification_version: 3
 summary: Simple Solr client
-test_files: 
+test_files:
 - spec/config/master_slave.yml
 - spec/config/simple_solr.yml
 - spec/db/database.yml.example
 - spec/db/models.rb
 - spec/db/schema.rb
-- spec/simple_solr/active_record_spec.rb
 - spec/simple_solr/configuration_spec.rb
+- spec/simple_solr/search_spec.rb
+- spec/simple_solr/update_spec.rb
 - spec/simple_solr_spec.rb
 - spec/spec_helper.rb
 - spec/support/database.rb