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.



90
91
92
93
94
 
# File 'lib/ro_crate/model/entity.rb', line 90

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) ⇒ Object

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 /



37
38
39
 
# File 'lib/ro_crate/model/entity.rb', line 37

def self.format_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 



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

def ==(other)
  return super unless other.is_a?(Entity)
  canonical_id == other.canonical_id
end

#[](key) ⇒ Object 



186
187
188
 
# File 'lib/ro_crate/model/entity.rb', line 186

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

#[]=(key, value) ⇒ Object 



190
191
192
 
# File 'lib/ro_crate/model/entity.rb', line 190

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.



47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/ro_crate/model/entity.rb', line 47

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.



68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/ro_crate/model/entity.rb', line 68

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) 


170
171
172
 
# File 'lib/ro_crate/model/entity.rb', line 170

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:



109
110
111
 
# File 'lib/ro_crate/model/entity.rb', line 109

def dereference(id)
  crate.entities.detect { |e| e.canonical_id == crate.resolve_id(id) } if id
end

#eql?(other) ⇒ Boolean

Returns:

  • (Boolean) 


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

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) 


178
179
180
 
# File 'lib/ro_crate/model/entity.rb', line 178

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) 


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

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

#hash ⇒ Object 



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

def hash
  canonical_id.hash
end

#id ⇒ Object 



115
116
117
 
# File 'lib/ro_crate/model/entity.rb', line 115

def id
  @properties['@id']
end

#id=(id) ⇒ Object 



119
120
121
 
# File 'lib/ro_crate/model/entity.rb', line 119

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

#inspect ⇒ Object 



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

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 



182
183
184
 
# File 'lib/ro_crate/model/entity.rb', line 182

def raw_properties
  @properties
end

#reference ⇒ Hash

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

Returns:

  • (Hash) 


100
101
102
 
# File 'lib/ro_crate/model/entity.rb', line 100

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

#to_json ⇒ Object 



194
195
196
 
# File 'lib/ro_crate/model/entity.rb', line 194

def to_json
  @properties.to_json
end

#type ⇒ Object 



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

def type
  @properties['@type']
end

#type=(type) ⇒ Object 



127
128
129
 
# File 'lib/ro_crate/model/entity.rb', line 127

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