ro-crate 0.4.8 → 0.4.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7003f224766d4445498db499257b246ea2dbfb842f0f5e0c8d04471ccea4d299
-  data.tar.gz: f62e7c90a54f26aa6b18cf98310c998ada8c6836975c997f551b2b1ab7d85e29
+  metadata.gz: d9f081110d1e5b5e94674cb53d07262fbce50ec3f63437d5c4c1ecda8b04f835
+  data.tar.gz: 0cd710a9cd86063e706fd9cf338e5fdf55f5bc6993f306af4f50d6f9191a0d87
 SHA512:
-  metadata.gz: f63fa2c3b9d88ec76f20e8986986d81878dc8bbb82bedd4c2c862ca6fca7f021ad84309678abb12ec6de7fb498a87711409f3f64809aba4c09c5b00676c60aac
-  data.tar.gz: 16616f82e91760e9a6ff3eff1199c327143401086b0f9c577908e28d023e27828b7e36eeffc65333ec3aa440697b8f18cddd9406185f116ccc59ff238c98b1e9
+  metadata.gz: 8ce573fbd259108edbb528e24f0d9647cfee4454378d57a4b3392aaeb0dea80385b2828221a0979caa4733be0e2108a4a535725846f576c9ac97866f46911e47
+  data.tar.gz: ffc7aafbdccb3f4897ad2acae726714d7a313f02fd87e5c96173da2b12860dfa1318b9b323dde751e3ac10c9a66cf29effea383037bc4622eaf5113dd01bd426

data/Gemfile.lock

@@ -1,31 +1,31 @@
 PATH
   remote: .
   specs:
-    ro-crate (0.4.8)
-      addressable (~> 2.7.0)
+    ro-crate (0.4.12)
+      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/contextual_entity.rb

@@ -3,21 +3,9 @@ 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)
+    def self.format_local_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
+      i.start_with?('#') ? i : "##{i}"
     end
 
     ##

data/lib/ro_crate/model/crate.rb

@@ -8,6 +8,11 @@ module ROCrate
     properties(%w[name datePublished author license identifier distribution contactPoint publisher description url hasPart])
 
     def self.format_id(id)
+      i = super(id)
+      i.end_with?('/') ? i : "#{i}/"
+    end
+
+    def self.format_local_id(id)
       return id if id == IDENTIFIER
       super
     end
@@ -20,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.
     #
@@ -163,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.
     #
@@ -215,21 +238,21 @@ 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
@@ -241,6 +264,29 @@ module ROCrate
       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,7 +3,9 @@ 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_id(id)
+    properties(%w[name contentSize dateModified encodingFormat identifier sameAs author])
+
+    def self.format_local_id(id)
       super.chomp('/')
     end
 
@@ -13,8 +15,6 @@ 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
@@ -24,12 +24,13 @@ module ROCrate
     end
 
     ##
-    # A map of all the files/directories associated with this DataEntity.
+    # 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,9 +2,7 @@ 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_id(id)
+    def self.format_local_id(id)
       super + '/'
     end
 
@@ -30,11 +28,11 @@ module ROCrate
     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

@@ -29,12 +29,34 @@ module ROCrate
     end
 
     ##
-    # Format the given ID with rules appropriate for this type.
+    # Format the given ID with rules appropriate for this type if it is local/relative, leave as-is if absolute.
+    #
+    # @param id [String] The candidate ID to be formatted.
+    # @return [String] The formatted ID.
+    def self.format_id(id)
+      begin
+        uri = URI(id)
+      rescue ArgumentError, URI::InvalidURIError
+        uri = nil
+      end
+
+      if uri&.absolute?
+        id
+      else
+        format_local_id(id)
+      end
+    end
+
+    ##
+    # Format the given local ID with rules appropriate for this type.
     # For example:
     #  * contextual entities MUST be absolute URIs, or begin with: #
     #  * files MUST NOT begin with ./
     #  * directories MUST NOT begin with ./ (except for the crate itself), and MUST end with /
-    def self.format_id(id)
+    #
+    # @param id [String] The candidate local ID to be formatted.
+    # @return [String] The formatted local ID.
+    def self.format_local_id(id)
       Addressable::URI.escape(id.sub(/\A\.\//, '')) # Remove initial ./ if present
     end
 
@@ -107,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
 
@@ -168,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
@@ -204,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,12 @@ module ROCrate
   ##
   # A data entity that represents a single file.
   class File < DataEntity
-    properties(%w[name contentSize dateModified encodingFormat identifier sameAs])
-
     ##
     # 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 = {})
@@ -58,7 +56,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.
     #