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
Public Class Methods
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 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
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
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
# File lib/ro_crate/model/entity.rb, line 167 def ==(other) return super unless other.is_a?(Entity) canonical_id == other.canonical_id end
# File lib/ro_crate/model/entity.rb, line 208 def [](key) @properties[key] end
# File lib/ro_crate/model/entity.rb, line 212 def []=(key, value) @properties[key] = value 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.
# 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
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
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
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
# 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
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
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
# File lib/ro_crate/model/entity.rb, line 163 def hash canonical_id.hash end
# File lib/ro_crate/model/entity.rb, line 137 def id @properties['@id'] end
# File lib/ro_crate/model/entity.rb, line 141 def id=(id) @properties['@id'] = self.class.format_id(id) end
# 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
# File lib/ro_crate/model/entity.rb, line 153 def properties=(props) @properties.replace(props) end
# File lib/ro_crate/model/entity.rb, line 204 def raw_properties @properties end
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
# File lib/ro_crate/model/entity.rb, line 216 def to_json @properties.to_json end
# File lib/ro_crate/model/entity.rb, line 145 def type @properties['@type'] end
# File lib/ro_crate/model/entity.rb, line 149 def type=(type) @properties['@type'] = type end
Private Instance Methods
# File lib/ro_crate/model/entity.rb, line 231 def default_properties { '@id' => "##{SecureRandom.uuid}", '@type' => 'Thing' } end