picky-client 1.1.7 → 1.2.0

data/lib/picky-client/{engine.rb → client.rb}

@@ -1,16 +1,52 @@
+# Ruby Search Client Frontend for the Picky search engine.
+#
+# === Usage
+#
+# ==== 1. Set up search clients.
+# 
+#   # Create search client instances e.g. in your development.rb, production.rb etc.
+#   #
+#   # Use the right host, port where your Picky server runs. Then, choose a URL path as defined
+#   # in your <tt>app/application.rb</tt> in the server.
+#   #
+#   FullBooks = Picky::Client::Full.new :host => 'localhost', :port => 8080, :path => '/books/full'
+#   LiveBooks = Picky::Client::Live.new :host => 'localhost', :port => 8080, :path => '/books/live'
+#
+# ==== 2. Get results.
+#
+#   # Then, in your search methods, call #search.
+#   #
+#   # You will get back a Hash with categorized results.
+#   # 
+#   results = FullBooks.search 'my query', :offset => 10
+#   
+# ==== 3. Work with the results.
+#
+#   # To make the Hash more useful, extend it with a few convenience methods.
+#   # See Picky::Convenience.
+#   #
+#   results.extend Picky::Convenience
+#
+#   # One of the added Methods is:
+#   #   populate_with(ModelThatSupportsFind, &optional_block_where_you_get_model_instance_and_you_can_render)
+#   # This adds the rendered models to the results Hash.
+#   #
+#   results.populate_with Book do |book|
+#     book.to_s
+#   end
+#   
+# ==== 4. Last step is encoding it back into JSON.
+#
+#   # Encode the results in JSON and return it to the Javascript Client (or your frontend). 
+#   #
+#   ActiveSupport::JSON.encode results
+#
+# Note: The client might be rewritten such that instead of an http request it connects through tcp/0mq.
+#
 require 'net/http'
 
 module Picky
-  # Frontend for the search client.
-  #
-  # Configure a search by passing the options in the initializer:
-  #   * host
-  #   * port
-  #   * path
-  #
-  # TODO Rewrite such that instead of an http request we connect through tcp.
-  # Or use EventMachine.
-  #
+  
   module Client
 
     class Base
@@ -52,10 +88,10 @@ module Picky
       #
       # Returns a hash. Extend with Convenience.
       #
-      def search params = {}
-        return {} unless params[:query] && !params[:query].empty?
+      def search query, params = {}
+        return {} unless query && !query.empty?
         
-        send_search params
+        send_search params.merge :query => query
       end
       
       # Sends a search to the configured address.

data/lib/picky-client/convenience.rb

@@ -1,5 +1,6 @@
 module Picky
-  # Use this class to extend the hash the serializer returns.
+  
+  # Use this class to extend the hash that the client returns.
   #
   module Convenience
 
@@ -8,42 +9,59 @@ module Picky
     def empty?
       allocations.empty?
     end
-    # Returns the topmost limit results.
+    
+    # Returns the topmost n results.
+    # (Note that not all ids are returned with the results. By default only maximally 20.)
+    #
+    # === Parameters
+    # * limit: The amount of ids to return. Default is 20.
     #
     def ids limit = 20
       ids = []
       allocations.each { |allocation| allocation[4].each { |id| break if ids.size > limit; ids << id } }
       ids
     end
-    # Removes the ids from each allocation.
+    
+    # Removes all ids of each allocation.
     #
     def clear_ids
       allocations.each { |allocation| allocation[4].clear }
     end
 
-    # Caching readers.
+    # Returns the allocations.
     #
     def allocations
       @allocations || @allocations = self[:allocations]
     end
+    # Returns the number of allocations.
+    #
     def allocations_size
       @allocations_size || @allocations_size = allocations.size
     end
+    # Returns the total of results.
+    #
     def total
       @total || @total = self[:total]
     end
     
-    # Populating the results.
+    # Populates the ids with (rendered) model instances.
     #
     # Give it an AR class and options for the find and it
     # will yield each found result for you to render.
     #
     # If you don't pass it a block, it will just use the AR results.
     #
-    def populate_with klass, amount = 20, options = {}, &block
+    # === Parameters
+    # * model_class: The model to use for the results. Will call #find on the given class.
+    # * amount: Amount of results to populate. Default 20.
+    #
+    # === Options
+    # * options are directly passed through to the ModelClass.find(ids, options) method. Default is {}.
+    #
+    def populate_with model_class, amount = 20, options = {}, &block
       the_ids = ids amount
       
-      objects = klass.find the_ids, options
+      objects = model_class.find the_ids, options
       
       # Put together a mapping.
       #
@@ -58,13 +76,18 @@ module Picky
       
       objects.collect! &block if block_given?
       
-      replace_ids_with objects
+      amend_ids_with objects
       clear_ids
       
       objects
     end
-    # The rendered results or AR instances if you
-    # have populated the results.
+    
+    # Returns either
+    # * the rendered entries, if you have used #populate_with _with_ a block
+    # OR
+    # * the model instances, if you have used #populate_with _without_ a block
+    #
+    # Or, if you haven't called #populate_with yet, you will get an empty array.
     #
     def entries limit = 20
       if block_given?
@@ -79,7 +102,7 @@ module Picky
     
     # The ids need to come in the order which the ids were returned by the ids method.
     #
-    def replace_ids_with entries
+    def amend_ids_with entries # :nodoc:
       i = 0
       self.allocations.each do |allocation|
         allocation[5] = allocation[4].map do |_|

data/lib/picky-client.rb

@@ -4,6 +4,6 @@ require 'rubygems'
 require 'yajl'
 
 dir = File.dirname __FILE__
-require File.expand_path('picky-client/engine', dir)
+require File.expand_path('picky-client/client', dir)
 require File.expand_path('picky-client/convenience', dir)
 require File.expand_path('picky-client/helper', dir)

data/spec/picky-client/{engine_spec.rb → client_spec.rb}

@@ -104,15 +104,32 @@ describe Picky::Client do
     end
 
     describe "search" do
+      describe 'ok search term given' do
+        it 'calls send_search correctly' do
+          @full.should_receive(:send_search).once.with :query => 'hello'
+          
+          @full.search 'hello'
+        end
+      end
+      describe 'no search term given' do
+        it "should raise an ArgumentError" do
+          lambda { @full.search }.should raise_error(ArgumentError)
+        end
+      end
       describe "with nil as search term" do
         before(:each) do
           @query = nil
         end
-        it "should return a Search::Results for bla" do
-          @full.search(:query => @query).should be_kind_of(Hash)
+        it "should return a Search::Results" do
+          @full.search(@query).should be_kind_of(Hash)
         end
         it "should return an empty Search::Results" do
-          @full.search(:query => @query).should be_empty
+          @full.search(@query).should be_empty
+        end
+        it 'calls send_search correctly' do
+          @full.should_receive(:send_search).never
+          
+          @full.search @query
         end
       end
       describe "with '' as search term" do
@@ -120,10 +137,15 @@ describe Picky::Client do
           @query = ''
         end
         it "should return a Search::Results" do
-          @full.search(:query => @query).should be_kind_of(Hash)
+          @full.search(@query).should be_kind_of(Hash)
         end
         it "should return an empty Search::Results" do
-          @full.search(:query => @query).should be_empty
+          @full.search(@query).should be_empty
+        end
+        it 'calls send_search correctly' do
+          @full.should_receive(:send_search).never
+          
+          @full.search @query
         end
       end
     end
@@ -170,15 +192,32 @@ describe Picky::Client do
     end
 
     describe "search" do
+      describe 'ok search term given' do
+        it 'calls send_search correctly' do
+          @live.should_receive(:send_search).once.with :query => 'hello'
+          
+          @live.search 'hello'
+        end
+      end
+      describe 'no search term given' do
+        it "should raise an ArgumentError" do
+          lambda { @live.search }.should raise_error(ArgumentError)
+        end
+      end
       describe "with nil as search term" do
         before(:each) do
           @query = nil
         end
         it "should return a Search::Results" do
-          @live.search(:query => @query).should be_kind_of(Hash)
+          @live.search(@query).should be_kind_of(Hash)
         end
         it "should return an empty Search::Results" do
-          @live.search(:query => @query).should be_empty
+          @live.search(@query).should be_empty
+        end
+        it 'calls send_search correctly' do
+          @live.should_receive(:send_search).never
+          
+          @live.search @query
         end
       end
       describe "with '' as search term" do
@@ -186,10 +225,15 @@ describe Picky::Client do
           @query = ''
         end
         it "should return a Search::Results" do
-          @live.search(:query => @query).should be_kind_of(Hash)
+          @live.search(@query).should be_kind_of(Hash)
         end
         it "should return an empty Search::Results" do
-          @live.search(:query => @query).should be_empty
+          @live.search(@query).should be_empty
+        end
+        it 'calls send_search correctly' do
+          @live.should_receive(:send_search).never
+          
+          @live.search @query
         end
       end
     end

data/spec/picky-client/convenience_spec.rb

@@ -125,7 +125,7 @@ describe Picky::Convenience do
     end
     it 'should populate with the entries' do
       new_ids = (11..31).to_a # +10
-      @results.replace_ids_with new_ids
+      @results.amend_ids_with new_ids
       @results.entries.should == (11..30).to_a
     end
   end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
-  - 1
-  - 7
-  version: 1.1.7
+  - 2
+  - 0
+  version: 1.2.0
 platform: ruby
 authors: 
 - Florian Hanke
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-15 00:00:00 +01:00
+date: 2010-12-17 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -41,13 +41,13 @@ extensions: []
 extra_rdoc_files: 
 - README.rdoc
 files: 
+- lib/picky-client/client.rb
 - lib/picky-client/convenience.rb
-- lib/picky-client/engine.rb
 - lib/picky-client/helper.rb
 - lib/picky-client.rb
 - README.rdoc
+- spec/picky-client/client_spec.rb
 - spec/picky-client/convenience_spec.rb
-- spec/picky-client/engine_spec.rb
 - spec/picky-client/helper_spec.rb
 has_rdoc: false
 homepage: http://floere.github.com/picky
@@ -82,6 +82,6 @@ signing_key:
 specification_version: 3
 summary: picky Ruby Search Engine Client
 test_files: 
+- spec/picky-client/client_spec.rb
 - spec/picky-client/convenience_spec.rb
-- spec/picky-client/engine_spec.rb
 - spec/picky-client/helper_spec.rb