aspire 0.1.0

data/lib/aspire/enumerator/json_enumerator.rb

@@ -0,0 +1,130 @@
+module Aspire
+  # Enumerator classes for Aspire reading list processing
+  module Enumerator
+    # Enumerates over the properties of a JSON data structure
+    class JSONEnumerator
+      # @!attribute [rw] hooks
+      #   @return [Hash] the callback hooks
+      attr_accessor :hooks
+
+      # The Enumerator::Yielder instance from an Enumerator.new call
+      # @!attribute [rw] yielder
+      #   @return [Enumerator::Yielder] the yielder instance from an Enumerator
+      attr_accessor :yielder
+
+      # Initialises a new JSONEnumerator instance
+      # @param yielder [Enumerator::Yielder] the yielder from an Enumerator
+      # @param hooks [Hash] a hash of executable callback hooks:
+      #   {
+      #     after_array: proc { |key,value,index| }
+      #     after_hash: proc { |key,value,index| }
+      #     after_yield: proc { |key,value,index| }
+      #     before_array: proc { |key,value,index| }
+      #     before_hash: proc { |key,value,index| }
+      #     before_yield: proc { |key,value,index| }
+      #   }
+      #
+      #   Each callback is a Proc accepting a property key (name), value, and
+      #   optionally the numeric index of the property in its parent array (this
+      #   is nil if the property is not an array member).
+      #
+      #   Value is an array for after/before_array, a hash for after/before_hash
+      #   and any type for after/before_yield.
+      #
+      #   All before hooks must return a truthy value to allow processing of
+      #   the value, or a falsey value to prevent processing of the value.
+      #
+      #   Filters should be implemented in before hooks
+      #
+      #   Before hooks can also be used to process arrays and hashes as a whole.
+      #   They should return false if property-level processing is not required.
+      # @return [void]
+      def initialize(yielder = nil, **hooks)
+        self.hooks = hooks
+        self.yielder = yielder
+      end
+
+      def [](hook, *args, **kwargs)
+        h = hooks[hook]
+        return true unless h && h.respond_to?(:call)
+        h.call(*args, **kwargs) ? true : false
+      end
+
+      def []=(hook, proc)
+        unless proc.is_a?(Proc) || proc.is_a?(Method)
+          raise ArgumentError, 'Proc or Method expected'
+        end
+        hooks[hook] = proc
+      end
+
+      # Enumerates an array of JSON data structures
+      # @param key [String] the property name
+      # @param array [Object] the property value
+      # @param index [Integer] the index of the property in its parent array, or
+      #   nil if not part of an array
+      # @return [void]
+      def array(key, array, index)
+        return unless self[:before_array, key, array, index]
+        i = 0
+        array.each do |value|
+          enumerate(key, value, i)
+          i += 1
+        end
+        self[:after_array, key, array, index]
+      end
+
+      # Enumerates the property/value pairs of a JSON data structure
+      # @param key [String] the property name
+      # @param value [Object] the property value
+      # @param index [Integer] the index of the property in its parent array, or
+      #   nil if not part of an array
+      # @return [void]
+      def enumerate(key, value, index = nil)
+        if value.is_a?(Array)
+          array(key, value, index)
+        elsif value.is_a?(Hash)
+          hash(key, value, index)
+        else
+          property(key, value, index)
+        end
+      end
+
+      # Returns an enumerator enumerating property/value pairs of JSON data
+      # @param key [String] the initial key of the data
+      # @param value [Object] the initial value of the data
+      # @return [Enumerator] the enumerator
+      def enumerator(key, value)
+        ::Enumerator.new do |yielder|
+          self.yielder = yielder
+          enumerate(key, value)
+        end
+      end
+
+      # Enumerates the property/value pairs of a JSON hash
+      # @param key [String] the property name
+      # @param hash [Hash] the hash to enumerate
+      # @param index [Integer] the index of the property in its parent array, or
+      #   nil if not part of an array
+      # @return [void]
+      def hash(key, hash, index = nil)
+        return unless self[:before_hash, key, hash, index]
+        hash.each do |k, v|
+          v.is_a?(Array) || v.is_a?(Hash) ? enumerate(k, v) : property(k, v)
+        end
+        self[:after_hash, key, hash, index]
+      end
+
+      # Yields a property/value pair
+      # @param key [String] the property name
+      # @param value [Object] the property value
+      # @param index [Integer] the index of the property in its parent array, or
+      #   nil if not part of an array
+      # @return [void]
+      def property(key, value, index = nil)
+        return unless self[:before_yield, key, value, index]
+        yielder << [key, value, index]
+        self[:after_yield, hooks, key, value, index]
+      end
+    end
+  end
+end

data/lib/aspire/enumerator/linked_data_uri_enumerator.rb

@@ -0,0 +1,32 @@
+require 'aspire/enumerator/json_enumerator'
+
+module Aspire
+  # Enumerator classes for Aspire reading list processing
+  module Enumerator
+    # Enumerates the URI properties of a linked data API object
+    class LinkedDataURIEnumerator < JSONEnumerator
+      # Initialises a new LinkedDataAPIEnumerator instance
+      # @param yielder [Enumerator::Yielder] the yielder from an Enumerator
+      # @param hooks [Hash] the callback hooks
+      # @yield [key, hash, index] passes each hash to the block
+      # @yieldparam key [Object] the hash property name
+      # @yieldparam hash [Hash] the hash
+      # @yieldparam index [Integer, nil] the index of the hash in its parent
+      #   array, or nil if not part of an array
+      def initialize(yielder = nil, **hooks)
+        super(yielder, **hooks)
+        # Yield only hashes { type: "uri", value: "..." }
+        self[:before_hash] = proc do |key, hash, index|
+          if hash['type'] == 'uri' && hash['value'] && !hash['value'].empty?
+            self.yielder << [key, hash, index]
+            false
+          else
+            true
+          end
+        end
+        # Do not yield properties
+        self[:before_yield] = proc { |_key, _value, _index| false }
+      end
+    end
+  end
+end

data/lib/aspire/enumerator/report_enumerator.rb

@@ -0,0 +1,64 @@
+require 'csv'
+
+require 'aspire/enumerator/base'
+
+module Aspire
+  # Enumerator classes for Aspire reading list processing
+  module Enumerator
+    # Enumerates rows from an exported Aspire report CSV (All Lists, All User
+    # Profiles etc.) with optional filtering
+    class ReportEnumerator < Base
+      # @!attribute [rw] file
+      #   @return [String] the filename of the report
+      attr_accessor :file
+
+      # @!attribute [rw] filters
+      #   @return [Array<Proc>] a list of filters to select rows for processing
+      attr_accessor :filters
+
+      # Initialises a new ListReport instance
+      # @param file [String] the filename of the report
+      # @param filters [Array<Proc>] a list of filters to select rows for
+      #   processing. Each proc accepts a parsed row from the CSV file and
+      #   returns true to accept it or false to reject it. All filters must
+      #   return true for the row to be yielded.
+      # @return [void]
+      def initialize(file = nil, filters = nil)
+        self.file = file
+        self.filters = filters
+      end
+
+      # Enumerates the report rows
+      # @return [void]
+      def enumerate(*_args, **_kwargs)
+        CSV.foreach(file, converters: date_converter, headers: true, encoding: 'ISO-8859-1') do |row|
+          yielder << row if filter(row)
+        end
+      end
+
+      private
+
+      # Returns a YYYY-MM-DD date converter for the CSV processor
+      # @return [Proc] the date converter
+      def date_converter
+        lambda do |s|
+          begin
+            Date.strptime(s, '%Y-%m-%d')
+          rescue ArgumentError
+            s
+          end
+        end
+      end
+
+      # Returns true if the row passes all filters, false otherwise
+      def filter(row)
+        # Return true if no filters are defined
+        return true if filters.nil? || filters.empty?
+        # Return false if any of the filters returns false
+        filters.each { |f| return false unless f.call(row) }
+        # All filters passed, return true
+        true
+      end
+    end
+  end
+end

data/lib/aspire/exceptions.rb

@@ -0,0 +1,36 @@
+module Aspire
+  module Exceptions
+    # The root of the caching exception hierarchy
+    class Error < StandardError; end
+
+    # Raised when a requested URL is not present in the cache
+    class CacheMiss < Error; end
+
+    # Raised when an Aspire API call fails
+    class APIError < Error; end
+
+    # Raised when an Aspire API call times out
+    class APITimeout < APIError; end
+
+    # Raised when a cache entry mark operation fails
+    class MarkError < Error; end
+
+    # Raised when trying to mark an already-marked cache entry
+    class MarkedError < Error; end
+
+    # Raised when a URL is not cacheable
+    class NotCacheable < Error; end
+
+    # Raised when data cannot be read from the cache
+    class ReadError < Error; end
+
+    # Raised when data cannot be removed from the cache
+    class RemoveError < Error; end
+
+    # Raised when a cache entry unmark operation fails
+    class UnmarkError < Error; end
+
+    # Raised when data cannot be written to the cache
+    class WriteError < Error; end
+  end
+end

data/lib/aspire/object.rb

@@ -0,0 +1,7 @@
+require 'aspire/object/digitisation'
+require 'aspire/object/factory'
+require 'aspire/object/list'
+require 'aspire/object/module'
+require 'aspire/object/resource'
+require 'aspire/object/time_period'
+require 'aspire/object/user'

data/lib/aspire/object/base.rb

@@ -0,0 +1,155 @@
+require 'cgi'
+
+require 'loofah'
+
+require 'aspire/util'
+
+module Aspire
+  module Object
+    # The base class for Aspire API objects
+    class Base
+      include Aspire::Util
+
+      # Aspire properties containing HTML markup will have the markup stripped
+      #   if STRIP_HTML = true"#{without format suffix (.html, .json etc.)}"
+      STRIP_HTML = true
+
+      # @!attribute [rw] factory
+      #   @return [Aspire::Object::Factory] the factory for creating
+      #     Aspire::Object instances
+      attr_accessor :factory
+
+      # @!attribute [rw] uri
+      #   @return [String] the URI of the object
+      attr_accessor :uri
+
+      # Initialises a new Aspire::Object instance
+      # @param uri [String] the URI of the object
+      # @param factory [Aspire::Object::Factory] the factory for creating
+      #   Aspire::Object instances
+      # @return [void]
+      def initialize(uri, factory)
+        self.factory = factory
+        # Normalise the URL to the linked data form
+        self.uri = factory ? factory.cache.linked_data_url(uri) : uri
+      end
+
+      # Returns a Boolean property value
+      # @param property [String] the property name
+      # @param data [Hash] the data hash containing the property
+      #   (defaults to self.ld)
+      # @param single [Boolean] if true, return a single value, otherwise return
+      #   an array of values
+      # @return [Boolean, Array<Boolean>] the property value(s)
+      def get_boolean(property, data, single: true)
+        get_property(property, data, single: single) do |value, _type|
+          value ? true : false
+        end
+      end
+
+      # Returns a DateTime instance for a timestamp property
+      # @param property [String] the property name
+      # @param data [Hash] the data hash containing the property (defaults to
+      #   self.ld)
+      # @param single [Boolean] if true, return a single value, otherwise return
+      #   an array of values
+      # @return [DateTime, Array<DateTime>] the property value(s)
+      def get_date(property, data, single: true)
+        get_property(property, data, single: single) do |value, _type|
+          DateTime.parse(value)
+        end
+      end
+
+      # Returns the value of a property
+      # @param property [String] the property name
+      # @param data [Hash] the data hash containing the property
+      #   (defaults to self.data)
+      # @param is_url [Boolean] if true, the property value is a URL
+      # @param single [Boolean] if true, return a single value, otherwise return
+      #   an array of values
+      # @return [Object, Array<Object>] the property value(s)
+      # @yield [value, type] passes the value and type to the block
+      # @yieldparam value [Object] the property value
+      # @yieldparam type [String] the type of the property value
+      # @yieldreturn [Object] the transformed property value
+      def get_property(property, data, is_url: false, single: true, &block)
+        values = data ? data[property] : nil
+        if values.is_a?(Array)
+          values = values.map do |value|
+            get_property_value(value, is_url: is_url, &block)
+          end
+          single ? values[0] : values
+        else
+          value = get_property_value(values, is_url: is_url, &block)
+          single ? value : [value]
+        end
+      end
+
+      # Returns a string representation of the APIObject instance (the URI)
+      # @return [String] the string representation of the APIObject instance
+      def to_s
+        uri.to_s
+      end
+
+      # Sets the URI of the object
+      # @param u [String] the URI of the object
+      # @return [void]
+      def uri=(u)
+        # Remove any format extension (.json, .rdf etc.)
+        ext = File.extname(u)
+        @uri = ext.nil? || ext.empty? ? u : u.rpartition(ext)[0]
+      end
+
+      protected
+
+      # Retrieves and transforms the property value
+      # @param value [String] the property value from the Aspire API
+      # @param is_url [Boolean] if true, the property value is a URL
+      # @yield [value, type] Passes the property value and type URI to the block
+      # @yieldparam value [Object] the property value
+      # @yieldparam type [String] the property value's type URI
+      # @yieldreturn [Object] the transformed property value
+      # @return [String] the property value
+      def get_property_value(value, is_url: false)
+        # Assume hash values are a type/value pair
+        if value.is_a?(Hash)
+          type = value['type']
+          value = value['value']
+        else
+          type = nil
+        end
+        # Apply transformations to string properties
+        value = transform(value, is_url: is_url) if value.is_a?(String)
+        # If a block is present, return the result of the block
+        return yield(value, type) if block_given?
+        # Otherwise return the value
+        value
+      end
+
+      # Removes HTML markup from property values
+      # @param value [String] the property value from the Aspire API
+      # @param is_url [Boolean] if true, the property value is a URL
+      # @return [String] the property value
+      def transform(value, is_url: false)
+        if is_url
+          # Remove HTML-escaped encodings from URLs without full HTML-stripping
+          CGI.unescape_html(value)
+        elsif STRIP_HTML
+          # Strip HTML preserving block-level whitespace
+          # - Loofah seems to preserve &amp; &quot; etc. so we remove these with
+          #   CGI.unescape_html
+          text = CGI.unescape_html(Loofah.fragment(value).to_text)
+          # Collapse all runs of whitespace to a single space
+          text.gsub!(/\s+/, ' ')
+          # Remove leading and trailing whitespace
+          text.strip!
+          # Return the transformed text
+          text
+        else
+          # Return value as-is
+          value
+        end
+      end
+    end
+  end
+end

data/lib/aspire/object/digitisation.rb

@@ -0,0 +1,43 @@
+require 'aspire/object/base'
+
+module Aspire
+  module Object
+    # Represents a digitisation record in the Aspire API
+    class Digitisation < Base
+      # @!attribute [rw] bundle_id
+      #   @return [String] the digitisation bundle ID
+      attr_accessor :bundle_id
+
+      # @!attribute [rw] request_id
+      #   @return [String] the digitisation request ID
+      attr_accessor :request_id
+
+      # @!attribute [rw] request_status
+      #   @return [String] the digitisation request status
+      attr_accessor :request_status
+
+      # Initialises a new Digitisation instance
+      # @param json [Hash] the parsed JSON data from the JSON API
+      # @param ld [Hash] the parsed JSON data from the linked data API
+      # @return [void]
+      def initialize(json: nil, ld: nil)
+        if json
+          self.bundle_id = json['bundleId']
+          self.request_id = json['requestId']
+          self.request_status = json['requestStatus']
+        else
+          self.bundle_id = nil
+          self.request_id = nil
+          self.request_status = nil
+        end
+      end
+
+      # Returns a string representation of the Digitisation instance (the
+      # request ID)
+      # @return [String] the string representation of the Digitisation instance
+      def to_s
+        request_id.to_s
+      end
+    end
+  end
+end