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.



22
23
24
25
26
 
# File 'lib/ro_crate/model/crate.rb', line 22

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)
  i = super(id)
  i.end_with?('/') ? i : "#{i}/"
end

.format_local_id(id) ⇒ Object 



15
16
17
18
 
# File 'lib/ro_crate/model/crate.rb', line 15

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

Instance Method Details

#add_all(source_directory, create_entities = true, include_hidden: false) ⇒ Array<DataEntity>

Recursively add the contents of the given source directory at the root of the crate. Useful for quickly RO-Crate-ifying a directory. Creates data entities for each file/directory discovered (excluding the top level directory itself) if ‘create_entities` is true.

Parameters:

  • source_directory (String, Pathname, ::File, ) —

    The source directory that will be included in the crate.

  • create_entities (Boolean) (defaults to: true) —

    Whether to create data entities for the added content, or just include them anonymously.

  • include_hidden (Boolean) (defaults to: false) —

    Whether to include hidden files, i.e. those prefixed by a ‘.` (period).

Returns:

  • (Array<DataEntity>) —

    Any entities that were created from the directory contents. Will be empty if ‘create_entities` was false.



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/ro_crate/model/crate.rb', line 79

def add_all(source_directory, create_entities = true, include_hidden: false)
  added = []

  if create_entities
    list_all_files(source_directory, include_hidden: include_hidden).each do |rel_path|
      source_path = Pathname.new(::File.join(source_directory, rel_path)).expand_path
      if source_path.directory?
        added << add_directory(source_path, rel_path)
      else
        added << add_file(source_path, rel_path)
      end
    end
  else
    populate_entries(Pathname.new(::File.expand_path(source_directory)), include_hidden: include_hidden)
  end

  added
end

#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:



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

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.



136
137
138
139
140
141
 
# File 'lib/ro_crate/model/crate.rb', line 136

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.



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

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:



65
66
67
 
# File 'lib/ro_crate/model/crate.rb', line 65

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:



51
52
53
 
# File 'lib/ro_crate/model/crate.rb', line 51

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:



38
39
40
 
# File 'lib/ro_crate/model/crate.rb', line 38

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:



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

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:



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

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) 


201
202
203
 
# File 'lib/ro_crate/model/crate.rb', line 201

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)



218
219
220
221
 
# File 'lib/ro_crate/model/crate.rb', line 218

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:



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

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:



175
176
177
 
# File 'lib/ro_crate/model/crate.rb', line 175

def entities
  default_entities | data_entities | contextual_entities
end

#entries ⇒ Hash{String => Entry}

# The RO-Crate’s “payload” of the crate - 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}) —

    ]



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/ro_crate/model/crate.rb', line 229

def entries
  # Gather a map of entries, starting from the crate itself, then any directory data entities, then finally any
  # file data entities. This ensures in the case of a conflict, the more "specific" data entities take priority.
  entries = own_entries
  non_self_entities = default_entities.reject { |e| e == self }
  sorted_entities = (non_self_entities | data_entities).sort_by { |e| e.is_a?(ROCrate::Directory) ? 0 : 1 }

  sorted_entities.each do |entity|
    entity.entries.each do |path, entry|
      entries[path] = entry
    end
  end

  entries
end

#get_binding ⇒ Object 



245
246
247
 
# File 'lib/ro_crate/model/crate.rb', line 245

def get_binding
  binding
end

#metadata ⇒ Metadata

The RO-Crate metadata file

Returns:



159
160
161
 
# File 'lib/ro_crate/model/crate.rb', line 159

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

#own_entries ⇒ Object 



223
 
# File 'lib/ro_crate/model/crate.rb', line 223

alias_method :own_entries, :entries

#preview ⇒ Preview

The RO-Crate preview file

Returns:



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

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

#properties ⇒ Object 



187
188
189
 
# File 'lib/ro_crate/model/crate.rb', line 187

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) 


211
212
213
 
# File 'lib/ro_crate/model/crate.rb', line 211

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

#uuid ⇒ Object 



191
192
193
 
# File 'lib/ro_crate/model/crate.rb', line 191

def uuid
  @uuid ||= SecureRandom.uuid
end