ro-crate 0.4.0

data/lib/ro_crate/model/data_entity.rb

@@ -0,0 +1,42 @@
+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)
+      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.
+    # @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
+        ROCrate::File
+      end
+    end
+
+    ##
+    # A map of all the files/directories associated with this DataEntity.
+    #
+    # @return [Hash{String => Entry}>] The key is the location within the crate, and the value is an Entry.
+    def entries
+      {}
+    end
+
+    ##
+    # A disk-safe filepath based on the ID of this DataEntity.
+    #
+    # @return [String] The relative file path of this DataEntity within the Crate.
+    def filepath
+      Addressable::URI.unescape(id.sub(/\A\//, '')).to_s # Remove initial / and decode %20 etc.
+    end
+  end
+end

data/lib/ro_crate/model/directory.rb

@@ -0,0 +1,60 @@
+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)
+      super + '/'
+    end
+
+    ##
+    # Create a new 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.
+    # @param source_directory [String, Pathname, ::File, nil] The source directory that will be included in the crate.
+    # @param crate_path [String] The relative path within the RO crate where this directory will be written.
+    # @param properties [Hash{String => Object}] A hash of JSON-LD properties to associate with this directory.
+    def initialize(crate, source_directory = nil, crate_path = nil, properties = {})
+      @directory_entries = {}
+
+      if source_directory
+        raise 'Not a directory' unless ::File.directory?(source_directory)
+        source_directory = Pathname.new(::File.expand_path(source_directory))
+        crate_path = source_directory.basename.to_s if crate_path.nil?
+
+        Dir.chdir(source_directory) { Dir.glob('**/*') }.each do |rel_path|
+          source_path = Pathname.new(::File.join(source_directory, rel_path)).expand_path
+          @directory_entries[rel_path] = Entry.new(source_path)
+        end
+      end
+
+      super(crate, crate_path, properties)
+    end
+
+    ##
+    # A map of all the files/directories under this directory, 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
+      entries = {}
+
+      @directory_entries.each do |rel_path, entry|
+        entries[::File.join(filepath, rel_path)] = entry
+      end
+
+      entries
+    end
+
+    private
+
+    def default_properties
+      super.merge(
+        '@id' => "#{SecureRandom.uuid}/",
+        '@type' => 'Dataset'
+      )
+    end
+  end
+end

data/lib/ro_crate/model/entity.rb

@@ -0,0 +1,216 @@
+module ROCrate
+  ##
+  # A generic "Entity" within an RO Crate. It has an identifier and a set of properties, and will be referenced in the
+  # RO Crate Metadata's @graph.
+  class Entity
+    attr_reader :crate
+    attr_reader :properties
+
+    ##
+    # Define Ruby-style getters/setters for the given list of properties.
+    # The getters/setters will have underscored names, and will automatically reference/dereference entities within the
+    # crate using their `@id`.
+    def self.properties(props)
+      props.each do |prop|
+        # Convert camelCase to under_score
+        underscored = prop.gsub(/([[:upper:]]*)([[:upper:]])([[:lower:]])/) do
+          m = Regexp.last_match
+          "#{m[1].downcase}_#{m[2].downcase}#{m[3]}"
+        end
+
+        define_method(underscored) do
+          auto_dereference(@properties[prop])
+        end
+
+        define_method("#{underscored}=") do |value|
+          @properties[prop] = auto_reference(value)
+        end
+      end
+    end
+
+    ##
+    # Format the given 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)
+      Addressable::URI.escape(id.sub(/\A\.\//, '')) # Remove initial ./ if present
+    end
+
+    ##
+    # Automatically replace references to entities (e.g. `{ '@id' : '#something' }`) with the Entity object itself.
+    #
+    # @param value [Hash, Array<Hash>, Object] A value that may be reference or array of references.
+    # @return [Entity, Array<Entity>, Object] Return an Entity, Array of Entities, or just the object itself if
+    #   it wasn't a reference after all.
+    def auto_dereference(value)
+      if value.is_a?(Array)
+        return value.map { |v| auto_dereference(v) }
+      end
+
+      if value.is_a?(Hash) && value['@id']
+        obj = dereference(value['@id'])
+        return obj if obj
+      end
+
+      value
+    end
+
+    ##
+    # Automatically replace an Entity or Array of Entities with a reference or Array of references. Also associates
+    # the Entity/Entities with the current crate. This is useful for maintaining the flat @graph of entities that the
+    # RO crate metadata file requires.
+    #
+    # @param value [Entity, Array<Entity>, Object] A value that may be reference or array of references.
+    # @return [Hash, Array<Hash>, Object] Return a reference, Array of references, or just the object itself if
+    #   it wasn't an Entity after all.
+    def auto_reference(value)
+      if value.is_a?(Array)
+        return value.map { |v| auto_reference(v) }
+      end
+
+      if value.is_a?(Entity)
+        # If it's from another crate, need to add it to this one.
+        crate.add_contextual_entity(value)
+
+        return value.reference
+      end
+
+      value
+    end
+
+    ##
+    # Create a new Entity.
+    #
+    # @param crate [Crate] The crate that owns this Entity.
+    # @param id [String, nil] An ID to identify this Entity, or blank 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 entity.
+    def initialize(crate, id = nil, properties = {})
+      @crate = crate
+      @properties = ROCrate::JSONLDHash.new(crate, default_properties.merge(properties))
+      self.id = id if id
+    end
+
+    ##
+    # Return a JSON-LD style reference: { '@id' : '#an-entity' } for this Entity.
+    #
+    # @return [Hash]
+    def reference
+      ROCrate::JSONLDHash.new(crate, '@id' => id)
+    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)
+      crate.entities.detect { |e| e.canonical_id == crate.resolve_id(id) } if id
+    end
+
+    alias_method :get, :dereference
+
+    def id
+      @properties['@id']
+    end
+
+    def id=(id)
+      @properties['@id'] = self.class.format_id(id)
+    end
+
+    def type
+      @properties['@type']
+    end
+
+    def type=(type)
+      @properties['@type'] = type
+    end
+
+    def properties=(props)
+      @properties.replace(props)
+    end
+
+    def inspect
+      prop_string = properties.inspect
+      prop_string = prop_string[0...509] + '...' if prop_string.length > 509
+      "<##{self.class.name} #{canonical_id} @properties=#{prop_string}>"
+    end
+
+    def hash
+      canonical_id.hash
+    end
+
+    def ==(other)
+      return super unless other.is_a?(Entity)
+      canonical_id == other.canonical_id
+    end
+
+    def eql?(other)
+      return super unless other.is_a?(Entity)
+      canonical_id == other.canonical_id
+    end
+
+    ##
+    # The "canonical", global ID of this entity relative to the canonical ID of the crate.
+    #
+    # In the case that the crate does not have an absolute URI as its ID, it will appear something like this:
+    #   arcp://uuid,b3d6fa2b-4e49-43ba-bd89-464e948b7f0c/foo - where `foo` is the local ID of this entity.
+    #
+    # If the crate does have an absolute URI, it will appear relative to that e.g.:
+    #   http://mycoolcrate.info/foo - where `foo` is the local ID of this entity.
+    #
+    # If the entity itself has an absolute URI, that will be used e.g.:
+    #   http://website.com/foo.txt - where `http://website.com/foo.txt ` is the local ID of this entity.
+    #
+    # This is used, for example, to compare equality of two entities.
+    #
+    # @return [Addressable::URI]
+    def canonical_id
+      crate.resolve_id(id)
+    end
+
+    ##
+    # Is this entity local to the crate or an external reference?
+    #
+    # @return [boolean]
+    def external?
+      crate.canonical_id.host != canonical_id.host
+    end
+
+    def raw_properties
+      @properties
+    end
+
+    def [](key)
+      @properties[key]
+    end
+
+    def []=(key, value)
+      @properties[key] = value
+    end
+
+    def to_json
+      @properties.to_json
+    end
+
+    ##
+    # A safe way of checking if the Entity has the given type, regardless of whether the Entity has a single, or Array of types.
+    # Does not check superclasses etc.
+    # @param type [String] The type to check, e.g. "File".
+    # @return [Boolean]
+    def has_type?(type)
+      @properties.has_type?(type)
+    end
+
+    private
+
+    def default_properties
+      {
+        '@id' => "##{SecureRandom.uuid}",
+        '@type' => 'Thing'
+      }
+    end
+  end
+end

data/lib/ro_crate/model/entry.rb

@@ -0,0 +1,57 @@
+module ROCrate
+  ##
+  # A class to represent a "physical" file or directory within an RO crate.
+  # It handles the actual reading/writing of bytes.
+  class Entry
+    attr_reader :source
+
+    ##
+    # Create a new Entry.
+    #
+    # @param source [#read] An IO-like source that can be read.
+    def initialize(source)
+      @source = source
+    end
+
+    ##
+    # Write the source to the destination via a buffer.
+    #
+    # @param dest [#write] An IO-like destination to write to.
+    def write(dest)
+      input = source
+      input = input.open('rb') if input.is_a?(Pathname)
+      while (buff = input.read(4096))
+        dest.write(buff)
+      end
+    end
+
+    ##
+    # Read from the source.
+    #
+    def read
+      source.read
+    end
+
+    ##
+    # Does this Entry point to a directory on the disk?
+    def directory?
+      ::File.directory?(source) rescue false
+    end
+
+    ##
+    # Does this Entry point to a remote resource?
+    def remote?
+      false
+    end
+
+    def path
+      if source.is_a?(Pathname)
+        source.to_s
+      elsif source.respond_to?(:path)
+        source.path
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/ro_crate/model/file.rb

@@ -0,0 +1,76 @@
+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 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 = {})
+      if crate_path.is_a?(Hash) && properties.empty?
+        properties = crate_path
+        crate_path = nil
+      end
+
+      if source.is_a?(String)
+        uri = URI(source) rescue nil
+        if uri.absolute?
+          source = uri
+        else
+          source = Pathname.new(source).expand_path
+        end
+      elsif source.is_a?(::File)
+        source = Pathname.new(source).expand_path
+      end
+
+      if crate_path.nil?
+        crate_path = source.basename.to_s if source.respond_to?(:basename)
+        crate_path = source.to_s if source.is_a?(URI) && source.absolute?
+      end
+
+      super(crate, crate_path, properties)
+
+      if source.is_a?(URI) && source.absolute?
+        @entry = RemoteEntry.new(source)
+      else
+        @entry = Entry.new(source)
+      end
+    end
+
+    ##
+    # The "physical" source file that will be read.
+    #
+    # @return [Entry] An Entry pointing to the source.
+    def source
+      @entry
+    end
+
+    ##
+    # A map of all the files/directories associated with this File. Should only be a single key and value.
+    # (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
+      remote? ? {} : { filepath => source }
+    end
+
+    def remote?
+      @entry.remote?
+    end
+
+    private
+
+    def default_properties
+      super.merge(
+        '@id' => "#{SecureRandom.uuid}",
+        '@type' => 'File'
+      )
+    end
+  end
+end