Class: ROCrate::Crate

Inherits:
Directory show all
Defined in:
lib/ro_crate/model/crate.rb

Overview

A Ruby abstraction of an RO Crate.

Constant Summary collapse

IDENTIFIER = 
'./'.freeze

Instance Attribute Summary collapse

Attributes inherited from Entity

#crate

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from DataEntity

#filepath, specialize

Methods inherited from Entity

#==, #[], #[]=, #auto_dereference, #auto_reference, #dereference, #eql?, #external?, #has_type?, #hash, #id, #id=, #inspect, properties, #raw_properties, #reference, #to_json, #type, #type=

Constructor Details

#initialize(id = IDENTIFIER, properties = {}) ⇒ Crate

Initialize an empty RO Crate.



17
18
19
20
21
 
# File 'lib/ro_crate/model/crate.rb', line 17

def initialize(id = IDENTIFIER, properties = {})
  @data_entities = []
  @contextual_entities = []
  super(self, nil, id, properties)
end

Instance Attribute Details

#contextual_entities ⇒ Object (readonly)

Returns the value of attribute contextual_entities.



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

def contextual_entities
  @contextual_entities
end

#data_entities ⇒ Object (readonly)

Returns the value of attribute data_entities.



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

def data_entities
  @data_entities
end

Class Method Details

.format_id(id) ⇒ Object 



10
11
12
13
 
# File 'lib/ro_crate/model/crate.rb', line 10

def self.format_id(id)
  return id if id == IDENTIFIER
  super
end

Instance Method Details

#add_contact_point(id, properties = {}) ⇒ ContactPoint

Create a new ROCrate::ContactPoint and add it to the crate

Parameters:

  • id (String, nil) —

    An ID to identify this contact point, 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 contact point.

Returns:



82
83
84
 
# File 'lib/ro_crate/model/crate.rb', line 82

def add_contact_point(id, properties = {})
  add_contextual_entity(ROCrate::ContactPoint.new(self, id, properties))
end

#add_contextual_entity(entity) ⇒ Entity

Add a contextual entity to the crate

Parameters:

  • entity (Entity) —

    the entity to add to the crate.

Returns:

  • (Entity) —

    the entity itself, or a clone of the entity “owned” by this crate.



102
103
104
105
106
107
 
# File 'lib/ro_crate/model/crate.rb', line 102

def add_contextual_entity(entity)
  entity = claim(entity)
  contextual_entities.delete(entity) # Remove (then re-add) the entity if it exists
  contextual_entities.push(entity)
  entity
end

#add_data_entity(entity) ⇒ Entity

Add a data entity to the crate

Parameters:

  • entity (Entity) —

    the entity to add to the crate.

Returns:

  • (Entity) —

    the entity itself, or a clone of the entity “owned” by this crate.



114
115
116
117
118
119
 
# File 'lib/ro_crate/model/crate.rb', line 114

def add_data_entity(entity)
  entity = claim(entity)
  data_entities.delete(entity) # Remove (then re-add) the entity if it exists
  data_entities.push(entity)
  entity
end

#add_directory(source_directory, crate_path = nil, entity_class: ROCrate::Directory, **properties) ⇒ Entity

Create a new directory and add it to the crate.

Parameters:

  • source_directory (String, Pathname, ::File, #read, nil) —

    The source directory that will be included in the crate.

  • crate_path (String) (defaults to: nil) —

    The relative path within the RO crate where this directory will be written.

  • entity_class (Class) (defaults to: ROCrate::Directory) —

    The class to use to instantiate the Entity, useful if you have created a subclass of ROCrate::Directory that you want to use. (defaults to ROCrate::Directory).

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

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

Returns:



60
61
62
 
# File 'lib/ro_crate/model/crate.rb', line 60

def add_directory(source_directory, crate_path = nil, entity_class: ROCrate::Directory, **properties)
  entity_class.new(self, source_directory, crate_path, properties).tap { |e| add_data_entity(e) }
end

#add_external_file(source, entity_class: ROCrate::File, **properties) ⇒ Entity

Create a new file that references a remote URI and add it to the crate.

Parameters:

  • source (String, URI) —

    The URI to add.

  • entity_class (Class) (defaults to: ROCrate::File) —

    The class to use to instantiate the Entity, useful if you have created a subclass of ROCrate::File that you want to use. (defaults to ROCrate::File).

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

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

Returns:



46
47
48
 
# File 'lib/ro_crate/model/crate.rb', line 46

def add_external_file(source, entity_class: ROCrate::File, **properties)
  entity_class.new(self, source, nil, properties).tap { |e| add_data_entity(e) }
end

#add_file(source, crate_path = nil, entity_class: ROCrate::File, **properties) ⇒ Entity

Create a new file and add it to the crate.

Parameters:

  • source (String, Pathname, ::File, #read, nil) —

    The source on the disk where this file will be read.

  • crate_path (String) (defaults to: nil) —

    The relative path within the RO crate where this file will be written.

  • entity_class (Class) (defaults to: ROCrate::File) —

    The class to use to instantiate the Entity, useful if you have created a subclass of ROCrate::File that you want to use. (defaults to ROCrate::File).

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

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

Returns:



33
34
35
 
# File 'lib/ro_crate/model/crate.rb', line 33

def add_file(source, crate_path = nil, entity_class: ROCrate::File, **properties)
  entity_class.new(self, source, crate_path, properties).tap { |e| add_data_entity(e) }
end

#add_organization(id, properties = {}) ⇒ Organization

Create a new ROCrate::Organization and add it to the crate

Parameters:

  • id (String, nil) —

    An ID to identify this organization, 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 organization.

Returns:



93
94
95
 
# File 'lib/ro_crate/model/crate.rb', line 93

def add_organization(id, properties = {})
  add_contextual_entity(ROCrate::Organization.new(self, id, properties))
end

#add_person(id, properties = {}) ⇒ Person

Create a new ROCrate::Person and add it to the crate

Parameters:

  • id (String, nil) —

    An ID to identify this person, 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 person.

Returns:



71
72
73
 
# File 'lib/ro_crate/model/crate.rb', line 71

def add_person(id, properties = {})
  add_contextual_entity(ROCrate::Person.new(self, id, properties))
end

#canonical_id ⇒ Addressable::URI

The “canonical”, global ID of the crate. If the crate was not given an absolute URI as its ID, it will use an “Archive and Package” (ARCP) URI with the UUID of the crate, for example:

arcp://uuid,b3d6fa2b-4e49-43ba-bd89-464e948b7f0c/

Returns:

  • (Addressable::URI) 


167
168
169
 
# File 'lib/ro_crate/model/crate.rb', line 167

def canonical_id
  Addressable::URI.parse("arcp://uuid,#{uuid}").join(id)
end

#claim(entity) ⇒ Object

Copy the entity, but as if it was in this crate. (Or just return the entity if it was already included)



184
185
186
187
 
# File 'lib/ro_crate/model/crate.rb', line 184

def claim(entity)
  return entity if entity.crate == self
  entity.class.new(crate, entity.id, entity.raw_properties)
end

#default_entities ⇒ Array<Entity>

Entities for the metadata file and crate itself, which should be present in all RO crates.

Returns:



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

def default_entities
  [metadata, preview, self]
end

#entities ⇒ Array<Entity>

All the entities within the crate. Includes contextual entities, data entities, the crate itself and its metadata file.

Returns:



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

def entities
  default_entities | data_entities | contextual_entities
end

#entries ⇒ Hash{String => Entry}

A map of all the files/directories contained in the RO crate, where the key is the destination path within the crate and the value is an Entry where the source data can be read.

Returns:

  • (Hash{String => Entry}) —

    ]



194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/ro_crate/model/crate.rb', line 194

def entries
  entries = {}

  (default_entities | data_entities).each do |entity|
    next if entity == self
    entity.entries.each do |path, io|
      entries[path] = io
    end
  end

  entries
end

#get_binding ⇒ Object 



207
208
209
 
# File 'lib/ro_crate/model/crate.rb', line 207

def get_binding
  binding
end

#metadata ⇒ Metadata

The RO crate metadata file

Returns:



125
126
127
 
# File 'lib/ro_crate/model/crate.rb', line 125

def metadata
  @metadata ||= ROCrate::Metadata.new(self)
end

#preview ⇒ Preview

The RO crate preview file

Returns:



133
134
135
 
# File 'lib/ro_crate/model/crate.rb', line 133

def preview
  @preview ||= ROCrate::Preview.new(self)
end

#properties ⇒ Object 



153
154
155
 
# File 'lib/ro_crate/model/crate.rb', line 153

def properties
  super.merge('hasPart' => data_entities.map(&:reference))
end

#resolve_id(id) ⇒ Addressable::URI

Return an absolute URI for the given string ID, relative to the crate’s canonical ID.

Parameters:

  • id (String) —

    The ID to “join” onto the crate’s base URI.

Returns:

  • (Addressable::URI) 


177
178
179
 
# File 'lib/ro_crate/model/crate.rb', line 177

def resolve_id(id)
  canonical_id.join(id)
end

#uuid ⇒ Object 



157
158
159
 
# File 'lib/ro_crate/model/crate.rb', line 157

def uuid
  @uuid ||= SecureRandom.uuid
end