summaryrefslogtreecommitdiff
path: root/src/core/model
diff options
context:
space:
mode:
Diffstat (limited to 'src/core/model')
-rw-r--r--src/core/model/Document.cpp20
-rw-r--r--src/core/model/Document.hpp97
-rw-r--r--src/core/model/Domain.hpp229
3 files changed, 232 insertions, 114 deletions
diff --git a/src/core/model/Document.cpp b/src/core/model/Document.cpp
index 854e717..e5d0755 100644
--- a/src/core/model/Document.cpp
+++ b/src/core/model/Document.cpp
@@ -57,20 +57,22 @@ int DocumentEntity::getFieldDescriptorIndex(const std::string &fieldName)
return -1;
}
-void DocumentEntity::getField(NodeVector<StructuredEntity> &res,
- const std::string &fieldName)
+NodeVector<StructuredEntity> &DocumentEntity::getField(
+ const std::string &fieldName)
{
int f = getFieldDescriptorIndex(fieldName);
if (f < 0) {
- NodeVector<StructuredEntity> empty{this};
- res = NodeVector<StructuredEntity>(this);
+ throw OusiaException("No field for the given name exists!");
}
- res = fields[f];
+ return fields[f];
}
NodeVector<StructuredEntity> &DocumentEntity::getField(
- Rooted<FieldDescriptor> fieldDescriptor)
+ Handle<FieldDescriptor> fieldDescriptor)
{
+ if(fieldDescriptor.isNull()){
+ throw OusiaException("The given FieldDescriptor handle is null!");
+ }
const NodeVector<FieldDescriptor> &fds = descriptor->getFieldDescriptors();
int f = 0;
for (auto &fd : fds) {
@@ -155,8 +157,7 @@ Rooted<StructuredEntity> StructuredEntity::buildEntity(
return {nullptr};
}
// append the new entity to the right field.
- NodeVector<StructuredEntity> field(parent);
- parent->getField(field, fieldName);
+ NodeVector<StructuredEntity>& field = parent->getField(fieldName);
field.push_back(entity);
// and return it.
@@ -179,8 +180,7 @@ Rooted<DocumentPrimitive> DocumentPrimitive::buildEntity(
return {nullptr};
}
// append the new entity to the right field.
- NodeVector<StructuredEntity> field(parent);
- parent->getField(field, fieldName);
+ NodeVector<StructuredEntity>& field = parent->getField(fieldName);
field.push_back(entity);
// and return it.
diff --git a/src/core/model/Document.hpp b/src/core/model/Document.hpp
index 2d792c5..fabdcaf 100644
--- a/src/core/model/Document.hpp
+++ b/src/core/model/Document.hpp
@@ -32,21 +32,33 @@
* Structure Nodes, effectively resulting in a Document Graph instead of a
* Document Tree (other references may introduce cycles as well).
*
- * Consider this simplified XML representation of a document (TODO: Use
- * non-simplified XML as soon as possible):
+ * Consider this XML representation of a document using the "book" domain:
*
- * <Document implements="book">
- * <StructureEntity class="book">
- * <StructureEntity class="section">
- * <DocumentPrimitive>
- * This is some text with some <Anchor id="1"/>emphasized and
- * <Anchor id="2"/>strong<Anchor id="3"/> text.
- * </DocumentPrimitive>
- * <AnnotationEntity class="emphasized" start="1", end="3"/>
- * <AnnotationEntity class="strong" start="2", end="3"/>
- * </StructureEntity>
- * </StructureEntity>
- * </Document>
+ * <doc>
+ * <head>
+ * <import rel="domain" src="book_domain.oxm"/>
+ * <import rel="domain" src="emphasized_domain.oxm"/>
+ * <alias tag="paragraph" aka="p"/>
+ * </head>
+ * <book>
+ * This might be some introductory text or a dedication. Ideally, of
+ * course, such elements would be semantically specified as such in
+ * additional domains (or in this one).
+ * <chapter name="myFirstChapter">
+ * Here we might have an introduction to the chapter, including some
+ * overview of the chapters structure.
+ * <section name="myFirstSection">
+ * Here we might find the actual section content.
+ * </section>
+ * <section name="mySndSection">
+ * Here we might find the actual section <em>content</em>.
+ *
+ *
+ * And there might even be another paragraph.
+ * </section>
+ * </chapter>
+ * </book>
+ * </doc>
*
* As can be seen the StructureEntities inherently follow a tree structure that
* is restricted by the implicit context free grammar of the "book" Domain
@@ -56,12 +68,32 @@
* Another interesting fact is the special place of AnnotationEntities: They are
* Defined by start and end Anchors in the text. Note that this allows for
* overlapping annotations and provides a more intuitive (and semantically
- * sound) handling of such span-like concepts.
+ * sound) handling of such span-like concepts. So the
+ *
+ * <em>content</em>
+ *
+ * is implicitly expanded to:
+ *
+ * <a id="1"/>content<a id="2"/>
+ * <emphasized start="1" end="2"/>
+ *
* Note that the place of an AnnotationEntity within the XML above is not
* strictly defined. It might as well be placed as a child of the "book" node.
* In general it is recommended to use the lowest possible place in the
* StructureTree to include the AnnotationEntity for better readability.
*
+ * Also note that text content like
+ *
+ * Here we might find the actual section content.
+ *
+ * is implicitly expanded using transparency to:
+ *
+ * <paragraph>
+ * <text>
+ * Here we might find the actual section content.
+ * </text>
+ * </paragraph>
+ *
* @author Benjamin Paaßen (bpaassen@techfak.uni-bielefeld.de)
*/
@@ -124,12 +156,6 @@ public:
Variant getAttributes() const { return attributes; }
/**
- * This allows a direct manipulation of the internal data structure of a
- * DocumentEntity and is not recommended. TODO: Delete this?
- */
- std::vector<NodeVector<StructuredEntity>> &getFields() { return fields; }
-
- /**
* This returns true if there is a FieldDescriptor in the Descriptor for
* this DocumentEntity which has the given name. If an empty name is
* given it is assumed that the 'default' FieldDescriptor is referenced,
@@ -148,29 +174,18 @@ public:
/**
* This returns the vector of entities containing all members of the field
- * for which the FieldDescriptor has the specified name. If an empty name is
- * given it is assumed that the 'default' FieldDescriptor is referenced,
- * where 'default' means either:
+ * 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).
*
- * Note that the output of this method might well be ambigous: If no
- * FieldDescriptor matches the given name an empty NodeVector is
- * returned. This is also the case, however, if there are no members for an
- * existing field. Therefore it is recommended to additionally check the
- * output of "hasField" or use the version of this method with
- * a FieldDescriptor as input.
+ * If the name is unknown an exception is thrown.
*
- * @param fieldName is the name of the field as specified in the
+ * @param fieldName is the name of a field as specified in the
* FieldDescriptor in the Domain description.
- * @param res is a NodeVector reference where the result will be
- * stored. After using this method the reference will
- * either refer to all StructuredEntities in that field. If
- * the field is unknown or if no members exist in that
- * field yet, the NodeVector will be empty.
+ * @return a NodeVector of all StructuredEntities in that field.
*/
- void getField(NodeVector<StructuredEntity> &res,
- const std::string &fieldName = "");
+ NodeVector<StructuredEntity> &getField(const std::string &fieldName = "");
/**
* This returns the vector of entities containing all members of the field
@@ -184,7 +199,7 @@ public:
* @return a NodeVector of all StructuredEntities in that field.
*/
NodeVector<StructuredEntity> &getField(
- Rooted<FieldDescriptor> fieldDescriptor);
+ Handle<FieldDescriptor> fieldDescriptor);
};
/**
@@ -365,7 +380,7 @@ public:
*/
class Document : public Node {
private:
- //TODO: Might there be several roots? E.g. metadata?
+ // TODO: Might there be several roots? E.g. metadata?
Owned<StructuredEntity> root;
public:
@@ -375,7 +390,7 @@ public:
{
}
- void setRoot(Handle<StructuredEntity> root) { root = acquire(root); };
+ void setRoot(Handle<StructuredEntity> root) { this->root = acquire(root); };
Rooted<StructuredEntity> getRoot() const { return root; }
};
diff --git a/src/core/model/Domain.hpp b/src/core/model/Domain.hpp
index cd74a19..7e4e9f7 100644
--- a/src/core/model/Domain.hpp
+++ b/src/core/model/Domain.hpp
@@ -30,24 +30,65 @@
* terms "StructuredClass" and "FieldDescriptor".
* On the top level you would start with a StructuredClass, say "book", which
* in turn might contain two FieldDescriptors, one for the meta data of ones
- * book and one for the actual structure. Consider the following (simplified)
- * XML notation (TODO: Use a non-simplified notation as soon as the format is
- * clear.)
- *
- * <StructuredClass name="book">
- * <FieldDescriptor name="structure", type="TREE", optional="false">
- * <children>
- * Here we would reference the possible child classes, e.g. section,
- * paragraph, etc.
- * </children>
- * </FieldDescriptor>
- * <FieldDescriptor name="meta", type="SUBTREE", optional="true">
- * <children>
- * Here we would reference the possible child classes for meta,
- * information, e.g. authors, date, version, etc.
- * </children>
- * </FieldDescriptor>
- * </StructuredClass>
+ * book and one for the actual structure. Consider the following XML:
+ *
+ * <domain name="book">
+ * <structs>
+ * <struct name="book" cardinality="1" isRoot="true">
+ * <fields>
+ * <field>
+ * <children>
+ * <child name="book.chapter"/>
+ * <child name="book.paragraph"/>
+ * </children>
+ * </field>
+ * </fields>
+ * </struct>
+ * <struct name="chapter">
+ * <fields>
+ * <field>
+ * <children>
+ * <child name="book.section"/>
+ * <child name="book.paragraph"/>
+ * </children>
+ * </field>
+ * </fields>
+ * </struct>
+ * <struct name="section">
+ * <fields>
+ * <field>
+ * <children>
+ * <child name="book.subsection"/>
+ * <child name="book.paragraph"/>
+ * </children>
+ * </field>
+ * </fields>
+ * </struct>
+ * <struct name="subsection">
+ * <fields>
+ * <field>
+ * <children>
+ * <child name="book.paragraph"/>
+ * </children>
+ * </field>
+ * </fields>
+ * </struct>
+ * <struct name="paragraph" transparent="true" role="paragraph">
+ * <fields>
+ * <field>
+ * <children>
+ * <child name="book.text"/>
+ * </children>
+ * </field>
+ * </fields>
+ * </struct>
+ * <struct name="text" transparent="true" role="text">
+ * <fields>
+ * <field name="content" type="PRIMITIVE" primitiveType="string"/>
+ * </fields>
+ * </struct>
+ * </structs>
+ * </domain>
*
* Note that we define one field as the TREE (meaning the main or default
* document structure) and one mearly as SUBTREE, relating to supporting
@@ -58,11 +99,19 @@
* TREE field and at least one permitted child must exist, either primitive or
* as another StructuredClass.
*
- * The translation to context free grammars is roughly as follows:
+ * The translation to context free grammars is as follows:
*
- * BOOK := book BOOK_STRUCTURE BOOK_META
- * BOOK_STRUCTURE := SECTION BOOK_STRUCTURE | PARAGRAPH BOOK_STRUCTURE | epsilon
- * BOOK_META := AUTHOR BOOK_META | DATE BOOK_META
+ * BOOK := <book> BOOK_TREE </book>
+ * BOOK_TREE := CHAPTER BOOK_TREE | PARAGRAPH BOOK_TREE | epsilon
+ * CHAPTER := <chapter> CHAPTER_TREE </chapter>
+ * CHAPTER_TREE := SECTION CHAPTER_TREE | PARAGRAPH CHAPTER_TREE | epsilon
+ * SECTION := <section> SECTION_TREE </section>
+ * SECTION_TREE := SUBSECTION SECTION_TREE | PARAGRAPH SECTION_TREE |
+ * epsilon
+ * SUBSECTION := <subsection> SUBSECTION_TREE </subsection>
+ * SUBSECTION_TREE := PARAGRAPH SUBSECTION_TREE | epsilon
+ * PARAGRAPH := <paragraph> PARAGRAPH_CONTENT </paragraph>
+ * PARAGRAPH_CONTENT := string
*
* Note that this translation recurs to further nonterminals like SECTION but
* necessarily produces one "book" terminal. Also note that, in principle,
@@ -70,11 +119,72 @@
* the proper StructuredClass. This can be regulated by the "cardinality"
* property of a StructuredClass.
*
+ * It is possible to add further fields, like we would in the "headings" domain
+ * to add titles to our structure.
+ *
+ * <domain name="headings">
+ * <head>
+ * <import rel="domain" src="book.oxm"/>
+ * </head>
+ * <structs>
+ * <struct name="heading" cardinality="0-1" transparent="true">
+ * <parents>
+ * <parent name="book.book">
+ * <field name="heading" type="SUBTREE"/>
+ * </parent>
+ * ...
+ * </parents>
+ * <fields>
+ * <fieldRef name="book.paragraph.">
+ * </fields>
+ * </structs>
+ * </domain>
+ *
+ * This would change the context free grammar as follows:
+ *
+ * BOOK := <book> HEADING BOOK_TREE </book>
+ * HEADING := <heading> PARAGRAPH </heading>
+ *
* AnnotationClasses on the other hand do not specify a context free grammar.
* They merely specify what kinds of Annotations are allowed within this domain
* and which fields or attributes they have. Note that Annotations are allowed
* to define structured children that manifest e.g. meta information of that
- * Annotation.
+ * Annotation. An example for that would be the "comment" domain:
+ *
+ * <domain name="comments">
+ * <head>
+ * <import rel="domain" src="book.oxm"/>
+ * </head>
+ * <annos>
+ * <anno name="comment">
+ * <fields>
+ * <field name="replies" type="SUBTREE">
+ * <children>
+ * <child name="reply"/>
+ * </children>
+ * </field>
+ * </fields>
+ * </anno>
+ * </annos>
+ * <structs>
+ * <struct name="reply">
+ * <fields>
+ * <field name="replies" type="SUBTREE">
+ * <children>
+ * <child name="reply"/>
+ * </children>
+ * </field>
+ * <field name="content" type="SUBTREE">
+ * <children>
+ * <child name="book.paragraph"/>
+ * </children>
+ * </field>
+ * </fields>
+ * </struct>
+ * </structs>
+ * </domain>
+ *
+ * Here we have comment annotations, which have a reply tree as sub structure.
*
* @author Benjamin Paaßen (bpaassen@techfak.uni-bielefeld.de)
*/
@@ -105,13 +215,17 @@ class Domain;
* Hierarchy.
*
* As an example consider the "paragraph" StructuredClass, which might allow
- * the actual text content. Here is the according simplified XML (TODO: replace
- * with a non-simplified version as soon as the XML syntax is clear.)
+ * the actual text content. Here is the according XML:
*
- * <StructuredClass name="paragraph">
- * <FieldDescriptor name="text", type="PRIMITIVE", optional="false",
- * primitiveType="string"/>
- * </StructuredClass>
+ * <struct name="paragraph" transparent="true" role="paragraph">
+ * <fields>
+ * <field>
+ * <children>
+ * <child name="book.text"/>
+ * </children>
+ * </field>
+ * </fields>
+ * </struct>
*
* Accordingly the primitiveType field of a FieldDescriptor may only be
* defined if the type is set to "PRIMITIVE". If the type is something else
@@ -286,36 +400,28 @@ typedef RangeSet<size_t> Cardinality;
* consult the Header documentation above.
*
* Note that a StructuredClass may "invade" an existing Domain description by
- * defining itself as a viable child in one existing field. Consider a "section"
- * StructuredClass (continuing the example in the header documentation):
- *
- * <StructuredClass name="section">
- * <FieldDescriptor name="structure", type="TREE", optional="false">
- * <children>
- * <classRef>paragraph</classRef>
- * </children>
- * </FieldDescriptor>
- * </StructuredClass>
- *
- * Of course in most cases we do not only want to allow paragraphs inside
- * sections, but also (for example) lists. How would one add that
- * without manipulating the existing domain or having to define an entirely
- * new domain in which section allows for lists?
- *
- * Our solution to this problem is the parent mechanism. The simplified XML
- * (TODO: Use non-simplified version as soon as possible) for the "list"
- * StructuredClass would look like this:
- *
- * <StructuredClass name="list">
- * <FieldDescriptor name="structure", type="TREE", optional="false">
- * <children>
- * <classRef>item</classRef>
- * </children>
- * </FieldDescriptor>
- * <parents>
- * <fieldRef>section.structure</fieldRef>
- * </parents>
- * </StructuredClass>
+ * defining itself as a viable child in one existing field. Consider the
+ * example of the "heading" domain from the header documentation again:
+ *
+ * <domain name="headings">
+ * <head>
+ * <import rel="domain" src="book.oxm"/>
+ * </head>
+ * <structs>
+ * <struct name="heading" cardinality="0-1" transparent="true">
+ * <parents>
+ * <parent name="book.book">
+ * <field name="heading" type="SUBTREE"/>
+ * </parent>
+ * ...
+ * </parents>
+ * <fields>
+ * <fieldRef name="book.paragraph.">
+ * </fields>
+ * </structs>
+ * </domain>
+ *
+ * The "parent" construct allows to "invade" another domain.
*
* This does indeed interfere with an existing domain and one must carefully
* craft such parent references to not create undesired side effects. However
@@ -404,8 +510,7 @@ public:
Handle<StructType> attributesDescriptor = nullptr,
// TODO: What would be a wise default value for isa?
Handle<StructuredClass> isa = nullptr,
- bool transparent = false,
- bool root = false)
+ bool transparent = false, bool root = false)
: Descriptor(mgr, std::move(name), domain, attributesDescriptor),
cardinality(cardinality),
isa(acquire(isa)),
@@ -497,9 +602,7 @@ extern const Rtti<model::Descriptor> Descriptor;
extern const Rtti<model::StructuredClass> StructuredClass;
extern const Rtti<model::AnnotationClass> AnnotationClass;
extern const Rtti<model::Domain> Domain;
-
}
-
}
#endif /* _OUSIA_MODEL_DOMAIN_HPP_ */
generated by cgit v1.2.3 (git 2.39.1) at 2025-05-01 07:36:19 +0000