ro-crate 0.4.0

data/lib/ro_crate/model/metadata.rb

@@ -0,0 +1,38 @@
+module ROCrate
+  ##
+  # A representation of the `ro-crate-metadata.jsonld` file.
+  class Metadata < File
+    IDENTIFIER = 'ro-crate-metadata.json'.freeze
+    IDENTIFIER_1_0 = 'ro-crate-metadata.jsonld'.freeze # 1.0 spec identifier
+    RO_CRATE_BASE = 'https://w3id.org/ro/crate/'
+    CONTEXT = "#{RO_CRATE_BASE}1.1/context".freeze
+    SPEC = "#{RO_CRATE_BASE}1.1".freeze
+
+    def initialize(crate, properties = {})
+      super(crate, nil, IDENTIFIER, properties)
+    end
+
+    ##
+    # Generate the crate's `ro-crate-metadata.jsonld`.
+    # @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)
+    end
+
+    private
+
+    def source
+      Entry.new(StringIO.new(generate))
+    end
+
+    def default_properties
+      {
+        '@id' => IDENTIFIER,
+        '@type' => 'CreativeWork',
+        'about' => { '@id' => crate.id },
+        'conformsTo' => { '@id' => SPEC }
+      }
+    end
+  end
+end

data/lib/ro_crate/model/organization.rb

@@ -0,0 +1,13 @@
+module ROCrate
+  ##
+  # A contextual entity that represents an organization.
+  class Organization < ContextualEntity
+    properties(['name'])
+
+    private
+
+    def default_properties
+      super.merge('@type' => 'Organization')
+    end
+  end
+end

data/lib/ro_crate/model/person.rb

@@ -0,0 +1,13 @@
+module ROCrate
+  ##
+  # A contextual entity that represents a person.
+  class Person < ContextualEntity
+    properties(%w[name familyName givenName identifier sameAs])
+
+    private
+
+    def default_properties
+      super.merge('@type' => 'Person')
+    end
+  end
+end

data/lib/ro_crate/model/preview.rb

@@ -0,0 +1,43 @@
+require 'erb'
+
+module ROCrate
+  ##
+  # A representation of the `ro-crate-preview.html` file.
+  class Preview < File
+    IDENTIFIER = 'ro-crate-preview.html'.freeze
+    DEFAULT_TEMPLATE = ::File.expand_path(::File.join(::File.dirname(__FILE__), '..', 'ro-crate-preview.html.erb'))
+
+    ##
+    # The ERB template to use when rendering the preview.
+    # @return [String]
+    attr_accessor :template
+
+    def initialize(crate, properties = {})
+      @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)
+    end
+
+    private
+
+    def source
+      Entry.new(StringIO.new(generate))
+    end
+
+    def default_properties
+      {
+        '@id' => IDENTIFIER,
+        '@type' => 'CreativeWork',
+        'about' => { '@id' => ROCrate::Crate::IDENTIFIER }
+      }
+    end
+  end
+end

data/lib/ro_crate/model/remote_entry.rb

@@ -0,0 +1,46 @@
+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
+    attr_reader :uri
+
+    ##
+    # Create a new RemoteEntry.
+    #
+    # @param uri [URI] An absolute URI.
+    def initialize(uri)
+      @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)
+    end
+
+    ##
+    # Does this RemoteEntry point to a directory on the disk?
+    def directory?
+      false
+    end
+
+    ##
+    # Does this RemoteEntry point to a remote resource?
+    def remote?
+      true
+    end
+  end
+end

data/lib/ro_crate/reader.rb

@@ -0,0 +1,213 @@
+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.
+    #
+    # @param source [String, ::File, Pathname] The source location for the crate.
+    # @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)
+        read_directory(source)
+      else
+        read_zip(source, target_dir: target_dir)
+      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)
+      Dir.chdir(target) do
+        Zip::File.open(source) do |zipfile|
+          zipfile.each do |entry|
+            unless ::File.exist?(entry.name)
+              FileUtils::mkdir_p(::File.dirname(entry.name))
+              zipfile.extract(entry, entry.name)
+            end
+          end
+        end
+      end
+    end
+
+    ##
+    # 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 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)
+    end
+
+    ##
+    # Reads an RO Crate from a directory.
+    #
+    # @param source [String, ::File, Pathname] The location of the directory.
+    # @return [Crate] The RO Crate.
+    def self.read_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)
+      else
+        raise 'No metadata found!'
+      end
+    end
+
+    ##
+    # Extracts all the entities from the @graph of the RO Crate Metadata.
+    #
+    # @param metadata_json [String] A string containing the 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)
+      graph = metadata['@graph']
+
+      if graph
+        # Collect all the things in the graph, mapped by their @id
+        entities = {}
+        graph.each do |entity|
+          entities[entity['@id']] = entity
+        end
+
+        # 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::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]
+
+        entities
+      else
+        raise "No @graph found in metadata!"
+      end
+    end
+
+    ##
+    # Create 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.
+    # @return [Crate] The RO Crate.
+    def self.build_crate(entity_hash, source)
+      ROCrate::Crate.new.tap do |crate|
+        crate.properties = entity_hash.delete(ROCrate::Crate::IDENTIFIER)
+        crate.metadata.properties = entity_hash.delete(ROCrate::Metadata::IDENTIFIER)
+        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
+      end
+    end
+
+    ##
+    # Discover data entities from the `hasPart` property of a crate, and create DataEntity objects for them.
+    # Entities are looked up in the given `entity_hash` (and then removed from it).
+    # @param crate [Crate] The RO Crate being read.
+    # @param source [String, ::File, Pathname] The location of the RO Crate being read.
+    # @param entity_hash [Hash] A Hash containing all the entities in the @graph, mapped by their @id.
+    # @return [Array<ROCrate::File, ROCrate::Directory>] The extracted DataEntity objects.
+    def self.extract_data_entities(crate, source, entity_hash)
+      crate.raw_properties['hasPart'].map do |ref|
+        entity_props = entity_hash.delete(ref['@id'])
+        next unless entity_props
+        entity_class = ROCrate::DataEntity.specialize(entity_props)
+        entity = create_data_entity(crate, entity_class, source, entity_props)
+        next if entity.nil?
+        entity
+      end.compact
+    end
+
+    ##
+    # Create appropriately specialized ContextualEntity objects from the given hash of entities and their properties.
+    # @param crate [Crate] The RO Crate being read.
+    # @param entity_hash [Hash] A Hash containing all the entities in the @graph, mapped by their @id.
+    # @return [Array<ContextualEntity>] The extracted ContextualEntity objects.
+    def self.extract_contextual_entities(crate, entity_hash)
+      entities = []
+
+      entity_hash.each do |id, entity_props|
+        entity_class = ROCrate::ContextualEntity.specialize(entity_props)
+        entity = entity_class.new(crate, id, entity_props)
+        entities << entity
+      end
+
+      entities
+    end
+
+    ##
+    # Create a DataEntity of the given class.
+    # @param crate [Crate] The RO Crate being read.
+    # @param source [String, ::File, Pathname] The location of the RO Crate being read.
+    # @param entity_props [Hash] A Hash containing the entity's properties, including its @id.
+    # @return [ROCrate::File, ROCrate::Directory, nil] The DataEntity object,
+    #          or nil if it referenced a local file that wasn't found.
+    def self.create_data_entity(crate, entity_class, source, entity_props)
+      id = entity_props.delete('@id')
+      decoded_id = URI.decode_www_form_component(id)
+      path = nil
+      uri = URI(id) rescue nil
+      if uri&.absolute?
+        path = uri
+        decoded_id = nil
+      else
+        [id, decoded_id].each do |i|
+          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
+      end
+
+      entity_class.new(crate, path, decoded_id, entity_props)
+    end
+
+
+    ##
+    # 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.
+    def self.extract_metadata_entity(entities)
+      key = entities.detect do |_, props|
+        props.dig('conformsTo', '@id')&.start_with?(ROCrate::Metadata::RO_CRATE_BASE)
+      end&.first
+
+      return entities.delete(key) if key
+
+      # Legacy support
+      (entities.delete("./#{ROCrate::Metadata::IDENTIFIER}") ||
+          entities.delete(ROCrate::Metadata::IDENTIFIER) ||
+          entities.delete("./#{ROCrate::Metadata::IDENTIFIER_1_0}") ||
+          entities.delete(ROCrate::Metadata::IDENTIFIER_1_0))
+    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
+    # @return [Hash{String => Hash}] A Hash containing (hopefully) one value, the root entity's properties,
+    # mapped by its @id.
+    def self.extract_root_entity(entities)
+      root_id = entities[ROCrate::Metadata::IDENTIFIER].dig('about', '@id')
+      raise "Metadata entity does not reference any root entity" unless root_id
+      entities.delete(root_id)
+    end
+  end
+end

data/lib/ro_crate/ro-crate-preview.html.erb

@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title><%= name || "New RO Crate" %></title>
+  <script type="application/ld+json"><%= metadata.generate %></script>
+  <meta name="generator" content="https://github.com/fbacall/ro-crate-ruby">
+  <meta name="keywords" content="RO Crate">
+</head>
+<body>
+  <h1><%= name || "New RO Crate" %></h1>
+  <% if url %>
+    <a href="<%= url %>" target="_blank"><%= url %></a>
+  <% end %>
+  <p>
+    <%= description %>
+  </p>
+  <dl>
+    <% if author %>
+      <dt>Author</dt>
+      <dd><%= author %></dd>
+    <% end %>
+    <% if contact_point %>
+      <dt>Contact</dt>
+      <dd><%= contact_point %></dd>
+    <% end %>
+    <% if publisher %>
+      <dt>Publisher</dt>
+      <dd><%= publisher %></dd>
+    <% end %>
+    <% if license %>
+      <dt>License</dt>
+      <dd><%= license %></dd>
+    <% end %>
+  </dl>
+
+  <h2>Contents</h2>
+  <ul>
+    <% data_entities.each do |data_entity| %>
+      <li id="__data_entity_<%= data_entity.id.gsub(/\s/, '-') %>">
+        <% if data_entity.external? %>
+          <strong><a href="<%= data_entity.id %>" target="_blank"><%= data_entity.name || data_entity.id %></a></strong>
+        <% else %>
+          <strong><%= data_entity.name || data_entity.id %></strong>
+        <% end %>
+        <% if data_entity.content_size %>
+          <br/>Size: <%= data_entity.content_size %>
+        <% end %>
+        <% if data_entity.encoding_format %>
+          <br/>Format: <%= data_entity.encoding_format %>
+        <% end %>
+      </li>
+    <% end %>
+  </ul>
+</body>
+</html>

data/lib/ro_crate/writer.rb

@@ -0,0 +1,48 @@
+module ROCrate
+  ##
+  # A class to handle writing of RO Crates to Zip files or directories.
+  class Writer
+    ##
+    # Initialize a new Writer for the given Crate.
+    # @param crate [Crate] The RO Crate to be written.
+    def initialize(crate)
+      @crate = crate
+    end
+
+    ##
+    # Write the crate to a directory.
+    #
+    # @param dir [String] A path for the directory for the crate to be written to. All parent directories will be created.
+    # @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|
+        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)
+          temp.close
+          FileUtils.mv(temp, fullpath)
+        ensure
+          temp.unlink
+        end
+      end
+    end
+
+    ##
+    # Write the crate to a zip file.
+    #
+    # @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|
+          next if entry.directory?
+          zip.get_output_stream(path) { |s| entry.write(s) }
+        end
+      end
+    end
+  end
+end