Skip to content

Commit

Permalink
Ensure author method works for data entities #18
Browse files Browse the repository at this point in the history
Updated README a bit, with note on property getting/setting.
  • Loading branch information
fbacall committed Apr 28, 2021
1 parent 5702d4d commit f065548
Show file tree
Hide file tree
Showing 6 changed files with 52 additions and 5 deletions.
37 changes: 37 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,43 @@ and run `bundle install`.

## Usage

This gem consists a hierarchy of classes to model RO-Crate "entities": the crate itself, data entities
(files and directory) and contextual entities (with a limited set of specializations, such as `ROCrate::Person`).
They are all descendents of the `ROCrate::Entity` class, with the `ROCrate::Crate` class representing the crate itself.

The `ROCrate::Reader` class handles reading of RO-Crates into the above model, from a Zip file or directory.

The `ROCrate::Writer` class can write out an `ROCrate::Crate` instance into a Zip file or directory.

**Note:** for performance reasons, the gem is currently not linked-data aware and will allow you to set properties that
are not semantically valid.

### Entities
Entities correspond to entries in the `@graph` of the RO-Crate's metadata JSON-LD file. Each entity class is
basically a wrapper around a set of JSON properties, with some convenience methods for getting/setting some
commonly used properties (`crate.name = "My first crate"`).

These convenience getter/setter methods will automatically handle turning objects into references and adding them to the
`@graph` if necessary.

##### Getting/Setting Arbitrary Properties of Entities
As well as using the pre-defined getter/setter methods, you can get/set arbitrary properties like so.

To set the "creativeWorkStatus" property of the RO-Crate itself to a string literal:
```ruby
crate['creativeWorkStatus'] = 'work-in-progress'
```

If you want to reference other entities in the crate, you can get a JSON-LD reference from an entity object by using the `reference` method:
```ruby
joe = crate.add_person('joe', { name: 'Joe Bloggs' }) # Add the entity to the @graph
crate.properties['copyrightHolder'] = joe.reference # Reference the entity from the "copyrightHolder" property
```
and to resolve those references back to the object, use the `dereference` method:
```ruby
joe = crate.properties['copyrightHolder'].dereference
```

### Documentation

[Click here for API documentation](https://www.researchobject.org/ro-crate-ruby/).
Expand Down
2 changes: 2 additions & 0 deletions lib/ro_crate/model/data_entity.rb
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ module ROCrate
# A class to represent a "Data Entity" within an RO-Crate.
# Data Entities are the actual physical files and directories within the Crate.
class DataEntity < Entity
properties(%w[name contentSize dateModified encodingFormat identifier sameAs author])

def self.format_local_id(id)
super.chomp('/')
end
Expand Down
2 changes: 0 additions & 2 deletions lib/ro_crate/model/directory.rb
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@ module ROCrate
##
# A data entity that represents a directory of potentially many files and subdirectories (or none).
class Directory < DataEntity
properties(%w[name contentSize dateModified encodingFormat identifier sameAs])

def self.format_local_id(id)
super + '/'
end
Expand Down
2 changes: 0 additions & 2 deletions lib/ro_crate/model/file.rb
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@ module ROCrate
##
# A data entity that represents a single file.
class File < DataEntity
properties(%w[name contentSize dateModified encodingFormat identifier sameAs])

##
# Create a new ROCrate::File. PLEASE NOTE, the new file will not be added to the crate. To do this, call
# Crate#add_data_entity, or just use Crate#add_file.
Expand Down
2 changes: 1 addition & 1 deletion lib/ro_crate/model/organization.rb
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ module ROCrate
##
# A contextual entity that represents an organization.
class Organization < ContextualEntity
properties(['name'])
properties(%w[name])

private

Expand Down
12 changes: 12 additions & 0 deletions test/crate_test.rb
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,18 @@ class CrateTest < Test::Unit::TestCase
assert_equal 2, crate1.contextual_entities.first.properties['cats']
end

test 'sharing entities' do
crate = ROCrate::Crate.new
info = crate.add_file(fixture_file('info.txt'),'the_info.txt')
bob = crate.add_person('bob', name: 'Bob Jones')
crate.author = bob
info.author = bob

assert_equal [bob], crate.contextual_entities
assert_equal bob, info.author
assert_equal bob, crate.author
end

test 'external files' do
crate = ROCrate::Crate.new
local = crate.add_file(fixture_file('info.txt'))
Expand Down

0 comments on commit f065548

Please sign in to comment.