ro-crate 0.4.11 → 0.4.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62f3979b325743d31720f803dbf75690ad6b7b9bcf9f2cbf63d8200a2bb204ba
-  data.tar.gz: 3a229e06492a3f9a90721799f43929d6a5ca01fc0a0ff34d917eeebff037d9d4
+  metadata.gz: 92f4b8cd765215082edea1be4e3c065a29ddcdbbc43a79576a4782ba8d797f07
+  data.tar.gz: d8936210124988edd8fd942c978a93ea6ee6f17fa1bcbfd3b6528e7475143ca1
 SHA512:
-  metadata.gz: 242b8e326756d51ab583726db7fb94763286f2764bdf1f0523cd9dab5fa560fe4da3016a4a4b84b0cc6bcef4ec096aeae7dc2fd344ef6cb5ee045cf99a954ef9
-  data.tar.gz: 4abaece91d997ac398ee627f639fc98c924768c255bac1bb6c9ce7f43fc03f5b018a2fc657008863c65537592261e85f697ef2c7e200c20621ba41ff0a933541
+  metadata.gz: cf88d846278c037fd4437db9f1cd5f3fd31d6901eeb161a38417a5919edaf9e013f28cfadea7a59bf77a687c5946f540ee6cfa28ccc001d473dac41eaf3c5f3e
+  data.tar.gz: ab8413b46ad23145ca6d68f2554cad6eacb9f2ecd349e890b6380295029da5426110e447c863170d997071a6dba3f76c72006ca6a90b9a456ac96858e114aa86

data/.github/workflows/tests.yml

@@ -3,6 +3,10 @@ on: [push, pull_request]
 jobs:
   run-tests:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ['2.6', '2.7']
+      fail-fast: false
     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.
@@ -11,6 +15,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
+          ruby-version: ${{ matrix.ruby }}
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
       - name: Run tests
         run: bundle exec rake test

data/.ruby-version

@@ -1 +1 @@
-ruby-2.6.6
+ruby-2.7.5

data/Gemfile.lock

@@ -1,21 +1,21 @@
 PATH
   remote: .
   specs:
-    ro-crate (0.4.11)
-      addressable (~> 2.7.0)
+    ro-crate (0.4.15)
+      addressable (>= 2.7, < 2.9)
       rubyzip (~> 2.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.7.0)
+    addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
     docile (1.3.5)
     hashdiff (1.0.1)
-    power_assert (0.4.1)
-    public_suffix (4.0.3)
+    power_assert (1.1.3)
+    public_suffix (4.0.6)
     rake (13.0.0)
     rubyzip (2.0.0)
     safe_yaml (1.0.5)
@@ -25,7 +25,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.2)
-    test-unit (3.2.3)
+    test-unit (3.2.9)
       power_assert
     webmock (3.8.3)
       addressable (>= 2.3.6)
@@ -45,4 +45,4 @@ DEPENDENCIES
   yard (~> 0.9.25)
 
 BUNDLED WITH
-   1.17.3
+   2.3.6

data/README.md

@@ -1,5 +1,7 @@
 # ro-crate-ruby
 
+![Tests](https://github.com/ResearchObject/ro-crate-ruby/actions/workflows/tests.yml/badge.svg)
+
 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/

data/lib/ro_crate/json_ld_hash.rb

@@ -2,6 +2,11 @@ module ROCrate
   ##
   # A wrapper class for Hash that adds methods to dereference Entities within an RO-Crate.
   class JSONLDHash < ::Hash
+    def self.[](graph, content = {})
+      @graph = graph
+      super(stringified(content))
+    end
+
     def initialize(graph, content = {})
       @graph = graph
       super()

data/lib/ro_crate/model/crate.rb

@@ -25,6 +25,15 @@ module ROCrate
       super(self, nil, id, properties)
     end
 
+    ##
+    # Lookup an Entity using the given ID (in this Entity's crate).
+    #
+    # @param id [String] The ID to query.
+    # @return [Entity, nil]
+    def dereference(id)
+      entities.detect { |e| e.canonical_id == crate.resolve_id(id) } if id
+    end
+
     ##
     # Create a new file and add it to the crate.
     #
@@ -229,32 +238,70 @@ module ROCrate
       entity.class.new(crate, entity.id, entity.raw_properties)
     end
 
-    alias_method :own_entries, :entries
+    alias_method :own_payload, :payload
     ##
-    # # The RO-Crate's "payload" of the crate - 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.
+    # The file payload of the RO-Crate - a map of all the files/directories contained in the RO-Crate, where the
+    # key is the path relative to the crate's root, and the value is an Entry where the source data can be read.
     #
     # @return [Hash{String => Entry}>]
-    def entries
+    def payload
       # Gather a map of entries, starting from the crate itself, then any directory data entities, then finally any
       # file data entities. This ensures in the case of a conflict, the more "specific" data entities take priority.
-      entries = own_entries
+      entries = own_payload
       non_self_entities = default_entities.reject { |e| e == self }
       sorted_entities = (non_self_entities | data_entities).sort_by { |e| e.is_a?(ROCrate::Directory) ? 0 : 1 }
 
       sorted_entities.each do |entity|
-        entity.entries.each do |path, entry|
+        entity.payload.each do |path, entry|
           entries[path] = entry
         end
       end
 
       entries
     end
+    alias_method :entries, :payload
 
     def get_binding
       binding
     end
 
+    ##
+    # Remove the entity from the RO-Crate.
+    #
+    # @param entity [Entity, String] The entity or ID of an entity to remove from the crate.
+    # @param remove_orphaned [Boolean] Should linked contextual entities also be removed from the crate they are left
+    #                                   dangling (nothing else is linked to them)?
+    #
+    # @return [Entity, nil] The entity that was deleted, or nil if nothing was deleted.
+    def delete(entity, remove_orphaned: true)
+      entity = dereference(entity) if entity.is_a?(String)
+      return unless entity
+
+      deleted = data_entities.delete(entity) || contextual_entities.delete(entity)
+
+      if deleted && remove_orphaned
+        crate_entities = crate.linked_entities(deep: true)
+        to_remove = (entity.linked_entities(deep: true) - crate_entities)
+        to_remove.each(&:delete)
+      end
+
+      deleted
+    end
+
+    ##
+    # Remove any contextual entities that are not linked from any other entity.
+    # Optionally takes a block to decide whether the given entity should be removed or not, otherwise removes all
+    # unlinked entities.
+    # @yieldparam [ContextualEntity] entity An unlinked contextual entity.
+    # @yieldparam [Boolean] remove Should this entity be removed?
+    #
+    # @return [Array<ContextualEntity>] The entities that were removed.
+    def gc(&block)
+      unlinked_entities = contextual_entities - metadata.linked_entities(deep: true)
+
+      unlinked_entities.select(&block).each { |e| e.delete(remove_orphaned: false) }
+    end
+
     private
 
     def full_entry_path(relative_path)

data/lib/ro_crate/model/data_entity.rb

@@ -5,10 +5,6 @@ module ROCrate
   class DataEntity < Entity
     properties(%w[name contentSize dateModified encodingFormat identifier sameAs author])
 
-    def self.format_local_id(id)
-      super.chomp('/')
-    end
-
     ##
     # Return an appropriate specialization of DataEntity for the given properties.
     # @param props [Hash] Set of properties to try and infer the type from.
@@ -18,18 +14,35 @@ module ROCrate
       type = [type] unless type.is_a?(Array)
       if type.include?('Dataset')
         ROCrate::Directory
-      else
+      elsif type.include?('File')
         ROCrate::File
+      else
+        self
       end
     end
 
     ##
-    # A map of all the files/directories associated with this DataEntity.
+    # Create a new ROCrate::DataEntity. This entity represents something that is neither a file or directory, but
+    # still constitutes part of the crate.
+    # PLEASE NOTE, the new data entity will not be added to the crate. To do this, call Crate#add_data_entity.
+    #
+    # @param crate [Crate] The RO-Crate that owns this directory.
+    # @param source [nil] Ignored. For compatibility with the File and Directory constructor signatures.
+    # @param id [String, nil] An ID to identify this DataEntity, or nil 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 DataEntity.
+    def initialize(crate, source = nil, id = nil, properties = {})
+      super(crate, id, properties)
+    end
+
+    ##
+    # The payload of all the files/directories associated with this DataEntity, mapped by their relative file path.
     #
     # @return [Hash{String => Entry}>] The key is the location within the crate, and the value is an Entry.
-    def entries
+    def payload
       {}
     end
+    alias_method :entries, :payload
 
     ##
     # A disk-safe filepath based on the ID of this DataEntity.

data/lib/ro_crate/model/directory.rb

@@ -3,11 +3,11 @@ module ROCrate
   # A data entity that represents a directory of potentially many files and subdirectories (or none).
   class Directory < DataEntity
     def self.format_local_id(id)
-      super + '/'
+      super.chomp('/') + '/'
     end
 
     ##
-    # Create a new Directory. PLEASE NOTE, the new directory will not be added to the crate. To do this, call
+    # Create a new ROCrate::Directory. PLEASE NOTE, the new directory will not be added to the crate. To do this, call
     # Crate#add_data_entity, or just use Crate#add_directory.
     #
     # @param crate [Crate] The RO-Crate that owns this directory.
@@ -24,15 +24,15 @@ module ROCrate
         crate_path = source_directory.basename.to_s if crate_path.nil?
       end
 
-      super(crate, crate_path, properties)
+      super(crate, nil, crate_path, properties)
     end
 
     ##
-    # The "payload" of this directory - a map of all the files/directories, where the key is the destination path
+    # The payload of this directory - a map of all the files/directories, 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
+    def payload
       entries = {}
       entries[filepath.chomp('/')] = @entry if @entry
 

data/lib/ro_crate/model/entity.rb

@@ -129,16 +129,26 @@ module ROCrate
     # @param id [String] The ID to query.
     # @return [Entity, nil]
     def dereference(id)
-      crate.entities.detect { |e| e.canonical_id == crate.resolve_id(id) } if id
+      crate.dereference(id)
     end
-
     alias_method :get, :dereference
 
+    ##
+    # Remove this entity from the RO-Crate.
+    #
+    # @param remove_orphaned [Boolean] Should linked contextual entities also be removed from the crate (if nothing else is linked to them)?
+    #
+    # @return [Entity, nil] This entity, or nil if nothing was deleted.
+    def delete(remove_orphaned: true)
+      crate.delete(self, remove_orphaned: remove_orphaned)
+    end
+
     def id
       @properties['@id']
     end
 
     def id=(id)
+      @canonical_id = nil
       @properties['@id'] = self.class.format_id(id)
     end
 
@@ -190,13 +200,13 @@ module ROCrate
     #
     # @return [Addressable::URI]
     def canonical_id
-      crate.resolve_id(id)
+      @canonical_id ||= crate.resolve_id(id)
     end
 
     ##
     # Is this entity local to the crate or an external reference?
     #
-    # @return [boolean]
+    # @return [Boolean]
     def external?
       crate.canonical_id.host != canonical_id.host
     end
@@ -226,6 +236,35 @@ module ROCrate
       @properties.has_type?(type)
     end
 
+    ##
+    # Gather a list of entities linked to this one through its properties.
+    # @param deep [Boolean] If false, only consider direct links, otherwise consider transitive links.
+    # @param linked [Hash{String => Entity}] Discovered entities, mapped by their ID, to avoid loops when recursing.
+    # @return [Array<Entity>]
+    def linked_entities(deep: false, linked: {})
+      properties.each_key do |key|
+        value = properties[key] # We're doing this to call the JSONLDHash#[] method which wraps
+        value = [value] if value.is_a?(JSONLDHash)
+
+        if value.is_a?(Array)
+          value.each do |v|
+            if v.is_a?(JSONLDHash) && !linked.key?(v['@id'])
+              entity = v.dereference
+              next unless entity
+              linked[entity.id] = entity
+              if deep
+                entity.linked_entities(deep: true, linked: linked).each do |e|
+                  linked[e.id] = e
+                end
+              end
+            end
+          end
+        end
+      end
+
+      linked.values.compact
+    end
+
     private
 
     def default_properties

data/lib/ro_crate/model/entry.rb

@@ -14,10 +14,10 @@ module ROCrate
     end
 
     ##
-    # Write the source to the destination via a buffer.
+    # Write the entry's source to the destination via a buffer.
     #
     # @param dest [#write] An IO-like destination to write to.
-    def write(dest)
+    def write_to(dest)
       input = source
       input = input.open('rb') if input.is_a?(Pathname)
       while (buff = input.read(4096))

data/lib/ro_crate/model/file.rb

@@ -2,6 +2,10 @@ module ROCrate
   ##
   # A data entity that represents a single file.
   class File < DataEntity
+    def self.format_local_id(id)
+      super.chomp('/')
+    end
+
     ##
     # Create a new ROCrate::File. PLEASE NOTE, the new file will not be added to the crate. To do this, call
     # Crate#add_data_entity, or just use Crate#add_file.
@@ -32,7 +36,7 @@ module ROCrate
         crate_path = source.to_s if source.is_a?(URI) && source.absolute?
       end
 
-      super(crate, crate_path, properties)
+      super(crate, nil, crate_path, properties)
 
       if source.is_a?(URI) && source.absolute?
         @entry = RemoteEntry.new(source)
@@ -56,7 +60,7 @@ module ROCrate
     # (for compatibility with Directory#entries)
     #
     # @return [Hash{String => Entry}>] The key is the location within the crate, and the value is an Entry.
-    def entries
+    def payload
       remote? ? {} : { filepath => source }
     end
 

data/lib/ro_crate/model/remote_entry.rb

@@ -2,7 +2,7 @@ module ROCrate
   ##
   # A class to represent a reference within an RO-Crate, to a remote file held on the internet somewhere.
   # It handles the actual reading/writing of bytes.
-  class RemoteEntry
+  class RemoteEntry < Entry
     attr_reader :uri
 
     ##
@@ -13,22 +13,11 @@ module ROCrate
       @uri = uri
     end
 
-    def write(dest)
-      raise 'Cannot write to a remote entry!'
-    end
-
-    ##
-    # Read from the source.
-    #
-    def read
-      source.read
-    end
-
     ##
     # @return [IO] An IO object for the remote resource.
     #
     def source
-      open(uri)
+      uri.open
     end
 
     ##

data/lib/ro_crate/reader.rb

@@ -181,9 +181,10 @@ module ROCrate
         crate.metadata.properties = entity_hash.delete(ROCrate::Metadata::IDENTIFIER)
         crate.metadata.context = context
         preview_properties = entity_hash.delete(ROCrate::Preview::IDENTIFIER)
-        if preview_properties
-          preview_path = ::File.join(source, ROCrate::Preview::IDENTIFIER)
-          crate.preview = ROCrate::Preview.new(crate, ::File.exists?(preview_path) ? Pathname.new(preview_path) : nil, preview_properties)
+        preview_path = ::File.join(source, ROCrate::Preview::IDENTIFIER)
+        preview_path = ::File.exists?(preview_path) ? Pathname.new(preview_path) : nil
+        if preview_properties || preview_path
+          crate.preview = ROCrate::Preview.new(crate, preview_path, preview_properties || {})
         end
         crate.add_all(source, false)
       end
@@ -244,10 +245,10 @@ module ROCrate
           fullpath = ::File.join(source, i)
           path = Pathname.new(fullpath) if ::File.exist?(fullpath)
         end
-        unless path
-          warn "Missing file/directory: #{id}, skipping..."
-          return nil
-        end
+        # unless path
+        #   warn "Missing file/directory: #{id}, skipping..."
+        #   return nil
+        # end
       end
 
       entity_class.new(crate, path, decoded_id, entity_props)
@@ -261,7 +262,9 @@ module ROCrate
     # mapped by its @id, or nil if nothing is found.
     def self.extract_metadata_entity(entities)
       key = entities.detect do |_, props|
-        props.dig('conformsTo', '@id')&.start_with?(ROCrate::Metadata::RO_CRATE_BASE)
+        conforms = props['conformsTo']
+        conforms = [conforms] unless conforms.is_a?(Array)
+        conforms.compact.any? { |c| c['@id']&.start_with?(ROCrate::Metadata::RO_CRATE_BASE) }
       end&.first
 
       return entities.delete(key) if key

data/lib/ro_crate/writer.rb

@@ -16,14 +16,14 @@ module ROCrate
     # @param overwrite [Boolean] Whether or not to overwrite existing files.
     def write(dir, overwrite: true)
       FileUtils.mkdir_p(dir) # Make any parent directories
-      @crate.entries.each do |path, entry|
+      @crate.payload.each do |path, entry|
         fullpath = ::File.join(dir, path)
         next if !overwrite && ::File.exist?(fullpath)
         next if entry.directory?
         FileUtils.mkdir_p(::File.dirname(fullpath))
         temp = Tempfile.new('ro-crate-temp')
         begin
-          entry.write(temp)
+          entry.write_to(temp)
           temp.close
           FileUtils.mv(temp, fullpath)
         ensure
@@ -38,9 +38,9 @@ module ROCrate
     # @param destination [String, ::File] The destination where to write the RO-Crate zip.
     def write_zip(destination)
       Zip::File.open(destination, Zip::File::CREATE) do |zip|
-        @crate.entries.each do |path, entry|
+        @crate.payload.each do |path, entry|
           next if entry.directory?
-          zip.get_output_stream(path) { |s| entry.write(s) }
+          zip.get_output_stream(path) { |s| entry.write_to(s) }
         end
       end
     end

data/lib/ro_crate.rb

@@ -10,8 +10,8 @@ require 'ro_crate/json_ld_hash'
 require 'ro_crate/model/entity'
 require 'ro_crate/model/data_entity'
 require 'ro_crate/model/file'
-require 'ro_crate/model/remote_entry'
 require 'ro_crate/model/entry'
+require 'ro_crate/model/remote_entry'
 require 'ro_crate/model/directory'
 require 'ro_crate/model/metadata'
 require 'ro_crate/model/preview_generator'

data/ro_crate.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'ro-crate'
-  s.version     = '0.4.11'
+  s.version     = '0.4.15'
   s.summary     = 'Create, manipulate, read RO-Crates.'
   s.authors     = ['Finn Bacall']
   s.email       = 'finn.bacall@manchester.ac.uk'
@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.homepage    = 'https://github.com/ResearchObject/ro-crate-ruby'
   s.require_paths = ['lib']
   s.licenses    = ['MIT']
-  s.add_runtime_dependency 'addressable', '~> 2.7.0'
+  s.add_runtime_dependency 'addressable', '>= 2.7', '< 2.9'
   s.add_runtime_dependency 'rubyzip', '~> 2.0.0'
   s.add_development_dependency 'rake', '~> 13.0.0'
   s.add_development_dependency 'test-unit', '~> 3.2.3'

data/test/crate_test.rb

@@ -215,7 +215,7 @@ class CrateTest < Test::Unit::TestCase
     crate = ROCrate::Crate.new
     entities = crate.add_all(fixture_file('directory').path, include_hidden: true)
 
-    paths = crate.entries.keys
+    paths = crate.payload.keys
     assert_equal 11, paths.length
     assert_includes paths, 'data'
     assert_includes paths, 'root.txt'
@@ -250,7 +250,7 @@ class CrateTest < Test::Unit::TestCase
 
     assert_empty entities
 
-    paths = crate.entries.keys
+    paths = crate.payload.keys
     assert_equal 11, paths.length
     assert_includes paths, 'data'
     assert_includes paths, 'root.txt'
@@ -278,7 +278,7 @@ class CrateTest < Test::Unit::TestCase
     crate = ROCrate::Crate.new
     entities = crate.add_all(fixture_file('directory').path)
 
-    paths = crate.entries.keys
+    paths = crate.payload.keys
     assert_equal 8, paths.length
     assert_includes paths, 'data'
     assert_includes paths, 'root.txt'
@@ -305,4 +305,75 @@ class CrateTest < Test::Unit::TestCase
 
     assert_equal "5678\n", crate.dereference('data/info.txt').source.read
   end
+
+  test 'can delete entities' do
+    crate = ROCrate::Crate.new
+    file = crate.add_file(StringIO.new(''), 'file')
+    person = crate.add_person('#bob', { name: 'Bob' })
+    file.author = person
+
+    assert crate.delete(file)
+    assert_not_include crate.entities, file
+    assert_not_include crate.entities, person
+  end
+
+  test 'can delete entities by id' do
+    crate = ROCrate::Crate.new
+    file = crate.add_file(StringIO.new(''), 'file')
+    person = crate.add_person('#bob', { name: 'Bob' })
+    file.author = person
+
+    assert crate.delete('file')
+    assert_not_include crate.entities, file
+    assert_not_include crate.entities, person
+  end
+
+  test 'legacy entries method still returns same result as payload' do
+    crate = ROCrate::Crate.new
+    crate.add_all(fixture_file('directory').path)
+
+    paths = crate.entries.keys
+    assert_equal 8, paths.length
+    assert_includes paths, 'data'
+    assert_includes paths, 'root.txt'
+    assert_includes paths, 'info.txt'
+    assert_includes paths, 'data/binary.jpg'
+    assert_includes paths, 'data/info.txt'
+    assert_includes paths, 'data/nested.txt'
+    assert_not_includes paths, '.dotfile'
+    assert_not_includes paths, '.dir'
+    assert_not_includes paths, '.dir/test.txt'
+    assert_includes paths, 'ro-crate-metadata.json'
+    assert_includes paths, 'ro-crate-preview.html'
+
+    assert_equal crate.payload.keys, crate.entries.keys
+  end
+
+  test 'can garbage collect unlinked entities' do
+    crate = ROCrate::Reader.read(fixture_file('unlinked_entity_crate').path)
+
+    unlinked = crate.gc
+    assert_equal 2, unlinked.length
+    ids = unlinked.map(&:id)
+    assert_includes ids, '#joe'
+    assert_includes ids, '#joehouse'
+    assert_not_includes crate.contextual_entities, unlinked.first
+    assert_not_includes crate.contextual_entities, unlinked.last
+    assert_nil crate.get('#joe')
+    assert_nil crate.get('#joehouse')
+  end
+
+  test 'can conditionally garbage collect unlinked entities using a block' do
+    crate = ROCrate::Reader.read(fixture_file('unlinked_entity_crate').path)
+
+    unlinked = crate.gc do |entity|
+      entity.is_a?(ROCrate::Person)
+    end
+    assert_equal 1, unlinked.length
+    ids = unlinked.map(&:id)
+    assert_includes ids, '#joe'
+    assert_not_includes crate.contextual_entities, unlinked.first
+    assert_nil crate.get('#joe')
+    assert crate.get('#joehouse')
+  end
 end