class ROCrate::Entity

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.

Attributes

crate[R]
properties[R]

Public Class Methods

format_id(id) click to toggle source

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.

# File lib/ro_crate/model/entity.rb, line 36
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_local_id(id) click to toggle source

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 /

@param id [String] The candidate local ID to be formatted. @return [String] The formatted local ID.

# File lib/ro_crate/model/entity.rb, line 59
def self.format_local_id(id)
  Addressable::URI.escape(id.sub(/\A\.\//, '')) # Remove initial ./ if present
end
new(crate, id = nil, properties = {}) click to toggle source

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.

# File lib/ro_crate/model/entity.rb, line 112
def initialize(crate, id = nil, properties = {})
  @crate = crate
  @properties = ROCrate::JSONLDHash.new(crate, default_properties.merge(properties))
  self.id = id if id
end
properties(props) click to toggle source

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`.

# File lib/ro_crate/model/entity.rb, line 13
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

Public Instance Methods

==(other) click to toggle source
Calls superclass method
# File lib/ro_crate/model/entity.rb, line 167
def ==(other)
  return super unless other.is_a?(Entity)
  canonical_id == other.canonical_id
end
[](key) click to toggle source
# File lib/ro_crate/model/entity.rb, line 208
def [](key)
  @properties[key]
end
[]=(key, value) click to toggle source
# File lib/ro_crate/model/entity.rb, line 212
def []=(key, value)
  @properties[key] = value
end
auto_dereference(value) click to toggle source

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.
# File lib/ro_crate/model/entity.rb, line 69
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
auto_reference(value) click to toggle source

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.
# File lib/ro_crate/model/entity.rb, line 90
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
canonical_id() click to toggle source

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]

# File lib/ro_crate/model/entity.rb, line 192
def canonical_id
  crate.resolve_id(id)
end
dereference(id) click to toggle source

Lookup an Entity using the given ID (in this Entity's crate).

@param id [String] The ID to query. @return [Entity, nil]

# File lib/ro_crate/model/entity.rb, line 131
def dereference(id)
  crate.entities.detect { |e| e.canonical_id == crate.resolve_id(id) } if id
end
Also aliased as: get
eql?(other) click to toggle source
Calls superclass method
# File lib/ro_crate/model/entity.rb, line 172
def eql?(other)
  return super unless other.is_a?(Entity)
  canonical_id == other.canonical_id
end
external?() click to toggle source

Is this entity local to the crate or an external reference?

@return [boolean]

# File lib/ro_crate/model/entity.rb, line 200
def external?
  crate.canonical_id.host != canonical_id.host
end
get(id)
Alias for: dereference
has_type?(type) click to toggle source

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]

# File lib/ro_crate/model/entity.rb, line 225
def has_type?(type)
  @properties.has_type?(type)
end
hash() click to toggle source
# File lib/ro_crate/model/entity.rb, line 163
def hash
  canonical_id.hash
end
id() click to toggle source
# File lib/ro_crate/model/entity.rb, line 137
def id
  @properties['@id']
end
id=(id) click to toggle source
# File lib/ro_crate/model/entity.rb, line 141
def id=(id)
  @properties['@id'] = self.class.format_id(id)
end
inspect() click to toggle source
# File lib/ro_crate/model/entity.rb, line 157
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
properties=(props) click to toggle source
# File lib/ro_crate/model/entity.rb, line 153
def properties=(props)
  @properties.replace(props)
end
raw_properties() click to toggle source
# File lib/ro_crate/model/entity.rb, line 204
def raw_properties
  @properties
end
reference() click to toggle source

Return a JSON-LD style reference: { '@id' : '#an-entity' } for this Entity.

@return [Hash]

# File lib/ro_crate/model/entity.rb, line 122
def reference
  ROCrate::JSONLDHash.new(crate, '@id' => id)
end
to_json() click to toggle source
# File lib/ro_crate/model/entity.rb, line 216
def to_json
  @properties.to_json
end
type() click to toggle source
# File lib/ro_crate/model/entity.rb, line 145
def type
  @properties['@type']
end
type=(type) click to toggle source
# File lib/ro_crate/model/entity.rb, line 149
def type=(type)
  @properties['@type'] = type
end

Private Instance Methods

default_properties() click to toggle source
# File lib/ro_crate/model/entity.rb, line 231
def default_properties
  {
    '@id' => "##{SecureRandom.uuid}",
    '@type' => 'Thing'
  }
end