dnz-client 0.0.2

data/History.txt

@@ -0,0 +1,4 @@
+=== 0.0.1 2009-07-14
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2009 Boost New Media (http://www.boost.co.nz)
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,21 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+License.txt
+Rakefile
+lib/dnz.rb
+lib/dnz/attributes.rb
+lib/dnz/client.rb
+lib/dnz/facet.rb
+lib/dnz/result.rb
+lib/dnz/search.rb
+script/console
+script/destroy
+script/generate
+spec/dnz/client_spec.rb
+spec/dnz/result_spec.rb
+spec/dnz/search_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+tasks/rspec.rake

data/PostInstall.txt

@@ -0,0 +1,3 @@
+For more information on DigitalNZ, see http://digitalnz.org
+
+

data/README.rdoc

@@ -0,0 +1,46 @@
+= DigitalNZ Client Library
+
+* http://github.com/boost/dnz-client
+
+== SYNOPSIS:
+
+  require 'dnz/client'
+  client = DNZ::Client.new('abcdefg') # API KEY
+  search = client.search('otago')
+  search.results.each do |result|
+    puts result.title
+  end
+
+== REQUIREMENTS:
+
+* Nokogiri
+* ActiveSupport
+
+== INSTALL:
+
+* sudo gem install dnz-client / sudo gem install boost-dnz-client
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Boost New Media (http:/www.boost.co.nz)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require './lib/dnz'
+
+Hoe.plugin :newgem
+# Hoe.plugin :website
+# Hoe.plugin :cucumberfeatures
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.spec 'dnz-client' do
+  self.developer 'Jeremy Wells', 'jeremy@boost.co.nz'
+  self.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  self.description = "Ruby library for accessing Digital New Zealand's search API (digitalnz.org)"
+  #self.rubyforge_name       = self.name # TODO this is default value
+  self.extra_deps         = [['activesupport','>= 2.0.2'], ['nokogiri', '>= 1.2.3']]
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# remove_task :default
+# task :default => [:spec, :features]

data/lib/dnz/attributes.rb

@@ -0,0 +1,9 @@
+module DNZ
+  module Attributes
+    def method_missing(symbol, *args)
+      if args.empty? && @attributes.has_key?(symbol.to_s)
+        @attributes[symbol.to_s]
+      end
+    end
+  end
+end

data/lib/dnz/client.rb

@@ -0,0 +1,131 @@
+require 'rubygems'
+require 'open-uri'
+require 'set'
+require 'active_support'
+require 'dnz/search'
+
+module DNZ
+  # This is a simple client for accessing the digitalnz.org API
+  # for searching New Zealand's digital content. It provides
+  # access to search results and facet information.
+  #
+  # Author:: Jeremy Wells, Boost New Media (http://www.boost.co.nz)
+  # Copyright:: Copyright (c) 2009 Boost New Media
+  # License:: MIT
+  class Client
+    # The dnz API key
+    attr_reader :api_key
+    # The base URL (defaults to http://api.digitalnz.org)
+    attr_reader :base_url
+    # The version of the API to use (defaults to v1)
+    attr_reader :version
+
+    APIS = {
+      :search => 'records/${version}.xml/',
+      :custom_search => 'custom_searches/${version}/${title}.xml'
+    }
+
+    ARGS = {
+      :search => Set.new([
+        :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
+    FACETS = [
+      :category, :content_partner, :creator, :language, :rights, :century, :decade, :year
+    ]
+
+    # Constructor method for the Client class. An API key must be provided.
+    # The base url and version default to "http://api.digitalnz.org" and "v1".
+    #
+    # ==== Example
+    #   client = DNZ::Client.new('abcdefghijklmnoq')
+    #   search = client.search('some text')
+    #   search.results.each do |result|
+    #     puts result.title
+    #   end
+    def initialize(api_key, base_url = 'http://api.digitalnz.org', version = 'v1')
+      @api_key = api_key
+      @base_url = base_url
+      @version = version
+    end
+
+    # Get a list of all categories using the 'category' facet.
+    #
+    # ==== Example
+    #   categories = client.categories
+    #   categories.each do |category|
+    #     puts category.name
+    #   end
+    def categories
+      search('*:*', :facets => 'category', :facet_num_results => 100).facets['category'].values
+    end
+
+    # Run a search using the digitalnz.org API.
+    #
+    # ==== Options
+    #
+    # * <tt>:num_results</tt> - The number of results to return in this call. Defaults to 20.
+    # * <tt>:start</tt> - The starting offset of the results.
+    # * <tt>:facets</tt> - The facets to return for this search.
+    #
+    # ==== Example
+    #   search = client.search('rubgy', :num_results => 50)
+    #   search.results.each_with_index do |result, index|
+    #     puts "#{index+1}: #{result.title}"
+    #   end
+    def search(text, options = {})
+      options.reverse_merge!(
+        :search_text => text,
+        :num_results => 20,
+        :start => 0
+      )
+
+      # Select the correct page
+      page = options.delete(:page)
+      options[:start] = (page-1) * options[:num_results] if page
+
+      DNZ::Search.new(self, options)
+    end  
+
+    # Make a direct call to the digitalnz.org API.
+    #
+    # * <tt>api</tt> - The api call to make. This must be listed in the APIS constant.
+    # * <tt>options</tt> - A hash of options to pass to the API call. These options must be defined in the ARGS constant.
+    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('&')
+      url = self.base_url + '/' + APIS[api].gsub('${version}', self.version) + '?' + qs
+      open(url)
+    end
+
+    private
+
+    def validate_options(path, options = {})
+      options.symbolize_keys!
+
+      if ARGS.has_key?(path) && !Set.new(options.keys).subset?(ARGS[path])
+        raise ArgumentError.new("Valid options for #{path} are: #{ARGS[path].to_a.join(', ')}, provided: #{options.keys.join(', ')}")
+      end
+    end
+  end
+end

data/lib/dnz/facet.rb

@@ -0,0 +1,48 @@
+require 'dnz/attributes'
+
+module DNZ
+  class Facet
+    attr_reader :name
+    attr_reader :values
+    attr_reader :search
+
+    def initialize(client, search, doc)
+      @name = doc.xpath('facet-field').text
+      @values = []
+      @search = search
+
+      doc.xpath('values').first.children.each do |value_doc|
+        value = DNZ::FacetValue.new(client, self, value_doc)
+        @values << value if value.valid?
+      end
+    end
+  end
+
+  class FacetValue
+    attr_reader :name, :count
+
+    def initialize(client, facet, doc)
+      @client = client
+      @facet = facet
+      @search_text = facet.search.text
+      @name = doc.xpath('name').text
+      @count = doc.xpath('num-results').text.to_i
+    end
+
+    def valid?
+      !self.name.blank?
+    end
+
+    def search(text = @search_text, options = {})
+      @client.search('%s:%s %s' % [@facet.name, self.name, text], options)
+    end
+
+    def inspect
+      {:name => self.name, :count => self.count}.inspect
+    end
+
+    def to_s
+      self.name
+    end
+  end
+end

data/lib/dnz/result.rb

@@ -0,0 +1,16 @@
+require 'dnz/attributes'
+
+module DNZ
+  # A DNZ::Search result record
+  class Result
+    include DNZ::Attributes
+    
+    def initialize(doc)
+      @attributes = {}
+
+      doc.children.each do |child|
+        @attributes[child.name.downcase.underscore] = child.text.to_s
+      end
+    end
+  end
+end

data/lib/dnz/search.rb

@@ -0,0 +1,143 @@
+require 'nokogiri'
+require 'dnz/result'
+require 'dnz/facet_array'
+require 'dnz/facet'
+
+begin
+  gem 'mislav-will_paginate' rescue nil
+  require 'will_paginate/collection' rescue nil
+rescue LoadError => e
+end
+
+module DNZ
+  # This class represents a digitalnz search API call. It should not be created directly. Instead
+  # use the <tt>Client.search</tt> method.
+  #
+  # === Example
+  #   search = client.search('text')
+  #   puts "%d results found on %d pages" % [search.result_count, search.pages]
+  class Search
+    attr_reader :result_count
+
+    # Constructor for Search class. Do not call this directly, instead use the <tt>Client.search</tt> method.
+    def initialize(client, search_options)
+      @client = client
+      @search_options = search_options
+
+      execute
+    end
+
+    # The text used for searching
+    def text
+      @search_options[:search_text]
+    end
+
+    # The search options passed to the digitalnz API
+    def options
+      @search_options
+    end
+
+    # An array of results. If the mislav-will_paginate gem is installed this will return a paginated array.
+    def results
+      if @results.nil?
+        parse_results
+        paginate_results if defined? WillPaginate::Collection
+      end
+
+      @results
+    end
+
+    # An array of facets.
+    #
+    # === Example
+    #   search = client.search('text', :facets => 'category')
+    #   categories = search.facets['category']
+    #   categories.each do |category|
+    #     puts '%d results in category %s' % [category.count, category.name]
+    #   end
+    def facets
+      parse_facets if @facets.nil?
+      @facets
+    end
+
+    # The current page of results, based on the number of requested results and the start value
+    # (see <tt>Client.search</tt>).
+    def page
+      (((@start || 0) / num_results_requested) + 1) rescue 1
+    end
+
+    # Set the page. This will update the search :start option and call the API again. The results array
+    # will be replaced with the new page of results.
+    def page=(new_page)
+      @search_options['start'] = (new_page-1) * num_results_requested
+      execute
+    end
+
+    # The number of pages available for the current search.
+    def pages
+      num_results_requested < result_count ? (result_count.to_f / num_results_requested).ceil : 0
+    end
+
+    # The number of results requested via the :num_results option (see <tt>Client.search</tt>).
+    def num_results_requested
+      @num_results_requested || 20
+    end
+
+    def to_s
+      {
+        :results => self.results.length,
+        :facets => self.facets.length,
+        :page => self.page,
+        :pages => self.pages
+      }.inspect
+    end
+
+    private
+
+    def doc
+      @doc ||= Nokogiri::XML(@xml)
+    end
+
+    def execute
+      @doc = nil
+      @results = nil
+      @facets = nil
+      @xml = @client.send(:fetch, :search, @search_options)
+
+      parse_attributes
+
+      self
+    end
+
+    def paginate_results
+      @results = WillPaginate::Collection.create(self.page, num_results_requested, self.result_count) do |pager|
+        pager.replace @results
+      end
+    end
+
+    def parse_attributes
+      %w(num-results-requested result-count start).each do |node|
+        if child = doc.root.xpath(node).first
+          name = child.name.downcase.underscore
+          value = child['type'] == 'integer' ? child.text.to_i : child.text
+          instance_variable_set('@%s' % name, value)
+        end
+      end
+    end
+
+    def parse_results
+      @results = []
+      doc.xpath('//results/result').each do |result_xml|
+        @results << DNZ::Result.new(result_xml)
+      end
+    end
+
+    def parse_facets
+      @facets = FacetArray.new
+
+      doc.xpath('//facets/facet').each do |facet_xml|
+        @facets << DNZ::Facet.new(@client, self, facet_xml)
+      end
+    end
+  end
+end

data/lib/dnz.rb

@@ -0,0 +1,8 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'dnz/client'
+
+module Dnz
+  VERSION = '0.0.2'
+end

data/script/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/dnz.rb'}"
+
+puts "Loading dnz gem"
+exec "#{irb} #{libs} --simple-prompt"

data/script/destroy

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/destroy'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Destroy.new.run(ARGV)

data/script/generate

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+APP_ROOT = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+begin
+  require 'rubigen'
+rescue LoadError
+  require 'rubygems'
+  require 'rubigen'
+end
+require 'rubigen/scripts/generate'
+
+ARGV.shift if ['--help', '-h'].include?(ARGV[0])
+RubiGen::Base.use_component_sources! [:rubygems, :newgem, :newgem_theme, :test_unit]
+RubiGen::Scripts::Generate.new.run(ARGV)

data/spec/dnz/client_spec.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+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 '#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)
+    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=*:*')
+      end
+      @client.fetch(:search, :search_text => '*:*')
+    end
+  end
+end

data/spec/dnz/result_spec.rb

@@ -0,0 +1,8 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'dnz/result'
+
+include DNZ
+
+describe Result do
+  
+end

data/spec/dnz/search_spec.rb

@@ -0,0 +1,55 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+require 'dnz/search'
+
+include DNZ
+
+describe Search do
+  before(:each) do
+    @xml = %Q{<?xml version="1.0"?>
+<response>
+  <results>
+    <result>
+      <attribute>test</attribute>
+    </result>
+  </results>
+  <facets>
+    <facet>
+      <value>test</value>
+    </facet>
+  </facets>
+</response>
+    }
+
+    @doc = Nokogiri::XML(@xml)
+    @client = mock(:client)
+    @result = mock(:result)
+    @facet = mock(:facet)
+    @options = {:search_text => 'test'}
+
+    Result.stub!(:new).and_return(@result)
+    Facet.stub!(:new).and_return(@facet)
+    
+    @client.stub!(:fetch).and_return(@xml)
+  end
+
+  describe 'Search.new' do
+    it 'should call @client.fetch' do
+      @client.should_receive(:fetch).with(:search, :search_text => 'test').and_return(@xml)
+      Search.new(@client, @options)
+    end
+
+    it 'should create one result' do
+      Result.should_receive(:new).and_return(@result)
+      Search.new(@client, @options).results.should == [@result]
+    end
+
+    it 'should create one facet' do
+      Facet.should_receive(:new).and_return(@facet)
+      Search.new(@client, @options).facets.should == [@facet]
+    end
+
+    it 'should return facets as a FacetArray' do
+      Search.new(@client, @options).facets.should be_a(FacetArray)
+    end
+  end
+end

data/spec/spec.opts

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

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require File.expand_path(File.dirname(__FILE__) + '/../lib/dnz')
+require 'spec/matchers'
+require 'rubygems'
+
+include Spec::Matchers
+
+Spec::Runner.configure do |config|
+   
+end

data/tasks/rspec.rake

@@ -0,0 +1,21 @@
+begin
+  require 'spec'
+rescue LoadError
+  require 'rubygems'
+  require 'spec'
+end
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts <<-EOS
+To use rspec for testing you must install rspec gem:
+    gem install rspec
+EOS
+  exit(0)
+end
+
+desc "Run the specs under spec"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ['--options', "spec/spec.opts"]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification 
+name: dnz-client
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Jeremy Wells
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-12 00:00:00 +13:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.0.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.3
+    version: 
+description: Ruby library for accessing Digital New Zealand's search API (digitalnz.org)
+email: 
+- jeremy@boost.co.nz
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- License.txt
+files: 
+- History.txt
+- Manifest.txt
+- PostInstall.txt
+- README.rdoc
+- License.txt
+- Rakefile
+- lib/dnz.rb
+- lib/dnz/attributes.rb
+- lib/dnz/client.rb
+- lib/dnz/facet.rb
+- lib/dnz/result.rb
+- lib/dnz/search.rb
+- script/console
+- script/destroy
+- script/generate
+- spec/dnz/client_spec.rb
+- spec/dnz/result_spec.rb
+- spec/dnz/search_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- tasks/rspec.rake
+has_rdoc: true
+homepage: http://github.com/boost/dnz-client
+licenses: []
+
+post_install_message: PostInstall.txt
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: dnz-client
+rubygems_version: 1.3.3
+signing_key: 
+specification_version: 3
+summary: ""
+test_files: []
+