ro-crate 0.4.10 → 0.4.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb6b4eba94b7190b7888cf3b1ddc8a8c6d0b464834ff48c45d9b50e6b13844ce
-  data.tar.gz: 70e0079caadfa3f17745e918f8109ec5908a8aa0c87d80aeaebfc55fdc03a9a8
+  metadata.gz: 5d94d65b4375c3923a828f763c749e9958d975c2f3fd3ee55b996f718cd9317c
+  data.tar.gz: 3ce5e362db42e5a790991bef4fe252d507a35e83eff00a58b1fe99ce4f5808e6
 SHA512:
-  metadata.gz: 62c9875be216987ceaca7e47f92112ba744109e4df9f8dcbba9023211ef3fc278f74f8ce7421523a0f443000f251627735eb01ce2357e9e526e36c23818bbba0
-  data.tar.gz: 0b5be2eedc7a045ccf25db4e3d800107f30d00b62e1e4b5bdb1deed1eed941897f46621bef9fa9a012891bc058857de82d6afebeb122153f8ffc944b8ca06a7a
+  metadata.gz: dd26c3d0fc2783f7424ba022ae03d5cc14c0e4aa7f96e2c6b682f82be3af9cee5cacb1480b414b5ab2f37d08e19b38b377455afd1ec74017901788a4a6500bab
+  data.tar.gz: eb6f983303b2b50fafaec3a03c4c3f855b4c12a4fcd80611d20916ec1f64c078973e842d1425c3101a1609b16db3bdfbe56eccde2a703de0efc360df0a48550f

data/Gemfile.lock

@@ -1,31 +1,31 @@
 PATH
   remote: .
   specs:
-    ro-crate (0.4.10)
-      addressable (~> 2.7.0)
+    ro-crate (0.4.14)
+      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.1)
+    docile (1.3.5)
     hashdiff (1.0.1)
-    json (2.3.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)
-    simplecov (0.16.1)
+    simplecov (0.21.2)
       docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
-    test-unit (3.2.3)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.2)
+    test-unit (3.2.9)
       power_assert
     webmock (3.8.3)
       addressable (>= 2.3.6)
@@ -39,7 +39,7 @@ PLATFORMS
 DEPENDENCIES
   rake (~> 13.0.0)
   ro-crate!
-  simplecov (~> 0.16.1)
+  simplecov (~> 0.21.2)
   test-unit (~> 3.2.3)
   webmock (~> 3.8.3)
   yard (~> 0.9.25)

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/
@@ -17,6 +19,43 @@ and run `bundle install`.
 
 ## Usage
 
+This gem consists a hierarchy of classes to model RO-Crate "entities": the crate itself, data entities 
+(files and directory) and contextual entities (with a limited set of specializations, such as `ROCrate::Person`). 
+They are all descendents of the `ROCrate::Entity` class, with the `ROCrate::Crate` class representing the crate itself. 
+
+The `ROCrate::Reader` class handles reading of RO-Crates into the above model, from a Zip file or directory.
+
+The `ROCrate::Writer` class can write out an `ROCrate::Crate` instance into a Zip file or directory.
+
+**Note:** for performance reasons, the gem is currently not linked-data aware and will allow you to set properties that 
+are not semantically valid.
+
+### Entities
+Entities correspond to entries in the `@graph` of the RO-Crate's metadata JSON-LD file. Each entity class is 
+basically a wrapper around a set of JSON properties, with some convenience methods for getting/setting some 
+commonly used properties (`crate.name = "My first crate"`).
+ 
+These convenience getter/setter methods will automatically handle turning objects into references and adding them to the 
+`@graph` if necessary.
+
+##### Getting/Setting Arbitrary Properties of Entities
+As well as using the pre-defined getter/setter methods, you can get/set arbitrary properties like so.
+
+To set the "creativeWorkStatus" property of the RO-Crate itself to a string literal:
+```ruby
+crate['creativeWorkStatus'] = 'work-in-progress'
+```
+
+If you want to reference other entities in the crate, you can get a JSON-LD reference from an entity object by using the `reference` method:
+```ruby
+joe = crate.add_person('joe', { name: 'Joe Bloggs' }) # Add the entity to the @graph
+crate['copyrightHolder'] = joe.reference # Reference the entity from the "copyrightHolder" property
+```
+and to resolve those references back to the object, use the `dereference` method:
+```ruby
+joe = crate['copyrightHolder'].dereference
+```
+
 ### Documentation
 
 [Click here for API documentation](https://www.researchobject.org/ro-crate-ruby/).

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.
     #
@@ -168,6 +177,15 @@ module ROCrate
       @preview ||= ROCrate::Preview.new(self)
     end
 
+    ##
+    # Set the RO-Crate preview file
+    # @param preview [Preview] the preview to set.
+    #
+    # @return [Preview]
+    def preview=(preview)
+      @preview = claim(preview)
+    end
+
     ##
     # All the entities within the crate. Includes contextual entities, data entities, the crate itself and its metadata file.
     #
@@ -220,32 +238,56 @@ 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
+
     private
 
     def full_entry_path(relative_path)

data/lib/ro_crate/model/data_entity.rb

@@ -3,9 +3,7 @@ module ROCrate
   # A class to represent a "Data Entity" within an RO-Crate.
   # Data Entities are the actual physical files and directories within the Crate.
   class DataEntity < Entity
-    def self.format_local_id(id)
-      super.chomp('/')
-    end
+    properties(%w[name contentSize dateModified encodingFormat identifier sameAs author])
 
     ##
     # Return an appropriate specialization of DataEntity for the given properties.
@@ -13,23 +11,38 @@ module ROCrate
     # @return [Class]
     def self.specialize(props)
       type = props['@type']
-      id = props['@id']
-      abs = URI(id)&.absolute? rescue false
       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

@@ -2,14 +2,12 @@ module ROCrate
   ##
   # A data entity that represents a directory of potentially many files and subdirectories (or none).
   class Directory < DataEntity
-    properties(%w[name contentSize dateModified encodingFormat identifier sameAs])
-
     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.
@@ -26,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,33 @@ 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 do |key, value|
+        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
+              linked[entity.id] = entity if 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,14 +2,16 @@ module ROCrate
   ##
   # A data entity that represents a single file.
   class File < DataEntity
-    properties(%w[name contentSize dateModified encodingFormat identifier sameAs])
+    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.
     #
     # @param crate [Crate] The RO-Crate that owns this file.
-    # @param source [String, Pathname, ::File, #read, URI, nil] The source on the disk (or on the internet if a URI) where this file will be read.
+    # @param source [String, Pathname, ::File, URI, nil, #read] The source on the disk (or on the internet if a URI) where this file will be read.
     # @param crate_path [String] The relative path within the RO-Crate where this file will be written.
     # @param properties [Hash{String => Object}] A hash of JSON-LD properties to associate with this file.
     def initialize(crate, source, crate_path = nil, properties = {})
@@ -34,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)
@@ -58,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/metadata.rb

@@ -17,7 +17,15 @@ module ROCrate
     # @return [String] The rendered JSON-LD as a "prettified" string.
     def generate
       graph = crate.entities.map(&:properties).reject(&:empty?)
-      JSON.pretty_generate('@context' => CONTEXT, '@graph' => graph)
+      JSON.pretty_generate('@context' => context, '@graph' => graph)
+    end
+
+    def context
+      @context || CONTEXT
+    end
+
+    def context= c
+      @context = c
     end
 
     private

data/lib/ro_crate/model/organization.rb

@@ -2,7 +2,7 @@ module ROCrate
   ##
   # A contextual entity that represents an organization.
   class Organization < ContextualEntity
-    properties(['name'])
+    properties(%w[name])
 
     private
 

data/lib/ro_crate/model/preview.rb

@@ -12,26 +12,14 @@ module ROCrate
     # @return [String]
     attr_accessor :template
 
-    def initialize(crate, properties = {})
+    def initialize(crate, source = nil, properties = {})
+      source ||= PreviewGenerator.new(self)
       @template = nil
-      super(crate, nil, IDENTIFIER, properties)
-    end
-
-    ##
-    # Generate the crate's `ro-crate-preview.html`.
-    # @return [String] The rendered HTML as a string.
-    def generate
-      b = crate.get_binding
-      renderer = ERB.new(template || ::File.read(DEFAULT_TEMPLATE))
-      renderer.result(b)
+      super(crate, source, IDENTIFIER, properties)
     end
 
     private
 
-    def source
-      Entry.new(StringIO.new(generate))
-    end
-
     def default_properties
       {
         '@id' => IDENTIFIER,

data/lib/ro_crate/model/preview_generator.rb

@@ -0,0 +1,40 @@
+require 'erb'
+
+module ROCrate
+  ##
+  # A class to handle generation of an RO-Crate's preview HTML in an IO-like way (to fit into an Entry).
+  class PreviewGenerator
+    ##
+    # @param preview [Preview] The RO-Crate preview object.
+    def initialize(preview)
+      @preview = preview
+    end
+
+    def read(*args)
+      io.read(*args)
+    end
+
+    ##
+    # Generate the crate's `ro-crate-preview.html`.
+    # @return [String] The rendered HTML as a string.
+    def generate
+      b = crate.get_binding
+      renderer = ERB.new(template)
+      renderer.result(b)
+    end
+
+    def template
+      @preview.template || ::File.read(Preview::DEFAULT_TEMPLATE)
+    end
+
+    def crate
+      @preview.crate
+    end
+
+    private
+
+    def io
+      @io ||= StringIO.new(generate)
+    end
+  end
+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,17 +13,6 @@ 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.
     #