fieldhand 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fe77387e599f04fe11981420174c0c53c6f1b3ce
-  data.tar.gz: f3bc88686b42bca448c52a06988273dcae890b8f
+  metadata.gz: cbb2e358fe735e190c98cdbb891d1e061ac9c94a
+  data.tar.gz: 64d94a760f881779790518e59a9508a1678d2be2
 SHA512:
-  metadata.gz: aac19ca6cdda6acc837c4d8f2e33874fccaa30ee91b3e78e9f0e0a5948b93712785507e960a3c13cfa55da963695b7ce695ddd86333358041335868ee6dca6bd
-  data.tar.gz: e1dfdb2adf541cf2a4dc2c3cfbe39da2b5843595b484ff6a7fcf31f22694431a38b09dcbbbc855d6ee3426ad789ce3fcea45f4263f215b62001be4cf076c8f48
+  metadata.gz: 59ba22ea64add43e36fa2dab85230818515950ca78ddaa4e9db6fb322de59b9b59ecf7ae4fcbdc3cf85f177ebc084773bfaf96f86da15e5843b148296e529de6
+  data.tar.gz: 114f1acb87901c6935dea29b9b03e7d115ca937486f069ef4af939a1f3a39592fe4a9d9abb50557ac7ff8ac9f27676f6b7cfb619a79cb9313aeb82f6b46e73ec

data/README.md

@@ -2,7 +2,7 @@
 
 A Ruby library for harvesting metadata from [OAI-PMH](https://www.openarchives.org/OAI/openarchivesprotocol.html) repositories.
 
-**Current version:** 0.3.0  
+**Current version:** 0.3.1  
 **Supported Ruby versions:** 1.8.7, 1.9.2, 1.9.3, 2.0, 2.1, 2.2
 
 ## Installation

data/lib/fieldhand/arguments.rb

@@ -2,6 +2,16 @@ require 'fieldhand/datestamp'
 
 module Fieldhand
   # A class for converting Fieldhand arguments into OAI-PMH query parameters.
+  #
+  # Specifically:
+  #
+  # * :metadata_prefix
+  # * :resumption_token
+  # * :from
+  # * :until
+  # * :set
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#HTTPRequestFormat
   class Arguments
     VALID_KEYS = {
       :metadata_prefix => 'metadataPrefix',
@@ -13,10 +23,32 @@ module Fieldhand
 
     attr_reader :options
 
+    # Return a new `Arguments` with the given `Hash`.
     def initialize(options = {})
       @options = options
     end
 
+    # Return a query as a `Hash` suitable for encoding as a query string in an OAI-PMH request.
+    #
+    # Converts arguments passed with symbol keys into the corresponding strings as defined in the OAI-PMH protocol,
+    # converting values into the appropriate format (e.g. `Time`s, `Date`s, `MetadataFormat`s and `Set`s into strings).
+    #
+    # Defaults to returning a metadata prefix of "oai_dc".
+    #
+    # Raises an `ArgumentError` if an unknown argument is encountered.
+    #
+    # # Examples
+    #
+    # ```
+    # Fieldhand::Arguments.new(:metadata_prefix => 'xoai', :from => Date.new(2001, 1, 1)).to_query
+    # #=> { "metadataPrefix" => "xoai", "from" => "2001-01-01" }
+    #
+    # Fieldhand::Arguments.new(:until => Time.utc(2001, 1, 1, 12, 0, 0)).to_query
+    # #=> { "metadataPrefix"=>"oai_dc", "until" => "2001-01-01T12:00:00Z" }
+    #
+    # Fieldhand::Arguments.new(:foo => "bar").to_query
+    # # ArgumentError: unknown argument: foo
+    # ```
     def to_query
       options.inject(defaults) do |query, (key, value)|
         raise ::ArgumentError, "unknown argument: #{key}" unless VALID_KEYS.key?(key)
@@ -27,12 +59,12 @@ module Fieldhand
       end
     end
 
+    private
+
     def defaults
       { 'metadataPrefix' => 'oai_dc' }
     end
 
-    private
-
     def convert_value(key, value)
       return value.to_s unless key == :from || key == :until
 

data/lib/fieldhand/datestamp.rb

@@ -4,6 +4,10 @@ require 'time'
 module Fieldhand
   # A class to handle datestamps of varying granularity.
   class Datestamp
+    # Return either a `Date` or `Time` for the given string datestamp.
+    #
+    # As repositories may only support date-level granularity rather than time-level granularity, we need to handle both
+    # types of datestamp.
     def self.parse(datestamp)
       if datestamp.size == 10
         ::Date.strptime(datestamp)
@@ -12,14 +16,21 @@ module Fieldhand
       end
     end
 
+    # Return a string UTC datestamp given a string, `Date`, `Time` or anything responding to `xmlschema`.
+    #
+    # The granularity of the resulting datestamp depends on the input type:
+    #
+    # * Strings are returned untouched (assuming they are already formatted datestamps)
+    # * Dates will return a date-level granularity datestamp, e.g. 2001-01-01
+    # * Times will return a time-level granularity UTC datestamp, e.g. 2001-01-01T00:00:00Z
+    # * DateTimes will return a time-level granularity UTC datestamp, e.g. 2001-01-01T00:00:00Z
+    # * Anything else is assumed to respond to `xmlschema`
     def self.unparse(datestamp)
       case datestamp
-      when ::String
-        datestamp
-      when ::Date
-        datestamp.strftime
-      when ::Time
-        datestamp.utc.xmlschema
+      when ::String then datestamp
+      when ::DateTime then unparse(::Time.xmlschema(datestamp.to_s))
+      when ::Date then datestamp.strftime
+      when ::Time then datestamp.utc.xmlschema
       else
         datestamp.xmlschema
       end

data/lib/fieldhand/get_record_parser.rb

@@ -0,0 +1,23 @@
+require 'fieldhand/record'
+
+module Fieldhand
+  # A parser for GetRecord responses
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#GetRecord
+  class GetRecordParser
+    attr_reader :response_parser
+
+    # Return a new parser populated with the given response parser.
+    def initialize(response_parser)
+      @response_parser = response_parser
+    end
+
+    # Return an array of `Record`s found in the response.
+    def items
+      response_parser.
+        root.
+        locate('GetRecord/record').
+        map { |item| Record.new(item, response_parser.response_date) }
+    end
+  end
+end

data/lib/fieldhand/header.rb

@@ -15,27 +15,38 @@ module Fieldhand
   class Header
     attr_reader :element, :response_date
 
+    # Return a new Header with the given element and an optional response date.
+    #
+    # Defaults the response date to the current time.
     def initialize(element, response_date = Time.now)
       @element = element
       @response_date = response_date
     end
 
+    # Test whether this item is marked as deleted or not.
+    #
+    # Note that a repository's support for deleted records can be interrogated through the `Identify` request, see
+    # https://www.openarchives.org/OAI/openarchivesprotocol.html#DeletedRecords
     def deleted?
       status == 'deleted'
     end
 
+    # Return the optional status of this item.
     def status
       element['status']
     end
 
+    # Return the unique identifier of this item.
     def identifier
       @identifier ||= element.identifier.text
     end
 
+    # Return the UTC datestamp of this item.
     def datestamp
       @datestamp ||= Datestamp.parse(element.datestamp.text)
     end
 
+    # Return any set memberships of this item.
     def sets
       @sets ||= element.locate('setSpec/^String')
     end

data/lib/fieldhand/identify.rb

@@ -8,43 +8,71 @@ module Fieldhand
   class Identify
     attr_reader :element, :response_date
 
+    # Return a new Identify with the given element and optional response date.
+    #
+    # Defaults the response date to the current time.
     def initialize(element, response_date = Time.now)
       @element = element
       @response_date = response_date
     end
 
+    # Return the human readable name for the repository.
     def name
       @name ||= element.repositoryName.text
     end
 
+    # Return the base URL of the repository as a URI.
+    #
+    # See https://www.openarchives.org/OAI/openarchivesprotocol.html#HTTPRequestFormat
     def base_url
       @base_url ||= URI(element.baseURL.text)
     end
 
+    # Return the version of the OAI-PMH protocol supported by the repository as a string.
     def protocol_version
       @protocol_version ||= element.protocolVersion.text
     end
 
+    # Return the guaranteed lower limit of all datestamps recording changes, modifications, or deletions in the
+    # repository as a `Date` or `Time` depending on the granularity of the repository.
     def earliest_datestamp
       @earliest_datestamp ||= Datestamp.parse(element.earliestDatestamp.text)
     end
 
+    # Return the manner in which the repository supports the notion of deleted records as a string.
+    #
+    # Possible values are:
+    #
+    # * no
+    # * transient
+    # * persistent
+    #
+    # See https://www.openarchives.org/OAI/openarchivesprotocol.html#DeletedRecords
     def deleted_record
       @deleted_record ||= element.deletedRecord.text
     end
 
+    # Return the finest harvesting granularity supported by the repository. The legitimate values are YYYY-MM-DD and
+    # YYYY-MM-DDThh:mm:ssZ with meanings as defined in ISO 8601.
+    #
+    # See http://www.w3.org/TR/NOTE-datetime
     def granularity
       @granularity ||= element.granularity.text
     end
 
+    # Return any e-mail addresses of administrators of the repository as an array of strings.
     def admin_emails
       @admin_emails ||= element.locate('adminEmail/^String')
     end
 
+    # Return any compression encodings supported by the repository as an array of strings.
     def compression
       @compression ||= element.locate('compression/^String')
     end
 
+    # Return any raw description elements used by communities to describe their repositories as an array of strings.
+    #
+    # As these can be in any format, Fieldhand does not attempt to parse the elements but leaves that to users.
     def descriptions
       @descriptions ||= element.locate('description')
     end

data/lib/fieldhand/identify_parser.rb

@@ -0,0 +1,26 @@
+require 'fieldhand/identify'
+
+module Fieldhand
+  # A parser for Identify responses.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#Identify
+  class IdentifyParser
+    attr_reader :response_parser
+
+    # Return a new parser for the given response parser.
+    def initialize(response_parser)
+      @response_parser = response_parser
+    end
+
+    # Return an array of `Identify`s found in the response.
+    #
+    # In reality, there will only ever be at most one `Identify` in a response but having a consistent interface with
+    # the other parsers keeps the supporting code simpler.
+    def items
+      response_parser.
+        root.
+        locate('Identify').
+        map { |item| Identify.new(item, response_parser.response_date) }
+    end
+  end
+end

data/lib/fieldhand/list_identifiers_parser.rb

@@ -0,0 +1,23 @@
+require 'fieldhand/header'
+
+module Fieldhand
+  # A parser for ListIdentifiers responses.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#ListIdentifiers
+  class ListIdentifiersParser
+    attr_reader :response_parser
+
+    # Return a new parser for the given response parser.
+    def initialize(response_parser)
+      @response_parser = response_parser
+    end
+
+    # Return an array of `Header`s found in the response.
+    def items
+      response_parser.
+        root.
+        locate('ListIdentifiers/header').
+        map { |item| Header.new(item, response_parser.response_date) }
+    end
+  end
+end

data/lib/fieldhand/list_metadata_formats_parser.rb

@@ -0,0 +1,23 @@
+require 'fieldhand/metadata_format'
+
+module Fieldhand
+  # A parser for ListMetadataFormats responses.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#ListMetadataFormats
+  class ListMetadataFormatsParser
+    attr_reader :response_parser
+
+    # Return a parser for the given response parser.
+    def initialize(response_parser)
+      @response_parser = response_parser
+    end
+
+    # Return an array of `MetadataFormat`s found in the response.
+    def items
+      response_parser.
+        root.
+        locate('ListMetadataFormats/metadataFormat').
+        map { |item| MetadataFormat.new(item, response_parser.response_date) }
+    end
+  end
+end

data/lib/fieldhand/list_records_parser.rb

@@ -0,0 +1,23 @@
+require 'fieldhand/record'
+
+module Fieldhand
+  # A parser for ListRecords responses.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#ListRecords
+  class ListRecordsParser
+    attr_reader :response_parser
+
+    # Return a parser for the given response body.
+    def initialize(response_parser)
+      @response_parser = response_parser
+    end
+
+    # Return an array of `Record`s found in the response.
+    def items
+      response_parser.
+        root.
+        locate('ListRecords/record').
+        map { |item| Record.new(item, response_parser.response_date) }
+    end
+  end
+end

data/lib/fieldhand/list_sets_parser.rb

@@ -0,0 +1,23 @@
+require 'fieldhand/set'
+
+module Fieldhand
+  # A parser for ListSets responses.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#ListSets
+  class ListSetsParser
+    attr_reader :response_parser
+
+    # Return a new parser for the given response parser.
+    def initialize(response_parser)
+      @response_parser = response_parser
+    end
+
+    # Return an array of `Set`s found in the response.
+    def items
+      response_parser.
+        root.
+        locate('ListSets/set').
+        map { |item| Set.new(item, response_parser.response_date) }
+    end
+  end
+end

data/lib/fieldhand/logger.rb

@@ -6,6 +6,7 @@ module Fieldhand
   module Logger
     module_function
 
+    # Return a new `Logger` that logs to the null device on this platform.
     def null
       ::Logger.new(null_device)
     end

data/lib/fieldhand/metadata_format.rb

@@ -7,23 +7,32 @@ module Fieldhand
   class MetadataFormat
     attr_reader :element, :response_date
 
+    # Return a new Metadata Format for the given element with an optional response date.
+    #
+    # The response date defaults to the current time.
     def initialize(element, response_date = Time.now)
       @element = element
       @response_date = response_date
     end
 
+    # Return the prefix as a string representation of the format.
+    #
+    # This makes it possible to pass a Metadata Format to methods that expect a string metadata prefix.
     def to_s
       prefix
     end
 
+    # Return the string metadata prefix for the format.
     def prefix
       @prefix ||= element.metadataPrefix.text
     end
 
+    # Return the location of an XML Schema describing the format as a URI.
     def schema
       @schema ||= URI(element.schema.text)
     end
 
+    # Return the XML Namespace URI for the format.
     def namespace
       @namespace ||= URI(element.metadataNamespace.text)
     end

data/lib/fieldhand/paginator.rb

@@ -1,40 +1,24 @@
-require 'fieldhand/datestamp'
 require 'fieldhand/logger'
-require 'ox'
+require 'fieldhand/response_parser'
 require 'cgi'
 require 'net/http'
 require 'uri'
 
 module Fieldhand
   NetworkError = ::Class.new(::StandardError)
-  ProtocolError = ::Class.new(::StandardError)
-  BadArgumentError = ::Class.new(ProtocolError)
-  BadResumptionTokenError = ::Class.new(ProtocolError)
-  BadVerbError = ::Class.new(ProtocolError)
-  CannotDisseminateFormatError = ::Class.new(ProtocolError)
-  IdDoesNotExistError = ::Class.new(ProtocolError)
-  NoRecordsMatchError = ::Class.new(ProtocolError)
-  NoMetadataFormatsError = ::Class.new(ProtocolError)
-  NoSetHierarchyError = ::Class.new(ProtocolError)
 
   # An abstraction over interactions with an OAI-PMH repository, handling requests, responses and paginating over
   # results using a resumption token.
   #
   # See https://www.openarchives.org/OAI/openarchivesprotocol.html#FlowControl
   class Paginator
-    ERROR_CODES = {
-      'badArgument' => BadArgumentError,
-      'badResumptionToken' => BadResumptionTokenError,
-      'badVerb' => BadVerbError,
-      'cannotDisseminateFormat' => CannotDisseminateFormatError,
-      'idDoesNotExist' => IdDoesNotExistError,
-      'noRecordsMatch' => NoRecordsMatchError,
-      'noMetadataFormats' => NoMetadataFormatsError,
-      'noSetHierarchy' => NoSetHierarchyError
-    }.freeze
-
     attr_reader :uri, :logger, :http
 
+    # Return a new paginator for the given repository base URI and optional logger.
+    #
+    # The URI can be passed as either a `URI` or something that can be parsed as a URI such as a string.
+    #
+    # The logger will default to a null logger appropriate to this platform.
     def initialize(uri, logger = Logger.null)
       @uri = uri.is_a?(::URI) ? uri : URI(uri)
       @logger = logger
@@ -42,31 +26,56 @@ module Fieldhand
       @http.use_ssl = true if @uri.scheme == 'https'
     end
 
-    def items(verb, path, query = {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-      return enum_for(:items, verb, path, query) unless block_given?
+    # Return an `Enumerator` of items retrieved from the repository with the given `verb` and `query`, parsed with the
+    # given `parser_class`.
+    #
+    # The query defaults to an empty hash but will be merged with the given `verb` when making requests to the
+    # repository.
+    #
+    # Expects the `parser_class` to respond to `items`, returning an `Enumerable` list of items that will be yielded to
+    # the caller.
+    #
+    # Raises a `ProtocolError` for any errors in the response.
+    #
+    # Fieldhand attempts to handle all flow control for the user using resumption tokens from the response so they only
+    # need handle lazy enumerators and not worry about pagination and underlying network requests.
+    #
+    # # Examples
+    #
+    # ```
+    # paginator = Fieldhand::Paginator.new('http://www.example.com/oai')
+    # paginator.items('ListRecords', Fieldhand::ListRecordsParser).take(10_000)
+    # #=> [#<Fieldhand::Record: ...>, ...]
+    # ```
+    #
+    # See https://www.openarchives.org/OAI/openarchivesprotocol.html#FlowControl
+    def items(verb, parser_class, query = {})
+      return enum_for(:items, verb, parser_class, query) unless block_given?
 
       loop do
-        document = ::Ox.parse(request(query.merge('verb' => verb)))
-        response_date = document.root.locate('responseDate[0]/^String').map { |date| Datestamp.parse(date) }.first
-
-        document.root.locate('error').each do |error|
-          convert_error(error)
-        end
-
-        document.root.locate(path).each do |item|
-          yield item, response_date
+        response_parser = parse_response(query.merge('verb' => verb))
+        parser_class.new(response_parser).items.each do |item|
+          yield item
         end
 
-        resumption_token = document.root.locate('?/resumptionToken/^String').first
-        break unless resumption_token
+        break unless response_parser.resumption_token
 
-        logger.debug('Fieldhand') { "Resumption token for #{verb}: #{resumption_token}" }
-        query = { 'resumptionToken' => resumption_token }
+        logger.debug('Fieldhand') { "Resumption token for #{verb}: #{response_parser.resumption_token}" }
+        query = { 'resumptionToken' => response_parser.resumption_token }
       end
     end
 
     private
 
+    def parse_response(query = {})
+      response_parser = ResponseParser.new(request(query))
+      response_parser.errors.each do |error|
+        raise error
+      end
+
+      response_parser
+    end
+
     def request(query = {})
       request_uri = uri.dup
       request_uri.query = encode_query(query)
@@ -79,12 +88,6 @@ module Fieldhand
       raise NetworkError, "error requesting #{query}: #{e}"
     end
 
-    def convert_error(error)
-      return unless ERROR_CODES.key?(error['code'])
-
-      raise ERROR_CODES.fetch(error['code']), error.text
-    end
-
     def encode_query(query = {})
       query.map { |k, v| ::CGI.escape(k) << '=' << ::CGI.escape(v) }.join('&')
     end

data/lib/fieldhand/record.rb

@@ -8,39 +8,58 @@ module Fieldhand
   class Record
     attr_reader :element, :response_date
 
+    # Return a new Record for the given element with an optional response date.
+    #
+    # Defaults the response date to the current time.
     def initialize(element, response_date = Time.now)
       @element = element
       @response_date = response_date
     end
 
+    # Test whether this item is marked as deleted or not according to its header.
+    #
+    # Note that a repository's support for deleted records can be interrogated through the `Identify` request, see
+    # https://www.openarchives.org/OAI/openarchivesprotocol.html#DeletedRecords
     def deleted?
       header.deleted?
     end
 
+    # Return the optional status of this item according to its header.
     def status
       header.status
     end
 
+    # Return the unique identifier of this item according to its header.
     def identifier
       header.identifier
     end
 
+    # Return the UTC datestamp of this item according to its header as a `Date` or `Time` depending on the granularity
+    # of this repository.
     def datestamp
       header.datestamp
     end
 
+    # Return any set memberships of this item according to its header.
     def sets
       header.sets
     end
 
+    # Return the single manifestation of the metadata of this item as a string, if present.
+    #
+    # As metadata can be in any format, Fieldhand does not attempt to parse it but leave that to the user.
     def metadata
       @metadata ||= element.locate('metadata[0]').map { |metadata| Ox.dump(metadata) }.first
     end
 
+    # Return any about elements describing the metadata of this record as an array of strings.
+    #
+    # As about elements can be in any format, Fieldhand does not attempt to parse them but leave that to the user.
     def about
       @about ||= element.locate('about').map { |about| Ox.dump(about) }
     end
 
+    # Return the associated Header for this record.
     def header
       @header ||= Header.new(element.header)
     end

data/lib/fieldhand/repository.rb

@@ -1,11 +1,12 @@
 require 'fieldhand/arguments'
-require 'fieldhand/header'
-require 'fieldhand/identify'
+require 'fieldhand/get_record_parser'
+require 'fieldhand/identify_parser'
+require 'fieldhand/list_identifiers_parser'
+require 'fieldhand/list_metadata_formats_parser'
+require 'fieldhand/list_records_parser'
+require 'fieldhand/list_sets_parser'
 require 'fieldhand/logger'
-require 'fieldhand/metadata_format'
 require 'fieldhand/paginator'
-require 'fieldhand/record'
-require 'fieldhand/set'
 require 'uri'
 
 module Fieldhand
@@ -15,75 +16,112 @@ module Fieldhand
   class Repository
     attr_reader :uri, :logger
 
+    # Return a new repository with the given base URL and an optional logger.
+    #
+    # The base URL can be passed as a `URI` or anything that can be parsed as a URI such as a string.
+    #
+    # Defaults to using a null logger specific to this platform.
     def initialize(uri, logger = Logger.null)
       @uri = uri.is_a?(::URI) ? uri : URI(uri)
       @logger = logger
     end
 
+    # Send an Identify request to the repository and return an `Identify` response.
+    #
+    # Raises a `NetworkError` if there is an issue contacting the repository or a `ProtocolError` if received in
+    # response.
+    #
+    # See https://www.openarchives.org/OAI/openarchivesprotocol.html#Identify
     def identify
-      paginator.
-        items('Identify', 'Identify').
-        map { |identify, response_date| Identify.new(identify, response_date) }.
-        first
+      paginator.items('Identify', IdentifyParser).first
     end
 
+    # Send a ListMetadataFormats request to the repository (with an optional identifier) and return an `Enumerator` of
+    # `MetadataFormat`s.
+    #
+    # Raises a `NetworkError` if there is an issue contacting the repository or a `ProtocolError` if received in
+    # response.
+    #
+    # See https://www.openarchives.org/OAI/openarchivesprotocol.html#ListMetadataFormats
     def metadata_formats(identifier = nil)
-      return enum_for(:metadata_formats, identifier) unless block_given?
+      query = {}
+      query['identifier'] = identifier if identifier
 
-      arguments = {}
-      arguments['identifier'] = identifier if identifier
-
-      paginator.
-        items('ListMetadataFormats', 'ListMetadataFormats/metadataFormat', arguments).
-        each do |format, response_date|
-          yield MetadataFormat.new(format, response_date)
-        end
+      paginator.items('ListMetadataFormats', ListMetadataFormatsParser, query)
     end
 
+    # Send a ListSets request to the repository and return an `Enumerator` of `Set`s.
+    #
+    # Raises a `NetworkError` if there is an issue contacting the repository or a `ProtocolError` if received in
+    # response.
+    #
+    # See https://www.openarchives.org/OAI/openarchivesprotocol.html#ListSets
     def sets
-      return enum_for(:sets) unless block_given?
-
-      paginator.
-        items('ListSets', 'ListSets/set').
-        each do |set, response_date|
-          yield Set.new(set, response_date)
-        end
+      paginator.items('ListSets', ListSetsParser)
     end
 
+    # Send a ListRecords request to the repository with optional arguments and return an `Enumerator` of `Records`s.
+    #
+    # The following arguments can be used:
+    #
+    # * :metadata_prefix - The prefix of the metadata format to be used for record metadata, defaults to "oai_dc"
+    # * :from - A `Date`, `Time` or formatted string specifying a lower bound for datestamp-based selective harvesting
+    # * :until - A `Date`, `Time` or formatted string specifying an upper bound for datestamp-based selective harvesting
+    # * :set - A `Set` or string set spec which specifies set criteria for selective harvesting
+    # * :resumption_token - A valid resumption token for resuming a previous request (note that Fieldhand typically
+    #                       handles resumption internally so this should not be normally used)
+    #
+    # Raises a `NetworkError` if there is an issue contacting the repository or a `ProtocolError` if received in
+    # response.
+    #
+    # # Examples
+    #
+    # ```
+    # repository = Fieldhand::Repository.new('http://www.example.com/oai')
+    # repository.records.each do |record|
+    #   next if record.deleted?
+    #
+    #   puts record.metadata
+    # end
+    # ```
+    #
+    # See https://www.openarchives.org/OAI/openarchivesprotocol.html#ListRecords
     def records(arguments = {})
-      return enum_for(:records, arguments) unless block_given?
-
       query = Arguments.new(arguments).to_query
 
-      paginator.
-        items('ListRecords', 'ListRecords/record', query).
-        each do |record, response_date|
-          yield Record.new(record, response_date)
-        end
+      paginator.items('ListRecords', ListRecordsParser, query)
     end
 
+    # Send a ListIdentifiers request to the repository with optional arguments and return an `Enumerator` of `Header`s.
+    #
+    # This supports the same arguments as `Fieldhand::Repository#records` but only returns record headers.
+    #
+    # Raises a `NetworkError` if there is an issue contacting the repository or a `ProtocolError` if received in
+    # response.
+    #
+    # See https://www.openarchives.org/OAI/openarchivesprotocol.html#ListIdentifiers
     def identifiers(arguments = {})
-      return enum_for(:identifiers, arguments) unless block_given?
-
       query = Arguments.new(arguments).to_query
 
-      paginator.
-        items('ListIdentifiers', 'ListIdentifiers/header', query).
-        each do |header, response_date|
-          yield Header.new(header, response_date)
-        end
+      paginator.items('ListIdentifiers', ListIdentifiersParser, query)
     end
 
+    # Send a GetRecord request to the repository with the given identifier and optional metadata prefix and return a
+    # `Record`.
+    #
+    # Supports passing a :metadata_prefix argument with a given metadata prefix which otherwise defaults to "oai_dc".
+    #
+    # Raises a `NetworkError` if there is an issue contacting the repository or a `ProtocolError` if received in
+    # response.
+    #
+    # See https://www.openarchives.org/OAI/openarchivesprotocol.html#GetRecord
     def get(identifier, arguments = {})
       query = {
         'identifier' => identifier,
         'metadataPrefix' => arguments.fetch(:metadata_prefix, 'oai_dc')
       }
 
-      paginator.
-        items('GetRecord', 'GetRecord/record', query).
-        map { |record, response_date| Record.new(record, response_date) }.
-        first
+      paginator.items('GetRecord', GetRecordParser, query).first
     end
 
     private

data/lib/fieldhand/response_parser.rb

@@ -0,0 +1,67 @@
+require 'fieldhand/datestamp'
+require 'ox'
+
+module Fieldhand
+  ProtocolError = ::Class.new(::StandardError)
+  BadArgumentError = ::Class.new(ProtocolError)
+  BadResumptionTokenError = ::Class.new(ProtocolError)
+  BadVerbError = ::Class.new(ProtocolError)
+  CannotDisseminateFormatError = ::Class.new(ProtocolError)
+  IdDoesNotExistError = ::Class.new(ProtocolError)
+  NoRecordsMatchError = ::Class.new(ProtocolError)
+  NoMetadataFormatsError = ::Class.new(ProtocolError)
+  NoSetHierarchyError = ::Class.new(ProtocolError)
+
+  # A parser for elements common to all OAI-PMH HTTP responses.
+  #
+  # See https://www.openarchives.org/OAI/openarchivesprotocol.html#HTTPResponseFormat
+  class ResponseParser
+    ERROR_CODES = {
+      'badArgument' => BadArgumentError,
+      'badResumptionToken' => BadResumptionTokenError,
+      'badVerb' => BadVerbError,
+      'cannotDisseminateFormat' => CannotDisseminateFormatError,
+      'idDoesNotExist' => IdDoesNotExistError,
+      'noRecordsMatch' => NoRecordsMatchError,
+      'noMetadataFormats' => NoMetadataFormatsError,
+      'noSetHierarchy' => NoSetHierarchyError
+    }.freeze
+
+    attr_reader :response
+
+    # Return a new parser for the given response body.
+    def initialize(response)
+      @response = response
+    end
+
+    # Return the response date as a `Date` or `Time` depending on the granularity of the repository.
+    def response_date
+      @response_date ||= root.locate('responseDate[0]/^String').map { |date| Datestamp.parse(date) }.first
+    end
+
+    # Return any errors found in the response as `ProtocolError`s.
+    #
+    # Note that this does not _raise_ the errors but simply returns them.
+    def errors
+      @errors ||= root.locate('error').map { |error| convert_error(error) }
+    end
+
+    # Return the resumption token from the response, if present.
+    def resumption_token
+      @resumption_token ||= root.locate('?/resumptionToken[0]/^String').first
+    end
+
+    # Return the root element of the parsed document.
+    def root
+      @root ||= ::Ox.parse(response).root
+    end
+
+    private
+
+    def convert_error(element)
+      return unless ERROR_CODES.key?(element['code'])
+
+      ERROR_CODES.fetch(element['code']).new(element.text)
+    end
+  end
+end

data/lib/fieldhand/set.rb

@@ -7,23 +7,34 @@ module Fieldhand
   class Set
     attr_reader :element, :response_date
 
+    # Return a Set with the given element and optional response date.
+    #
+    # Defaults the response date to the current time.
     def initialize(element, response_date = Time.now)
       @element = element
       @response_date = response_date
     end
 
+    # Return the set's spec as its string representation.
+    #
+    # This means that Sets can be used as arguments that expect a set spec.
     def to_s
       spec
     end
 
+    # Return the set's unique identifier within the repository.
     def spec
       @spec ||= element.setSpec.text
     end
 
+    # Return the set's short human-readable name.
     def name
       @name ||= element.setName.text
     end
 
+    # Return any descriptions of the set as an array of strings.
+    #
+    # As descriptions can be in any format, Fieldhand does not attempt to parse them but leave this to the user.
     def descriptions
       @descriptions ||= element.locate('setDescription').map { |description| Ox.dump(description) }
     end

data/spec/fieldhand/arguments_spec.rb

@@ -1,6 +1,6 @@
 require 'fieldhand/arguments'
-require 'fieldhand/set'
 require 'fieldhand/metadata_format'
+require 'fieldhand/set'
 require 'ox'
 require 'date'
 require 'time'

data/spec/fieldhand/datestamp_spec.rb

@@ -33,6 +33,16 @@ module Fieldhand
       it 'unparses strings into themselves' do
         expect(described_class.unparse('2001-01-01')).to eq('2001-01-01')
       end
+
+      it 'unparses DateTimes into time-granularity datestamps' do
+        expect(described_class.unparse(::DateTime.new(2001, 1, 1, 0, 0, 0))).to eq('2001-01-01T00:00:00Z')
+      end
+
+      it 'unparses unknown types by calling xmlschema' do
+        datestamp = Struct.new(:xmlschema).new('2001-01-01')
+
+        expect(described_class.unparse(datestamp)).to eq('2001-01-01')
+      end
     end
   end
 end

data/spec/fieldhand/paginator_spec.rb

@@ -1,3 +1,8 @@
+require 'fieldhand/get_record_parser'
+require 'fieldhand/identify_parser'
+require 'fieldhand/list_metadata_formats_parser'
+require 'fieldhand/list_records_parser'
+require 'fieldhand/list_sets_parser'
 require 'fieldhand/paginator'
 
 module Fieldhand
@@ -8,7 +13,7 @@ module Fieldhand
                          'bad_argument_error.xml')
         paginator = described_class.new('http://www.example.com/oai')
 
-        expect { paginator.items('Identify', 'Identify', 'bad' => 'Argument').first }.
+        expect { paginator.items('Identify', IdentifyParser, 'bad' => 'Argument').first }.
           to raise_error(BadArgumentError)
       end
 
@@ -17,7 +22,7 @@ module Fieldhand
                          'bad_resumption_token_error.xml')
         paginator = described_class.new('http://www.example.com/oai')
 
-        expect { paginator.items('ListRecords', 'ListRecords/record', 'resumptionToken' => 'foo').first }.
+        expect { paginator.items('ListRecords', ListRecordsParser, 'resumptionToken' => 'foo').first }.
           to raise_error(BadResumptionTokenError)
       end
 
@@ -26,7 +31,7 @@ module Fieldhand
                          'bad_verb_error.xml')
         paginator = described_class.new('http://www.example.com/oai')
 
-        expect { paginator.items('Bad', 'Bad').first }.
+        expect { paginator.items('Bad', IdentifyParser).first }.
           to raise_error(BadVerbError)
       end
 
@@ -35,7 +40,7 @@ module Fieldhand
                          'cannot_disseminate_format_error.xml')
         paginator = described_class.new('http://www.example.com/oai')
 
-        expect { paginator.items('ListRecords', 'ListRecords/record', 'metadataPrefix' => 'bad').first }.
+        expect { paginator.items('ListRecords', ListRecordsParser, 'metadataPrefix' => 'bad').first }.
           to raise_error(CannotDisseminateFormatError)
       end
 
@@ -45,7 +50,7 @@ module Fieldhand
         paginator = described_class.new('http://www.example.com/oai')
 
         expect {
-          paginator.items('GetRecord', 'GetRecord/record', 'metadataPrefix' => 'oai_dc', 'identifier' => 'bad').first
+          paginator.items('GetRecord', GetRecordParser, 'metadataPrefix' => 'oai_dc', 'identifier' => 'bad').first
         }.to raise_error(IdDoesNotExistError)
       end
 
@@ -56,7 +61,7 @@ module Fieldhand
 
         expect {
           paginator.
-            items('ListRecords', 'ListRecords/record', 'metadataPrefix' => 'oai_dc', 'from' => '2999-01-01').
+            items('ListRecords', ListRecordsParser, 'metadataPrefix' => 'oai_dc', 'from' => '2999-01-01').
             first
         }.to raise_error(NoRecordsMatchError)
       end
@@ -67,7 +72,7 @@ module Fieldhand
         paginator = described_class.new('http://www.example.com/oai')
 
         expect {
-          paginator.items('ListMetadataFormats', 'ListMetadataFormats/metadataFormat', 'identifier' => 'bad').first
+          paginator.items('ListMetadataFormats', ListMetadataFormatsParser, 'identifier' => 'bad').first
         }.to raise_error(NoMetadataFormatsError)
       end
 
@@ -76,7 +81,7 @@ module Fieldhand
                          'no_set_hierarchy_error.xml')
         paginator = described_class.new('http://www.example.com/oai')
 
-        expect { paginator.items('ListSets', 'ListSets/set').first }.
+        expect { paginator.items('ListSets', ListSetsParser).first }.
           to raise_error(NoSetHierarchyError)
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fieldhand
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Paul Mucur
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-08 00:00:00.000000000 Z
+date: 2017-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ox
@@ -90,13 +90,20 @@ files:
 - lib/fieldhand.rb
 - lib/fieldhand/arguments.rb
 - lib/fieldhand/datestamp.rb
+- lib/fieldhand/get_record_parser.rb
 - lib/fieldhand/header.rb
 - lib/fieldhand/identify.rb
+- lib/fieldhand/identify_parser.rb
+- lib/fieldhand/list_identifiers_parser.rb
+- lib/fieldhand/list_metadata_formats_parser.rb
+- lib/fieldhand/list_records_parser.rb
+- lib/fieldhand/list_sets_parser.rb
 - lib/fieldhand/logger.rb
 - lib/fieldhand/metadata_format.rb
 - lib/fieldhand/paginator.rb
 - lib/fieldhand/record.rb
 - lib/fieldhand/repository.rb
+- lib/fieldhand/response_parser.rb
 - lib/fieldhand/set.rb
 - spec/fieldhand/arguments_spec.rb
 - spec/fieldhand/datestamp_spec.rb