resync 0.1.0

data/lib/resync/types/change.rb

@@ -0,0 +1,14 @@
+require 'ruby-enum'
+
+module Resync
+  module Types
+    # The type of change indicated by a reference in a +ChangeList+, +ChangeDump+, etc.
+    class Change
+      include Ruby::Enum
+
+      define :CREATED, 'created'
+      define :UPDATED, 'updated'
+      define :DELETED, 'deleted'
+    end
+  end
+end

data/lib/resync/types/change_frequency.rb

@@ -0,0 +1,18 @@
+require 'ruby-enum'
+
+module Resync
+  module Types
+    # The frequency of changes to a resource.
+    class ChangeFrequency
+      include Ruby::Enum
+
+      define :ALWAYS, 'always'
+      define :HOURLY, 'hourly'
+      define :DAILY, 'daily'
+      define :WEEKLY, 'weekly'
+      define :MONTHLY, 'monthly'
+      define :YEARLY, 'yearly'
+      define :NEVER, 'never'
+    end
+  end
+end

data/lib/resync/types.rb

@@ -0,0 +1,6 @@
+module Resync
+  # Enumerated types for controlled vocabularies.
+  module Types
+    Dir.glob(File.expand_path('../types/*.rb', __FILE__), &method(:require))
+  end
+end

data/lib/resync/version.rb

@@ -0,0 +1,4 @@
+module Resync
+  # The version of this gem.
+  VERSION = '0.1.0'
+end

data/lib/resync/xml.rb

@@ -0,0 +1,216 @@
+require 'uri'
+require 'time'
+require 'xml/mapping'
+
+module Resync
+  # Helper methods and modules related to reading and writing XML.
+  module XML
+
+    # ------------------------------------------------------
+    # Module shared methods
+
+    # Ensures that the provided value is a +URI+, parsing it if necessary.
+    #
+    # @param url [URI, String] the URI.
+    # @raise [URI::InvalidURIError] if +url+ cannot be converted to a URI.
+    def self.to_uri(url)
+      return nil unless url
+      (url.is_a? URI) ? url : URI.parse(url)
+    end
+
+    # Extracts a +REXML::Element+ from the specified object.
+    #
+    # @param xml [String, IO, REXML::Document, REXML::Element] A string or IO-like
+    #   object containing an XML document (with or without XML declaration), or an
+    #   XML document, or an XML element.
+    # @return [REXML::Element] the root element of the document, or the element
+    #   itself if +xml+ is already an element.
+    def self.element(xml)
+      case xml
+      when REXML::Document
+        xml.root
+      when REXML::Element
+        xml
+      else
+        fail ArgumentError, "Unexpected argument type; expected XML document, String, or IO source, was #{xml.class}" unless can_parse(xml)
+        REXML::Document.new(xml).root
+      end
+    end
+
+    # ------------------------------------------------------------
+    # Private class methods
+
+    # Whether the argument can be parsed as an +REXML::Document+
+    #
+    # @return [Boolean] true if +REXML::Document.new()+ should be able to parse
+    #   the argument, false otherwise
+    def self.can_parse(arg)
+      arg.is_a?(String) ||
+        (arg.respond_to?(:read) &&
+            arg.respond_to?(:readline) &&
+            arg.respond_to?(:nil?) &&
+            arg.respond_to?(:eof?))
+    end
+    private_class_method :can_parse
+
+    # ------------------------------------------------------------
+    # Time
+
+    # Maps +Time+ objects.
+    class TimeNode < ::XML::Mapping::SingleAttributeNode
+      def initialize(*args)
+        path, *args = super(*args)
+        @path = ::XML::XXPath.new(path)
+        args
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#extract_attr_value+.
+      def extract_attr_value(xml)
+        value = default_when_xpath_err { @path.first(xml).text }
+        value ? Time.iso8601(value).utc : nil
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#set_attr_value+.
+      def set_attr_value(xml, value)
+        @path.first(xml, ensure_created: true).text = value.iso8601
+      end
+    end
+
+    ::XML::Mapping.add_node_class TimeNode
+
+    # ------------------------------------------------------------
+    # URI
+
+    # Maps +URI+ objects.
+    class UriNode < ::XML::Mapping::SingleAttributeNode
+      def initialize(*args)
+        path, *args = super(*args)
+        @path = ::XML::XXPath.new(path)
+        args
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#extract_attr_value+.
+      def extract_attr_value(xml)
+        URI(default_when_xpath_err { @path.first(xml).text })
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#set_attr_value+.
+      def set_attr_value(xml, value)
+        @path.first(xml, ensure_created: true).text = value.to_s
+      end
+    end
+
+    ::XML::Mapping.add_node_class UriNode
+
+    # ------------------------------------------------------------
+    # Resync::Types::Change
+
+    # Maps +Resync::Types::Change+ values.
+    class ChangeNode < ::XML::Mapping::SingleAttributeNode
+      def initialize(*args)
+        path, *args = super(*args)
+        @path = ::XML::XXPath.new(path)
+        args
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#extract_attr_value+.
+      def extract_attr_value(xml)
+        Resync::Types::Change.parse(default_when_xpath_err { @path.first(xml).text })
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#set_attr_value+.
+      def set_attr_value(xml, value)
+        @path.first(xml, ensure_created: true).text = value.to_s
+      end
+    end
+
+    ::XML::Mapping.add_node_class ChangeNode
+
+    # ------------------------------------------------------------
+    # Resync::Types::Changefreq
+
+    # Maps +Resync::Types::Changefreq+ values.
+    class ChangefreqNode < ::XML::Mapping::SingleAttributeNode
+      def initialize(*args)
+        path, *args = super(*args)
+        @path = ::XML::XXPath.new(path)
+        args
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#extract_attr_value+.
+      def extract_attr_value(xml)
+        Resync::Types::ChangeFrequency.parse(default_when_xpath_err { @path.first(xml).text })
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#set_attr_value+.
+      def set_attr_value(xml, value)
+        @path.first(xml, ensure_created: true).text = value.to_s
+      end
+    end
+
+    ::XML::Mapping.add_node_class ChangefreqNode
+
+    # ------------------------------------------------------------
+    # MIME::Type
+
+    # Maps +MIME::Type+ values.
+    class MimeTypeNode < ::XML::Mapping::SingleAttributeNode
+      def initialize(*args)
+        path, *args = super(*args)
+        @path = ::XML::XXPath.new(path)
+        args
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#extract_attr_value+.
+      def extract_attr_value(xml)
+        mime_type = default_when_xpath_err { @path.first(xml).text }
+        return nil unless mime_type
+        return mime_type if mime_type.is_a?(MIME::Type)
+
+        mt = MIME::Types[mime_type].first
+        return mt if mt
+
+        MIME::Type.new(mime_type)
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#set_attr_value+.
+      def set_attr_value(xml, value)
+        @path.first(xml, ensure_created: true).text = value.to_s
+      end
+    end
+
+    ::XML::Mapping.add_node_class MimeTypeNode
+
+    # ------------------------------------------------------------
+    # Whitespace-separated hashcode list
+
+    # Maps the whitespace-separated list of hash codes in a +<rs:ln>+
+    # or +<rs:md>+ tag to a hash of digest values keyed by hash algorithm.
+    # (See {Resync::Descriptor#hashes}.)
+    class HashCodesNode < ::XML::Mapping::SingleAttributeNode
+      def initialize(*args)
+        path, *args = super(*args)
+        @path = ::XML::XXPath.new(path)
+        args
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#extract_attr_value+.
+      def extract_attr_value(xml)
+        hashes = default_when_xpath_err { @path.first(xml).text }
+        return {} unless hashes
+        return hashes if hashes.is_a?(Hash)
+        hashes.split(/[[:space:]]+/).map { |hash| hash.split(':') }.to_h
+      end
+
+      # Implements +::XML::Mapping::SingleAttributeNode#set_attr_value+.
+      def set_attr_value(xml, value)
+        return if value.empty?
+        hash_str = value.map { |k, v| "#{k}:#{v}" }.join(' ')
+        @path.first(xml, ensure_created: true).text = hash_str
+      end
+    end
+
+    ::XML::Mapping.add_node_class HashCodesNode
+
+  end
+end

data/lib/resync/xml_parser.rb

@@ -0,0 +1,65 @@
+module Resync
+
+  # Parses ResourceSync XML documents and returns appropriate objects.
+  module XMLParser
+
+    # The list of parseable types, organized by XML mapping.
+    ROOT_TYPES = {
+      _default: [
+        CapabilityList,
+        ChangeDump,
+        ChangeDumpManifest,
+        ChangeList,
+        ResourceDump,
+        ResourceDumpManifest,
+        ResourceList,
+        SourceDescription
+      ],
+      sitemapindex: [
+        ChangeListIndex,
+        ResourceListIndex
+      ]
+    }
+    private_constant :ROOT_TYPES
+
+    CAPABILITY_ATTRIBUTE = "/*/[namespace-uri() = 'http://www.openarchives.org/rs/terms/' and local-name() = 'md']/@capability"
+    private_constant :CAPABILITY_ATTRIBUTE
+
+    # Parses the specified ResourceSync document and returns the appropriate object
+    # based on the +capability+ attribute of the root element's metadata (i.e. +<rs:md>+).
+    #
+    # @param xml [String, REXML::Document, REXML::Element] a ResourceSync XML document
+    #   (or its root element)
+    def self.parse(xml)
+      root_element = XML.element(xml)
+      mapping = root_element.name == 'sitemapindex' ? :sitemapindex : :_default
+      root_type = find_root_type(ROOT_TYPES[mapping], root_element)
+      root_type.load_from_xml(root_element, mapping: mapping)
+    end
+
+    def self.find_root_type(types, root_element)
+      capability = capability_for(root_element)
+      root_type = types.find { |t| t::CAPABILITY == capability }
+      fail ArgumentError, "no mapped type for capability '#{capability}'" unless root_type
+      root_type
+    end
+
+    private_class_method :find_root_type
+
+    def self.capability_for(root_element)
+      capability = capability_attribute_for(root_element).value
+      fail ArgumentError, "unable to identify capability of root element in #{root_element}" unless capability
+      capability
+    end
+
+    private_class_method :capability_for
+
+    def self.capability_attribute_for(root_element)
+      capability_attr = REXML::XPath.first(root_element, CAPABILITY_ATTRIBUTE)
+      fail ArgumentError, "unable to identify capability of root element in #{root_element}" unless capability_attr
+      capability_attr
+    end
+
+    private_class_method :capability_attribute_for
+  end
+end

data/lib/resync.rb

@@ -0,0 +1,4 @@
+# A Ruby gem for working with the {http://www.openarchives.org/rs/1.0/resourcesync ResourceSync} web synchronization framework.
+module Resync
+  Dir.glob(File.expand_path('../resync/*.rb', __FILE__), &method(:require))
+end

data/resync.gemspec

@@ -0,0 +1,36 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'resync/version'
+require 'uri'
+
+Gem::Specification.new do |spec|
+  spec.name = 'resync'
+  spec.version = Resync::VERSION
+  spec.authors = ['David Moles']
+  spec.email = ['david.moles@ucop.edu']
+  spec.summary = 'Utility library for ResourceSync'
+  spec.description = 'A Ruby gem for working with the ResourceSync web synchronization framework'
+  spec.license = 'MIT'
+
+  origin_uri = URI(`git config --get remote.origin.url`.chomp)
+  spec.homepage = URI::HTTP.build(host: origin_uri.host, path: origin_uri.path.chomp('.git')).to_s
+
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'mime-types', '~> 2.5'
+  spec.add_dependency 'ruby-enum', '~> 0.4'
+  spec.add_dependency 'xml-mapping', '~> 0.10'
+
+  spec.add_development_dependency 'equivalent-xml', '~> 0.6.0'
+  spec.add_development_dependency 'rake', '~> 10.4'
+  spec.add_development_dependency 'rspec', '~> 3.2'
+  spec.add_development_dependency 'rubocop', '~> 0.29.1'
+  spec.add_development_dependency 'simplecov', '~> 0.9.2'
+  spec.add_development_dependency 'simplecov-console', '~> 0.2.0'
+  spec.add_development_dependency 'yard', '~> 0.8'
+end