From 753c0c0db2e1d934a8ed53e3732bfe0283fbc868 Mon Sep 17 00:00:00 2001
From: Edouard DUPIN <yui.heero@gmail.com>
Date: Mon, 11 Apr 2016 21:57:33 +0200
Subject: [PATCH] [DOC] Basic documentation done
---
exml/Attribute.h | 5 ++++-
exml/AttributeList.h | 3 +++
exml/Comment.h | 13 +++++++-----
exml/Declaration.h | 8 +++++++-
exml/Document.h | 32 ++++++++++++++++++++++-------
exml/Element.cpp | 15 ++++++--------
exml/Element.h | 48 +++++++++++++++++++++++++++++++++++++++-----
exml/Node.cpp | 14 ++++++-------
exml/Node.h | 31 +++++++++++++++++-----------
exml/Text.cpp | 4 ----
exml/Text.h | 20 +++++++++++++++---
11 files changed, 139 insertions(+), 54 deletions(-)
diff --git a/exml/Attribute.h b/exml/Attribute.h
index 80311df..6f069a0 100644
--- a/exml/Attribute.h
+++ b/exml/Attribute.h
@@ -11,6 +11,9 @@
#include <vector>
namespace exml {
+ /**
+ * @brief Single attribute element
+ */
class Attribute : public exml::Node {
protected:
/**
@@ -46,7 +49,7 @@ namespace exml {
};
public:
enum nodeType getType() const override {
- return exml::typeAttribute;
+ return exml::nodeType_attribute;
};
bool iParse(const std::string& _data, int32_t& _pos, bool _caseSensitive, exml::FilePos& _filePos, exml::Document& _doc) override;
bool iGenerate(std::string& _data, int32_t _indent) const override;
diff --git a/exml/AttributeList.h b/exml/AttributeList.h
index 5ad9d10..99f096d 100644
--- a/exml/AttributeList.h
+++ b/exml/AttributeList.h
@@ -13,6 +13,9 @@
#include <utility>
namespace exml {
+ /**
+ * @brief List of all attribute element in a node
+ */
class AttributeList : public exml::Node {
protected:
/**
diff --git a/exml/Comment.h b/exml/Comment.h
index b61121f..7e4abde 100644
--- a/exml/Comment.h
+++ b/exml/Comment.h
@@ -11,6 +11,9 @@
#include <vector>
namespace exml {
+ /**
+ * @brief Comment node: <!-- ... -->
+ */
class Comment : public exml::Node {
protected:
/**
@@ -30,19 +33,19 @@ namespace exml {
Comment(const std::string& _value) :
exml::Node(_value) {
- };
+ }
public:
enum nodeType getType() const override {
- return typeAttribute;
- };
+ return nodeType_attribute;
+ }
bool iParse(const std::string& _data, int32_t& _pos, bool _caseSensitive, exml::FilePos& _filePos, exml::Document& _doc) override;
bool iGenerate(std::string& _data, int32_t _indent) const override;
ememory::SharedPtr<exml::Comment> toComment() override {
return std::static_pointer_cast<exml::Comment>(shared_from_this());
- };
+ }
ememory::SharedPtr<const exml::Comment> toComment() const override {
return std::static_pointer_cast<const exml::Comment>(shared_from_this());
- };
+ }
};
}
diff --git a/exml/Declaration.h b/exml/Declaration.h
index 52c29d5..26aaf86 100644
--- a/exml/Declaration.h
+++ b/exml/Declaration.h
@@ -10,6 +10,9 @@
#include <exml/AttributeList.h>
namespace exml {
+ /**
+ * @brief Declaration node: <?XXXXXX ... >
+ */
class Declaration : public exml::AttributeList {
protected:
/**
@@ -29,7 +32,7 @@ namespace exml {
static ememory::SharedPtr<Declaration> create(const std::string& _name="");
public:
enum nodeType getType() const override{
- return typeAttribute;
+ return nodeType_attribute;
};
bool iGenerate(std::string& _data, int32_t _indent) const override;
bool iParse(const std::string& _data, int32_t& _pos, bool _caseSensitive, exml::FilePos& _filePos, exml::Document& _doc) override;
@@ -40,6 +43,9 @@ namespace exml {
return std::static_pointer_cast<const exml::Declaration>(shared_from_this());
};
};
+ /**
+ * @brief Declaration node: <?XML ... >
+ */
class DeclarationXML : public exml::Declaration {
public:
/**
diff --git a/exml/Document.h b/exml/Document.h
index c278182..643445a 100644
--- a/exml/Document.h
+++ b/exml/Document.h
@@ -11,6 +11,9 @@
#include <vector>
namespace exml {
+ /**
+ * @brief Basic document element of a document
+ */
class Document : public exml::Element {
public:
/**
@@ -78,26 +81,41 @@ namespace exml {
std::string m_Line; //!< Parse line error (copy)
exml::FilePos m_filePos; //!< position of the error
public:
+ /**
+ * @brief Request display error when detected (not print only at the end ...)
+ */
void displayErrorWhenDetected() {
m_writeErrorWhenDetexted = true;
- };
+ }
+ /**
+ * @brief Request NOT display error when detected.
+ */
void notDisplayErrorWhenDetected() {
m_writeErrorWhenDetexted = false;
- };
-
+ }
+ /**
+ * @brief Create an error in the parsing (call by the syetm for error management)
+ * @param[in] _data string of chat is wrong
+ * @param[in] _pos Position in the file
+ * @param[in] _filePos human position of the error
+ * @param[in] _comment Error string to display
+ */
void createError(const std::string& _data, int32_t _pos, const exml::FilePos& _filePos, const std::string& _comment);
+ /**
+ * @brief request display in log of the error
+ */
void displayError();
public:
enum nodeType getType() const override {
- return typeDocument;
- };
+ return nodeType_document;
+ }
bool iGenerate(std::string& _data, int32_t _indent) const override;
ememory::SharedPtr<exml::Document> toDocument() override {
return std::static_pointer_cast<exml::Document>(shared_from_this());
- };
+ }
ememory::SharedPtr<const exml::Document> toDocument() const override {
return std::static_pointer_cast<const exml::Document>(shared_from_this());
- };
+ }
};
};
diff --git a/exml/Element.cpp b/exml/Element.cpp
index 309155d..e038841 100644
--- a/exml/Element.cpp
+++ b/exml/Element.cpp
@@ -24,9 +24,6 @@ static bool isWhiteChar(char32_t _val) {
return false;
}
-ememory::SharedPtr<exml::Element> exml::Element::create() {
- return ememory::SharedPtr<exml::Element>(new exml::Element());
-}
ememory::SharedPtr<exml::Element> exml::Element::create(const std::string& _value) {
return ememory::SharedPtr<exml::Element>(new exml::Element(_value));
}
@@ -34,7 +31,7 @@ ememory::SharedPtr<exml::Element> exml::Element::create(const std::string& _valu
enum exml::nodeType exml::Element::getType(int32_t _id) const {
ememory::SharedPtr<const exml::Node> tmpp = getNode(_id);
if (tmpp == nullptr) {
- return exml::typeUnknow;
+ return exml::nodeType_unknow;
}
return tmpp->getType();
}
@@ -76,7 +73,7 @@ ememory::SharedPtr<exml::Element> exml::Element::getNamed(const std::string& _na
}
for (size_t iii=0; iii<m_listSub.size(); iii++) {
if( m_listSub[iii] != nullptr
- && m_listSub[iii]->getType() == exml::typeElement
+ && m_listSub[iii]->getType() == exml::nodeType_element
&& m_listSub[iii]->getValue() == _name) {
if (m_listSub[iii] == nullptr) {
return nullptr;
@@ -93,7 +90,7 @@ ememory::SharedPtr<const exml::Element> exml::Element::getNamed(const std::strin
}
for (size_t iii=0; iii<m_listSub.size(); iii++) {
if( m_listSub[iii] != nullptr
- && m_listSub[iii]->getType() == exml::typeElement
+ && m_listSub[iii]->getType() == exml::nodeType_element
&& m_listSub[iii]->getValue() == _name) {
if (m_listSub[iii] == nullptr) {
return nullptr;
@@ -109,7 +106,7 @@ void exml::Element::append(const ememory::SharedPtr<exml::Node>& _node) {
EXML_ERROR("Try to set an empty node");
return;
}
- if (_node->getType() == exml::typeAttribute) {
+ if (_node->getType() == exml::nodeType_attribute) {
appendAttribute(_node->toAttribute());
return;
}
@@ -125,7 +122,7 @@ void exml::Element::append(const ememory::SharedPtr<exml::Node>& _node) {
std::string exml::Element::getText() const {
std::string res;
if (m_listSub.size() == 1) {
- if (m_listSub[0]->getType() == typeText) {
+ if (m_listSub[0]->getType() == nodeType_text) {
res = m_listSub[0]->getValue();
} else {
m_listSub[0]->iGenerate(res, 0);
@@ -149,7 +146,7 @@ bool exml::Element::iGenerate(std::string& _data, int32_t _indent) const {
if (m_listSub.size()>0) {
if( m_listSub.size() == 1
&& m_listSub[0] != nullptr
- && m_listSub[0]->getType() == exml::typeText
+ && m_listSub[0]->getType() == exml::nodeType_text
&& std::dynamic_pointer_cast<exml::Text>(m_listSub[0])->countLines() == 1) {
_data += ">";
m_listSub[0]->iGenerate(_data,0);
diff --git a/exml/Element.h b/exml/Element.h
index ac104a4..836a5f4 100644
--- a/exml/Element.h
+++ b/exml/Element.h
@@ -12,6 +12,9 @@
#include <exml/AttributeList.h>
namespace exml {
+ /**
+ * @brief Basic element Node of an XML document <YYYYY>
+ */
class Element : public exml::AttributeList {
protected:
/**
@@ -27,8 +30,12 @@ namespace exml {
};
public:
- static ememory::SharedPtr<Element> create();
- static ememory::SharedPtr<Element> create(const std::string& _value);
+ /**
+ * @brief factory of an exml::Element
+ * @param[in] _value Name of the node.
+ * @return Shared pointer on the Element
+ */
+ static ememory::SharedPtr<Element> create(const std::string& _value="");
protected:
std::vector<ememory::SharedPtr<exml::Node>> m_listSub; //!< List of subNodes
public:
@@ -56,6 +63,11 @@ namespace exml {
* @return Pointer on node.
*/
ememory::SharedPtr<Node> getNode(int32_t _id);
+ /**
+ * @brief get the Node pointer of the element id.
+ * @param[in] _id Id of the element.
+ * @return Pointer on node.
+ */
ememory::SharedPtr<const Node> getNode(int32_t _id) const;
/**
* @brief get the element casted in Element (if the node is not an element return NULL).
@@ -63,6 +75,11 @@ namespace exml {
* @return Pointer on the element or NULL.
*/
ememory::SharedPtr<Element> getElement(int32_t _id);
+ /**
+ * @brief get the element casted in Element (if the node is not an element return NULL).
+ * @param[in] _id Id of the element.
+ * @return Pointer on the element or NULL.
+ */
ememory::SharedPtr<const Element> getElement(int32_t _id) const;
/**
* @brief get an element with his name (work only with exml::Element)
@@ -70,6 +87,11 @@ namespace exml {
* @return Pointer on the element or NULL.
*/
ememory::SharedPtr<Element> getNamed(const std::string& _name);
+ /**
+ * @brief get an element with his name (work only with exml::Element)
+ * @param[in] _name Name of the element that is requested
+ * @return Pointer on the element or NULL.
+ */
ememory::SharedPtr<const Element> getNamed(const std::string& _name) const;
/**
* @brief get the internal data of the element (if the element has some sub node thay are converted in xml string == > like this it is not needed to use <![CDATA[...]]>
@@ -77,10 +99,26 @@ namespace exml {
*/
std::string getText() const;
protected:
- bool subParse(const std::string& _data, int32_t& _pos, bool _caseSensitive, exml::FilePos& _filePos, exml::Document& _doc, bool _mainNode=false);
- public: // herited function:
+ /**
+ * @brief Parse sub node string
+ * @param[in] _data all file string data
+ * @param[in,out] _pos Position to start parsing in the file and return the end of parsing
+ * @param[in] _caseSensitive Case sensitive parsing (usefull for html)
+ * @param[in] _filePos Current File position of the parsing
+ * @param[in] _doc Document base reference
+ * @param[in] _mainNode if true, this is the first root node
+ * @return true parsing is done OK
+ * @return false An error appear in the parsing
+ */
+ bool subParse(const std::string& _data,
+ int32_t& _pos,
+ bool _caseSensitive,
+ exml::FilePos& _filePos,
+ exml::Document& _doc,
+ bool _mainNode=false);
+ public:
enum nodeType getType() const override {
- return typeElement;
+ return nodeType_element;
}
bool iParse(const std::string& _data, int32_t& _pos, bool _caseSensitive, exml::FilePos& _filePos, exml::Document& _doc) override;
bool iGenerate(std::string& _data, int32_t _indent) const override;
diff --git a/exml/Node.cpp b/exml/Node.cpp
index 2f249e8..93513ae 100644
--- a/exml/Node.cpp
+++ b/exml/Node.cpp
@@ -126,7 +126,7 @@ const std::string& exml::Node::getValue() const {
}
enum exml::nodeType exml::Node::getType() const {
- return typeNode;
+ return nodeType_node;
}
ememory::SharedPtr<exml::Document> exml::Node::toDocument() {
@@ -178,26 +178,26 @@ ememory::SharedPtr<const exml::Text> exml::Node::toText() const{
}
bool exml::Node::isDocument() const {
- return getType() == exml::typeDocument;
+ return getType() == exml::nodeType_document;
}
bool exml::Node::isAttribute() const {
- return getType() == exml::typeAttribute;
+ return getType() == exml::nodeType_attribute;
}
bool exml::Node::isComment() const {
- return getType() == exml::typeComment;
+ return getType() == exml::nodeType_comment;
}
bool exml::Node::isDeclaration() const {
- return getType() == exml::typeDeclaration;
+ return getType() == exml::nodeType_declaration;
}
bool exml::Node::isElement() const {
- return getType() == exml::typeElement;
+ return getType() == exml::nodeType_element;
}
bool exml::Node::isText() const {
- return getType() == exml::typeText;
+ return getType() == exml::nodeType_text;
}
diff --git a/exml/Node.h b/exml/Node.h
index 94b34ab..e35e70c 100644
--- a/exml/Node.h
+++ b/exml/Node.h
@@ -35,15 +35,18 @@ namespace exml {
class Element;
class Text;
+ /**
+ * @brief Type of the XML elements.
+ */
enum nodeType {
- typeUnknow, //!< might be an error ...
- typeNode, //!< might be an error ...
- typeDocument, //!< all the file main access
- typeDeclaration, //!< <?xml ... ?>
- typeAttribute, //!< the <Element ATTRIBUTE="ATTRIBUTE_VALUE" />
- typeElement, //!< the <XXX> ... </XXX>
- typeComment, //!< comment node : <!-- -->
- typeText, //!< <XXX> InsideText </XXX>
+ nodeType_unknow, //!< might be an error ...
+ nodeType_node, //!< might be an error ...
+ nodeType_document, //!< all the file main access
+ nodeType_declaration, //!< <?xml ... ?>
+ nodeType_attribute, //!< the <Element ATTRIBUTE="ATTRIBUTE_VALUE" />
+ nodeType_element, //!< the <XXX> ... </XXX>
+ nodeType_comment, //!< comment node : <!-- -->
+ nodeType_text, //!< <XXX> InsideText </XXX>
};
/**
* @brief Basic main object of all xml elements.
@@ -59,7 +62,7 @@ namespace exml {
};
/**
* @brief basic element of a xml structure
- * @param[in] value of the node
+ * @param[in] _value value of the node
*/
Node(const std::string& _value);
public:
@@ -73,14 +76,15 @@ namespace exml {
* @param[in] _data data string to parse.
* @param[in,out] _pos position in the string to start parse, return the position end of parsing.
* @param[in] _caseSensitive Request a parsion of element that is not case sensitive (all element is in low case)
- * @param[in,out] file parsing position (line x col x)
+ * @param[in,out] _filePos file parsing position (line x col x)
+ * @param[in,out] _doc Base document reference
* @return false if an error occured.
*/
virtual bool iParse(const std::string& _data, int32_t& _pos, bool _caseSensitive, exml::FilePos& _filePos, exml::Document& _doc) = 0;
/**
* @brief generate a string with the tree of the xml
* @param[in,out] _data string where to add the elements
- * @param[in] current indentation of the file
+ * @param[in] _indent current indentation of the file
* @return false if an error occured.
*/
virtual bool iGenerate(std::string& _data, int32_t _indent) const;
@@ -89,6 +93,7 @@ namespace exml {
public:
/**
* @brief get the current position where the element is in the file
+ * @return The file position reference
*/
const exml::FilePos& getPos() const;
protected:
@@ -124,9 +129,11 @@ namespace exml {
*/
void drawElementParsed(char32_t _val, const exml::FilePos& _filePos) const;
/**
- * @brief check if an element or attribute is availlable (not : !"#$%&'()*+,/;<=>?@[\]^`{|}~ \n\t\r and for first char : not -.0123456789).
+ * @brief check if an element or attribute is availlable (not : !"#$%&'()*+,/;<=>?@[\]^`{|}~ \\n\\t\\r and for first char : not -.0123456789).
* @param[in] _val Value to check the conformity.
* @param[in] _firstChar True if the element check is the first char.
+ * @return true The value can be a part of attribute name
+ * @return false The value can NOT be a part of attribute name
*/
bool checkAvaillable(char32_t _val, bool _firstChar) const;
/**
diff --git a/exml/Text.cpp b/exml/Text.cpp
index 71cf91e..358ec6f 100644
--- a/exml/Text.cpp
+++ b/exml/Text.cpp
@@ -60,10 +60,6 @@ static bool isWhiteChar(char32_t _val) {
return false;
}
-ememory::SharedPtr<exml::Text> exml::Text::create() {
- return ememory::SharedPtr<exml::Text>(new exml::Text());
-}
-
ememory::SharedPtr<exml::Text> exml::Text::create(const std::string& _data) {
return ememory::SharedPtr<exml::Text>(new exml::Text(_data));
}
diff --git a/exml/Text.h b/exml/Text.h
index c3773f7..a6d18ef 100644
--- a/exml/Text.h
+++ b/exml/Text.h
@@ -11,6 +11,9 @@
#include <vector>
namespace exml {
+ /**
+ * @brief Text node interface (internal data between two balise : <XXX> ALL here </XXX>
+ */
class Text : public exml::Node {
protected:
/**
@@ -23,8 +26,12 @@ namespace exml {
*/
Text(const std::string& _data) : exml::Node(_data) { };
public:
- static ememory::SharedPtr<exml::Text> create();
- static ememory::SharedPtr<exml::Text> create(const std::string& _data);
+ /**
+ * @brief defined factory
+ * @param[in] _data Data in the Text area
+ * @return Shared pointer on the Text element
+ */
+ static ememory::SharedPtr<exml::Text> create(const std::string& _data="");
/**
* @brief count the number of line in the current text
* @return The number of lines
@@ -32,7 +39,7 @@ namespace exml {
int32_t countLines() const;
public:
enum nodeType getType() const override{
- return typeText;
+ return nodeType_text;
};
bool iParse(const std::string& _data, int32_t& _pos, bool _caseSensitive, exml::FilePos& _filePos, exml::Document& _doc) override;
bool iGenerate(std::string& _data, int32_t _indent) const override;
@@ -43,6 +50,9 @@ namespace exml {
return std::static_pointer_cast<const exml::Text>(shared_from_this());
};
};
+ /**
+ * @brief Text node interface for balise CDATA <![CDATA[*******]]>
+ */
class TextCDATA : public exml::Text {
protected:
/**
@@ -50,6 +60,10 @@ namespace exml {
*/
TextCDATA() { };
public:
+ /**
+ * @brief defined factory
+ * @return Shared pointer on the Text CDATA element
+ */
static ememory::SharedPtr<TextCDATA> create();
public:
bool iParse(const std::string& _data, int32_t& _pos, bool _caseSensitive, exml::FilePos& _filePos, exml::Document& _doc) override;