From 2441b5fa2b864cef4d01c005a1ad8bcfb0f8191e Mon Sep 17 00:00:00 2001 From: Oliver Woolland Date: Fri, 20 Nov 2026 13:35:26 +0000 Subject: [PATCH 1/3] Remove shared pointer, have addEntity return a ref to the entity and disallow entity creation --- include/ro-crate.hpp | 101 +++++++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 51 deletions(-) diff --git a/include/ro-crate.hpp b/include/ro-crate.hpp index 538b8f4..2f9216f 100644 --- a/include/ro-crate.hpp +++ b/include/ro-crate.hpp @@ -3,7 +3,6 @@ #include #include -#include #include #include #include @@ -30,19 +29,14 @@ namespace rocrate { * Represents an entity in the RO-Crate. * An entity can have multiple types and properties, where each property can have multiple values. * Properties can be set as either literal values or references to other entities. + * + * Entities are created and added via ROCrate::addEntity, + * which constructs the Entity and returns a mutable reference to it. */ class Entity { - + public: Entity() = delete; - - /** - * Constructs an Entity with the specified types. - * - * @param types A vector of strings representing the types of the entity. - * @throw std::invalid_argument if the types vector is empty. - */ - explicit Entity(std::vector types); ~Entity() = default; /** @@ -58,7 +52,7 @@ namespace rocrate { Value value, ValueType type = ValueType::Literal ); - + /** * Sets a property to reference another entity. * @@ -72,6 +66,17 @@ namespace rocrate { private: friend class ROCrate; + /** + * Constructs an Entity with the specified types. + * + * Private since entities are always constructed and owned by an RO-Crate + * via ROCrate::addEntity. + * + * @param types A vector of strings representing the types of the entity. + * @throw std::invalid_argument if the types vector is empty. + */ + explicit Entity(std::vector types); + /** * Assigns an '@id' to the entity. * @@ -79,24 +84,22 @@ namespace rocrate { * @throw std::invalid_argument if the id is empty. */ void assignId(const std::string& id); - std::shared_ptr properties_; + Properties properties_; }; - inline Entity::Entity(std::vector types) - : properties_(std::make_shared()) { - + inline Entity::Entity(std::vector types) { // Validate types (reject empty) if ( types.empty() ) { throw std::invalid_argument("Entity must have at least one type."); } - + // Set the types of the entity std::vector typeValues; for (const auto& type : types) typeValues.push_back({type, ValueType::Literal}); - properties_->emplace("@type", typeValues); + properties_.emplace("@type", typeValues); } - + inline void Entity::set(Property property, Value value, ValueType valueType) { // Validate property and value if (property.empty()) @@ -108,8 +111,8 @@ namespace rocrate { "Use ROCrate::addEntity to assign an ID."); // Check property is not duplicate - ignore if so - auto it = properties_->find(property); - if (it != properties_->end()) { + auto it = properties_.find(property); + if (it != properties_.end()) { for (const auto& existingValue : it->second) { if (existingValue.value == value && existingValue.type == valueType) { // Duplicate found, ignore @@ -119,7 +122,7 @@ namespace rocrate { } // Add the value to the property in the properties map - (*properties_)[property].push_back({value, valueType}); + properties_[property].push_back({value, valueType}); } inline void Entity::set(Property property, const Entity& entity) { @@ -129,8 +132,8 @@ namespace rocrate { } // Check if the entity has an '@id' property set - const auto id = entity.properties_->find("@id"); - if (id == entity.properties_->end() || id->second.empty()) + const auto id = entity.properties_.find("@id"); + if (id == entity.properties_.end() || id->second.empty()) throw std::runtime_error("Entity does not have an '@id' property set."); // Add JSON reference to the entity's '@id' to the property in the properties map @@ -144,7 +147,7 @@ namespace rocrate { } // Assign the '@id' property to the entity's properties map - (*properties_)["@id"] = {{id, ValueType::Literal}}; + properties_["@id"] = {{id, ValueType::Literal}}; } // --------------------------------------------------------------------------- @@ -170,14 +173,15 @@ namespace rocrate { ROCrate(); /** - * Adds an entity to the RO-Crate's entity register with the specified id. + * Constructs an entity with the given types and adds it to the RO-Crate's entity register. * * @param id The identifier for the entity. - * @param entity The entity to add to the RO-Crate. - * @throw std::invalid_argument if the id is empty. + * @param types A vector of strings representing the types of the entity. + * @return A mutable reference to the newly created entity, now owned by the RO-Crate. + * @throw std::invalid_argument if the id is empty, or if the types vector is empty. * @throw std::runtime_error if an entity with the given id already exists in the RO-Crate. */ - void addEntity(const std::string& id, Entity& entity); + Entity& addEntity(const std::string& id, std::vector types); /** * Retrieves an entity from the RO-Crate's entity register by its id. @@ -241,24 +245,21 @@ namespace rocrate { // Initialise the RO-Crate with an empty entity register entities_ = {}; - // Create the root metadata entity (ro-crate-metadata.json) - Entity rootEntity({"CreativeWork"}); + // Create the root metadata entity (ro-crate-metadata.json) and the root dataset entity + Entity& rootEntity = addEntity("ro-crate-metadata.json", {"CreativeWork"}); + Entity& datasetEntity = addEntity("./", {"Dataset"}); + rootEntity.set( "conformsTo", "https://w3id.org/ro/crate/1.3", ValueType::Reference ); - addEntity("ro-crate-metadata.json", rootEntity); - - // Create the root dataset entity - Entity datasetEntity({"Dataset"}); - addEntity("./", datasetEntity); // Add the root dataset entity to the root metadata entity rootEntity.set("about", datasetEntity); } - inline void ROCrate::addEntity(const std::string& id, Entity& entity) { + inline Entity& ROCrate::addEntity(const std::string& id, std::vector types) { // Validate the id (reject empty) if (id.empty()) { throw std::invalid_argument("Entity ID cannot be empty."); @@ -268,12 +269,14 @@ namespace rocrate { if (entities_.find(id) != entities_.end()) { throw std::runtime_error("Entity with id '" + id + "' already exists in the RO-Crate."); } - - // Add the assigned ID to the Entity itself + + // Construct the entity and assign it the given ID + Entity entity(std::move(types)); entity.assignId(id); - // Add an entity to the RO-Crate's entity register - entities_.emplace(id, entity); + // Add the entity to the RO-Crate's entity register and return a reference to it + entities_.emplace(id, std::move(entity)); + return entities_.at(id); } inline Entity& ROCrate::getEntity(const std::string& id) { @@ -373,17 +376,13 @@ namespace rocrate { entityTypes.push_back(type.get()); } - // Try getting the entity from the register, if it exists, otherwise create a new one - Entity entity({"Thing"}); // Default type, will be overridden if entity exists - try { - // Existing entity - entity = getEntity(entityId); - updateProperties(entity, entityJson); - } catch (const std::runtime_error&) { - // Entity does not exist, create a new one - entity = Entity(entityTypes); + // Get the entity from the register if it already exists, otherwise create a new one + auto it = entities_.find(entityId); + if (it != entities_.end()) { + updateProperties(it->second, entityJson); + } else { + Entity& entity = addEntity(entityId, entityTypes); updateProperties(entity, entityJson); - addEntity(entityId, entity); } } } @@ -446,7 +445,7 @@ namespace rocrate { nlohmann::json serialized; serialized["@id"] = id; - for (const auto& [property, values] : *entity.properties_) { + for (const auto& [property, values] : entity.properties_) { if (property == "@id") { continue; } From 04081bca59166372114695c55aa9693d5d93945f Mon Sep 17 00:00:00 2001 From: Oliver Woolland Date: Fri, 20 Nov 2026 13:35:52 +0000 Subject: [PATCH 2/3] Bump tests for new api - addEntity creates entities --- tests/example.cpp | 20 +++++-------- tests/integration.cpp | 45 +++++++++++----------------- tests/unit.cpp | 69 ++++++++++++++++++------------------------- 3 files changed, 53 insertions(+), 81 deletions(-) diff --git a/tests/example.cpp b/tests/example.cpp index f59c820..98b9d7e 100644 --- a/tests/example.cpp +++ b/tests/example.cpp @@ -17,40 +17,36 @@ void create_example_ro_crate() { // this is currently missing // Get the root metadata entity from the crate and set the description - Entity root = crate.getEntity("ro-crate-metadata.json"); + Entity& root = crate.getEntity("ro-crate-metadata.json"); root.set("description", "RO-Crate Metadata File Descriptor (this file)"); // Add name, description to the root data entity (./) - Entity rootData = crate.getEntity("./"); + Entity& rootData = crate.getEntity("./"); rootData.set("name", "Example RO-Crate"); rootData.set("description", "The RO-Crate Root Data Entity"); // -------------------------------------------------------------------------- // Create the person, which is a contextual entity, and add it to the crate - - Entity alice({"Person"}); + + Entity& alice = crate.addEntity("#alice", {"Person"}); alice.set("name", "Alice"); alice.set("description", "One of hopefully many Contextual Entities"); - crate.addEntity("#alice", alice); // -------------------------------------------------------------------------- // Create the place, another contextual entity, and add it to the crate - Entity catalinaPark({"Place"}); + Entity& catalinaPark = crate.addEntity("http://sws.geonames.org/8152662/", {"Place"}); catalinaPark.set("name", "Catalina Park"); - crate.addEntity("http://sws.geonames.org/8152662/", catalinaPark); // -------------------------------------------------------------------------- // Create two datasets, which are data entities, and add them to the crate. - Entity data1({"File"}); + Entity& data1 = crate.addEntity("data1.txt", {"File"}); data1.set("description", "One of hopefully many Data Entities"); data1.set("author", alice); data1.set("contentLocation", catalinaPark); - crate.addEntity("data1.txt", data1); rootData.set("hasPart", data1); // Ensure that the root data entity has a hasPart relationship to data1 - Entity data2({"File"}); - crate.addEntity("data2.txt", data2); - rootData.set("hasPart", data2); + Entity& data2 = crate.addEntity("data2.txt", {"File"}); + rootData.set("hasPart", data2); // -------------------------------------------------------------------------- // Write out diff --git a/tests/integration.cpp b/tests/integration.cpp index 9b7a599..58dc4cf 100644 --- a/tests/integration.cpp +++ b/tests/integration.cpp @@ -14,7 +14,7 @@ TEST_CASE("Minimal RO-Crate", "[integration]") ROCrate crate; // Add metadata to root data entity - Entity rootData = crate.getEntity("./"); + Entity& rootData = crate.getEntity("./"); rootData.set("cite-as", "https://doi.org/10.4225/59/59672c09f4a4b"); rootData.set("datePublished", "2017"); rootData.set("name", "Data files associated with the manuscript:Effects of facilitated family case conferencing for ..."); @@ -22,19 +22,16 @@ TEST_CASE("Minimal RO-Crate", "[integration]") rootData.set("creditText", "Agar, M. et al., 2017. Data supporting \"Effects of facilitated family case conferencing for advanced dementia: A cluster randomised clinical trial\". https://doi.org/10.4225/59/59672c09f4a4b"); // Create the license entity - Entity license({"CreativeWork"}); + Entity& license = crate.addEntity("https://creativecommons.org/licenses/by-nc-sa/3.0/au/", {"CreativeWork"}); license.set("description", "This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Australia License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/au/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA."); license.set("identifier", "https://creativecommons.org/licenses/by-nc-sa/3.0/au/"); license.set("name", "Attribution-NonCommercial-ShareAlike 3.0 Australia (CC BY-NC-SA 3.0 AU)"); - crate.addEntity("https://creativecommons.org/licenses/by-nc-sa/3.0/au/", license); - // Create the DOI entry - Entity doi({"PropertyValue"}); + Entity& doi = crate.addEntity("https://doi.org/10.4225/59/59672c09f4a4b", {"PropertyValue"}); doi.set("propertyID", "https://registry.identifiers.org/registry/doi"); doi.set("value", "doi:10.4225/59/59672c09f4a4b"); doi.set("url", "https://doi.org/10.4225/59/59672c09f4a4b"); - crate.addEntity("https://doi.org/10.4225/59/59672c09f4a4b", doi); rootData.set("identifier", doi); // Add license to root data entity @@ -59,31 +56,27 @@ TEST_CASE("Example with file and directory", "[integration]") ROCrate crate; // Add metadata to root data entity - Entity rootData = crate.getEntity("./"); + Entity& rootData = crate.getEntity("./"); rootData.set("name", "Example Dataset"); rootData.set("datePublished", "2016-02-01"); rootData.set("license", "CC-BY"); // Create the author entity - Entity author({"Person"}); + Entity& author = crate.addEntity("https://orcid.org/0000-0003-4953-0830", {"Person"}); author.set("name", "Michael Lake"); - crate.addEntity("https://orcid.org/0000-0003-4953-0830", author); rootData.set("author", author); // Create the file entity - Entity file({"File"}); + Entity& file = crate.addEntity("cp7glop.ai", {"File"}); file.set("name", "Diagram showing trend to increase"); file.set("contentSize", "383766"); file.set("description", "Illustrator file for Glop Pot"); file.set("encodingFormat", "application/pdf"); - crate.addEntity("cp7glop.ai", file); // Create the directory entity - Entity directory({"Dataset"}); + Entity& directory = crate.addEntity("lots_of_little_files/", {"Dataset"}); directory.set("name", "Too many files"); directory.set("description", "This directory contains many small files -- the name of the file is a date in YYYY-MM-DD.csv, each file contains daily temperature readings, sampled hourly for the Glop Pot cave."); - - crate.addEntity("lots_of_little_files/", directory); // Add file and directory to root data entity rootData.set("hasPart", file); @@ -99,7 +92,7 @@ TEST_CASE("Example with file and directory", "[integration]") "/tests/fixtures/example-with-file-directory.json", outputPath ); - + } // REF: https://www.researchobject.org/ro-crate/specification/1.3/data-entities.html#web-based-data-entities @@ -109,22 +102,20 @@ TEST_CASE("Example with web resources", "[integration]") ROCrate crate; // Survey responses file - Entity surveyResponses({"File"}); + Entity& surveyResponses = crate.addEntity("survey-responses-2019.csv", {"File"}); surveyResponses.set("name", "Survey responses"); surveyResponses.set("contentSize", "26452"); surveyResponses.set("encodingFormat", "text/csv"); - crate.addEntity("survey-responses-2019.csv", surveyResponses); // RO-Crate specification file - Entity roCrateSpec({"File"}); + Entity& roCrateSpec = crate.addEntity("https://zenodo.org/record/3541888/files/ro-crate-1.0.0.pdf", {"File"}); roCrateSpec.set("name", "RO-Crate specification"); roCrateSpec.set("contentSize", "310691"); roCrateSpec.set("description", "RO-Crate specification"); roCrateSpec.set("encodingFormat", "application/pdf"); - crate.addEntity("https://zenodo.org/record/3541888/files/ro-crate-1.0.0.pdf", roCrateSpec); // Add to root data entity - Entity rootData = crate.getEntity("./"); + Entity& rootData = crate.getEntity("./"); rootData.set("hasPart", surveyResponses); rootData.set("hasPart", roCrateSpec); @@ -138,7 +129,7 @@ TEST_CASE("Example with web resources", "[integration]") "/tests/fixtures/example-with-web-resources.json", outputPath ); - + } // REF: https://www.researchobject.org/ro-crate/specification/1.3/crate-focus.html (RO-Crates which focus on multiple Contextual Entities) @@ -148,34 +139,32 @@ TEST_CASE("RO-Crate which focuses on multiple Contextual Entities", "[integratio ROCrate crate; // Add metadata to the RO-Crate metadata file descriptor - Entity metadataFileDescriptor = crate.getEntity("ro-crate-metadata.json"); + Entity& metadataFileDescriptor = crate.getEntity("ro-crate-metadata.json"); metadataFileDescriptor.set("description", "RO-Crate Metadata File Descriptor (this file)"); // Add metadata to root data entity - Entity rootData = crate.getEntity("./"); + Entity& rootData = crate.getEntity("./"); rootData.set("name", "Language Data Ontology"); rootData.set("description", "This is an experimental language data ontology based on OLAC terms for use in the ATAP and LDaCA projects"); - + // Add additional context crate.addContext("txc", "https://purl.archive.org/language-data-commons/terms#"); // Create the first contextual entity - Entity annotation({"rdfs:Class"}); + Entity& annotation = crate.addEntity("txc:Annotation", {"rdfs:Class"}); annotation.set("name", "Annotation"); annotation.set("sameAs", "http://www.language-archives.org/REC/type-20020628.html#annotation"); annotation.set("rdfs:comment", "The resource includes information which annotates some other linguistic record."); annotation.set("rdfs:label", "Annotation"); annotation.set("rdfs:subClassOf", "schema:CreativeWork", ValueType::Reference); - crate.addEntity("txc:Annotation", annotation); // Create the second contextual entity - Entity collectionEvent({"rdfs:Class"}); + Entity& collectionEvent = crate.addEntity("txc:CollectionEvent", {"rdfs:Class"}); collectionEvent.set("name", "CollectionEvent"); collectionEvent.set("rdfs:comment", "A description of an event at which one or more PrimaryTexts were captured, e.g. as video or audio"); collectionEvent.set("rdfs:label", "CollectionEvent"); collectionEvent.set("rdfs:subClassOf", "schema:Event", ValueType::Reference); collectionEvent.set("rdfs:subClassOf", "schema:CreateAction", ValueType::Reference); - crate.addEntity("txc:CollectionEvent", collectionEvent); // Add mentions to root data entity rootData.set("mentions", annotation); diff --git a/tests/unit.cpp b/tests/unit.cpp index 7e8e1ff..b915e50 100644 --- a/tests/unit.cpp +++ b/tests/unit.cpp @@ -7,57 +7,64 @@ #include "test_helpers.hpp" using rocrate::Entity; +using rocrate::ROCrate; // ------------------------------------------------------------------------------ // Unit tests for Entity class // ------------------------------------------------------------------------------ TEST_CASE("Ensure entity creation occurs without throwing", "[unit]") { - Entity alice({"Person"}); + ROCrate crate; + crate.addEntity("#alice", {"Person"}); } TEST_CASE("Ensure entity creation throws if no types are provided", "[unit]") { - // Create an entity with an empty types vector, which should throw an invalid_argument exception - REQUIRE_THROWS_AS(Entity(std::vector{}), std::invalid_argument); + // Adding an entity with an empty types vector should throw an invalid_argument exception + ROCrate crate; + REQUIRE_THROWS_AS(crate.addEntity("#thing", std::vector{}), std::invalid_argument); } TEST_CASE("Ensure set by value succeeds with valid input", "[unit]") { - Entity alice({"Person"}); + ROCrate crate; + Entity& alice = crate.addEntity("#alice", {"Person"}); REQUIRE_NOTHROW(alice.set("name", "Alice")); REQUIRE_NOTHROW(alice.set("description", "One of hopefully many Contextual Entities")); } TEST_CASE("Rejects empty property names", "[unit]") { - Entity entity({"Thing"}); + ROCrate crate; + Entity& entity = crate.addEntity("#thing", {"Thing"}); REQUIRE_THROWS_AS(entity.set("", "value"), std::invalid_argument); } TEST_CASE("Rejects empty property values", "[unit]") { - Entity entity({"Thing"}); + ROCrate crate; + Entity& entity = crate.addEntity("#thing", {"Thing"}); REQUIRE_THROWS_AS(entity.set("name", ""), std::invalid_argument); } TEST_CASE("Rejects direct ID assignment", "[unit]") { - Entity entity({"Thing"}); + ROCrate crate; + Entity& entity = crate.addEntity("#thing", {"Thing"}); REQUIRE_THROWS_AS(entity.set("@id", "#thing"), std::invalid_argument); } TEST_CASE("Rejects empty entity IDs", "[unit]") { - rocrate::ROCrate crate; - Entity entity({"Thing"}); + ROCrate crate; REQUIRE_THROWS_AS( - crate.addEntity("", entity), + crate.addEntity("", {"Thing"}), std::invalid_argument ); } TEST_CASE("Rejects empty link property names", "[unit]") { - Entity source({"Thing"}); - Entity target({"Thing"}); + ROCrate crate; + Entity& source = crate.addEntity("#source", {"Thing"}); + Entity& target = crate.addEntity("#target", {"Thing"}); REQUIRE_THROWS_AS( target.set("", source), @@ -66,7 +73,8 @@ TEST_CASE("Rejects empty link property names", "[unit]") { } TEST_CASE("Ignore duplicate key-value pairs", "[unit]") { - Entity entity({"Thing"}); + ROCrate crate; + Entity& entity = crate.addEntity("#thing", {"Thing"}); REQUIRE_NOTHROW(entity.set("name", "value")); REQUIRE_NOTHROW(entity.set("name", "value")); // Should not throw, but also not add a duplicate @@ -74,20 +82,6 @@ TEST_CASE("Ignore duplicate key-value pairs", "[unit]") { SUCCEED("No exceptions thrown, can't currently assert on entity values as they are not exposed in the API"); } -TEST_CASE("Ensure failure if entity is linked before being assigned an ID", "[unit]") { - // Create the person, but do not add to a crate (so no @id yet) - Entity alice({"Person"}); - alice.set("name", "Alice"); - alice.set("description", "One of hopefully many Contextual Entities"); - - // Create a dataset and attempt to link to the person - Entity data1({"File"}); - data1.set("description", "One of hopefully many Data Entities"); - - // This fails at link time because the linked entity has no @id yet. - REQUIRE_THROWS_AS(data1.set("author", alice), std::runtime_error); -} - // ------------------------------------------------------------------------------- // Unit tests for RO-Crate class // ------------------------------------------------------------------------------- @@ -111,13 +105,11 @@ TEST_CASE("RO-Crate initilises with valid root metadata and dataset entities", " REQUIRE_NOTHROW(crate.getEntity("./")); } -TEST_CASE("Crate and builder observe shared entity updates", "[unit]") { +TEST_CASE("addEntity returns a mutable reference into the crate", "[unit]") { rocrate::ROCrate crate; - Entity alice({"Person"}); + Entity& alice = crate.addEntity("#alice", {"Person"}); - crate.addEntity("#alice", alice); - - alice.set("name", "Alice"); + alice.set("name", "Alice"); crate.getEntity("#alice").set("description", "Updated"); SUCCEED("No exceptions thrown, can't currently assert on entity values as they are not exposed in the API"); @@ -149,31 +141,26 @@ TEST_CASE("Add context throws if context is empty", "[unit]") { TEST_CASE("Add entity throws if ID is empty", "[unit]") { rocrate::ROCrate crate; - Entity alice({"Person"}); - REQUIRE_THROWS_AS(crate.addEntity("", alice), std::invalid_argument); + REQUIRE_THROWS_AS(crate.addEntity("", {"Person"}), std::invalid_argument); } TEST_CASE("Add entity rejects entities with duplicate IDs", "[unit]") { // Create a crate and add an entity rocrate::ROCrate crate; - Entity alice({"Person"}); + Entity& alice = crate.addEntity("#alice", {"Person"}); alice.set("name", "Alice"); - crate.addEntity("#alice", alice); // Attempt to add another entity with the same ID - Entity aliceDuplicate({"Person"}); - aliceDuplicate.set("name", "Alice Duplicate"); - REQUIRE_THROWS_AS(crate.addEntity("#alice", aliceDuplicate), std::runtime_error); + REQUIRE_THROWS_AS(crate.addEntity("#alice", {"Person"}), std::runtime_error); } TEST_CASE("Write out RO-Crate to JSON-LD without throwing", "[unit]") { rocrate::ROCrate crate; - Entity alice({"Person"}); + Entity& alice = crate.addEntity("#alice", {"Person"}); alice.set("name", "Alice"); - crate.addEntity("#alice", alice); REQUIRE_NOTHROW(crate.writeOut("ro-crate-metadata.json")); } From da922d4606621dfa16af10504564ae4c5edd6ad9 Mon Sep 17 00:00:00 2001 From: Oliver Woolland Date: Fri, 20 Nov 2026 13:36:13 +0000 Subject: [PATCH 3/3] Update docs for removed shared pointer / addEntity creates entities --- README.md | 85 +++++++++++++++++++++++-------------------------------- 1 file changed, 36 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 20b8070..24519f5 100644 --- a/README.md +++ b/README.md @@ -34,39 +34,35 @@ void create_example_ro_crate() { // this is currently missing // Get the root metadata entity from the crate and set the description - Entity root = crate.getEntity("ro-crate-metadata.json"); + Entity& root = crate.getEntity("ro-crate-metadata.json"); root.set("description", "RO-Crate Metadata File Descriptor (this file)"); // Add name, description to the root data entity (./) - Entity rootData = crate.getEntity("./"); + Entity& rootData = crate.getEntity("./"); rootData.set("name", "Example RO-Crate"); rootData.set("description", "The RO-Crate Root Data Entity"); // -------------------------------------------------------------------------- // Create the person, which is a contextual entity, and add it to the crate - Entity alice({"Person"}); + Entity& alice = crate.addEntity("#alice", {"Person"}); alice.set("name", "Alice"); alice.set("description", "One of hopefully many Contextual Entities"); - crate.addEntity("#alice", alice); // -------------------------------------------------------------------------- // Create the place, another contextual entity, and add it to the crate - Entity catalinaPark({"Place"}); + Entity& catalinaPark = crate.addEntity("http://sws.geonames.org/8152662/", {"Place"}); catalinaPark.set("name", "Catalina Park"); - crate.addEntity("http://sws.geonames.org/8152662/", catalinaPark); // -------------------------------------------------------------------------- // Create two datasets, which are data entities, and add them to the crate. - Entity data1({"File"}); + Entity& data1 = crate.addEntity("data1.txt", {"File"}); data1.set("description", "One of hopefully many Data Entities"); data1.set("author", alice); data1.set("contentLocation", catalinaPark); - crate.addEntity("data1.txt", data1); rootData.set("hasPart", data1); // Ensure that the root data entity has a hasPart relationship to data1 - Entity data2({"File"}); - crate.addEntity("data2.txt", data2); + Entity& data2 = crate.addEntity("data2.txt", {"File"}); rootData.set("hasPart", data2); // -------------------------------------------------------------------------- @@ -94,51 +90,46 @@ root data entity (./). ROCrate crate; ``` -### Create an Entity +### Create an Entity -To create an entity, instantiate the `Entity` class. You must provide a type, -or can provide a list of types. +Entities are always owned by an RO-Crate: creating one and adding it to the +crate happen in a single step, via the `addEntity` method on `ROCrate`. The +first argument is the entity ID, and the second is a type, or list of types. +`addEntity` constructs the entity and returns a mutable reference to it. ```cpp +ROCrate crate; + // Single type -Entity alice({"Person"}); +Entity& alice = crate.addEntity("#alice", {"Person"}); // Multiple types -Entity data1({"File", "Dataset"}); +Entity& data1 = crate.addEntity("data1.txt", {"File", "Dataset"}); ``` ### Add properties to an Entity -To add properties to an entity, use the `set` method. The first argument is the -property name, and the second argument is the property value. The property value -can either be a string, or another entity. +To add properties to an entity, use the `set` method on the reference returned +by `addEntity` (or `getEntity`). The first argument is the property name, and +the second argument is the property value. The property value can either be a +string, or another entity. If a string property value is provided, it create a straightforward key-value pair in the entity e.g. `name: "Alice"`. If an entity is provided, it will create a relationship between the two entities e.g. `author: { "@id": "#alice" }`. ```cpp +ROCrate crate; + // Add a string property -Entity alice({"Person"}); +Entity& alice = crate.addEntity("#alice", {"Person"}); alice.set("name", "Alice"); // Add a relationship property -Entity data1({"File"}); +Entity& data1 = crate.addEntity("data1.txt", {"File"}); data1.set("author", alice); ``` -### Add an Entity to an RO-Crate - -To add an entity to an RO-Crate, use the `addEntity` method. The first argument is -the entity ID, and the second argument is the entity object. - -```cpp -ROCrate crate; - -Entity alice({"Person"}); -crate.addEntity("#alice", alice); -``` - ### Add additional context to an RO-Crate To add additional context to an RO-Crate, use the `addContext` method. The first @@ -175,25 +166,19 @@ relationships between entities. ### Entity lifecycle -When an entity is created, it is not automatically added to the RO-Crate. The user -must explicitly add the entity to the RO-Crate using the `addEntity` method. - -When an entity is added to the RO-Crate, it is stored in a map of entities. - -For maximum flexiblity, an already added entity may still be updated on the -original entity object. The RO-Crate shares the same entity object, so any changes -made to the original entity will be reflected in the RO-Crate. +An entity cannot exist independently of an RO-Crate: it is always constructed +and owned by the crate's entity register, via `ROCrate::addEntity`. This method +returns a mutable reference to the entity, which can be used to set further +properties, or passed to `set` on other entities to create relationships. Worked example: ```cpp ROCrate crate; -Entity alice({"Person"}); +Entity& alice = crate.addEntity("#alice", {"Person"}); alice.set("name", "Alice"); -crate.addEntity("#alice", alice); - /* Crate state: { "#alice": { @@ -203,12 +188,9 @@ crate.addEntity("#alice", alice); } */ -// Add an additional property to the crate entity -Entity crateAlice = crate.getEntity("#alice"); -crateAlice.set("description", "One of hopefully many Contextual Entities"); - -// Add an additional property to the original entity object -alice.set("occupation", "Software Engineer"); +// Further updates go through the same reference, or a fresh one from getEntity +alice.set("description", "One of hopefully many Contextual Entities"); +crate.getEntity("#alice").set("occupation", "Software Engineer"); /* Crate state: { @@ -222,6 +204,11 @@ alice.set("occupation", "Software Engineer"); */ ``` +Note that `getEntity` and `addEntity` both return references (`Entity&`). +Copying the result into a plain `Entity` variable (rather than binding a +reference) makes an independent copy that will not reflect further changes, +and will not itself reflect changes made to the crate's entity afterwards. + ## Reference Reference documentation generated by [doxide](doxide.org) is available [here](http://esciencelab.org.uk/ro-crate-cpp/).