diff options
author | Benjamin Paassen <bpaassen@techfak.uni-bielefeld.de> | 2015-01-12 13:42:10 +0100 |
---|---|---|
committer | Benjamin Paassen <bpaassen@techfak.uni-bielefeld.de> | 2015-01-12 13:42:10 +0100 |
commit | 60d9d3f9f54fab975c39d4c341f118df90628375 (patch) | |
tree | e3e43951c70960b6cd8d55abb348bd4d4589bb2b /src | |
parent | 909a9e98999e72262bd353027ce70c6c0377cf9c (diff) |
normalized NodeVector access in model classes and added some more documentation to model classes.
Diffstat (limited to 'src')
-rw-r--r-- | src/core/model/Document.cpp | 32 | ||||
-rw-r--r-- | src/core/model/Document.hpp | 190 | ||||
-rw-r--r-- | src/core/model/Domain.cpp | 6 | ||||
-rw-r--r-- | src/core/model/Domain.hpp | 203 | ||||
-rw-r--r-- | src/core/model/Typesystem.hpp | 18 |
5 files changed, 385 insertions, 64 deletions
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<FieldDescriptor> &fds = descriptor->getFieldDescriptors(); unsigned int f = 0; @@ -56,21 +57,15 @@ int DocumentEntity::getFieldDescriptorIndex(const std::string &fieldName) f++; } } - return -1; -} - -NodeVector<StructuredEntity> &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<StructuredEntity> &DocumentEntity::getField( - Handle<FieldDescriptor> fieldDescriptor) +int DocumentEntity::getFieldDescriptorIndex( + Handle<FieldDescriptor> fieldDescriptor, bool enforce) const { if (fieldDescriptor.isNull()) { throw OusiaException("The given FieldDescriptor handle is null!"); @@ -80,13 +75,18 @@ NodeVector<StructuredEntity> &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<class T> +template <class T> class Rtti; namespace model { @@ -145,11 +145,15 @@ private: const Variant attributes; std::vector<NodeVector<StructuredEntity>> fields; - int getFieldDescriptorIndex(const std::string &fieldName); + int getFieldDescriptorIndex(const std::string &fieldName, + bool enforce) const; + + int getFieldDescriptorIndex(Handle<FieldDescriptor> fieldDescriptor, + bool enforce) const; public: DocumentEntity(Manager &mgr, Handle<Node> parent, - Handle<Descriptor> descriptor, Variant attributes, + Handle<Descriptor> 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<StructuredEntity> &getField(const std::string &fieldName = ""); + const NodeVector<StructuredEntity> &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<StructuredEntity> &getField( - Handle<FieldDescriptor> fieldDescriptor); + const NodeVector<StructuredEntity> &getField( + Handle<FieldDescriptor> 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<StructuredEntity> 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<Handle<StructuredEntity>> &ss, + const std::string &fieldName = "") + { + NodeVector<StructuredEntity> &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<StructuredEntity> s, + Handle<FieldDescriptor> 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<Handle<StructuredEntity>> &ss, + Handle<FieldDescriptor> fieldDescriptor) + { + NodeVector<StructuredEntity> &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<DocumentEntity> parent, - Variant content) + Variant content = {}) : StructuredEntity(mgr, parent, nullptr, std::move(content)) { } @@ -296,9 +380,24 @@ private: Owned<Anchor> end; public: - AnnotationEntity(Manager &mgr, Handle<Node> parent, - Handle<AnnotationClass> descriptor, Variant attributes, - Handle<Anchor> start, Handle<Anchor> 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<Document> parent, + Handle<AnnotationClass> descriptor, Handle<Anchor> start, + Handle<Anchor> end, Variant attributes = {}, std::string name = "") : DocumentEntity(mgr, parent, descriptor, attributes, std::move(name)), start(acquire(start)), @@ -306,14 +405,25 @@ public: { } - Rooted<Anchor> getStart() { return start; } + /** + * Returns the start Anchor of this AnnotationEntity. + * + * @return the start Anchor of this AnnotationEntity. + */ + Rooted<Anchor> getStart() const { return start; } - Rooted<Anchor> getEnd() { return end; } + /** + * Returns the end Anchor of this AnnotationEntity. + * + * @return the end Anchor of this AnnotationEntity. + */ + Rooted<Anchor> 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<StructuredEntity> root) { this->root = acquire(root); }; + /** + * Returns the root StructuredEntity of this Document. + * + * @return the root StructuredEntity of this Document. + */ Rooted<StructuredEntity> getRoot() const { return root; } - NodeVector<AnnotationEntity> &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<AnnotationEntity> &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<AnnotationEntity> 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<Handle<AnnotationEntity>> &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<Domain> &getDomains() const { return domains; } + /** + * Adds a Domain reference to this Document. + */ void addDomain(Handle<Domain> d) { domains.push_back(d); } - void addDomains(const std::vector<Handle<Domain>> d) + /** + * Adds multiple Domain references to this Document. + */ + void addDomains(const std::vector<Handle<Domain>> &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<Attribute> &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<class T> +template <class T> class Rtti; namespace model { @@ -324,10 +324,29 @@ public: { } - // TODO: Is returning a NodeVector alright? - NodeVector<StructuredClass> &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<StructuredClass> &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<StructuredClass> 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<Handle<StructuredClass>> &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<StructType> getAttributesDescriptor() const { return attributesDescriptor; } - - // TODO: Is returning a NodeVector alright? - NodeVector<FieldDescriptor> &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<FieldDescriptor> &getFieldDescriptors() const { return fieldDescriptors; } - const NodeVector<FieldDescriptor> &getFieldDescriptors() const + /** + * Adds a FieldDescriptor to this Descriptor. + */ + void addFieldDescriptor(Handle<FieldDescriptor> fd) { - return fieldDescriptors; + fieldDescriptors.push_back(fd); + } + + /** + * Adds multiple FieldDescriptors to this Descriptor. + */ + void addFieldDescriptors(const std::vector<Handle<FieldDescriptor>>& 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<StructuredClass> getIsA() const { return isa; } - // TODO: Is returning a NodeVector alright? - NodeVector<FieldDescriptor> &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<FieldDescriptor> &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<FieldDescriptor> 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<Handle<FieldDescriptor>>& 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> domain, // TODO: What would be a wise default value for attributes? Handle<StructType> attributesDescriptor) @@ -553,7 +640,7 @@ public: */ class Domain : public Node { private: - NodeVector<StructuredClass> structureClasses; + NodeVector<StructuredClass> structuredClasses; NodeVector<AnnotationClass> 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<SystemTypesystem> 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<Handle<Typesystem>>{sys}) { } - // TODO: Is returning a NodeVector alright? - NodeVector<StructuredClass> &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<StructuredClass> &getStructureClasses() const { - return structureClasses; + return structuredClasses; } - const NodeVector<StructuredClass> &getStructureClasses() const + /** + * Adds a StructuredClass to this Domain. + */ + void addStructuredClass(Handle<StructuredClass> s) { - return structureClasses; + structuredClasses.push_back(s); } - NodeVector<AnnotationClass> &getAnnotationClasses() + /** + * Adds multiple StructuredClasses to this Domain. + */ + void addStructuredClasses(const std::vector<Handle<StructuredClass>> &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<AnnotationClass> &getAnnotationClasses() const { return annotationClasses; } - NodeVector<Typesystem> &getTypesystems() { return typesystems; } + /** + * Adds an AnnotationClass to this Domain. + */ + void addAnnotationClass(Handle<AnnotationClass> a) + { + annotationClasses.push_back(a); + } + + /** + * Adds multiple AnnotationClasses to this Domain. + */ + void addAnnotationClasses(const std::vector<Handle<AnnotationClass>> &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<Typesystem> &getTypesystems() const { return typesystems; } + + /** + * Adds a Typesystem reference to this Domain. + */ + void addTypesystem(Handle<Typesystem> t) { typesystems.push_back(t); } + + /** + * Adds multiple Typesystem references to this Domain. + */ + void addTypesystems(const std::vector<Handle<Typesystem>> &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<class T> +template <class T> class Rtti; namespace model { @@ -829,6 +829,14 @@ public: void addType(Handle<Type> type) { types.push_back(type); } /** + * Adds the given types to the type list. + */ + void addTypes(const std::vector<Handle<Type>> &ts) + { + types.insert(types.end(), ts.begin(), ts.end()); + } + + /** * Adds the given constant to the constant list. */ void addConstant(Handle<Constant> constant) @@ -837,6 +845,14 @@ public: } /** + * Adds the given constants to the constant list. + */ + void addConstants(const std::vector<Handle<Constant>> &cs) + { + constants.insert(constants.end(), cs.begin(), cs.end()); + } + + /** * Returns a reference to list containing all registered types. * * @return NodeVector containing all registered types. |