iiif-presentation 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1e600987059a68eef0064df0b7d4a62606af135e
+  data.tar.gz: d1a85d821d52a370f9c3b0cd27383437cd242694
+SHA512:
+  metadata.gz: 65ab0328b4f5c514e4c6a3860d24aa00d0d9908971d64ff0a36fd000d552c1992711700c30ea690a43b1a436b3c8b459242d1f853a01a71b0b699a4685fd8228
+  data.tar.gz: e210d147df7c6ce971c518c5f117c2918aadab3ad9f4e115a3add980453f81251a33acd3ec69dcb576b0f5157c23b14df37f9517e4b82505d8ae9fa09cc32eb0

data/.gitignore

@@ -0,0 +1,4 @@
+coverage/
+pkg/
+Gemfile.lock
+

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--format documentation

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.1.0
+gemfile:
+  - gemfiles/rails3.gemfile
+  - gemfiles/rails4.gemfile

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2014, Jon Stroop
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,173 @@
+# O'Sullivan: A Ruby API for working with IIIF Presentation manifests
+
+[![Build Status](https://travis-ci.org/IIIF/osullivan.svg?branch=development)](https://travis-ci.org/IIIF/osullivan)
+[![Coverage Status](https://coveralls.io/repos/IIIF/osullivan/badge.svg?branch=development&service=github)](https://coveralls.io/github/IIIF/osullivan?branch=development)
+
+
+## Installation
+
+From the source code do `rake install`, or get the latest release [from RubyGems](https://rubygems.org/gems/iiif-presentation).
+
+## Building New Objects
+
+There is (or will be) a class for all types in [IIIF Presentation API Spec](http://iiif.io/api/presentation/2.0/).
+
+
+
+
+```ruby
+require 'iiif/presentation'
+
+seed = {
+    '@id' => 'http://example.com/manifest',
+    'label' => 'My Manifest'
+}
+# Any options you add are added to the object
+manifest = IIIF::Presentation::Manifest.new(seed)
+
+canvas = IIIF::Presentation::Canvas.new()
+# All classes act like `ActiveSupport::OrderedHash`es, for the most part.
+# Use `[]=` to set JSON-LD properties...
+canvas['@id'] = 'http://example.com/canvas'
+# ...but there are also accessors and mutators for the properties mentioned in 
+# the spec
+canvas.width = 10
+canvas.height = 20
+canvas.label = 'My Canvas'
+
+oc = IIIF::Presentation::Resource.new('@id' => 'http://example.com/content')
+canvas.other_content << oc
+
+manifest.sequences << canvas
+
+puts manifest.to_json(pretty: true)
+```
+
+Methods are generated dynamically, which means `#methods` is your friend:
+
+```ruby
+manifest = IIIF::Presentation::Manifest.new()
+puts manifest.methods(false)
+> label=
+> label
+> description=
+> description
+> thumbnail=
+> thumbnail
+> attribution=
+> attribution
+> viewing_hint=
+> viewingHint=
+> viewing_hint
+> viewingHint
+[...]
+```
+
+Note that multi-word properties are implemented as snake_case (because this is
+Ruby), but is serialized as camelCase. There are camelCase aliases for these.
+
+```ruby
+manifest = IIIF::Presentation::Manifest.new()
+manifest.viewing_hint = 'paged'
+puts manifest.to_json(pretty: true, force: true) # force: true skips validations
+
+> {
+>   "@context": "http://iiif.io/api/presentation/2/context.json",
+>   "@type": "sc:Manifest",
+>   "viewingHint": "paged"
+> }
+
+```
+
+## Parsing Existing Objects
+
+Use `IIIF::Service#parse`. It will figure out what the object
+should be, based on `@type`, and fall back to `ActiveSupport::OrderedHash` when
+it can't e.g.:
+
+```ruby
+seed = '{
+  "@context": "http://iiif.io/api/presentation/2/context.json",
+  "@id": "http://example.com/manifest",
+  "@type": "sc:Manifest",
+  "label": "My Manifest",
+  "service": {
+    "@context": "http://iiif.io/api/image/2/context.json",
+    "@id":"http://www.example.org/images/book1-page1",
+    "profile":"http://iiif.io/api/image/2/profiles/level2.json"
+  },
+  "seeAlso": {
+    "@id": "http://www.example.org/library/catalog/book1.marc",
+    "format": "application/marc"
+  },
+  "sequences": [
+    {
+      "@id":"http://www.example.org/iiif/book1/sequence/normal",
+      "@type":"sc:Sequence",
+      "label":"Current Page Order",
+      "viewingDirection":"left-to-right",
+      "viewingHint":"paged",
+      "startCanvas": "http://www.example.org/iiif/book1/canvas/p2",
+      "canvases": [
+        {
+          "@id": "http://example.com/canvas",
+          "@type": "sc:Canvas",
+          "width": 10,
+          "height": 20,
+          "label": "My Canvas",
+          "otherContent": [
+            {
+              "@id": "http://example.com/content",
+              "@type":"sc:AnnotationList",
+              "motivation": "sc:painting"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}'
+
+obj = IIIF::Service.parse(seed) # can also be a file path or a Hash
+puts obj.class
+puts obj.see_also.class
+
+> IIIF::Presentation::Manifest
+> ActiveSupport::OrderedHash
+```
+
+## Validation and Exceptions
+
+This is work in progress. Right now exceptions are generally raised when you 
+try to set something to a type it should never be:
+
+```ruby
+manifest = IIIF::Presentation::Manifest.new
+manifest.sequences = 'quux'
+
+> [...] sequences must be an Array. (IIIF::Presentation::IllegalValueError)
+```
+
+and also if any required properties are missing when calling `to_json`
+
+```ruby
+canvas = IIIF::Presentation::Canvas.new('@id' => 'http://example.com/canvas')
+puts canvas.to_json(pretty: true)
+
+> A(n) width is required for each IIIF::Presentation::Canvas (IIIF::Presentation::MissingRequiredKeyError)
+```
+
+but you can skip this validation by adding `force: true`:
+
+```ruby
+canvas = IIIF::Presentation::Canvas.new('@id' => 'http://example.com/canvas')
+puts canvas.to_json(pretty: true, force: true)
+
+> {
+>   "@context": "http://iiif.io/api/presentation/2/context.json",
+>   "@id": "http://example.com/canvas",
+>   "@type": "sc:Canvas"
+> }
+```
+This all needs a bit of tidying up, finishing, and refactoring, so expect it to 
+change.

data/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :ci do
+  Rake::Task['spec'].invoke
+end
+
+task default: :ci

data/VERSION

@@ -0,0 +1 @@
+0.0.4

data/gemfiles/rails3.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec :path=>"../"
+
+gem 'activesupport', '~> 3.2', '>= 3.2.18'

data/gemfiles/rails4.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec :path=>"../"
+
+gem 'activesupport', '~> 4.1'

data/iiif-presentation.gemspec

@@ -0,0 +1,28 @@
+version = File.read(File.expand_path('../VERSION', __FILE__)).strip
+
+Gem::Specification.new do |spec|
+  spec.name          = 'iiif-presentation'
+  spec.version       = version
+  spec.authors       = ['Jon Stroop']
+  spec.email         = ['jpstroop@gmail.com']
+  spec.description   = 'API for working with IIIF Presentation manifests.'
+  spec.summary       = 'API for working with IIIF Presentation manifests.'
+  spec.license       = 'Simplified BSD'
+  spec.homepage      = 'https://github.com/iiif/osullivan'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{^spec/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'coveralls'
+  spec.add_development_dependency 'webmock'
+  spec.add_development_dependency 'multi_json'
+  spec.add_development_dependency 'vcr', '~> 2.9.3'
+
+  spec.add_dependency 'json'
+  spec.add_dependency 'activesupport', '>= 3.2.18'
+  spec.add_dependency 'faraday', '~> 0.9.0'
+end

data/lib/active_support/ordered_hash.rb

@@ -0,0 +1,147 @@
+require 'active_support/inflector'
+require 'active_support/ordered_hash'
+
+module ActiveSupport
+  class OrderedHash < ::Hash
+
+    # Insert a new key and value at the suppplied index.
+    #
+    # Note that this is slightly different from Array#insert in that new
+    # entries must be added one at a time, i.e. insert(n, k, v, k, v...) is
+    # not supported.
+    #
+    # @param [Integer] index
+    # @param [Object] key
+    # @param [Object] value
+    def insert(index, key, value)
+      tmp = ActiveSupport::OrderedHash.new
+      index = self.length + 1 + index if index < 0
+      if index < 0
+        m = "Index #{index} is too small for current length (#{length})"
+        raise IndexError, m
+      end
+      if index > 0
+        i=0
+        self.each do |k,v|
+          tmp[k] = v
+          self.delete(k)
+          i+=1
+          break if i == index
+        end
+      end
+      tmp[key] = value
+      tmp.merge!(self) # copy the remaining to tmp
+      self.clear       # start over...
+      self.merge!(tmp) # now put them all back
+      self
+    end
+
+    # Insert a key and value before an existing key or the first entry for'
+    # which the supplied block evaluates to true. The block takes precendence
+    # over the supplied key.
+    # Options:'
+    #  * :existing_key (default: nil). If nil or not supplied then a block is required.
+    #  * :new_key (required)
+    #  * :value (required)
+    # @raise KeyError if the supplied existing key is not found, the new
+    # key exists, or the block never evaluates to true.
+    def insert_before(hsh, &block)
+      existing_key = hsh.fetch(:existing_key, nil)
+      new_key = hsh[:new_key]
+      value = hsh[:value]
+      if block_given?
+        self.insert_here(0, new_key, value, &block)
+      else
+        self.insert_here(0, new_key, value, existing_key)
+      end
+    end
+
+    # Insert a key and value after an existing key or the first entry for'
+    # which the supplied block evaluates to true. The block takes precendence
+    # over the supplied key.
+    # Options:'
+    #  * :existing_key (default: nil). If nil or not supplied then a block is required.
+    #  * :new_key (required)
+    #  * :value (required)
+    # @raise KeyError if the supplied existing key is not found, the new
+    # key exists, or the block never evaluates to true.
+    def insert_after(hsh, &block)
+      existing_key = hsh.fetch(:existing_key, nil)
+      new_key = hsh[:new_key]
+      value = hsh[:value]
+      if block_given?
+        self.insert_here(1, new_key, value, &block)
+      else
+        self.insert_here(1, new_key, value, existing_key)
+      end
+    end
+
+    # Delete any keys that are empty arrays
+    def remove_empties
+      self.keys.each do |key|
+        if (self[key].kind_of?(Array) && self[key].empty?) || self[key].nil?
+          self.delete(key)
+        end
+      end
+    end
+
+    # Covert snake_case keys to camelCase
+    def camelize_keys
+      self.keys.each_with_index do |key, i|
+        if key != key.camelize(:lower)
+          self.insert(i, key.camelize(:lower), self[key])
+          self.delete(key)
+        end
+      end
+      self
+    end
+
+    # Covert camelCase keys to snake_case
+    def snakeize_keys
+      self.keys.each_with_index do |key, i|
+        if key != key.underscore
+          self.insert(i, key.underscore, self[key])
+          self.delete(key)
+        end
+      end
+      self
+    end
+
+
+    # Prepends an entry to the front of the object.
+    # Note that this is slightly different from Array#unshift in that new
+    # entries must be added one at a time, i.e. unshift([k,v],[k,v],...) is
+    # not currently supported.
+    def unshift k,v
+      self.insert(0, k, v)
+      self
+    end
+
+    protected
+    def insert_here(where, new_key, value, existing_key=nil, &block)
+      idx = nil
+      if block_given?
+        self.each_with_index do |(k,v), i|
+          if yield(k, v)
+            idx = i
+            break
+          end
+        end
+        if idx.nil?
+          raise KeyError, "Supplied block never evaluates to true"
+        end
+      else
+        unless self.has_key?(existing_key)
+          raise KeyError, "Existing key '#{existing_key}' does not exist"
+        end
+        if self.has_key?(new_key)
+          raise KeyError, "Supplied new key '#{new_key}' already exists"
+        end
+        idx = self.keys.index(existing_key) + where
+      end
+      self.insert(idx, new_key, value)
+      self
+    end
+
+  end
+end

data/lib/iiif/hash_behaviours.rb

@@ -0,0 +1,150 @@
+require 'forwardable'
+
+module IIIF
+  module HashBehaviours
+    extend Forwardable
+
+    # TODO:
+    #  * reject
+    #  * replace
+
+    def_delegators :@data, :[], :[]=, :camelize_keys, :delete, :empty?,
+    :fetch, :has_key?, :has_value?, :include?, :insert, :insert_after,
+    :insert_before, :key, :key?, :keys, :length, :member?, :shift, :size,
+    :snakeize_keys, :store, :unshift, :value?, :values
+
+
+    ###
+    # Methods that take a block and should return an instance (self or a new'
+    # instance) have been overridden to do so, rather than an'
+    # ActiveSupport::OrderedHash based on the internal hash
+
+    SIMPLE_SELF_RETURNERS = %w[delete_if each each_key each_value keep_if]
+
+    SIMPLE_SELF_RETURNERS.each do |method_name|
+      define_method(method_name) do |*arg, &block|
+        unless block.nil? # block_given? doesn't seem to work in this context
+          @data.send(method_name, *arg, &block)
+          return self
+        else
+          @data.send(method_name)
+        end
+      end
+    end
+
+    # Clear is the only method that returns self but doesn't accept a block
+    def clear
+      @data.clear
+      return self
+    end
+
+    # Returns a new instance of this class containing the contents of'
+    # another_obj. The argument can be any object that implements two
+    # methods:
+    #
+    #    obj.each { |k,v| block }
+    #    obj.has_key?
+    #
+    # If no block is specified, the value for entries with duplicate keys'
+    # will be those of the argument, but at the index of the original; all'
+    # other entries will be appended to the end.
+    #
+    # If a block is specified the value for each duplicate key is determined'
+    # by calling the block with the key, its value in hsh and its value in'
+    # another_obj.
+    def merge another_obj
+      new_instance =  self.class.new
+      # self.clone # Would this be better? What happens to other attributes of the class?
+      if block_given?
+        self.each do |k,v|
+          if another_obj.has_key? k
+            new_instance[k] = yield(k, self[k], another_obj[k])
+          else
+            new_instance[k] = v
+          end
+        end
+      else
+        self.each { |k,v| new_instance[k] = v }
+        another_obj.each { |k,v| new_instance[k] = v }
+      end
+      new_instance
+    end
+
+    # Adds the entries from another obj to this one. The argument can be any
+    # object that implements two methods:
+    #
+    #    obj.each { |k,v| block }
+    #    obj.has_key?
+    #
+    # If no block is specified, the value for entries with duplicate keys'
+    # will be those of the argument, but at the index of the original; all'
+    # other entries will be appended to the end.
+    #
+    # If a block is specified the value for each duplicate key is determined'
+    # by calling the block with the key, its value in hsh and its value in'
+    # another_obj.
+    def merge! another_obj
+      if block_given?
+        self.each do |k,v|
+          if another_obj.has_key? k
+            self[k] = yield(k, self[k], another_obj[k])
+          else
+            self[k] = v
+          end
+        end
+      else
+        self.each { |k,v| self[k] = v }
+        another_obj.each { |k,v| self[k] = v }
+      end
+      self
+    end
+    alias update merge!
+
+    # Deletes entries for which the supplied block evaluates to true.
+    # Equivalent to #delete_if, but returns nil if there were no changes
+    def reject!
+      if block_given?
+        return_nil = true
+        @data.each do |k, v|
+          if yield(k, v)
+            @data.delete(k)
+            return_nil = false
+          end
+        end
+        return return_nil ? nil : self
+      else
+        return self.data.reject!
+      end
+    end
+
+    # Returns a new instance consisting of entries for which the block returns
+    # true. Not that an enumerator is not available for the OrderedHash'
+    # implementation
+    def select
+      new_instance = self.class.new
+      if block_given?
+        @data.each { |k,v| new_instance.data[k] = v if yield(k,v) }
+      end
+      return new_instance
+    end
+
+    # Deletes entries for which the supplied block evaluates to false.
+    # Equivalent to Hash#keep_if, but returns nil if no changes were made.
+    def select!
+      if block_given?
+        return_nil = true
+        @data.each do |k,v|
+          unless yield(k,v)
+            @data.delete(k)
+            return_nil = false
+          end
+        end
+        return nil if return_nil
+      end
+      self
+    end
+
+  end
+
+end
+