oai 0.2.1 → 0.3.0

data/lib/oai/client/response.rb

@@ -1,7 +1,9 @@
 module OAI
 
-  # An OAI::Response contains entries and a resumption token. If a resumption token is present, 
+  # An OAI::Response contains entries and a resumption token. If a resumption token is present,
   # then you must use it to fetch the rest of the entries for your query. For example:
+  #
+  # ```ruby
   #  # List all records in a given set
   #  client = OAI::Client.new 'http://my-oai-provider.example.com/oai'
   #  response = client.list_records :set => 'my_set_name'
@@ -13,14 +15,15 @@ module OAI
   #    # Note: You do not need to pass the options hash again, just the verb and the resumption token
   #    response = client.list_records :resumption_token => token if token
   #  end
-
+  # ```
   class Response
     include OAI::XPath
-    attr_reader :doc, :resumption_token
+    attr_reader :doc, :resumption_token, :resumption_block
 
-    def initialize(doc)
+    def initialize(doc, &resumption_block)
       @doc = doc
       @resumption_token = xpath(doc, './/resumptionToken')
+      @resumption_block = resumption_block
 
       # throw an exception if there was an error
       error = xpath_first(doc, './/error')

data/lib/oai/client/resumable.rb

@@ -0,0 +1,42 @@
+module OAI
+  module Resumable
+
+    class ResumptionWrapper
+      include Enumerable
+
+      def initialize(response)
+        @response = response
+        @resumption_block = response.resumption_block
+      end
+
+      def each(&block)
+        yield_from_response &block
+        while resumable?
+          @response = @resumption_block.call @response
+          yield_from_response &block
+        end
+      end
+
+      private
+
+      def yield_from_response(&block)
+        @response.each do |obj|
+          block.call(obj)
+        end
+      end
+
+      def resumable?
+        @response.resumption_token and not @response.resumption_token.empty?
+      end
+
+    end
+
+    def full
+      if @resumption_block.nil?
+        raise NotImplementedError.new("Resumption block not provided")
+      end
+      ResumptionWrapper.new(self)
+    end
+
+  end
+end

data/lib/oai/harvester/shell.rb

@@ -1,13 +1,12 @@
 module OAI
   module Harvester
-    # = OAI::Harvester::Shell
-    # 
     # A OAI-PMH client shell allowing OAI Harvesting to be configured in
-    # an interactive manner.  Typing 'oai' on the command line starts the
+    # an interactive manner.  Typing `oai` on the command line starts the
     # shell.  The first time the shell is run it will prompt for the following
     # configuration details:
-    # 1. A storage directory for all harvested records.  Harvests will be 
-    #    stored under this directory in a directory structure based on the 
+    #
+    # 1. A storage directory for all harvested records.  Harvests will be
+    #    stored under this directory in a directory structure based on the
     #    date of the harvest.
     # 2. A log file directory.
     # 3. Email address(es) for sending daily harvesting activity reports.
@@ -21,15 +20,15 @@ module OAI
     #
     # The shell automatically pulls down the list of sets in the repository, and
     # the supported metadata prefixes.  Making it very simple to setup harvests.
-    #  
+    #
     class Shell
       include Readline
-    
+
       def initialize(config)
         @conf = config
         @conf.sites ||= {} # Initialize sites hash there isn't one
       end
-    
+
       def start
         unless @conf.storage
           banner "Entering first-time setup"
@@ -54,9 +53,9 @@ module OAI
           end
         end
       end
-    
+
       private
-    
+
       def help
         banner "Commands:"
         puts "\tharvest site [date]     - Harvest site(s) manually"
@@ -68,7 +67,7 @@ module OAI
         puts "\tedit [site]             - Change settings for a provider site"
         puts "\texit                    - Exit the harvester shell.\n\n"
       end
-    
+
       def harvest(options)
         site, *date = options.split(/\s/)
         if @conf.sites.keys.include?(site)
@@ -80,7 +79,7 @@ module OAI
                 puts "Couldn't parse the date supplied"
                 return
               end
-            else 
+            else
               date = nil
             end
             harvester = Harvest.new(@conf, @conf.storage, date)
@@ -91,7 +90,7 @@ module OAI
         end
         puts # blank line
       end
-    
+
       def list(args = nil)
         if 'config' == args
           banner "Current Configuration"
@@ -104,7 +103,7 @@ module OAI
         end
         puts # blank line
       end
-    
+
       def info(args)
         banner "Provider Site Information"
         sites = args.split(/[,\s|\s|,]/)
@@ -115,21 +114,21 @@ module OAI
       rescue
         puts args + " doesn't appear to be configured, use list to see configured repositories."
       end
-    
+
       def new
         banner "Define New Harvesting Site"
         name, site = form
         @conf.sites[name] = site
         @conf.save
       end
-    
+
       def edit(name)
         banner "Edit Harvesting Site"
         name, site = form(name)
         @conf.sites[name] = site
         @conf.save
       end
-    
+
       def remove(site)
         if 'Y' == readline("Remove #{site}? (Y/N): ").upcase
           @conf.sites.delete(site)
@@ -149,14 +148,14 @@ module OAI
             end
           end
           site = @conf.sites[name] || {}
-      
+
           # URL
           url = prompt("url", site['url'])
           while(not (site['url'] = verify(url)))
             puts "Trouble contacting provider, bad url?"
             url = prompt("url", site['url'])
           end
-      
+
           # Metadata formats
           formats = metadata(site['url'])
           report "Repository supports [#{formats.join(', ')}] metadata formats."
@@ -187,15 +186,15 @@ module OAI
             puts "Must be daily, weekly, or monthly"
             period = expand_period(prompt("period", "daily"))
           end
-      
+
           site['period'] = period
-      
+
           return [name, site]
-        rescue 
+        rescue
           puts "Problem adding/updating provider, aborting. (#{$!})"
         end
       end
-    
+
       def config
         begin
           directory = prompt("storage directory", @conf.storage)
@@ -205,7 +204,7 @@ module OAI
 
           email = @conf.email.join(', ') rescue nil
           @conf.email = parse_emails(prompt("email", email))
-        
+
           @conf.mail_server = prompt("mail server", @conf.mail_server)
 
           logfile = prompt("log file(s) directory", @conf.logfile)
@@ -215,22 +214,22 @@ module OAI
           @conf.storage = directory
           @conf.logfile = logfile
           @conf.save
-        rescue 
+        rescue
           nil
         end
       end
-        
+
       def display(key, value, split = 40)
         (split - key.size).times { print " " } if key.size < split
         puts "#{key}: #{value}"
       end
-    
+
       def banner(str)
         puts "\n#{str}"
         str.size.times { print "-" }
         puts "\n"
       end
-      
+
       def report(str)
         puts "\n#{str}\n"
       end
@@ -240,7 +239,7 @@ module OAI
           print "\t"
         end
       end
-    
+
       def prompt(text, default = nil, split = 20)
         prompt_text = "#{text} [#{default}]: "
         (split - prompt_text.size).times { print " " } if prompt_text.size < split
@@ -248,7 +247,7 @@ module OAI
         raise RuntimeError.new("Exit loop") unless value
         return value.empty? ? default : value
       end
-    
+
       def verify(url)
         begin
           client = OAI::Client.new(url, :redirects => false)
@@ -264,7 +263,7 @@ module OAI
           end
         end
       end
-    
+
       def metadata(url)
         formats = []
         client = OAI::Client.new url
@@ -274,7 +273,7 @@ module OAI
         end
         formats
       end
-      
+
       def sets(url)
         sets = []
         client = OAI::Client.new url
@@ -292,35 +291,35 @@ module OAI
         end
         true
       end
-    
+
       def expand_period(str)
         return str if Config::PERIODS.include?(str)
         Config::PERIODS.each { |p| return p if p =~ /^#{str}/}
         nil
       end
-    
+
       def parse_emails(emails)
         return nil unless emails
         addresses = emails.split(/[,\s|\s|,]/)
       end
-        
+
       def list_config
         display("storage directory", @conf.storage, 20)
         display("email", @conf.email.join(', '), 20) if @conf.email
         display("mail server", @conf.mail_server, 20) if @conf.mail_server
         display("log location", @conf.logfile, 20) if @conf.logfile
       end
-    
+
       def list_sites
         banner "Sites"
         @conf.sites.each_key { |site| print_site(site) }
       end
-    
+
       def print_site(site)
         puts site
         @conf.sites[site].each { |k,v| display(k, v, 15)}
       end
-    
+
       def setup_cron
         banner "Scheduling Automatic Harvesting"
         puts "To activate automatic harvesting you must add an entry to"
@@ -330,9 +329,9 @@ module OAI
         puts "Windows users should use WinAt to schedule"
         puts "#{$0} to run every night.\n\n\n"
       end
-    
+
     end
 
   end
-end        
-      
+end
+

data/lib/oai/provider.rb

@@ -11,21 +11,21 @@ end
 
 %w{ response metadata_format resumption_token model partial_result
     response/record_response response/identify response/get_record
-    response/list_identifiers response/list_records 
+    response/list_identifiers response/list_records
     response/list_metadata_formats response/list_sets response/error
   }.each { |lib| require File.dirname(__FILE__) + "/provider/#{lib}" }
-  
+
 if defined?(ActiveRecord)
   require File.dirname(__FILE__) + "/provider/model/activerecord_wrapper"
   require File.dirname(__FILE__) + "/provider/model/activerecord_caching_wrapper"
 end
 
-# = OAI::Provider
+# # OAI::Provider
 #
-# Open Archives Initiative - Protocol for Metadata Harvesting see 
-# http://www.openarchives.org/ 
+# Open Archives Initiative - Protocol for Metadata Harvesting see
+# <http://www.openarchives.org/>
 #
-# == Features
+# ## Features
 # * Easily setup a simple repository
 # * Simple integration with ActiveRecord
 # * Dublin Core metadata format included
@@ -33,13 +33,14 @@ end
 # * Adaptable to any data source
 # * Simple resumption token support
 #
-# == Usage
+# ## Usage
 #
-# To create a functional provider either subclass Provider::Base, 
+# To create a functional provider either subclass {OAI::Provider::Base},
 # or reconfigure the defaults.
-# 
-# === Sub classing a provider
 #
+# ### Sub classing a provider
+#
+# ```ruby
 #  class MyProvider < Oai::Provider
 #    repository_name 'My little OAI provider'
 #    repository_url  'http://localhost/provider'
@@ -47,9 +48,11 @@ end
 #    admin_email 'root@localhost'   # String or Array
 #    source_model MyModel.new       # Subclass of OAI::Provider::Model
 #  end
+# ```
 #
-# === Configuring the default provider
+# ### Configuring the default provider
 #
+# ```ruby
 #  class Oai::Provider::Base
 #    repository_name 'My little OAI Provider'
 #    repository_url 'http://localhost/provider'
@@ -58,23 +61,27 @@ end
 #    sample_identifier 'oai:pubmedcentral.gov:13900'
 #    source_model MyModel.new
 #  end
+# ```
 #
 # The provider does allow a URL to be passed in at request processing time
 # in case the repository URL cannot be determined ahead of time.
 #
-# == Integrating with frameworks
+# ## Integrating with frameworks
 #
-# === Camping
+# ### Camping
 #
 # In the Models module of your camping application post model definition:
-# 
+#
+# ```ruby
 #   class CampingProvider < OAI::Provider::Base
 #     repository_name 'Camping Test OAI Repository'
 #     source_model ActiveRecordWrapper.new(YOUR_ACTIVE_RECORD_MODEL)
 #   end
+# ```
 #
 # In the Controllers module:
 #
+# ```ruby
 #   class Oai
 #     def get
 #       @headers['Content-Type'] = 'text/xml'
@@ -82,15 +89,17 @@ end
 #       provider.process_request(@input.merge(:url => "http:"+URL(Oai).to_s))
 #     end
 #   end
+# ```
 #
 # The provider will be available at "/oai"
 #
-# === Rails
+# ### Rails
 #
 # At the bottom of environment.rb create a OAI Provider:
 #
+# ```ruby
 #   # forgive the standard blog example.
-# 
+#
 #   require 'oai'
 #   class BlogProvider < OAI::Provider::Base
 #     repository_name 'My little OAI Provider'
@@ -100,9 +109,11 @@ end
 #     source_model OAI::Provider::ActiveRecordWrapper.new(Post)
 #     sample_identifier 'oai:pubmedcentral.gov:13900'
 #   end
+# ```
 #
 # Create a custom controller:
 #
+# ```ruby
 #   class OaiController < ApplicationController
 #     def index
 #       # Remove controller and action from the options.  Rails adds them automatically.
@@ -112,50 +123,54 @@ end
 #       render :text => response, :content_type => 'text/xml'
 #     end
 #   end
+# ```
 #
-# Special thanks to Jose Hales-Garcia for this solution. 
+# Special thanks to Jose Hales-Garcia for this solution.
 #
-# == Supporting custom metadata formats
+# ## Supporting custom metadata formats
 #
-# See Oai::Metadata for details.
-# 
-# == ActiveRecord Integration
+# See {OAI::MetadataFormat} for details.
 #
-# ActiveRecord integration is provided by the ActiveRecordWrapper class.
+# ## ActiveRecord Integration
+#
+# ActiveRecord integration is provided by the `ActiveRecordWrapper` class.
 # It takes one required paramater, the class name of the AR class to wrap,
 # and optional hash of options.
 #
 # Valid options include:
-# * timestamp_field - Specifies the model field to use as the update
-#   filter.  Defaults to 'updated_at'.
-# * limit -           Maximum number of records to return in each page/set.
-#   Defaults to 100.  The wrapper will paginate the result via resumption tokens.  
-#   Caution:  specifying too large a limit will adversely affect performance.
-# 
+#
+# * `timestamp_field` - Specifies the model field to use as the update
+#   filter.  Defaults to `updated_at`.
+# * `limit` -           Maximum number of records to return in each page/set.
+#   Defaults to 100.
+#   The wrapper will paginate the result via resumption tokens.
+#   _Caution:  specifying too large a limit will adversely affect performance._
+#
 # Mapping from a ActiveRecord object to a specific metadata format follows
 # this set of rules:
 #
-# 1. Does Model#to_{metadata_prefix} exist?  If so just return the result.
-# 2. Does the model provide a map via Model.map_{metadata_prefix}?  If so
+# 1. Does `Model#to_{metadata_prefix}` exist?  If so just return the result.
+# 2. Does the model provide a map via `Model.map_{metadata_prefix}`?  If so
 #    use the map to generate the xml document.
 # 3. Loop thru the fields of the metadata format and check to see if the
 #    model responds to either the plural, or singular of the field.
 #
 # For maximum control of the xml metadata generated, it's usually best to
-# provide a 'to_{metadata_prefix}' in the model.  If using Builder be sure
-# not to include any instruct! in the xml object.
-#  
-# === Explicit creation example 
+# provide a `to_{metadata_prefix}` in the model.  If using Builder be sure
+# not to include any `instruct!` in the xml object.
 #
+# ### Explicit creation example
+#
+# ```ruby
 #  class Post < ActiveRecord::Base
 #    def to_oai_dc
 #      xml = Builder::XmlMarkup.new
-#      xml.tag!("oai_dc:dc", 
+#      xml.tag!("oai_dc:dc",
 #        'xmlns:oai_dc' => "http://www.openarchives.org/OAI/2.0/oai_dc/",
 #        'xmlns:dc' => "http://purl.org/dc/elements/1.1/",
 #        'xmlns:xsi' => "http://www.w3.org/2001/XMLSchema-instance",
-#        'xsi:schemaLocation' => 
-#          %{http://www.openarchives.org/OAI/2.0/oai_dc/ 
+#        'xsi:schemaLocation' =>
+#          %{http://www.openarchives.org/OAI/2.0/oai_dc/
 #            http://www.openarchives.org/OAI/2.0/oai_dc.xsd}) do
 #          xml.tag!('oai_dc:title', title)
 #          xml.tag!('oai_dc:description', text)
@@ -166,24 +181,27 @@ end
 #      end
 #      xml.target!
 #    end
-#  end  
+#  end
+# ```
 #
-# === Mapping Example
+# ### Mapping Example
 #
+# ```ruby
 #  # Extremely contrived mapping
 #  class Post < ActiveRecord::Base
 #    def self.map_oai_dc
-#      {:subject => :tags, 
-#       :description => :text, 
-#       :creator => :user, 
+#      {:subject => :tags,
+#       :description => :text,
+#       :creator => :user,
 #       :contibutor => :comments}
 #    end
 #  end
+# ```
 #
 module OAI::Provider
   class Base
     include OAI::Provider
-    
+
     class << self
       attr_reader :formats
       attr_accessor :name, :url, :prefix, :email, :delete_support, :granularity, :model, :identifier, :description
@@ -192,11 +210,11 @@ module OAI::Provider
         @formats ||= {}
         @formats[format.prefix] = format
       end
-      
+
       def format_supported?(prefix)
         @formats.keys.include?(prefix)
       end
-      
+
       def format(prefix)
         if @formats[prefix].nil?
           raise OAI::FormatException.new
@@ -205,8 +223,8 @@ module OAI::Provider
         end
       end
 
-      protected 
-      
+      protected
+
       def inherited(klass)
         self.instance_variables.each do |iv|
           klass.instance_variable_set(iv, self.instance_variable_get(iv))
@@ -217,12 +235,12 @@ module OAI::Provider
       alias_method :repository_url,     :url=
       alias_method :record_prefix,      :prefix=
       alias_method :admin_email,        :email=
-      alias_method :deletion_support,   :delete_support=  
-      alias_method :update_granularity, :granularity=     
+      alias_method :deletion_support,   :delete_support=
+      alias_method :update_granularity, :granularity=
       alias_method :source_model,       :model=
       alias_method :sample_id,          :identifier=
       alias_method :extra_description,  :description=
-      
+
     end
 
     # Default configuration of a repository
@@ -235,7 +253,7 @@ module OAI::Provider
     Base.sample_id '13900'
 
     Base.register_format(OAI::Provider::Metadata::DublinCore.instance)
-    
+
     # Equivalent to '&verb=Identify', returns information about the repository
     def identify(options = {})
       Response::Identify.new(self.class, options).to_xml
@@ -246,33 +264,33 @@ module OAI::Provider
     def list_sets(options = {})
       Response::ListSets.new(self.class, options).to_xml
     end
-    
+
     # Equivalent to '&verb=ListMetadataFormats', returns a list of metadata formats
     # supported by the repository.
     def list_metadata_formats(options = {})
       Response::ListMetadataFormats.new(self.class, options).to_xml
     end
 
-    # Equivalent to '&verb=ListIdentifiers', returns a list of record headers that 
+    # Equivalent to '&verb=ListIdentifiers', returns a list of record headers that
     # meet the supplied criteria.
     def list_identifiers(options = {})
       Response::ListIdentifiers.new(self.class, options).to_xml
     end
-    
-    # Equivalent to '&verb=ListRecords', returns a list of records that meet the 
+
+    # Equivalent to '&verb=ListRecords', returns a list of records that meet the
     # supplied criteria.
     def list_records(options = {})
       Response::ListRecords.new(self.class, options).to_xml
     end
-    
+
     # Equivalent to '&verb=GetRecord', returns a record matching the required
-    # :identifier option 
+    # :identifier option
     def get_record(options = {})
       Response::GetRecord.new(self.class, options).to_xml
     end
-    
-    #  xml_response = process_verb('ListRecords', :from => 'October 1, 2005', 
-    #    :until => 'November 1, 2005') 
+
+    #  xml_response = process_verb('ListRecords', :from => 'October 1, 2005',
+    #    :until => 'November 1, 2005')
     #
     # If you are implementing a web interface using process_request is the
     # preferred way.
@@ -281,14 +299,14 @@ module OAI::Provider
 
         # Allow the request to pass in a url
         self.class.url = params['url'] ? params.delete('url') : self.class.url
-          
+
         verb = params.delete('verb') || params.delete(:verb)
-        
+
         unless verb and OAI::Const::VERBS.keys.include?(verb)
           raise OAI::VerbException.new
         end
-          
-        send(methodize(verb), params) 
+
+        send(methodize(verb), params)
 
       rescue => err
         if err.respond_to?(:code)
@@ -298,12 +316,12 @@ module OAI::Provider
         end
       end
     end
-    
+
     # Convert valid OAI-PMH verbs into ruby method calls
     def methodize(verb)
       verb.gsub(/[A-Z]/) {|m| "_#{m.downcase}"}.sub(/^\_/,'')
     end
-    
+
   end
-  
+
 end