dnz-client 0.0.4 → 0.0.5

data/History.txt

@@ -1,3 +1,9 @@
+=== 0.0.5 2009-09-15
+
+* Support for custom_search API calls.
+* Experimental support for beta API v2.
+* WARNING: Client.new signature has changed.
+
 === 0.0.4 2009-09-14
 
 * Bring memoizable from ActiveSupport into DNZ namespace.

data/lib/dnz/client.rb

@@ -23,7 +23,7 @@ module DNZ
 
     APIS = {
       :search => 'records/${version}.xml/',
-      :custom_search => 'custom_searches/${version}/${title}.xml'
+      :custom_search => 'custom_searches/${version}/${custom_search}.xml'
     }
 
     ARGS = {
@@ -37,9 +37,43 @@ module DNZ
           :direction,
           :facets,
           :facet_num_results,
-          :facet_start,
+          :facet_start
+        ]),
+        :custom_search => Set.new([
+          :custom_search,
+          :search_text,
+          :api_key,
+          :num_results,
+          :start,
+          :sort,
+          :direction
+        ])
+      },
+      :v2 => {
+        :search => Set.new([
+          :search_text,
+          :api_key,
+          :num_results,
+          :start,
+          :sort,
+          :direction,
+          :facets,
+          :facet_num_results,
+          :facet_start
+        ]),
+        :custom_search => Set.new([
+          :custom_search,
+          :search_text,
+          :api_key,
+          :num_results,
+          :start,
+          :sort,
+          :direction,
+          :facets,
+          :facet_num_results,
+          :facet_start
         ])
-      }
+      }      
     }
 
     # List of available facets that can be passed to search
@@ -56,7 +90,7 @@ module DNZ
     #   search.results.each do |result|
     #     puts result.title
     #   end
-    def initialize(api_key, base_url = 'http://api.digitalnz.org', version = 'v1')
+    def initialize(api_key, version = 'v1', base_url = 'http://api.digitalnz.org')
       @api_key = api_key
       @base_url = base_url
       @version = version
@@ -81,6 +115,7 @@ module DNZ
     # * <tt>:start</tt> - The starting offset of the results.
     # * <tt>:facets</tt> - The facets to return for this search.
     # * <tt>:filter</tt> - A hash of filters to apply to the results
+    # * <tt>:custom_search</tt> - The name of a custom search created at http://digitalnz.org
     #
     # ==== Example
     #   search = client.search('rubgy', :num_results => 50)
@@ -109,17 +144,12 @@ module DNZ
     def fetch(api, options = {})
       validate_options(api, options)
 
-      options = options.reverse_merge(:api_key => self.api_key)
-
-      #api_url = APIS[url]
-      #matches = (/\$\{(.*?)\}/)
-      #
-      #
-      #
-
-      # qs = options.map{|k,v| '%s=%s' % [k,v] }.join('&')
-      qs = options.to_query
-      url = self.base_url + '/' + APIS[api].gsub('${version}', self.version) + '?' + qs
+      options = options.reverse_merge(
+        :api_key => self.api_key,
+        :version => self.version
+      )
+      
+      url = create_url(api, options)
       
       begin
         open(url)
@@ -133,14 +163,40 @@ module DNZ
     end
 
     private
-
-    def validate_options(path, options = {})
+    
+    # Create a URL for a given API call with a hash of option
+    #
+    # * <tt>api</tt> - The api call to make. This must be listed in the APIS constant.
+    # * <tt>options</tt> - A hash of options.
+    def create_url(api, options)
       options = options.symbolize_keys
       
-      version_args = ARGS[@version.to_sym]
+      path = APIS[api].dup
+      variable_regex = /\$\{(.+?)\}/m
+      
+      while match = variable_regex.match(path)
+        variable_name = $1.to_sym
+                
+        if options.has_key?(variable_name)
+          path.sub!(variable_regex, options.delete(variable_name))
+        else
+          raise ArgumentError.new("Required argument missing: #{variable_name}")
+        end
+      end
+      
+      url = self.base_url + '/' + path
+      url + '?' + options.to_query
+    end
 
-      if version_args.has_key?(path) && !Set.new(options.keys).subset?(version_args[path])
-        raise ArgumentError.new("Valid options for #{path} are: #{version_args[path].to_a.join(', ')}, provided: #{options.keys.join(', ')}")
+    # Validate an options hash for a given api
+    def validate_options(api, options = {})
+      options = options.symbolize_keys
+      version_args = ARGS[@version.to_sym]
+      
+      if !version_args
+        raise ArgumentError.new("Invalid version API call: #{@version}, #{api}")
+      elsif version_args.has_key?(api) && !Set.new(options.keys).subset?(version_args[api])
+        raise ArgumentError.new("Valid options for #{api} are: #{version_args[api].to_a.join(', ')}, provided: #{options.keys.join(', ')}")
       end
     end
   end

data/lib/dnz/search.rb

@@ -4,6 +4,8 @@ require 'dnz/facet_array'
 require 'dnz/facet'
 require 'dnz/memoizable'
 
+# Load will_paginate if it's available
+# to provide pagination
 begin
   gem 'mislav-will_paginate' rescue nil
   require 'will_paginate/collection' rescue nil
@@ -18,6 +20,7 @@ module DNZ
   #   search = client.search('text')
   #   puts "%d results found on %d pages" % [search.result_count, search.pages]
   class Search
+    # The total number of results returned by the search
     attr_reader :result_count
     
     extend DNZ::Memoizable
@@ -88,9 +91,16 @@ module DNZ
         :pages => self.pages
       }.inspect
     end
+    
+    # Return true if this search is using a custom search engine
+    def custom_search?
+      !@search_options.has_key?(:custom_search)
+    end
 
     private
     
+    # Turn the filter hash into an array of strings
+    # in the format key:"value"
     def parsed_search_filter
       filter = @search_options[:filter]
       filter = {} unless filter.is_a?(Hash)
@@ -99,6 +109,7 @@ module DNZ
     end
     memoize :parsed_search_filter
     
+    # Join the search text with any filters with " AND "
     def parsed_search_text
       if parsed_search_filter.any?
         ([text] + parsed_search_filter).join(' AND ')
@@ -107,12 +118,15 @@ module DNZ
       end
     end
     
+    # The facets option gets turned into a comma separated string
     def parsed_search_facets
       search_facets = @search_options[:facets] || []
       search_facets = search_facets.join(',') if search_facets.is_a?(Array)
       search_facets
     end
     
+    # Turn the options into options acceptable for an API call.
+    # Removes the filter option and parses the other options.
     def parsed_search_options
       parsed_options = @search_options.dup
       parsed_options.delete(:filter)
@@ -124,16 +138,28 @@ module DNZ
     end
     memoize :parsed_search_options
 
+    # Return a Nokogiri document for the XML
     def doc
       @doc ||= Nokogiri::XML(@xml)
     end
+    
+    # Choose which API call to make, either search or
+    # custom_search if a custom search engine is specified.
+    def execute_action
+      if custom_search?
+        :search
+      else
+        :custom_search
+      end
+    end
 
+    # Execute the search by making the API call
     def execute
-      @doc = nil
-      @results = nil
-      @facets = nil
-      @xml = @client.send(:fetch, :search, parsed_search_options)
+      reset
+      
+      @xml = @client.send(:fetch, execute_action, parsed_search_options)
 
+      # Parse the results
       parse_attributes
       parse_facets
       parse_results
@@ -141,13 +167,22 @@ module DNZ
 
       self
     end
+    
+    # Reset important instance variables
+    def reset
+      @doc = nil
+      @results = nil
+      @facets = nil
+    end
 
+    # 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|
         pager.replace @results
       end
     end
 
+    # Parse important global attributes into instance variables
     def parse_attributes
       %w(num-results-requested result-count start).each do |node|
         if child = doc.root.xpath(node).first
@@ -158,13 +193,15 @@ module DNZ
       end
     end
 
+    # Parse the results into an array of DNZ::Result
     def parse_results
       @results = []
       doc.xpath('//results/result').each do |result_xml|
         @results << DNZ::Result.new(result_xml)
       end
     end
-
+    
+    # Parse the facets into an array of DNZ::FacetArray
     def parse_facets      
       @facets = FacetArray.new
 

data/lib/dnz.rb

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

data/spec/dnz/client_spec.rb

@@ -10,6 +10,91 @@ describe Client do
     @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
+      
+      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
+      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
+      
+      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 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
+  
 
   describe '#search' do
     it 'should create a new search object and return it' do

data/spec/spec.opts

@@ -1,4 +1,5 @@
 --colour
 --format progress
 --loadby mtime
---reverse
+--reverse
+--debugger

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dnz-client
 version: !ruby/object:Gem::Version 
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors: 
 - Jeremy Wells
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-14 00:00:00 +13:00
+date: 2009-10-15 00:00:00 +13:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency