ro-crate 0.4.6 → 0.4.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4880110308b68d8bc35333b1fc8a8396ea30e36069f92e059b8c57ec3567d33e
-  data.tar.gz: 77a17a0436f2dea14254a3501f9db349eed5460851d94ab4e87adb7be83e1b38
+  metadata.gz: 62f3979b325743d31720f803dbf75690ad6b7b9bcf9f2cbf63d8200a2bb204ba
+  data.tar.gz: 3a229e06492a3f9a90721799f43929d6a5ca01fc0a0ff34d917eeebff037d9d4
 SHA512:
-  metadata.gz: 711a45d7aaa63f8a5a7bba78e433d82875311472d6f4abfd6d388dd8565a7707036152c81de4059fd92da5b7851925caf9d808f39d115752e68eaddbdc85bac1
-  data.tar.gz: ce14efaf63e7224adc79cdb11d27bdec933be290ccf60196014cb7ce9380136451265a8f814e1ca7b70286fc32852024d429334bbaab18208d31095cd619dc9e
+  metadata.gz: 242b8e326756d51ab583726db7fb94763286f2764bdf1f0523cd9dab5fa560fe4da3016a4a4b84b0cc6bcef4ec096aeae7dc2fd344ef6cb5ee045cf99a954ef9
+  data.tar.gz: 4abaece91d997ac398ee627f639fc98c924768c255bac1bb6c9ce7f43fc03f5b018a2fc657008863c65537592261e85f697ef2c7e200c20621ba41ff0a933541

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ro-crate (0.4.6)
+    ro-crate (0.4.11)
       addressable (~> 2.7.0)
       rubyzip (~> 2.0.0)
 
@@ -12,19 +12,19 @@ GEM
       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)
     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)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.2)
     test-unit (3.2.3)
       power_assert
     webmock (3.8.3)
@@ -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

@@ -17,6 +17,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.rb

@@ -14,6 +14,7 @@ require 'ro_crate/model/remote_entry'
 require 'ro_crate/model/entry'
 require 'ro_crate/model/directory'
 require 'ro_crate/model/metadata'
+require 'ro_crate/model/preview_generator'
 require 'ro_crate/model/preview'
 require 'ro_crate/model/crate'
 require 'ro_crate/model/contextual_entity'

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
@@ -163,6 +168,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.
     #

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

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
 

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
 

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 = {})

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/reader.rb

@@ -3,29 +3,67 @@ module ROCrate
   # A class to handle reading of RO-Crates from Zip files or directories.
   class Reader
     ##
-    # Reads an RO-Crate from a directory of zip file.
+    # Reads an RO-Crate from a directory or zip file.
     #
-    # @param source [String, ::File, Pathname] The source location for the crate.
+    # @param source [String, ::File, Pathname, #read] The location of the zip or directory, or an IO-like object containing a zip.
     # @param target_dir [String, ::File, Pathname] The target directory where the crate should be unzipped (if its a Zip file).
     # @return [Crate] The RO-Crate.
     def self.read(source, target_dir: Dir.mktmpdir)
       raise "Not a directory!" unless ::File.directory?(target_dir)
-      if ::File.directory?(source)
+      begin
+        is_dir = ::File.directory?(source)
+      rescue TypeError
+        is_dir = false
+      end
+
+      if is_dir
         read_directory(source)
       else
         read_zip(source, target_dir: target_dir)
       end
     end
 
+    ##
+    # Extract the contents of the given Zip file/data to the given directory.
+    #
+    # @param source [String, ::File, Pathname, #read] The location of the zip file, or an IO-like object.
+    # @param target [String, ::File, Pathname] The target directory where the file should be unzipped.
+    def self.unzip_to(source, target)
+      source = Pathname.new(::File.expand_path(source)) if source.is_a?(String)
+
+      if source.is_a?(Pathname) || source.respond_to?(:path)
+        unzip_file_to(source, target)
+      else
+        unzip_io_to(source, target)
+      end
+    end
+
+    ##
+    # Extract the given Zip file data to the given directory.
+    #
+    # @param source [#read] An IO-like object containing a Zip file.
+    # @param target [String, ::File, Pathname] The target directory where the file should be unzipped.
+    def self.unzip_io_to(io, target)
+      Dir.chdir(target) do
+        Zip::InputStream.open(io) do |input|
+          while (entry = input.get_next_entry)
+            unless ::File.exist?(entry.name) || entry.name_is_directory?
+              FileUtils::mkdir_p(::File.dirname(entry.name))
+              ::File.binwrite(entry.name, input.read)
+            end
+          end
+        end
+      end
+    end
+
     ##
     # Extract the contents of the given Zip file to the given directory.
     #
     # @param source [String, ::File, Pathname] The location of the zip file.
     # @param target [String, ::File, Pathname] The target directory where the file should be unzipped.
-    def self.unzip_to(source, target)
-      source = ::File.expand_path(source)
+    def self.unzip_file_to(file_or_path, target)
       Dir.chdir(target) do
-        Zip::File.open(source) do |zipfile|
+        Zip::File.open(file_or_path) do |zipfile|
           zipfile.each do |entry|
             unless ::File.exist?(entry.name)
               FileUtils::mkdir_p(::File.dirname(entry.name))
@@ -40,13 +78,16 @@ module ROCrate
     # Reads an RO-Crate from a zip file. It first extracts the Zip file to a temporary directory, and then calls
     # #read_directory.
     #
-    # @param source [String, ::File, Pathname] The location of the zip file.
+    # @param source [String, ::File, Pathname, #read] The location of the zip file, or an IO-like object.
     # @param target_dir [String, ::File, Pathname] The target directory where the crate should be unzipped.
     # @return [Crate] The RO-Crate.
     def self.read_zip(source, target_dir: Dir.mktmpdir)
       unzip_to(source, target_dir)
 
-      read_directory(target_dir)
+      # Traverse the unzipped directory to try and find the crate's root
+      root_dir = detect_root_directory(target_dir)
+
+      read_directory(root_dir)
     end
 
     ##
@@ -55,13 +96,19 @@ module ROCrate
     # @param source [String, ::File, Pathname] The location of the directory.
     # @return [Crate] The RO-Crate.
     def self.read_directory(source)
+      raise "Not a directory!" unless ::File.directory?(source)
+
       source = ::File.expand_path(source)
       metadata_file = Dir.entries(source).detect { |entry| entry == ROCrate::Metadata::IDENTIFIER ||
           entry == ROCrate::Metadata::IDENTIFIER_1_0 }
 
       if metadata_file
-        entities = entities_from_metadata(::File.read(::File.join(source, metadata_file)))
-        build_crate(entities, source)
+        metadata_json = ::File.read(::File.join(source, metadata_file))
+        metadata = JSON.parse(metadata_json)
+        entities = entities_from_metadata(metadata)
+        context = metadata['@context']
+
+        build_crate(entities, source, context: context)
       else
         raise 'No metadata found!'
       end
@@ -70,10 +117,9 @@ module ROCrate
     ##
     # Extracts all the entities from the @graph of the RO-Crate Metadata.
     #
-    # @param metadata_json [String] A string containing the metadata JSON.
+    # @param metadata [Hash] A Hash containing the parsed metadata JSON.
     # @return [Hash{String => Hash}] A Hash of all the entities, mapped by their @id.
-    def self.entities_from_metadata(metadata_json)
-      metadata = JSON.parse(metadata_json)
+    def self.entities_from_metadata(metadata)
       graph = metadata['@graph']
 
       if graph
@@ -86,6 +132,7 @@ module ROCrate
         # Do some normalization...
         entities[ROCrate::Metadata::IDENTIFIER] = extract_metadata_entity(entities)
         raise "No metadata entity found in @graph!" unless entities[ROCrate::Metadata::IDENTIFIER]
+        entities[ROCrate::Preview::IDENTIFIER] = extract_preview_entity(entities)
         entities[ROCrate::Crate::IDENTIFIER] = extract_root_entity(entities)
         raise "No root entity (with @id: #{entities[ROCrate::Metadata::IDENTIFIER].dig('about', '@id')}) found in @graph!" unless entities[ROCrate::Crate::IDENTIFIER]
 
@@ -96,25 +143,49 @@ module ROCrate
     end
 
     ##
-    # Create a crate from the given set of entities.
+    # Create and populate crate from the given set of entities.
     #
     # @param entity_hash [Hash{String => Hash}] A Hash containing all the entities in the @graph, mapped by their @id.
     # @param source [String, ::File, Pathname] The location of the RO-Crate being read.
+    # @param crate_class [Class] The class to use to instantiate the crate,
+    #   useful if you have created a subclass of ROCrate::Crate that you want to use. (defaults to ROCrate::Crate).
+    # @param context [nil, String, Array, Hash] A custom JSON-LD @context (parsed), or nil to use default.
     # @return [Crate] The RO-Crate.
-    def self.build_crate(entity_hash, source)
-      ROCrate::Crate.new.tap do |crate|
+    def self.build_crate(entity_hash, source, crate_class: ROCrate::Crate, context:)
+      crate = initialize_crate(entity_hash, source, crate_class: crate_class, context: context)
+
+      extract_data_entities(crate, source, entity_hash).each do |entity|
+        crate.add_data_entity(entity)
+      end
+
+      # The remaining entities in the hash must be contextual.
+      extract_contextual_entities(crate, entity_hash).each do |entity|
+        crate.add_contextual_entity(entity)
+      end
+
+      crate
+    end
+
+    ##
+    # Initialize a crate from the given set of entities.
+    #
+    # @param entity_hash [Hash{String => Hash}] A Hash containing all the entities in the @graph, mapped by their @id.
+    # @param source [String, ::File, Pathname] The location of the RO-Crate being read.
+    # @param crate_class [Class] The class to use to instantiate the crate,
+    #   useful if you have created a subclass of ROCrate::Crate that you want to use. (defaults to ROCrate::Crate).
+    # @param context [nil, String, Array, Hash] A custom JSON-LD @context (parsed), or nil to use default.
+    # @return [Crate] The RO-Crate.
+    def self.initialize_crate(entity_hash, source, crate_class: ROCrate::Crate, context:)
+      crate_class.new.tap do |crate|
         crate.properties = entity_hash.delete(ROCrate::Crate::IDENTIFIER)
         crate.metadata.properties = entity_hash.delete(ROCrate::Metadata::IDENTIFIER)
+        crate.metadata.context = context
         preview_properties = entity_hash.delete(ROCrate::Preview::IDENTIFIER)
-        crate.preview.properties = preview_properties if preview_properties
-        crate.add_all(source, false)
-        extract_data_entities(crate, source, entity_hash).each do |entity|
-          crate.add_data_entity(entity)
-        end
-        # The remaining entities in the hash must be contextual.
-        extract_contextual_entities(crate, entity_hash).each do |entity|
-          crate.add_contextual_entity(entity)
+        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)
         end
+        crate.add_all(source, false)
       end
     end
 
@@ -186,8 +257,8 @@ module ROCrate
     ##
     # Extract the metadata entity from the entity hash, according to the rules defined here:
     # https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#finding-the-root-data-entity
-    # @return [Hash{String => Hash}] A Hash containing (hopefully) one value, the metadata entity's properties,
-    # mapped by its @id.
+    # @return [nil, Hash{String => Hash}] A Hash containing (hopefully) one value, the metadata entity's properties
+    # 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)
@@ -202,6 +273,13 @@ module ROCrate
           entities.delete(ROCrate::Metadata::IDENTIFIER_1_0))
     end
 
+    ##
+    # Extract the ro-crate-preview entity from the entity hash.
+    # @return [Hash{String => Hash}] A Hash containing the preview entity's properties mapped by its @id, or nil if nothing is found.
+    def self.extract_preview_entity(entities)
+      entities.delete("./#{ROCrate::Preview::IDENTIFIER}") || entities.delete(ROCrate::Preview::IDENTIFIER)
+    end
+
     ##
     # Extract the root entity from the entity hash, according to the rules defined here:
     # https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#finding-the-root-data-entity
@@ -212,5 +290,23 @@ module ROCrate
       raise "Metadata entity does not reference any root entity" unless root_id
       entities.delete(root_id)
     end
+
+    ##
+    # Finds an RO-Crate's root directory (where `ro-crate-metdata.json` is located) within a given directory.
+    #
+    # @param source [String, ::File, Pathname] The location of the directory.
+    # @return [Pathname, nil] The path to the root, or nil if not found.
+    def self.detect_root_directory(source)
+      Pathname(source).find do |entry|
+        if entry.file?
+          name = entry.basename.to_s
+          if name == ROCrate::Metadata::IDENTIFIER || name == ROCrate::Metadata::IDENTIFIER_1_0
+            return entry.parent
+          end
+        end
+      end
+
+      nil
+    end
   end
 end