From c5b8bbd56c02daa5aefd5d0a45803476fb687bbc Mon Sep 17 00:00:00 2001 From: Edouard DUPIN Date: Thu, 28 Apr 2016 21:48:13 +0200 Subject: [PATCH] [DOC] finish documentation --- doc/write.md | 2 +- ejson/Array.h | 5 +++ ejson/Boolean.h | 4 +++ ejson/Document.cpp | 14 ++++----- ejson/Document.h | 22 ++++++++++--- ejson/Null.h | 4 +++ ejson/Number.h | 4 +++ ejson/Object.h | 23 +++++++++++--- ejson/String.h | 4 +++ ejson/Value.h | 4 +-- ejson/internal/Array.cpp | 12 ++++++++ ejson/internal/Array.h | 25 +++++++++------ ejson/internal/Boolean.h | 9 ++++++ ejson/internal/Document.cpp | 56 +++++++++++++++++++++------------- ejson/internal/Document.h | 61 +++++++++++++++++++++++++++++-------- ejson/internal/Null.h | 7 +++++ ejson/internal/Number.h | 9 ++++++ ejson/internal/Object.h | 33 +++++++++++++++++--- ejson/internal/String.h | 9 ++++++ ejson/internal/Value.h | 5 ++- 20 files changed, 244 insertions(+), 68 deletions(-) diff --git a/doc/write.md b/doc/write.md index 99741cb..683a2f6 100644 --- a/doc/write.md +++ b/doc/write.md @@ -63,7 +63,7 @@ Object concept {#ejson_tutorial_concept} The ejson concept is to abstract the implementation of the internal system. All the element are mapped on shared memory. Then if you asign an element to an other, it is the same. You need to clone it if you want to have new standalone element. -@snippet write.cpp ejson_sample_read_clone +@snippet read.cpp ejson_sample_read_clone All example file {#ejson_tutorial_write_all} ================ diff --git a/ejson/Array.h b/ejson/Array.h index 5d96e7f..a8b2c6d 100644 --- a/ejson/Array.h +++ b/ejson/Array.h @@ -12,6 +12,9 @@ #include namespace ejson { + /** + * @brief ejson Array interface [ ... ]. + */ class Array : public ejson::Value { public: /** @@ -31,6 +34,7 @@ namespace ejson { /** * @brief Copy constructor * @param[in] _obj Object to copy + * @return Local reference on this object */ ejson::Array& operator= (const ejson::Array& _obj); public: @@ -131,6 +135,7 @@ namespace ejson { /** * @brief Remove Value with his iterator * @param[in] _it Iterator on the Value. + * @return New valid iterator on the next element or this.end() */ iterator remove(const iterator& _it); }; diff --git a/ejson/Boolean.h b/ejson/Boolean.h index 0fc04a7..f45ac89 100644 --- a/ejson/Boolean.h +++ b/ejson/Boolean.h @@ -11,6 +11,9 @@ #include namespace ejson { + /** + * @brief ejson Boolean interface: true/false. + */ class Boolean : public ejson::Value { public: /** @@ -31,6 +34,7 @@ namespace ejson { /** * @brief Copy constructor * @param[in] _obj Object to copy + * @return Local reference on this object */ ejson::Boolean& operator= (const ejson::Boolean& _obj); public: diff --git a/ejson/Document.cpp b/ejson/Document.cpp index c740536..611825a 100644 --- a/ejson/Document.cpp +++ b/ejson/Document.cpp @@ -67,20 +67,20 @@ bool ejson::Document::store(const std::string& _file) { return static_cast(m_data.get())->store(_file); } -void ejson::Document::displayErrorWhenDetected() { +void setDisplayError(bool _value){ if (m_data == nullptr) { - EJSON_ERROR("Can not displayErrorWhenDetected (nullptr) ..."); + EJSON_ERROR("Can not setDisplayError (nullptr) ..."); return; } - static_cast(m_data.get())->displayErrorWhenDetected(); + static_cast(m_data.get())->setDisplayError(_value); } -void ejson::Document::notDisplayErrorWhenDetected() { +bool getDisplayError() { if (m_data == nullptr) { - EJSON_ERROR("Can not notDisplayErrorWhenDetected (nullptr) ..."); - return; + EJSON_ERROR("Can not getDisplayError (nullptr) ..."); + return false; } - static_cast(m_data.get())->notDisplayErrorWhenDetected(); + return static_cast(m_data.get())->getDisplayError(_value); } void ejson::Document::displayError() { diff --git a/ejson/Document.h b/ejson/Document.h index 7f10c8d..05e97d4 100644 --- a/ejson/Document.h +++ b/ejson/Document.h @@ -15,6 +15,9 @@ #include namespace ejson { + /** + * @brief ejson Document interface (acces with the file and stream). + */ class Document : public ejson::Object { public: /** @@ -34,9 +37,9 @@ namespace ejson { /** * @brief Copy constructor * @param[in] _obj Object to copy + * @return Local reference on this object */ ejson::Document& operator= (const ejson::Document& _obj); - public: /** * @brief parse a string that contain an XML * @param[in] _data Data to parse @@ -65,9 +68,20 @@ namespace ejson { * @return true : Parsing is OK */ bool store(const std::string& _file); - public: - void displayErrorWhenDetected(); - void notDisplayErrorWhenDetected(); + /** + * @brief Set the display of the error when detected. + * @param[in] _value true: display error, false not display error (get it at end) + */ + void setDisplayError(bool _value); + /** + * @brief Get the display of the error status. + * @return true Display error + * @return false Does not display error (get it at end) + */ + bool getDisplayError(); + /** + * @brief Display error detected. + */ void displayError(); }; } diff --git a/ejson/Null.h b/ejson/Null.h index 1d12f92..12fdf7c 100644 --- a/ejson/Null.h +++ b/ejson/Null.h @@ -11,6 +11,9 @@ #include namespace ejson { + /** + * @brief ejson Null interface: 'null'. + */ class Null : public ejson::Value { public: /** @@ -30,6 +33,7 @@ namespace ejson { /** * @brief Copy constructor * @param[in] _obj Object to copy + * @return Local reference on this object */ ejson::Null& operator= (const ejson::Null& _obj); }; diff --git a/ejson/Number.h b/ejson/Number.h index 83ba9f1..a347739 100644 --- a/ejson/Number.h +++ b/ejson/Number.h @@ -11,6 +11,9 @@ #include namespace ejson { + /** + * @brief ejson Number interface. + */ class Number : public ejson::Value { public: /** @@ -31,6 +34,7 @@ namespace ejson { /** * @brief Copy constructor * @param[in] _obj Object to copy + * @return Local reference on this object */ ejson::Number& operator= (const ejson::Number& _obj); diff --git a/ejson/Object.h b/ejson/Object.h index 2aed29e..81ae9af 100644 --- a/ejson/Object.h +++ b/ejson/Object.h @@ -14,6 +14,9 @@ #include namespace ejson { + /** + * @brief ejson Object interface { ... }. + */ class Object : public ejson::Value { public: /** @@ -38,6 +41,7 @@ namespace ejson { /** * @brief Copy constructor * @param[in] _obj Object to copy + * @return Local reference on this object */ ejson::Object& operator= (const ejson::Object& _obj); @@ -49,11 +53,16 @@ namespace ejson { */ bool valueExist(const std::string& _name) const; /** - * @brief get the sub element with his name (no cast check) + * @brief Cet the sub element with his name (no cast check) * @param[in] _name Name of the object - * @return pointer on the element requested or nullptr if it not the corect type or does not existed + * @return Value on the element requested or a value that does not exist @ref ejson::Value::exist. */ ejson::Value operator[] (const std::string& _name); + /** + * @brief Get the const sub element with his name (no cast check) + * @param[in] _name Name of the object + * @return const Value on the element requested or a value that does not exist @ref ejson::Value::exist. + */ const ejson::Value operator[] (const std::string& _name) const; public: /** @@ -67,11 +76,16 @@ namespace ejson { */ size_t size() const; /** - * @brief get the pointer on an element reference with his ID. + * @brief Get the value on an element reference with his ID. * @param[in] _id Id of the element. - * @return nullptr if the element does not exist. + * @return Value on the element requested or a value that does not exist @ref ejson::Value::exist. */ ejson::Value operator[] (size_t _id); + /** + * @brief Get the const value on an element reference with his ID. + * @param[in] _id Id of the element. + * @return const Value on the element requested or a value that does not exist @ref ejson::Value::exist. + */ const ejson::Value operator[] (size_t _id) const; /** * @brief Get the element name (key). @@ -170,6 +184,7 @@ namespace ejson { /** * @brief Remove Value with his iterator * @param[in] _it Iterator on the Value. + * @return New valid iterator on the next element or this.end() */ iterator remove(const iterator& _it); }; diff --git a/ejson/String.h b/ejson/String.h index 41940bf..2774685 100644 --- a/ejson/String.h +++ b/ejson/String.h @@ -11,6 +11,9 @@ #include namespace ejson { + /** + * @brief ejson String interface. + */ class String : public ejson::Value { public: /** @@ -31,6 +34,7 @@ namespace ejson { /** * @brief Copy constructor * @param[in] _obj Object to copy + * @return Local reference on this object */ ejson::String& operator= (const ejson::String& _obj); public: diff --git a/ejson/Value.h b/ejson/Value.h index d5ab112..40df2a4 100644 --- a/ejson/Value.h +++ b/ejson/Value.h @@ -31,8 +31,8 @@ namespace ejson { * @brief Basic main object of all json elements. */ class Value { - friend ejson::Array; - friend ejson::Object; + friend class ejson::Array; + friend class ejson::Object; protected: ememory::SharedPtr m_data; //!< internal reference on a Value public: diff --git a/ejson/internal/Array.cpp b/ejson/internal/Array.cpp index 8028fae..2f3f36f 100644 --- a/ejson/internal/Array.cpp +++ b/ejson/internal/Array.cpp @@ -208,6 +208,18 @@ bool ejson::internal::Array::iGenerate(std::string& _data, size_t _indent) const return true; } +size_t ejson::internal::Array::size() const { + return m_value.size(); +} + +ememory::SharedPtr ejson::internal::Array::get(size_t _id) { + return m_value[_id]; +} + +const ememory::SharedPtr ejson::internal::Array::get(size_t _id) const { + return m_value[_id]; +} + bool ejson::internal::Array::add(ememory::SharedPtr _element) { if (_element == nullptr) { EJSON_ERROR("Request add on an nullptr pointer"); diff --git a/ejson/internal/Array.h b/ejson/internal/Array.h index 8fac474..14c8ae8 100644 --- a/ejson/internal/Array.h +++ b/ejson/internal/Array.h @@ -12,6 +12,9 @@ namespace ejson { namespace internal { + /** + * @brief ejson Array internal data implementation. + */ class Array : public ejson::internal::Value { protected: /** @@ -21,6 +24,10 @@ namespace ejson { m_type = ejson::valueType::array; } public: + /** + * @brief Create factory on the ejson::internal::Array + * @return A SharedPtr on the Array value + */ static ememory::SharedPtr create(); private: std::vector > m_value; //!< vector of sub elements @@ -29,21 +36,19 @@ namespace ejson { * @brief get the number of sub element in the current one * @return the Number of stored element */ - size_t size() const { - return m_value.size(); - } + size_t size() const; /** * @brief get the pointer on an element reference with his ID. * @param[in] _id Id of the element. * @return nullptr if the element does not exist. */ - ememory::SharedPtr get(size_t _id) { - return m_value[_id]; - } - //! @previous - const ememory::SharedPtr get(size_t _id) const{ - return m_value[_id]; - } + ememory::SharedPtr get(size_t _id); + /** + * @brief get the const pointer on an element reference with his ID. + * @param[in] _id Id of the element. + * @return nullptr if the element does not exist. + */ + const ememory::SharedPtr get(size_t _id) const; /** * @brief add an element on the array. * @param[in] _element element to add. diff --git a/ejson/internal/Boolean.h b/ejson/internal/Boolean.h index c0a33e0..a6f8d33 100644 --- a/ejson/internal/Boolean.h +++ b/ejson/internal/Boolean.h @@ -12,13 +12,22 @@ namespace ejson { namespace internal { + /** + * @brief ejson Boolean internal data implementation. + */ class Boolean : public ejson::internal::Value { protected: /** * @brief basic element of a xml structure + * @param[in] _value Value to set on the Element */ Boolean(bool _value=false); public: + /** + * @brief Create factory on the ejson::internal::Boolean + * @param[in] _value Value to set on the ejson::Value + * @return A SharedPtr on the Boolean value + */ static ememory::SharedPtr create(bool _value=false); protected: bool m_value; //!< value of the node diff --git a/ejson/internal/Document.cpp b/ejson/internal/Document.cpp index 9289303..eeeb63c 100644 --- a/ejson/internal/Document.cpp +++ b/ejson/internal/Document.cpp @@ -119,28 +119,6 @@ static std::string createPosPointer(const std::string& _line, size_t _pos) { return out; } -void ejson::internal::Document::displayError() { - if (m_comment.size() == 0) { - EJSON_ERROR("No error detected ???"); - return; - } - EJSON_ERROR(m_filePos << " " << m_comment << "\n" - << m_Line << "\n" - << createPosPointer(m_Line, m_filePos.getCol()) ); - #ifdef ENABLE_CRITICAL_WHEN_ERROR - EJSON_CRITICAL("detect error"); - #endif -} - -void ejson::internal::Document::createError(const std::string& _data, size_t _pos, const ejson::FilePos& _filePos, const std::string& _comment) { - m_comment = _comment; - m_Line = etk::extract_line(_data, _pos); - m_filePos = _filePos; - if (true == m_writeErrorWhenDetexted) { - displayError(); - } -} - bool ejson::internal::Document::iParse(const std::string& _data, size_t& _pos, ejson::FilePos& _filePos, ejson::internal::Document& _doc) { EJSON_PARSE_ELEMENT("start parse : 'Document' "); bool haveMainNode=false; @@ -194,3 +172,37 @@ bool ejson::internal::Document::iParse(const std::string& _data, size_t& _pos, e return true; } + +void ejson::internal::Document::setDisplayError(bool _value) { + m_writeErrorWhenDetexted = _value; +} + +bool ejson::internal::Document::getDisplayError() { + return m_writeErrorWhenDetexted; +} + +void ejson::internal::Document::displayError() { + if (m_comment.size() == 0) { + EJSON_INFO("No error detected ???"); + return; + } + EJSON_ERROR(m_filePos << " " << m_comment << "\n" + << m_Line << "\n" + << createPosPointer(m_Line, m_filePos.getCol()) ); + #ifdef ENABLE_CRITICAL_WHEN_ERROR + EJSON_CRITICAL("detect error"); + #endif +} + +void ejson::internal::Document::createError(const std::string& _data, + size_t _pos, + const ejson::FilePos& _filePos, + const std::string& _comment) { + m_comment = _comment; + m_Line = etk::extract_line(_data, _pos); + m_filePos = _filePos; + if (m_writeErrorWhenDetexted == true) { + displayError(); + } +} + diff --git a/ejson/internal/Document.h b/ejson/internal/Document.h index 178342c..af0325d 100644 --- a/ejson/internal/Document.h +++ b/ejson/internal/Document.h @@ -16,12 +16,19 @@ namespace ejson { namespace internal { + /** + * @brief ejson Document internal data implementation. + */ class Document : public ejson::internal::Object { public: /** * @brief Constructor */ Document(); + /** + * @brief Create factory on the ejson::internal::Document + * @return A SharedPtr on the Document value + */ static ememory::SharedPtr create(); public: /** @@ -53,27 +60,57 @@ namespace ejson { */ bool store(const std::string& _file); private: - bool m_writeErrorWhenDetexted; - std::string m_comment; - std::string m_Line; - ejson::FilePos m_filePos; + bool m_writeErrorWhenDetexted; //!< Flag to know if we need to display error when they are detected + std::string m_comment; //!< Error comment + std::string m_Line; //!< Line with the error + ejson::FilePos m_filePos; //!< Position in the file of the error public: - void displayErrorWhenDetected() { - m_writeErrorWhenDetexted=true; + /** + * @brief Set the display of the error when detected. + * @param[in] _value true: display error, false not display error (get it at end) + */ + void setDisplayError(bool _value) { + m_writeErrorWhenDetexted = _value; }; - void notDisplayErrorWhenDetected() { - m_writeErrorWhenDetexted=false; - }; - - void createError(const std::string& _data, size_t _pos, const ejson::FilePos& _filePos, const std::string& _comment); + /** + * @brief Get the display of the error status. + * @return true Display error + * @return false Does not display error (get it at end) + */ + bool getDisplayError(); + /** + * @brief Display error detected. + */ void displayError(); + /** + * @brief When parsing a subParser create an error that might be write later + * @param[in] _data Wall File or stream + * @param[in] _pos Position in the file (in nb char) + * @param[in] _filePos Position in x/y in the file + * @param[in] _comment Help coment + */ + void createError(const std::string& _data, + size_t _pos, + const ejson::FilePos& _filePos, + const std::string& _comment); public: - bool iParse(const std::string& _data, size_t& _pos, ejson::FilePos& _filePos, ejson::internal::Document& _doc) override; + bool iParse(const std::string& _data, + size_t& _pos, + ejson::FilePos& _filePos, + ejson::internal::Document& _doc) override; bool iGenerate(std::string& _data, size_t _indent) const override; }; } } +/** + * @brief Automatic create error on the basic Document object + * @param[in] doc Document reference + * @param[in] data main string parsed + * @param[in] pos Position in the file + * @param[in] filePos position in linre row in the file + * @param[in] comment Comment of the error find + */ #define EJSON_CREATE_ERROR(doc,data,pos,filePos,comment) \ do { \ EJSON_ERROR(comment); \ diff --git a/ejson/internal/Null.h b/ejson/internal/Null.h index 1931e83..d7dd847 100644 --- a/ejson/internal/Null.h +++ b/ejson/internal/Null.h @@ -12,6 +12,9 @@ namespace ejson { namespace internal { + /** + * @brief ejson Null internal data implementation. + */ class Null : public ejson::internal::Value { protected: /** @@ -19,6 +22,10 @@ namespace ejson { */ Null(); public: + /** + * @brief Create factory on the ejson::internal::Null + * @return A SharedPtr on the Null value + */ static ememory::SharedPtr create(); public: bool iParse(const std::string& _data, size_t& _pos, ejson::FilePos& _filePos, ejson::internal::Document& _doc) override; diff --git a/ejson/internal/Number.h b/ejson/internal/Number.h index 993d585..b413a0f 100644 --- a/ejson/internal/Number.h +++ b/ejson/internal/Number.h @@ -12,13 +12,22 @@ namespace ejson { namespace internal { + /** + * @brief ejson Number internal data implementation. + */ class Number : public ejson::internal::Value { protected: /** * @brief basic element of a xml structure + * @param[in] _value Value to set on the ejson::Value */ Number(double _value=0.0); public: + /** + * @brief Create factory on the ejson::internal::Number + * @param[in] _value Value to set on the ejson::Value + * @return A SharedPtr on the Number value + */ static ememory::SharedPtr create(double _value=0.0); protected: double m_value; //!< value of the node diff --git a/ejson/internal/Object.h b/ejson/internal/Object.h index f040a43..eab73e5 100644 --- a/ejson/internal/Object.h +++ b/ejson/internal/Object.h @@ -14,6 +14,9 @@ namespace ejson { namespace internal { + /** + * @brief ejson Object internal data implementation. + */ class Object : public ejson::internal::Value { protected: /** @@ -23,7 +26,16 @@ namespace ejson { m_type = ejson::valueType::object; }; public: + /** + * @brief Create factory on the ejson::internal::Object + * @return A SharedPtr on the Object value + */ static ememory::SharedPtr create(); + /** + * @brief Create factory on the ejson::internal::Object + * @param[in] _data Json stream to parse and interprete + * @return A SharedPtr on the Object value + */ static ememory::SharedPtr create(const std::string& _data); protected: etk::Hash > m_value; //!< value of the node (for element this is the name, for text it is the inside text ...) @@ -40,7 +52,11 @@ namespace ejson { * @return pointer on the element requested or nullptr if it not the corect type or does not existed */ ememory::SharedPtr get(const std::string& _name); - //! @previous + /** + * @brief get the sub element with his name (no cast check) + * @param[in] _name name of the object + * @return pointer on the element requested or nullptr if it not the corect type or does not existed + */ const ememory::SharedPtr get(const std::string& _name) const; public: /** @@ -89,16 +105,23 @@ namespace ejson { * @param[in] _id Id of the element. */ void remove(size_t _id); + /** + * @brief Clone the current object in an other Object + * @param[in] _obj Other object ot overwride + * @return true The clone has been corectly done, false otherwise + */ + bool cloneIn(const ememory::SharedPtr& _obj) const; + /** + * @brief Clone the current object + * @return A new object that has been clone + */ + ememory::SharedPtr cloneObj() const; public: bool iParse(const std::string& _data, size_t& _pos, ejson::FilePos& _filePos, ejson::internal::Document& _doc) override; bool iGenerate(std::string& _data, size_t _indent) const override; void clear() override; bool transfertIn(ememory::SharedPtr _obj) override; ememory::SharedPtr clone() const override; - - - bool cloneIn(const ememory::SharedPtr& _obj) const; - ememory::SharedPtr cloneObj() const; }; } } diff --git a/ejson/internal/String.h b/ejson/internal/String.h index 089d932..b85f000 100644 --- a/ejson/internal/String.h +++ b/ejson/internal/String.h @@ -12,13 +12,22 @@ namespace ejson { namespace internal { + /** + * @brief ejson String internal data implementation. + */ class String : public ejson::internal::Value { protected: /** * @brief basic element of a xml structure + * @param[in] _value Value to set on the ejson::Value */ String(const std::string& _value=""); public: + /** + * @brief Create factory on the ejson::internal::String + * @param[in] _value Value to set on the ejson::Value + * @return A SharedPtr on the String value + */ static ememory::SharedPtr create(const std::string& _value=""); protected: std::string m_value; //!< value of the node (for element this is the name, for text it is the inside text ...) diff --git a/ejson/internal/Value.h b/ejson/internal/Value.h index be0c560..ecceacb 100644 --- a/ejson/internal/Value.h +++ b/ejson/internal/Value.h @@ -27,6 +27,9 @@ namespace ejson { #else #define EJSON_PARSE_ATTRIBUTE EJSON_DEBUG #endif + /** + * @brief ejson internal data implementation (not for external user). + */ namespace internal { class Document; class Array; @@ -36,7 +39,7 @@ namespace ejson { class Number; class String; /** - * @brief Basic main object of all json elements. + * @brief Basic main object of all json data. */ class Value : public ememory::EnableSharedFromThis { protected: