ro-crate 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a00cfaaae356d223c2104408fc10f894aa53271f982924b3c73c9661169b69f
+  data.tar.gz: c26895cf57e0d1e4b31243a2f79031f5121ce0c7c598cb1862f6eb1e146fa2cc
+SHA512:
+  metadata.gz: c16426ceee5c8660c145ea9bf4de09cc58bff30d726992628616c9795c8bd54b102f524f6a28514660322e1465d2fe3f0071ea2894000ccfc30ed88a99d9ad86
+  data.tar.gz: fc8f8a3654ef0de78864a808cb797622189ee50becba25c1f0d1c095355655320c218c14d09a21f7baf87da34a1ec8bdcc93d50bd1f69ecc8dccc13708c090d6

data/.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Generate docs
+on:
+  release:
+    types: [published]
+jobs:
+  build-and-deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2.3.1 # If you're using actions/checkout@v2 you must set persist-credentials to false in most cases for the deployment to work correctly.
+        with:
+          persist-credentials: false
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - name: Generate docs
+        run: bundle exec yard -o doc
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@3.7.1
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages # The branch the action should deploy to.
+          FOLDER: doc # The folder the action should deploy.
+          CLEAN: true # Automatically remove deleted files from the deploy branch

data/.github/workflows/tests.yml

@@ -0,0 +1,16 @@
+name: Tests
+on: [push, pull_request]
+jobs:
+  run-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2.3.1 # If you're using actions/checkout@v2 you must set persist-credentials to false in most cases for the deployment to work correctly.
+        with:
+          persist-credentials: false
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,50 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.4.9

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,48 @@
+PATH
+  remote: .
+  specs:
+    ro-crate (0.3.0)
+      addressable (~> 2.7.0)
+      rubyzip (~> 2.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    docile (1.3.1)
+    hashdiff (1.0.1)
+    json (2.3.1)
+    power_assert (0.4.1)
+    public_suffix (4.0.3)
+    rake (13.0.0)
+    rubyzip (2.0.0)
+    safe_yaml (1.0.5)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    test-unit (3.2.3)
+      power_assert
+    webmock (3.8.3)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.25)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake (~> 13.0.0)
+  ro-crate!
+  simplecov (~> 0.16.1)
+  test-unit (~> 3.2.3)
+  webmock (~> 3.8.3)
+  yard (~> 0.9.25)
+
+BUNDLED WITH
+   1.17.3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 University of Manchester
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,79 @@
+# ro-crate-ruby
+
+This is a WIP gem for creating, manipulating and reading RO crates (conforming to version 1.1 of the specification).
+
+* RO Crate - https://researchobject.github.io/ro-crate/
+* RO Crate spec (1.1) - https://researchobject.github.io/ro-crate/1.1/
+
+## Installation
+
+Using bundler, add the following to your Gemfile:
+
+```
+gem 'ro-crate-ruby', git: 'https://github.com/ResearchObject/ro-crate-ruby.git'
+```
+
+and run `bundle install`.
+
+## Usage
+
+### Documentation
+
+[Click here for API documentation](https://www.researchobject.org/ro-crate-ruby/).
+
+### Examples
+
+```ruby
+require 'ro_crate_ruby'
+
+# Make a new crate
+crate = ROCrate::Crate.new
+crate.add_file(File.open('Gemfile')) # Using IO-like objects
+crate.add_file('README.md') # or paths
+
+# Write to a zip file
+ROCrate::Writer.new(crate).write_zip(File.new('ro_crate.zip', 'w'))
+
+# Write to a directory
+ROCrate::Writer.new(crate).write('./ro_crate_stuff')
+
+# Read an RO crate
+crate = ROCrate::Reader.read('./an_ro_crate_directory')
+
+# Make some changes
+existing_file = crate.dereference('some_data.csv')
+existing_file.name = 'Some amazing data'
+existing_author = existing_file.author
+joe = crate.add_person('joe', { name: 'Joe Bloggs' })
+file = crate.add_file('some_more_data.csv')
+file.author = [joe, existing_author]
+
+# Add an external file
+ext_file = crate.add_external_file('https://example.com/my_file.txt')
+
+# Write it back
+ROCrate::Writer.new(crate).write('./an_ro_crate_directory')
+```
+
+### RO Crate Preview
+A simple HTML preview page is generated when an RO Crate is written, containing a list of the crate's contents and some
+metadata. This preview is written to `ro-crate-preview.html` at the root of the RO Crate.
+
+The default template can be seen here [here](lib/ro_crate/ro-crate-preview.html.erb).
+
+You can customize this preview by providing your own ERB file. 
+The ERB file is evaluated using the `ROCrate::Crate` instance's `binding`.
+
+#### Example
+
+```ruby
+crate = ROCrate::Crate.new
+
+# ... add stuff to the crate
+ 
+# Tell the crate to use your own template (as a string)
+crate.preview.template = File.read('path_to_your_template.html.erb')
+
+# Write it
+ROCrate::Writer.new(crate).write('./an_ro_crate_directory')
+```

data/Rakefile

@@ -0,0 +1,30 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rdoc/task'
+
+desc 'Default: run unit tests.'
+task default: :test
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+  t.warning = false
+end
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Devise'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require 'ro_crate_ruby'
+  ARGV.clear
+  IRB.start
+end

data/lib/ro_crate/json_ld_hash.rb

@@ -0,0 +1,41 @@
+module ROCrate
+  ##
+  # A wrapper class for Hash that adds methods to dereference Entities within an RO Crate.
+  class JSONLDHash < ::Hash
+    def initialize(graph, content = {})
+      @graph = graph
+      super()
+      update(stringified(content))
+    end
+
+    def [](key)
+      jsonld_wrap(super)
+    end
+
+    def dereference
+      @graph.dereference(self['@id']) if self['@id']
+    end
+
+    def has_type?(type)
+      t = self['@type']
+      t.is_a?(Array) ? t.include?(type) : t == type
+    end
+
+    private
+
+    def jsonld_wrap(val)
+      if val.is_a?(Array)
+        val.map { |v| jsonld_wrap(v) }
+      elsif val.instance_of?(::Hash)
+        self.class.new(@graph, val)
+      else
+        val
+      end
+    end
+
+    # A slow and stupid way of making sure all hash keys are strings.
+    def stringified(hash)
+      JSON.parse(hash.to_json)
+    end
+  end
+end

data/lib/ro_crate/model/contact_point.rb

@@ -0,0 +1,13 @@
+module ROCrate
+  ##
+  # A contextual entity that represents a contact point.
+  class ContactPoint < ContextualEntity
+    properties(%w[name email])
+
+    private
+
+    def default_properties
+      super.merge('@type' => 'ContactPoint')
+    end
+  end
+end

data/lib/ro_crate/model/contextual_entity.rb

@@ -0,0 +1,41 @@
+module ROCrate
+  ##
+  # A class to represent a "Contextual Entity" within an RO Crate.
+  # Contextual Entities are used to describe and provide context to the Data Entities within the crate.
+  class ContextualEntity < Entity
+    def self.format_id(id)
+      i = super
+      begin
+        uri = URI(id)
+      rescue ArgumentError
+        uri = nil
+      end
+
+      if uri&.absolute?
+        i
+      elsif i.start_with?('#')
+        i
+      else
+        "##{i}"
+      end
+    end
+
+    ##
+    # Return an appropriate specialization of ContextualEntity for the given properties.
+    # @param props [Hash] Set of properties to try and infer the type from.
+    # @return [Class]
+    def self.specialize(props)
+      type = props['@type']
+      type = [type] unless type.is_a?(Array)
+      if type.include?('Person')
+        ROCrate::Person
+      elsif type.include?('Organization')
+        ROCrate::Organization
+      elsif type.include?('ContactPoint')
+        ROCrate::ContactPoint
+      else
+        self
+      end
+    end
+  end
+end

data/lib/ro_crate/model/crate.rb

@@ -0,0 +1,211 @@
+module ROCrate
+  ##
+  # A Ruby abstraction of an RO Crate.
+  class Crate < Directory
+    IDENTIFIER = './'.freeze
+    attr_reader :data_entities
+    attr_reader :contextual_entities
+    properties(%w[name datePublished author license identifier distribution contactPoint publisher description url hasPart])
+
+    def self.format_id(id)
+      return id if id == IDENTIFIER
+      super
+    end
+
+    ##
+    # Initialize an empty RO Crate.
+    def initialize(id = IDENTIFIER, properties = {})
+      @data_entities = []
+      @contextual_entities = []
+      super(self, nil, id, properties)
+    end
+
+    ##
+    # Create a new file and add it to the crate.
+    #
+    # @param source [String, Pathname, ::File, #read, nil] The source on the disk where this file will be read.
+    # @param crate_path [String] The relative path within the RO crate where this file will be written.
+    # @param entity_class [Class] The class to use to instantiate the Entity,
+    #   useful if you have created a subclass of ROCrate::File that you want to use. (defaults to ROCrate::File).
+    # @param properties [Hash{String => Object}] A hash of JSON-LD properties to associate with this file.
+    #
+    # @return [Entity]
+    def add_file(source, crate_path = nil, entity_class: ROCrate::File, **properties)
+      entity_class.new(self, source, crate_path, properties).tap { |e| add_data_entity(e) }
+    end
+
+    ##
+    # Create a new file that references a remote URI and add it to the crate.
+    #
+    # @param source [String, URI] The URI to add.
+    # @param entity_class [Class] The class to use to instantiate the Entity,
+    #   useful if you have created a subclass of ROCrate::File that you want to use. (defaults to ROCrate::File).
+    # @param properties [Hash{String => Object}] A hash of JSON-LD properties to associate with this file.
+    #
+    # @return [Entity]
+    def add_external_file(source, entity_class: ROCrate::File, **properties)
+      entity_class.new(self, source, nil, properties).tap { |e| add_data_entity(e) }
+    end
+
+    ##
+    # Create a new directory and add it to the crate.
+    #
+    # @param source_directory [String, Pathname, ::File, #read, nil] The source directory that will be included in the crate.
+    # @param crate_path [String] The relative path within the RO crate where this directory will be written.
+    # @param entity_class [Class] The class to use to instantiate the Entity,
+    #   useful if you have created a subclass of ROCrate::Directory that you want to use. (defaults to ROCrate::Directory).
+    # @param properties [Hash{String => Object}] A hash of JSON-LD properties to associate with this directory.
+    #
+    # @return [Entity]
+    def add_directory(source_directory, crate_path = nil, entity_class: ROCrate::Directory, **properties)
+      entity_class.new(self, source_directory, crate_path, properties).tap { |e| add_data_entity(e) }
+    end
+
+    ##
+    # Create a new ROCrate::Person and add it to the crate
+    #
+    # @param id [String, nil] An ID to identify this person, or blank to auto-generate an appropriate one,
+    #   (or determine via the properties param)
+    # @param properties [Hash{String => Object}] A hash of JSON-LD properties to associate with this person.
+    # @return [Person]
+    def add_person(id, properties = {})
+      add_contextual_entity(ROCrate::Person.new(self, id, properties))
+    end
+
+    ##
+    # Create a new ROCrate::ContactPoint and add it to the crate
+    #
+    # @param id [String, nil] An ID to identify this contact point, or blank to auto-generate an appropriate one,
+    #   (or determine via the properties param)
+    # @param properties [Hash{String => Object}] A hash of JSON-LD properties to associate with this contact point.
+    # @return [ContactPoint]
+    def add_contact_point(id, properties = {})
+      add_contextual_entity(ROCrate::ContactPoint.new(self, id, properties))
+    end
+
+    ##
+    # Create a new ROCrate::Organization and add it to the crate
+    #
+    # @param id [String, nil] An ID to identify this organization, or blank to auto-generate an appropriate one,
+    #   (or determine via the properties param)
+    # @param properties [Hash{String => Object}] A hash of JSON-LD properties to associate with this organization.
+    # @return [Organization]
+    def add_organization(id, properties = {})
+      add_contextual_entity(ROCrate::Organization.new(self, id, properties))
+    end
+
+    ##
+    # Add a contextual entity to the crate
+    #
+    # @param entity [Entity] the entity to add to the crate.
+    # @return [Entity] the entity itself, or a clone of the entity "owned" by this crate.
+    def add_contextual_entity(entity)
+      entity = claim(entity)
+      contextual_entities.delete(entity) # Remove (then re-add) the entity if it exists
+      contextual_entities.push(entity)
+      entity
+    end
+
+    ##
+    # Add a data entity to the crate
+    #
+    # @param entity [Entity] the entity to add to the crate.
+    # @return [Entity] the entity itself, or a clone of the entity "owned" by this crate.
+    def add_data_entity(entity)
+      entity = claim(entity)
+      data_entities.delete(entity) # Remove (then re-add) the entity if it exists
+      data_entities.push(entity)
+      entity
+    end
+
+    ##
+    # The RO crate metadata file
+    #
+    # @return [Metadata]
+    def metadata
+      @metadata ||= ROCrate::Metadata.new(self)
+    end
+
+    ##
+    # The RO crate preview file
+    #
+    # @return [Preview]
+    def preview
+      @preview ||= ROCrate::Preview.new(self)
+    end
+
+    ##
+    # All the entities within the crate. Includes contextual entities, data entities, the crate itself and its metadata file.
+    #
+    # @return [Array<Entity>]
+    def entities
+      default_entities | data_entities | contextual_entities
+    end
+
+    ##
+    # Entities for the metadata file and crate itself, which should be present in all RO crates.
+    #
+    # @return [Array<Entity>]
+    def default_entities
+      [metadata, preview, self]
+    end
+
+    def properties
+      super.merge('hasPart' => data_entities.map(&:reference))
+    end
+
+    def uuid
+      @uuid ||= SecureRandom.uuid
+    end
+
+    ##
+    # The "canonical", global ID of the crate. If the crate was not given an absolute URI as its ID,
+    # it will use an "Archive and Package" (ARCP) URI with the UUID of the crate, for example:
+    #   arcp://uuid,b3d6fa2b-4e49-43ba-bd89-464e948b7f0c/
+    #
+    # @return [Addressable::URI]
+    def canonical_id
+      Addressable::URI.parse("arcp://uuid,#{uuid}").join(id)
+    end
+
+    ##
+    # Return an absolute URI for the given string ID, relative to the crate's canonical ID.
+    #
+    # @param id [String] The ID to "join" onto the crate's base URI.
+    #
+    # @return [Addressable::URI]
+    def resolve_id(id)
+      canonical_id.join(id)
+    end
+
+    ##
+    # Copy the entity, but as if it was in this crate.
+    # (Or just return the entity if it was already included)
+    def claim(entity)
+      return entity if entity.crate == self
+      entity.class.new(crate, entity.id, entity.raw_properties)
+    end
+
+    ##
+    # A map of all the files/directories contained in the RO crate, where the key is the destination path within the crate
+    # and the value is an Entry where the source data can be read.
+    #
+    # @return [Hash{String => Entry}>]
+    def entries
+      entries = {}
+
+      (default_entities | data_entities).each do |entity|
+        next if entity == self
+        entity.entries.each do |path, io|
+          entries[path] = io
+        end
+      end
+
+      entries
+    end
+
+    def get_binding
+      binding
+    end
+  end
+end