dnz-client 0.0.9 → 0.1.0

data/History.txt

@@ -1,3 +1,8 @@
+=== 0.1.0 2010-05-13
+
+* Support for a global connection. This allows some convenient methods on other classes.
+* Added find and find_related methods to Facet class.
+
 === 0.0.9 2010-04-23
 
 * Support for previewing custom searches

data/lib/dnz.rb

@@ -4,5 +4,5 @@ $:.unshift(File.dirname(__FILE__)) unless
 require 'dnz/client'
 
 module Dnz
-  VERSION = '0.0.9'
+  VERSION = '0.1.0'
 end

data/lib/dnz/client.rb

@@ -15,6 +15,18 @@ module DNZ
   # Copyright:: Copyright (c) 2009 Boost New Media
   # License:: MIT
   class Client
+    cattr_accessor :connection
+    
+    class << self
+      def connect(*args)
+        self.connection = self.new(*args)
+      end
+      
+      def method_missing(method, *args, &block)
+        self.connection.send(method, *args, &block)
+      end
+    end
+    
     # The dnz API key
     attr_reader :api_key
     # The base URL (defaults to http://api.digitalnz.org)

data/lib/dnz/facet.rb

@@ -1,12 +1,43 @@
 require 'dnz/attributes'
 
 module DNZ
+  # A facet retrieved from DigitalNZ search results. The facet has a name and an array of
+  # FacetValue objects.
   class Facet
+    # The facet name
     attr_reader :name
-    attr_reader :values
+      
+    # The search that orginally ran to produce this facet
     attr_reader :search
     
     include Enumerable
+    
+    # Find a facet and return it. This is a convienence method for running
+    # Client.search('search', :facets => facet).facets[facet].
+    #
+    # * <tt>facet</tt> - The name of the facet.
+    # * <tt>search_text</tt> - Optional search text. Defaults to everything (*:*).
+    # * <tt>num_results</tt> - Optional maximum number of facet values to return in the
+    # facet. This defaults to -1 which means no limit.
+    def self.find(facet, search_text = '*:*', num_results = -1)      
+      options = {:facets => facet, :facet_num_results => num_results, :num_results => 0}
+      Client.search(search_text, options).facets[facet]
+    end
+    
+    # Find related facet values. This is a convienence method for running
+    # Client.search('parent_facet:value', :facets => facet).facets[facet]. It will
+    # return the facet and facet values for results scoped to another facet.
+    #
+    # * <tt>facet</tt> - The name of the facet.
+    # * <tt>parent_facet</tt> - The name of the facet to scope results to.
+    # * <tt>value</tt> - The facet value to scope the results to.
+    # * <tt>search_text</tt> - Optional search text. Defaults to everything (*:*).
+    # * <tt>num_results</tt> - Optional maximum number of facet values to return in the
+    # facet. This defaults to -1 which means no limit.
+    def self.find_related(facet, parent_facet, value, search_text = '*:*', num_results = -1)
+      search_text = [search_text, '%s:"%s"' % [parent_facet, value]].join(' AND ')
+      self.find(facet, search_text, num_results)
+    end
 
     def initialize(client, search, doc)
       @name = doc.xpath('facet-field').text
@@ -19,14 +50,17 @@ module DNZ
       end
     end
     
+    # An array of FacetValue objects
     def values
       @values.values
     end
-    
+
+    # Retrieve a FacetValue by name
     def [](index)
       @values[index]
     end
     
+    # Enumerate the FacetValue objects
     def each
       @values.each {|key, value| yield value }
     end

data/lib/dnz/results.rb

@@ -54,6 +54,10 @@ module DNZ
     def pages
       num_results_requested < result_count ? (result_count.to_f / num_results_requested).ceil : 1
     end
+    
+    def per_page
+      num_results_requested < 1 ? 1 : num_results_requested
+    end
 
     # The number of results requested via the :num_results option (see <tt>Client.search</tt>).
     def num_results_requested
@@ -76,7 +80,7 @@ module DNZ
 
     # Replace the results array with a paginated array
     def paginate_results
-      @results = WillPaginate::Collection.create(self.page, num_results_requested, self.result_count) do |pager|
+      @results = WillPaginate::Collection.create(self.page, per_page, self.result_count) do |pager|
         pager.replace @results
       end
     end

data/spec/dnz/client_spec.rb

@@ -4,151 +4,188 @@ require 'dnz/client'
 include DNZ
 
 describe Client do
-  before(:each) do
-    @client = Client.new('abc')
-    @client.stub!(:open) # make sure open is never called
-    @search = mock(:search)
-    DNZ::Search.stub!(:new).and_return(@search)
-  end
-  
-  describe 'APIs' do
-    describe 'v1' do
+  describe 'class' do
+    describe '::connect' do
       before do
-        @version = 'v1'
-        @client = Client.new('abc', @version)
-        @client.stub!(:open) # make sure open is never called
+        @mock_client = mock(:client)
+        Client.stub!(:new).and_return(@mock_client)
       end
       
-      describe 'search' do        
-        [:search_text,:api_key,:num_results,:start,:sort,:direction,:facets,:facet_num_results,:facet_start].each do |option|
-          it "should allow #{option}" do
-            lambda do
-              @client.send(:fetch, :search, {option => "test"})
-            end.should_not raise_error(ArgumentError)
-          end
-        end 
+      it 'should have no connection to begin with' do
+        Client.connection.should be_nil
       end
       
-      describe 'custom_search' do
-        it 'should require custom_search' do
-          lambda do
-            @client.send(:fetch, :custom_search, {}) 
-          end.should raise_error(ArgumentError, "Required argument missing: custom_search")
-        end
-        
-        [:search_text,:api_key,:num_results,:start,:sort,:direction].each do |option|
-          it "should allow #{option}" do
-            lambda do
-              @client.send(:fetch, :custom_search, {:custom_search => "test", option => "test"})
-            end.should_not raise_error(ArgumentError)
-          end
-        end
-        [:facets,:facet_num_results,:facet_start].each do |option|
-          it "should not allow #{option}" do
-            lambda do
-              @client.send(:fetch, :custom_search, {:custom_search => "test", option => "test"})
-            end.should raise_error(ArgumentError)
-          end
-        end
+      it 'should create a new client' do
+        Client.should_receive(:new).with('abc').and_return(@mock_client)
+        Client.connect('abc').should == @mock_client
+      end
+      
+      it 'should assign the new client to connection' do
+        Client.connect('abc')
+        Client.connection.should == @mock_client
       end
     end
     
-    describe 'v2' do
+    describe 'proxy methods' do
       before do
-        @version = 'v2'
-        @client = Client.new('abc', @version)
-        @client.stub!(:open) # make sure open is never called
+        @mock_client = mock(:client)
+        Client.stub!(:connection).and_return(@mock_client)
       end
       
-      describe 'search' do
-        [:search_text,:api_key,:num_results,:start,:sort,:direction,:facets,:facet_num_results,:facet_start].each do |option|
-          it "should allow #{option}" do
-            lambda do
-              @client.send(:fetch, :search, {})
-            end.should_not raise_error(ArgumentError)
-          end
-        end 
+      it 'should pass methods to client instance' do
+        @mock_client.should_receive(:test_method).with('test_argument')
+        Client.test_method('test_argument')
       end
-      
-      describe 'custom_search' do
-        it 'should require custom_search' do
-          lambda do
-            @client.send(:fetch, :custom_search, {}) 
-          end.should raise_error(ArgumentError, "Required argument missing: custom_search")
+    end
+  end
+  
+  describe 'instance' do
+    before(:each) do
+      @client = Client.new('abc')
+      @client.stub!(:open) # make sure open is never called
+      @search = mock(:search)
+      DNZ::Search.stub!(:new).and_return(@search)
+    end
+
+    describe 'APIs' do
+      describe 'v1' do
+        before do
+          @version = 'v1'
+          @client = Client.new('abc', @version)
+          @client.stub!(:open) # make sure open is never called
+        end
+
+        describe 'search' do        
+          [:search_text,:api_key,:num_results,:start,:sort,:direction,:facets,:facet_num_results,:facet_start].each do |option|
+            it "should allow #{option}" do
+              lambda do
+                @client.send(:fetch, :search, {option => "test"})
+              end.should_not raise_error(ArgumentError)
+            end
+          end 
         end
-        
-        [:search_text,:api_key,:num_results,:start,:sort,:direction].each do |option|
-          it "should allow #{option}" do
+
+        describe 'custom_search' do
+          it 'should require custom_search' do
             lambda do
-              @client.send(:fetch, :custom_search, {:custom_search => "test", option => "test"})
-            end.should_not raise_error(ArgumentError)
+              @client.send(:fetch, :custom_search, {}) 
+            end.should raise_error(ArgumentError, "Required argument missing: custom_search")
           end
+
+          [:search_text,:api_key,:num_results,:start,:sort,:direction].each do |option|
+            it "should allow #{option}" do
+              lambda do
+                @client.send(:fetch, :custom_search, {:custom_search => "test", option => "test"})
+              end.should_not raise_error(ArgumentError)
+            end
+          end
+          [:facets,:facet_num_results,:facet_start].each do |option|
+            it "should not allow #{option}" do
+              lambda do
+                @client.send(:fetch, :custom_search, {:custom_search => "test", option => "test"})
+              end.should raise_error(ArgumentError)
+            end
+          end
+        end
+      end
+
+      describe 'v2' do
+        before do
+          @version = 'v2'
+          @client = Client.new('abc', @version)
+          @client.stub!(:open) # make sure open is never called
+        end
+
+        describe 'search' do
+          [:search_text,:api_key,:num_results,:start,:sort,:direction,:facets,:facet_num_results,:facet_start].each do |option|
+            it "should allow #{option}" do
+              lambda do
+                @client.send(:fetch, :search, {})
+              end.should_not raise_error(ArgumentError)
+            end
+          end 
         end
-        [:facets,:facet_num_results,:facet_start].each do |option|
-          it "should allow #{option}" do
+
+        describe 'custom_search' do
+          it 'should require custom_search' do
             lambda do
-              @client.send(:fetch, :custom_search, {:custom_search => "test", option => "test"})
-            end.should_not raise_error(ArgumentError)
+              @client.send(:fetch, :custom_search, {}) 
+            end.should raise_error(ArgumentError, "Required argument missing: custom_search")
+          end
+
+          [:search_text,:api_key,:num_results,:start,:sort,:direction].each do |option|
+            it "should allow #{option}" do
+              lambda do
+                @client.send(:fetch, :custom_search, {:custom_search => "test", option => "test"})
+              end.should_not raise_error(ArgumentError)
+            end
+          end
+          [:facets,:facet_num_results,:facet_start].each do |option|
+            it "should allow #{option}" do
+              lambda do
+                @client.send(:fetch, :custom_search, {:custom_search => "test", option => "test"})
+              end.should_not raise_error(ArgumentError)
+            end
           end
         end
       end
     end
-  end
-  
 
-  describe '#search' do
-    it 'should create a new search object and return it' do
-      @client.search('*:*').should be(@search)
-    end
-  end
 
-  describe '#fetch' do
-    it 'should raise an error an invalid option is set' do
-      lambda do
-        @client.fetch(:search, :blahblah => 'dlfkgj')
-      end.should raise_error(ArgumentError)
+    describe '#search' do
+      it 'should create a new search object and return it' do
+        @client.search('*:*').should be(@search)
+      end
     end
 
-    it 'should call open with query string arguments' do
-      @client.should_receive(:open).with do |url|
-        url.should include('http://api.digitalnz.org/records/v1.xml/?')
-        url.should include('api_key=abc')
-        url.should include('search_text=%2A%3A%2A')
+    describe '#fetch' do
+      it 'should raise an error an invalid option is set' do
+        lambda do
+          @client.fetch(:search, :blahblah => 'dlfkgj')
+        end.should raise_error(ArgumentError)
       end
-      @client.fetch(:search, :search_text => '*:*')
-    end
-    
-    it 'should raise an InvalidApiKey error if the status is 401' do
-      @client.should_receive(:open).and_raise(OpenURI::HTTPError.new('401 Unauthorized', nil))
-      lambda do
+
+      it 'should call open with query string arguments' do
+        @client.should_receive(:open).with do |url|
+          url.should include('http://api.digitalnz.org/records/v1.xml/?')
+          url.should include('api_key=abc')
+          url.should include('search_text=%2A%3A%2A')
+        end
         @client.fetch(:search, :search_text => '*:*')
-      end.should raise_error(InvalidApiKeyError)
-    end
-  end
-  
-  describe '#categories' do
-    before do
-      @categories = mock(:categories)
-      @category = mock(:facet)
-      @category.stub!(:values).and_return(@categories)
-      @facets = mock(:facets)
-      @facets.stub!(:[]).with('category').and_return(@category)
-      @search.stub!(:facets).and_return(@facets)
-      @client.stub!(:search).and_return(@search)
-    end
-    
-    it 'should run a search for categories facet' do
-      @client.should_receive(:search).with('*:*', :facets => 'category', :facet_num_results => 100).and_return(@search)
-      @client.categories
-    end
+      end
 
-    it 'should run a search with custom_search' do
-      @client.should_receive(:search).with('*:*', :facets => 'category', :facet_num_results => 100, :custom_search => 'test').and_return(@search)
-      @client.categories(:custom_search => 'test')
+      it 'should raise an InvalidApiKey error if the status is 401' do
+        @client.should_receive(:open).and_raise(OpenURI::HTTPError.new('401 Unauthorized', nil))
+        lambda do
+          @client.fetch(:search, :search_text => '*:*')
+        end.should raise_error(InvalidApiKeyError)
+      end
     end
-    
-    it 'should return the categories facet' do
-      @client.categories.should == @categories
+
+    describe '#categories' do
+      before do
+        @categories = mock(:categories)
+        @category = mock(:facet)
+        @category.stub!(:values).and_return(@categories)
+        @facets = mock(:facets)
+        @facets.stub!(:[]).with('category').and_return(@category)
+        @search.stub!(:facets).and_return(@facets)
+        @client.stub!(:search).and_return(@search)
+      end
+
+      it 'should run a search for categories facet' do
+        @client.should_receive(:search).with('*:*', :facets => 'category', :facet_num_results => 100).and_return(@search)
+        @client.categories
+      end
+
+      it 'should run a search with custom_search' do
+        @client.should_receive(:search).with('*:*', :facets => 'category', :facet_num_results => 100, :custom_search => 'test').and_return(@search)
+        @client.categories(:custom_search => 'test')
+      end
+
+      it 'should return the categories facet' do
+        @client.categories.should == @categories
+      end
     end
   end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 9
-  version: 0.0.9
+  version: 0.1.0
 platform: ruby
 authors: 
 - Jeremy Wells
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-21 00:00:00 +12:00
+date: 2010-05-13 00:00:00 +12:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency