Class: ROCrate::Entity

Inherits:
Object
  • Object
show all
Defined in:
lib/ro_crate/model/entity.rb

Overview

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.

Direct Known Subclasses

ContextualEntity, DataEntity

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(crate, id = nil, properties = {}) ⇒ Entity

Create a new Entity.

Parameters:

  • crate (Crate) —

    The crate that owns this Entity.

  • id (String, nil) (defaults to: nil) —

    An ID to identify this Entity, or blank to auto-generate an appropriate one, (or determine via the properties param)

  • properties (Hash{String => Object}) (defaults to: {}) —

    A hash of JSON-LD properties to associate with this entity.



112
113
114
115
116
 
# 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

Instance Attribute Details

#crate ⇒ Object (readonly)

Returns the value of attribute crate.



6
7
8
 
# File 'lib/ro_crate/model/entity.rb', line 6

def crate
  @crate
end

#properties ⇒ Object

Returns the value of attribute properties.



7
8
9
 
# File 'lib/ro_crate/model/entity.rb', line 7

def properties
  @properties
end

Class Method Details

.format_id(id) ⇒ String

Format the given ID with rules appropriate for this type if it is local/relative, leave as-is if absolute.

Parameters:

  • id (String) —

    The candidate ID to be formatted.

Returns:

  • (String) —

    The formatted ID.



36
37
38
39
40
41
42
43
44
45
46
47
48
 
# 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) ⇒ String

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 /

Parameters:

  • id (String) —

    The candidate local ID to be formatted.

Returns:

  • (String) —

    The formatted local ID.



59
60
61
 
# 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

.properties(props) ⇒ Object

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



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
# 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

Instance Method Details

#==(other) ⇒ Object 



167
168
169
170
 
# 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) ⇒ Object 



208
209
210
 
# File 'lib/ro_crate/model/entity.rb', line 208

def [](key)
  @properties[key]
end

#[]=(key, value) ⇒ Object 



212
213
214
 
# File 'lib/ro_crate/model/entity.rb', line 212

def []=(key, value)
  @properties[key] = value
end

#auto_dereference(value) ⇒ Entity, ...

Automatically replace references to entities (e.g. ‘{ ’@id’ : ‘#something’ }‘) with the Entity object itself.

Parameters:

  • value (Hash, Array<Hash>, Object) —

    A value that may be reference or array of references.

Returns:

  • (Entity, Array<Entity>, Object) —

    Return an Entity, Array of Entities, or just the object itself if it wasn’t a reference after all.



69
70
71
72
73
74
75
76
77
78
79
80
 
# 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) ⇒ Hash, ...

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.

Parameters:

  • value (Entity, Array<Entity>, Object) —

    A value that may be reference or array of references.

Returns:

  • (Hash, Array<Hash>, Object) —

    Return a reference, Array of references, or just the object itself if it wasn’t an Entity after all.



90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# 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 ⇒ Addressable::URI

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.

Returns:

  • (Addressable::URI) 


192
193
194
 
# File 'lib/ro_crate/model/entity.rb', line 192

def canonical_id
  crate.resolve_id(id)
end

#dereference(id) ⇒ Entity? Also known as: get

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

Parameters:

  • id (String) —

    The ID to query.

Returns:



131
132
133
 
# 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

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean) 


172
173
174
175
 
# 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? ⇒ boolean

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

Returns:

  • (boolean) 


200
201
202
 
# File 'lib/ro_crate/model/entity.rb', line 200

def external?
  crate.canonical_id.host != canonical_id.host
end

#has_type?(type) ⇒ Boolean

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.

Parameters:

  • type (String) —

    The type to check, e.g. “File”.

Returns:

  • (Boolean) 


225
226
227
 
# File 'lib/ro_crate/model/entity.rb', line 225

def has_type?(type)
  @properties.has_type?(type)
end

#hash ⇒ Object 



163
164
165
 
# File 'lib/ro_crate/model/entity.rb', line 163

def hash
  canonical_id.hash
end

#id ⇒ Object 



137
138
139
 
# File 'lib/ro_crate/model/entity.rb', line 137

def id
  @properties['@id']
end

#id=(id) ⇒ Object 



141
142
143
 
# File 'lib/ro_crate/model/entity.rb', line 141

def id=(id)
  @properties['@id'] = self.class.format_id(id)
end

#inspect ⇒ Object 



157
158
159
160
161
 
# 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

#raw_properties ⇒ Object 



204
205
206
 
# File 'lib/ro_crate/model/entity.rb', line 204

def raw_properties
  @properties
end

#reference ⇒ Hash

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

Returns:

  • (Hash) 


122
123
124
 
# File 'lib/ro_crate/model/entity.rb', line 122

def reference
  ROCrate::JSONLDHash.new(crate, '@id' => id)
end

#to_json ⇒ Object 



216
217
218
 
# File 'lib/ro_crate/model/entity.rb', line 216

def to_json
  @properties.to_json
end

#type ⇒ Object 



145
146
147
 
# File 'lib/ro_crate/model/entity.rb', line 145

def type
  @properties['@type']
end

#type=(type) ⇒ Object 



149
150
151
 
# File 'lib/ro_crate/model/entity.rb', line 149

def type=(type)
  @properties['@type'] = type
end