sru 0.0.1

data/lib/sru.rb

@@ -0,0 +1,8 @@
+# allow people to require sru and get all the goodies
+
+require 'sru/client'
+require 'sru/explain'
+require 'sru/search_retrieve'
+require 'sru/scan'
+require 'sru/term'
+require 'sru/exception'

data/lib/sru/client.rb

@@ -0,0 +1,95 @@
+require 'uri'
+require 'cgi'
+require 'net/http'
+require 'rexml/document'
+
+module SRU
+
+  # A client for issuing requests to a particular SRU server.
+  # SRU is a RESTlike information retrieval protocol detailed at
+  # http://www.loc.gov/standards/sru/
+  
+  class Client
+
+    # creates a client object which will automatically perform an
+    # explain request to determine the version to be used in 
+    # subsequent requests.
+    
+    def initialize(base)
+      @server = URI.parse base
+
+      # stash this away for future requests
+      @version = self.explain.version
+    end
+
+
+    # Send an explain request to the SRU server and return a 
+    # SRU::ExplainResponse object.
+    #
+    # client = SRU::Client.new 'http://sru.example.com'
+    # explain = client.explain
+    
+    def explain
+      doc = get_doc(:operation => 'explain')
+      return ExplainResponse.new(doc)
+    end
+
+
+    # Send a searchRetrieve request to the SRU server and return
+    # a SRU::SearchResponse object. The first argument is the required 
+    # query option. Any remaining searchRetrieve options can be passed 
+    # as an optional second argument. 
+    # 
+    #   client = SRU::Client.new 'http://example.com/sru'
+    #   response = client.search_retrieve('mark twain', maximumRecords => 1)
+    
+    def search_retrieve(query, options={})
+      options['query'] = query
+      options['operation'] = 'searchRetrieve'
+      doc = get_doc(options)
+      return SearchResponse.new(doc)
+    end
+
+
+    # Send a scan request to the SRU server and return a SRU::ScanResponse
+    # object. You must supply the first parameter which is the searchClause.
+    # Other SRU options can be sent in a hash as the seond argument.
+    #
+    #   scan_response = client.scan 'title
+   
+    def scan(clause, options={})
+      options['scanClause'] = clause
+      options['operation'] = 'scan'
+      doc = get_doc(options)
+      return ScanResponse.new(doc)
+    end
+
+    private
+
+    # helper to fetch xml responses from the sru server
+    # given a set of options
+   
+    def get_doc(hash)
+      # all requests get a version
+      hash['version'] = @version 
+
+      # don't want to monkey with the original
+      uri = @server.clone
+
+      # no ruby class for building a query string!?!?
+      # probably just wasn't looking in the right place
+      parts = hash.entries.map { |entry| 
+        "#{entry[0]}=#{CGI.escape(entry[1].to_s)}"
+      }
+      uri.query = parts.join('&')
+
+      # fetch the xml and build/return a document object from it
+      begin
+        xml = Net::HTTP.get(uri)
+        return REXML::Document.new(xml)
+      rescue 
+        raise SRU::Exception, "exception during SRU operation", caller
+      end
+    end
+  end
+end

data/lib/sru/exception.rb

@@ -0,0 +1,5 @@
+# wrapper for exceptions that happen during an sru operation
+module SRU
+  class Exception < RuntimeError 
+  end
+end

data/lib/sru/explain.rb

@@ -0,0 +1,16 @@
+require 'sru/response'
+
+module SRU
+  class ExplainResponse < Response
+    def version
+      version = xpath('.//zs:explainResponse/zs:version')
+      return version if version
+
+      # also look here 
+      info = xpath_first('.//serverInfo')
+      return info.attributes['version'] if info
+      
+      return nil
+    end
+  end
+end

data/lib/sru/response.rb

@@ -0,0 +1,38 @@
+require 'rexml/xpath'
+
+module SRU
+
+  # base class for all SRU responses
+  class Response
+    attr_reader :doc
+
+    # namespaces for use in xpath queries
+    @@namespaces = {'zs' => 'http://www.loc.gov/zing/srw/'}
+
+    def initialize(doc)
+      @doc = doc
+    end
+
+    protected
+   
+    # get all nodes that match an xpath
+    def xpath_all(path)
+      return REXML::XPath.match(@doc, path, @@namespaces)
+    end
+
+    # get the first node that matches an xpath
+    def xpath_first(path)
+      elements = xpath_all(path)
+      return elements[0] if elements != nil
+      return nil
+    end
+
+    # get the text inside the first node that matches the xpath 
+    def xpath(path)
+      e = xpath_first(path)
+      return e.text if e != nil
+      return nil
+    end
+  end
+
+end

data/lib/sru/scan.rb

@@ -0,0 +1,16 @@
+require 'sru/response'
+
+module SRU
+
+  # A wrapper for the scan response from a SRU server.
+  class ScanResponse < Response
+    include Enumerable
+
+    def each
+      for term_node in xpath_all('.//zs:term')
+        yield Term.new(term_node) 
+      end
+    end
+  end
+
+end

data/lib/sru/search_retrieve.rb

@@ -0,0 +1,30 @@
+require 'sru/response'
+
+module SRU
+  
+  # An iterator for search results which allows you to do stuff like:
+  #
+  # client = SRU::Client.new 'http://sru.example.com'
+  # for record in client.search_retrieve('Mark Twain')
+  #   puts record 
+  # end
+  
+  class SearchResponse < Response
+    include Enumerable
+
+    def number_of_records
+      return Integer(xpath('.//zs:numberOfRecords'))
+    end
+
+    # Returns the contents of each recordData element in a 
+    # SRU searchRetrieve response.
+   
+    def each
+      for record_data in xpath_all('.//zs:recordData')
+        if record_data.elements.size > 0
+          yield record_data.elements[1]
+        end
+      end
+    end
+  end
+end

data/lib/sru/term.rb

@@ -0,0 +1,17 @@
+module SRU
+
+  # a class for representing a term in the response from a sru server
+  class Term < Response
+    attr_accessor :value, :number_of_records, :displayTerm, :whereInList, 
+      :extraTermData
+
+    def initialize(element)
+      super element
+      @value = xpath('value')
+      @number_of_records = xpath('numberOfRecords')
+      @display_term = xpath('displayTerm')
+      @whereInList = xpath('whereInList')
+      @extraTermData = xpath_first('extraTermData')
+    end
+  end
+end

data/test.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift 'lib'
+require 'test/unit'
+require 'sru'
+
+class ClientTests < Test::Unit::TestCase
+
+  def test_explain
+    client = SRU::Client.new 'http://z3950.loc.gov:7090/voyager'
+    explain = client.explain
+    assert_equal SRU::ExplainResponse, explain.class
+    assert_equal '1.1', explain.version
+  end
+
+  def test_search_retrieve
+    client = SRU::Client.new 'http://z3950.loc.gov:7090/voyager'
+    results = client.search_retrieve 'twain', :maximumRecords => 5
+    assert_equal 5, results.entries.size
+    assert results.number_of_records > 2000
+    assert_equal REXML::Element, results.entries[0].class
+    assert_equal 'record', results.entries[0].name
+
+    # hopefully there isn't a document that matches this :)
+    results = client.search_retrieve 'fidkidkdiejfl'
+    assert_equal 0, results.entries.size
+  end
+
+  def test_scan
+    # this scan response appears to be canned might need to change
+    client = SRU::Client.new 'http://tweed.lib.ed.ac.uk:8080/elf/search/copac'
+    scan = client.scan('foobar')
+    assert scan.entries.size > 0
+    assert_equal SRU::Term, scan.entries[0].class
+    assert_equal 'low', scan.entries[0].value
+    assert_equal '1', scan.entries[0].number_of_records
+  end
+
+  def test_xml_exception
+    assert_raise(SRU::Exception) {SRU::Client.new 'http://www.google.com'}
+  end
+
+  def test_http_exception
+    assert_raise(SRU::Exception) {SRU::Client.new 'http://example.com'}
+  end
+
+end
+
+

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: sru
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+date: 2006-04-16 00:00:00 -05:00
+summary: talk to sru servers with ruby
+require_paths: 
+  - lib
+email: ehs@pobox.com
+homepage: http://www.textualize.com/sruby
+rubyforge_project: 
+description: 
+autorequire: sru
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+  - Ed Summers
+files: 
+  - lib/sru
+  - lib/sru.rb
+  - lib/sru/client.rb
+  - lib/sru/exception.rb
+  - lib/sru/explain.rb
+  - lib/sru/response.rb
+  - lib/sru/scan.rb
+  - lib/sru/search_retrieve.rb
+  - lib/sru/term.rb
+test_files: 
+  - test.rb
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: []
+dependencies: []