From 60d9d3f9f54fab975c39d4c341f118df90628375 Mon Sep 17 00:00:00 2001 From: Benjamin Paassen Date: Mon, 12 Jan 2015 13:42:10 +0100 Subject: normalized NodeVector access in model classes and added some more documentation to model classes. --- src/core/model/Document.cpp | 32 +++---- src/core/model/Document.hpp | 190 +++++++++++++++++++++++++++++++++++---- src/core/model/Domain.cpp | 6 +- src/core/model/Domain.hpp | 203 ++++++++++++++++++++++++++++++++++++------ src/core/model/Typesystem.hpp | 18 +++- 5 files changed, 385 insertions(+), 64 deletions(-) (limited to 'src') diff --git a/src/core/model/Document.cpp b/src/core/model/Document.cpp index bed65c9..f591095 100644 --- a/src/core/model/Document.cpp +++ b/src/core/model/Document.cpp @@ -26,7 +26,8 @@ namespace model { /* Class DocumentEntity */ -int DocumentEntity::getFieldDescriptorIndex(const std::string &fieldName) +int DocumentEntity::getFieldDescriptorIndex(const std::string &fieldName, + bool enforce) const { const NodeVector &fds = descriptor->getFieldDescriptors(); unsigned int f = 0; @@ -56,21 +57,15 @@ int DocumentEntity::getFieldDescriptorIndex(const std::string &fieldName) f++; } } - return -1; -} - -NodeVector &DocumentEntity::getField( - const std::string &fieldName) -{ - int f = getFieldDescriptorIndex(fieldName); - if (f < 0) { + if (enforce) { throw OusiaException("No field for the given name exists!"); + } else { + return -1; } - return fields[f]; } -NodeVector &DocumentEntity::getField( - Handle fieldDescriptor) +int DocumentEntity::getFieldDescriptorIndex( + Handle fieldDescriptor, bool enforce) const { if (fieldDescriptor.isNull()) { throw OusiaException("The given FieldDescriptor handle is null!"); @@ -80,13 +75,18 @@ NodeVector &DocumentEntity::getField( for (auto &fd : fds) { if (fd->getName() == fieldDescriptor->getName() && fd->getFieldType() == fieldDescriptor->getFieldType()) { - return fields[f]; + return f; } f++; } - throw OusiaException( - "The given FieldDescriptor is not specified in the Descriptor of this " - "node."); + if (enforce) { + throw OusiaException( + "The given FieldDescriptor is not specified in the Descriptor of " + "this " + "node."); + } else { + return -1; + } } /* Class Document */ diff --git a/src/core/model/Document.hpp b/src/core/model/Document.hpp index a18e389..6e3b320 100644 --- a/src/core/model/Document.hpp +++ b/src/core/model/Document.hpp @@ -119,7 +119,7 @@ namespace ousia { // Forward declarations class RttiType; -template +template class Rtti; namespace model { @@ -145,11 +145,15 @@ private: const Variant attributes; std::vector> fields; - int getFieldDescriptorIndex(const std::string &fieldName); + int getFieldDescriptorIndex(const std::string &fieldName, + bool enforce) const; + + int getFieldDescriptorIndex(Handle fieldDescriptor, + bool enforce) const; public: DocumentEntity(Manager &mgr, Handle parent, - Handle descriptor, Variant attributes, + Handle descriptor, Variant attributes = {}, std::string name = "") : Node(mgr, std::move(name), parent), descriptor(acquire(descriptor)), @@ -181,9 +185,9 @@ public: * FieldDescriptor in the Domain description. * @return true if this FieldDescriptor exists. */ - bool hasField(const std::string &fieldName = "") + bool hasField(const std::string &fieldName = "") const { - return getFieldDescriptorIndex(fieldName) != -1; + return getFieldDescriptorIndex(fieldName, false) != -1; } /** @@ -199,7 +203,11 @@ public: * FieldDescriptor in the Domain description. * @return a NodeVector of all StructuredEntities in that field. */ - NodeVector &getField(const std::string &fieldName = ""); + const NodeVector &getField( + const std::string &fieldName = "") const + { + return fields[getFieldDescriptorIndex(fieldName, true)]; + } /** * This returns the vector of entities containing all members of the field @@ -212,8 +220,84 @@ public: * this DocumentEntity. * @return a NodeVector of all StructuredEntities in that field. */ - NodeVector &getField( - Handle fieldDescriptor); + const NodeVector &getField( + Handle fieldDescriptor) const + { + return fields[getFieldDescriptorIndex(fieldDescriptor, true)]; + } + /** + * This adds a StructuredEntity to the field with the given name. If an + * empty name is given it is assumed that the 'default' FieldDescriptor is + * referenced, where 'default' means either: + * 1.) The only TREE typed FieldDescriptor (if present) or + * 2.) the only FieldDescriptor (if only one is specified). + * + * If the name is unknown an exception is thrown. + * + * @param s is the StructuredEntity that shall be added. + * @param fieldName is the name of a field as specified in the + * FieldDescriptor in the Domain description. + */ + void addStructuredEntity(Handle s, + const std::string &fieldName = "") + { + fields[getFieldDescriptorIndex(fieldName, true)].push_back(s); + } + /** + * This adds multiple StructuredEntities to the field with the given name. + * If an empty name is given it is assumed that the 'default' + * FieldDescriptor is referenced, where 'default' means either: + * 1.) The only TREE typed FieldDescriptor (if present) or + * 2.) the only FieldDescriptor (if only one is specified). + * + * If the name is unknown an exception is thrown. + * + * @param ss are the StructuredEntities that shall be added. + * @param fieldName is the name of a field as specified in the + * FieldDescriptor in the Domain description. + */ + void addStructuredEntities(const std::vector> &ss, + const std::string &fieldName = "") + { + NodeVector &field = + fields[getFieldDescriptorIndex(fieldName, true)]; + field.insert(field.end(), ss.begin(), ss.end()); + } + + /** + * This adds a StructuredEntity to the field with the given FieldDescriptor. + * + * If the FieldDescriptor does not belong to the Descriptor of this node + * an exception is thrown. + * + * @param s is the StructuredEntity that shall be added. + * @param fieldDescriptor is a FieldDescriptor defined in the Descriptor for + * this DocumentEntity. + */ + void addStructuredEntity(Handle s, + Handle fieldDescriptor) + { + fields[getFieldDescriptorIndex(fieldDescriptor, true)].push_back(s); + } + + /** + * This adds multiple StructuredEntities to the field with the given + * FieldDescriptor. + * + * If the FieldDescriptor does not belong to the Descriptor of this node + * an exception is thrown. + * + * @param ss are the StructuredEntities that shall be added. + * @param fieldDescriptor is a FieldDescriptor defined in the Descriptor for + * this DocumentEntity. + */ + void addStructuredEntities(const std::vector> &ss, + Handle fieldDescriptor) + { + NodeVector &field = + fields[getFieldDescriptorIndex(fieldDescriptor, true)]; + field.insert(field.end(), ss.begin(), ss.end()); + } }; /** @@ -239,7 +323,7 @@ public: class DocumentPrimitive : public StructuredEntity { public: DocumentPrimitive(Manager &mgr, Handle parent, - Variant content) + Variant content = {}) : StructuredEntity(mgr, parent, nullptr, std::move(content)) { } @@ -296,9 +380,24 @@ private: Owned end; public: - AnnotationEntity(Manager &mgr, Handle parent, - Handle descriptor, Variant attributes, - Handle start, Handle end, + /** + * The constructor for an AnnotationEntity. + * + * @param mgr is the Manager instance. + * @param parent is the Document this AnnotationEntity is part of. + * @param descriptor is the AnnotationClass of this AnnotationEntity. + * @param start is the start Anchor of this AnnotationEntity. It has to + * be part of the Document given as parent. + * @param end is the end Anchor of this Annotationentity. It has to + * be part of the Document given as parent. + * @param attributes is a Map Variant containing attribute fillings for this + * AnnotationEntity. It is empty per default. + * @param name is some name for this AnnotationEntity that might be + * used for references later on. It is empty per default. + */ + AnnotationEntity(Manager &mgr, Handle parent, + Handle descriptor, Handle start, + Handle end, Variant attributes = {}, std::string name = "") : DocumentEntity(mgr, parent, descriptor, attributes, std::move(name)), start(acquire(start)), @@ -306,14 +405,25 @@ public: { } - Rooted getStart() { return start; } + /** + * Returns the start Anchor of this AnnotationEntity. + * + * @return the start Anchor of this AnnotationEntity. + */ + Rooted getStart() const { return start; } - Rooted getEnd() { return end; } + /** + * Returns the end Anchor of this AnnotationEntity. + * + * @return the end Anchor of this AnnotationEntity. + */ + Rooted getEnd() const { return end; } }; /** * A Document is mainly a wrapper for the Root structure node of the Document - * Graph. + * Graph. It also references the domains that have been used within this + * document and the AnnotationEntities that span over Anchors in this Document. */ class Document : public Node { private: @@ -332,17 +442,63 @@ public: { } + /** + * Sets the root StructuredEntity of this Document. + */ void setRoot(Handle root) { this->root = acquire(root); }; + /** + * Returns the root StructuredEntity of this Document. + * + * @return the root StructuredEntity of this Document. + */ Rooted getRoot() const { return root; } - NodeVector &getAnnotations() { return annotations; } + /** + * Returns a const reference to the NodeVector of AnnotationEntities that + * span over Anchors in this Documents structure. + * + * @return a const reference to the NodeVector of AnnotationEntities that + * span over Anchors in this Documents structure. + */ + const NodeVector &getAnnotations() const + { + return annotations; + } + + /** + * Adds an AnnotationEntity to this document. The Anchors used as start and + * end of this AnnotationEntity have to be part of this document. + */ + void addAnnotation(Handle a) { annotations.push_back(a); } + /** + * Adds multiple AnnotationEntities to this document. The Anchors used as + * start and end of these AnnotationEntities have to be part of this + * document. + */ + void addAnnotations(const std::vector> &as) + { + annotations.insert(annotations.end(), as.begin(), as.end()); + } + /** + * Returns a const reference to the NodeVector of Domains that are used + * within this Document. + * + * @return a const reference to the NodeVector of Domains that are used + * within this Document. + */ const NodeVector &getDomains() const { return domains; } + /** + * Adds a Domain reference to this Document. + */ void addDomain(Handle d) { domains.push_back(d); } - void addDomains(const std::vector> d) + /** + * Adds multiple Domain references to this Document. + */ + void addDomains(const std::vector> &d) { domains.insert(domains.end(), d.begin(), d.end()); } diff --git a/src/core/model/Domain.cpp b/src/core/model/Domain.cpp index 1de4f1a..17b1d2d 100644 --- a/src/core/model/Domain.cpp +++ b/src/core/model/Domain.cpp @@ -31,7 +31,7 @@ void Descriptor::continueResolve(ResolutionState &state) { if (attributesDescriptor != nullptr) { const NodeVector &attributes = - attributesDescriptor->getAttributes(); + attributesDescriptor->getAttributes(); continueResolveComposita(attributes, attributes.getIndex(), state); } continueResolveComposita(fieldDescriptors, fieldDescriptors.getIndex(), @@ -42,8 +42,8 @@ void Descriptor::continueResolve(ResolutionState &state) void Domain::continueResolve(ResolutionState &state) { - if (!continueResolveComposita(structureClasses, structureClasses.getIndex(), - state) | + if (!continueResolveComposita(structuredClasses, + structuredClasses.getIndex(), state) | continueResolveComposita(annotationClasses, annotationClasses.getIndex(), state)) { continueResolveReferences(typesystems, state); diff --git a/src/core/model/Domain.hpp b/src/core/model/Domain.hpp index 3a56e52..4b35fd4 100644 --- a/src/core/model/Domain.hpp +++ b/src/core/model/Domain.hpp @@ -212,7 +212,7 @@ namespace ousia { // Forward declarations class RttiType; -template +template class Rtti; namespace model { @@ -324,10 +324,29 @@ public: { } - // TODO: Is returning a NodeVector alright? - NodeVector &getChildren() { return children; } - + /** + * Returns a const reference to the NodeVector of StructuredClasses whose + * instances are allowed as children in the StructureTree of instances of + * this field. + * + * @return a const reference to the NodeVector of StructuredClasses whose + * instances are allowed as children in the StructureTree of instances of + * this field. + */ const NodeVector &getChildren() const { return children; } + + /** + * Adds a StructuredClass whose instances shall be allowed as children in + * the StructureTree of instances of this field. + */ + void addChild(Handle c){ children.push_back(c);} + + + /** + * Adds multiple StructuredClasses whose instances shall be allowed as + * children in the StructureTree of instances of this field. + */ + void addChildren(const std::vector> &cs){ children.insert(children.end(), cs.begin(), cs.end());} FieldType getFieldType() const { return fieldType; } @@ -381,20 +400,43 @@ public: { } + /** + * Returns a reference to the StructType that specifies the attribute keys + * as well as value domains for this Descriptor. + * + * @return a reference to the StructType that specifies the attribute keys + * as well as value domains for this Descriptor. + */ Rooted getAttributesDescriptor() const { return attributesDescriptor; } - - // TODO: Is returning a NodeVector alright? - NodeVector &getFieldDescriptors() + /** + * Returns a const reference to the NodeVector of all FieldDescriptors of + * this Descriptor. + * + * @return a const reference to the NodeVector of all FieldDescriptors of + * this Descriptor. + */ + const NodeVector &getFieldDescriptors() const { return fieldDescriptors; } - const NodeVector &getFieldDescriptors() const + /** + * Adds a FieldDescriptor to this Descriptor. + */ + void addFieldDescriptor(Handle fd) { - return fieldDescriptors; + fieldDescriptors.push_back(fd); + } + + /** + * Adds multiple FieldDescriptors to this Descriptor. + */ + void addFieldDescriptors(const std::vector>& fds) + { + fieldDescriptors.insert(fieldDescriptors.end(), fds.begin(), fds.end()); } }; @@ -491,11 +533,9 @@ public: * may occur at a specific point in the * StructureTree. For example: A document should * have at least one author. - * @param attributesDescriptor references a StructType that in turn - * specifies which key-value pairs are permitted - * as attributes for this StructuredClass. The - * default value is a null-reference, meaning - * that no attributes are permitted. + * @param attributesDescriptor is a StructType that specifies the attribute + * keys as well as value domains for this + * Descriptor. * @param isa references a parent StructuredClass. Please * look for more information on inheritance in * the class documentation above. The default is @@ -520,14 +560,48 @@ public: { } + /** + * Returns the Cardinality of this StructuredClass (as a RangeSet). + * + * @return the Cardinality of this StructuredClass (as a RangeSet). + */ const Cardinality &getCardinality() const { return cardinality; } + /** + * Returns the parent of this StructuredClass in the class inheritance + * hierarchy (!). This is not the same as the parents in the Structure Tree! + * + * @return the parent of this StructuredClass in the class inheritance + * hierarchy (!). + */ Rooted getIsA() const { return isa; } - // TODO: Is returning a NodeVector alright? - NodeVector &getParents() { return parents; } - + /** + * Returns a const reference to the NodeVector of FieldDescriptors that + * should allow an instance of this StructuredClass as child in the + * Structure Tree. This enables you to "invade" other domains as described + * in the StructuredClass documentation. + * + * @return a const reference to the NodeVector of FieldDescriptors that + * should allow an instance of this StructuredClass as child in the + * Structure Tree. + */ const NodeVector &getParents() const { return parents; } + + /** + * Adds a FieldDescriptor that should allow an instance of this + * StructuredClass as a child in the Structure Tree. + */ + void addParent(Handle p) { parents.push_back(p); } + + /** + * Adds multiple FieldDescriptors that should allow an instance of this + * StructuredClass as a child in the Structure Tree. + */ + void addParents(const std::vector>& ps) + { + parents.insert(parents.end(), ps.begin(), ps.end()); + } }; /** @@ -538,6 +612,19 @@ public: */ class AnnotationClass : public Descriptor { public: + /** + * The constructor for a new AnnotationClass. Note that you have to add + * the FieldDescriptors to it later on. + * + * @param mgr is the Manager instance. + * @param name is a name for this AnnotationClass that will + * be used for later references to this + * AnnotationClass. + * @param domain is the Domain this AnnotationClass belongs to. + * @param attributesDescriptor is a StructType that specifies the attribute + * keys as well as value domains for this + * Descriptor. + */ AnnotationClass(Manager &mgr, std::string name, Handle domain, // TODO: What would be a wise default value for attributes? Handle attributesDescriptor) @@ -553,7 +640,7 @@ public: */ class Domain : public Node { private: - NodeVector structureClasses; + NodeVector structuredClasses; NodeVector annotationClasses; // TODO: Is it wise to attach the type systems here? If not: What would be // a good alternative. @@ -563,39 +650,101 @@ protected: void continueResolve(ResolutionState &state) override; public: + /** + * The constructor for a new domain. Note that this is an empty Domain and + * still has to be filled with StructuredClasses and AnnotationClasses. + * + * @param mgr is the Manager instance. + * @param sys is the SystemTypesystem instance. + * @param name is a name for this domain which will be used for later + * references to this Domain. + */ Domain(Manager &mgr, Handle sys, std::string name) // TODO: Can a domain have a parent? : Node(mgr, std::move(name), nullptr), - structureClasses(this), + structuredClasses(this), annotationClasses(this), typesystems(this, std::vector>{sys}) { } - // TODO: Is returning a NodeVector alright? - NodeVector &getStructureClasses() + /** + * Returns a const reference to the NodeVector of StructuredClasses that are + * part of this Domain. + * + * @return a const reference to the NodeVector of StructuredClasses that are + * part of this Domain. + */ + const NodeVector &getStructureClasses() const { - return structureClasses; + return structuredClasses; } - const NodeVector &getStructureClasses() const + /** + * Adds a StructuredClass to this Domain. + */ + void addStructuredClass(Handle s) { - return structureClasses; + structuredClasses.push_back(s); } - NodeVector &getAnnotationClasses() + /** + * Adds multiple StructuredClasses to this Domain. + */ + void addStructuredClasses(const std::vector> &ss) { - return annotationClasses; + structuredClasses.insert(structuredClasses.end(), ss.begin(), ss.end()); } + /** + * Returns a const reference to the NodeVector of AnnotationClasses that are + * part of this Domain. + * + * @return a const reference to the NodeVector of AnnotationClasses that are + * part of this Domain. + */ const NodeVector &getAnnotationClasses() const { return annotationClasses; } - NodeVector &getTypesystems() { return typesystems; } + /** + * Adds an AnnotationClass to this Domain. + */ + void addAnnotationClass(Handle a) + { + annotationClasses.push_back(a); + } + + /** + * Adds multiple AnnotationClasses to this Domain. + */ + void addAnnotationClasses(const std::vector> &as) + { + annotationClasses.insert(annotationClasses.end(), as.begin(), as.end()); + } + /** + * Returns a const reference to the NodeVector of TypeSystems that are + * references in this Domain. + * + * @return a const reference to the NodeVector of TypeSystems that are + * references in this Domain. + */ const NodeVector &getTypesystems() const { return typesystems; } + + /** + * Adds a Typesystem reference to this Domain. + */ + void addTypesystem(Handle t) { typesystems.push_back(t); } + + /** + * Adds multiple Typesystem references to this Domain. + */ + void addTypesystems(const std::vector> &ts) + { + typesystems.insert(typesystems.end(), ts.begin(), ts.end()); + } }; } diff --git a/src/core/model/Typesystem.hpp b/src/core/model/Typesystem.hpp index 22b747f..890ae82 100644 --- a/src/core/model/Typesystem.hpp +++ b/src/core/model/Typesystem.hpp @@ -42,7 +42,7 @@ namespace ousia { // Forward declarations class RttiType; -template +template class Rtti; namespace model { @@ -828,6 +828,14 @@ public: */ void addType(Handle type) { types.push_back(type); } + /** + * Adds the given types to the type list. + */ + void addTypes(const std::vector> &ts) + { + types.insert(types.end(), ts.begin(), ts.end()); + } + /** * Adds the given constant to the constant list. */ @@ -836,6 +844,14 @@ public: constants.push_back(constant); } + /** + * Adds the given constants to the constant list. + */ + void addConstants(const std::vector> &cs) + { + constants.insert(constants.end(), cs.begin(), cs.end()); + } + /** * Returns a reference to list containing all registered types. * -- cgit v1.2.3