More schema serialization changes:

* add schema serialization helper macros
* const correctness; add schema ser to more classes
* Import CSchemaArchive from mrpt-web. From: https://github.com/MRPT/mrpt-web by @rachit173 for GSoC2018.
* Add jsoncpp as optional dep
* add json serialization unit test
* jsoncpp: fix use of static lib if only one present
* better JSON archive integration
* real JSON unit test for serializing
* attempt at deserializing unit test
* Ended API for read/write scheme archives to streams
* Add example
* Impl sch serializa for matrices; add serialization docs
* doxygen TOC in doc pages

CMakeLists.txt

@@ -292,6 +292,7 @@ include(cmakemodules/script_pcap.cmake REQUIRED)        # Check for the libpcap
 include(cmakemodules/script_vtk.cmake REQUIRED)         # Check for VTK
 include(cmakemodules/script_clang_tidy.cmake REQUIRED)  # Clang tidy
 include(cmakemodules/script_cvd.cmake REQUIRED)         # Check for VTK
+include(cmakemodules/script_jsoncpp.cmake REQUIRED)     # Check for jsoncpp
 
 # ---------------------------------------------------------------------------
 #			OPTIONS

cmakemodules/DefineExamples.cmake

@@ -70,6 +70,7 @@ IF(BUILD_EXAMPLES)
 	# === Depending on: serialization, io ===
 	SET(LIST_EXAMPLES_IN_THIS_DIR
 		# ----
+		serialization_json_example
 		serialization_stl
 		serialization_variant_example
 		# ----

cmakemodules/script_jsoncpp.cmake

@@ -0,0 +1,15 @@
+
+SET(CMAKE_MRPT_HAS_JSONCPP 0)
+SET(CMAKE_MRPT_HAS_JSONCPP_SYSTEM 0)
+
+OPTION(DISABLE_JSONCPP "Forces NOT using JSONCPP, even if it could be found by CMake" "OFF")
+MARK_AS_ADVANCED(DISABLE_JSONCPP)
+
+IF(NOT DISABLE_JSONCPP)
+	find_package(jsoncpp QUIET)
+	if(jsoncpp_FOUND)
+		# cmake imported target: "jsoncpp_lib"
+		SET(CMAKE_MRPT_HAS_JSONCPP 1)
+		SET(CMAKE_MRPT_HAS_JSONCPP_SYSTEM 1)
+	endif()
+ENDIF()

cmakemodules/script_show_final_summary.cmake

@@ -117,6 +117,7 @@ MESSAGE(STATUS " ______________________ OPTIONAL LIBRARIES _____________________
 SHOW_CONFIG_LINE_SYSTEM("Assimp (3D models)                  " CMAKE_MRPT_HAS_ASSIMP "[Version: ${ASSIMP_VERSION}]")
 SHOW_CONFIG_LINE_SYSTEM("ffmpeg libs (Video streaming)       " CMAKE_MRPT_HAS_FFMPEG "[avcodec ${LIBAVCODEC_VERSION}, avutil ${LIBAVUTIL_VERSION}, avformat ${LIBAVFORMAT_VERSION}]")
 SHOW_CONFIG_LINE_SYSTEM("gtest (Google unit testing library) " CMAKE_MRPT_HAS_GTEST )
+SHOW_CONFIG_LINE_SYSTEM("jsoncpp (JSON format serialization) " CMAKE_MRPT_HAS_JSONCPP "[Version: ${jsoncpp_VERSION}]")
 SHOW_CONFIG_LINE_SYSTEM("libjpeg (jpeg)                      " CMAKE_MRPT_HAS_JPEG)
 SHOW_CONFIG_LINE_SYSTEM("liblas (ASPRS LAS LiDAR format)     " CMAKE_MRPT_HAS_LIBLAS)
 SHOW_CONFIG_LINE       ("mexplus                             " CMAKE_MRPT_HAS_MATLAB)

doc/doxygen-pages/lib_mrpt_rtti.h

@@ -5,29 +5,33 @@
    | Copyright (c) 2005-2018, Individual contributors, see AUTHORS file        |
    | See: http://www.mrpt.org/Authors - All rights reserved.                   |
    | Released under BSD License. See details in http://www.mrpt.org/License    |
-   +---------------------------------------------------------------------------+ */
+   +---------------------------------------------------------------------------+
+ */
 
 /** \defgroup mrpt_rtti_grp [mrpt-rtti]
 
-Runtime Type Information (RTTI) library, providing compiler-independent class registry, class factory, and inheritance information.
+Runtime Type Information (RTTI) library, providing compiler-independent class
+registry, class factory, and inheritance information.
 
-<small> <a href="index.html#libs">Back to list of all libraries</a> | <a href="modules.html" >See all modules</a> </small>
-<br>
+<small> <a href="index.html#libs">Back to list of all libraries</a> | <a
+href="modules.html" >See all modules</a> </small> <br>
 
 # Library `mrpt-rtti`
 <small> [New in MRPT 2.0.0] </small>
 
 This library is part of MRPT and can be installed in Debian-based systems with:
 
-        sudo apt install libmrpt-rtti-dev
+		sudo apt install libmrpt-rtti-dev
+
+[TOC]
 
 Any class with RTTI support has to be derived from mrpt::rtti::CObject, either
 directly or via a hierarchy of inheriting classes.
 Class factory by name enables deserialization of polymorphic classes in the
 library \ref mrpt_serialization_grp.
 
-All classes defined in each MRPT module are automatically registered when loading
-the module (if dynamically linked).
+All classes defined in each MRPT module are automatically registered when
+loading the module (if dynamically linked).
 
 ## Example #1: defining new user classes
 

doc/doxygen-pages/lib_mrpt_serialization.h

@@ -5,66 +5,110 @@
    | Copyright (c) 2005-2018, Individual contributors, see AUTHORS file        |
    | See: http://www.mrpt.org/Authors - All rights reserved.                   |
    | Released under BSD License. See details in http://www.mrpt.org/License    |
-   +---------------------------------------------------------------------------+ */
+   +---------------------------------------------------------------------------+
+ */
 
 /** \defgroup mrpt_serialization_grp [mrpt-serialization]
 
+\page mrpt_serialization_grp [mrpt-serialization]
+
 Serialization (marshalling) portable library for C++ objects persistence.
 
-<small> <a href="index.html#libs">Back to list of all libraries</a> | <a href="modules.html" >See all modules</a> </small>
-<br>
+<small> <a href="index.html#libs">Back to list of all libraries</a> | <a
+href="modules.html" >See all modules</a> </small> <br>
 
 # Library `mrpt-serialization`
 <small> [New in MRPT 2.0.0] </small>
 
 This library is part of MRPT and can be installed in Debian-based systems with:
 
-        sudo apt install libmrpt-serialization-dev
+		sudo apt install libmrpt-serialization-dev
+
+[TOC]
+
+## Binary serialization (most efficient)
 
 Main classes and concepts associated with this library:
 - mrpt::serialization::CArchive provides:
-	- An abstraction of I/O streams (e.g. std::stream's, MRPT's mrpt::io::CStream's, sockets)
-	- A portable API (endianness aware) for serialization of data structures on those streams.
+	- An abstraction of I/O streams (e.g. std::stream's, MRPT's
+mrpt::io::CStream's, sockets)
+	- A portable API (endianness aware) for serialization of data structures on
+those streams.
 - mrpt::serialization::CSerializable provides:
 	- A generic way to define persistent C++ classes.
-	- Versioning: if class fields are added or removed, you'll still be able to read old data files.
+	- Versioning: if class fields are added or removed, you'll still be able to
+read old data files.
 
-Serialization happens via `archive << object` operators in all cases but, underneath, two mechanisms are provided:
-- **Direct overloading of the `<<`/`>>` operators** for mrpt::serialization::CArchive objects.
+Serialization happens via `archive << object` operators in all cases but,
+underneath, two mechanisms are provided:
+- **Direct overloading of the `<<`/`>>` operators** for
+mrpt::serialization::CArchive objects.
 	- Pros: concise declaration (just the two operator functions).
-	- Cons: Cannot handle versioning. Cannot deserialize unknown types (i.e. no support for class factory).
+	- Cons: Cannot handle versioning. Cannot deserialize unknown types (i.e. no
+support for class factory).
 - **Via mrpt::serialization::CSerializable** and associated macros:
 	- Pros: Allows polymorphic classes to be (de)serialized. Allows versioning.
-	- Cons: Requires adding macros to class definitions. Requires **registering** the class with \ref mrpt_rtti_grp.
+	- Cons: Requires adding macros to class definitions. Requires
+**registering** the class with \ref mrpt_rtti_grp.
 
-Support for STL containers is provided via this "direct mechanism" for the container structure itself, but contained
-elements can use any of the serialization mechanisms.
+Support for STL containers is provided via this "direct mechanism" for the
+container structure itself, but contained elements can use any of the
+serialization mechanisms.
 
-Serializing `shared_ptr<T>` is supported for any arbitrary type `T`. It is legal to serialize an empty (`nullptr`)
-smart pointer; an empty pointer will be read back. Polymorphic classes can be also writen and read, although reading
-a smart pointer to a polymorphic base class is only supported for classes derived from MRPT's CSerializable, since
-that operation requires registering types in a class factory (see \a mrpt_rtti_grp and mrpt::serialization::CSerializable).
+Serializing `shared_ptr<T>` is supported for any arbitrary type `T`. It is legal
+to serialize an empty (`nullptr`) smart pointer; an empty pointer will be read
+back. Polymorphic classes can be also writen and read, although reading a smart
+pointer to a polymorphic base class is only supported for classes derived from
+MRPT's CSerializable, since that operation requires registering types in a class
+factory (see \a mrpt_rtti_grp and mrpt::serialization::CSerializable).
 
-## Example #1: serialize STL container via MRPT `CStream`s
+### Example #1: serialize STL container via MRPT `CStream`s
 
 See: \ref serialization_stl/test.cpp
 \snippet serialization_stl/test.cpp example
 Output:
 \include serialization_stl/console.out
 
-## Example #2: serialize STL container via `std::ostream` and `std::istream`
+### Example #2: serialize STL container via `std::ostream` and `std::istream`
 
 See: \ref serialization_stl/test.cpp
 \snippet serialization_stl/test.cpp example_stdio
 Output:
 \include serialization_stl/console.out
 
-## Example #3: Serialization of existing MRPT classes
+### Example #3: Serialization of existing MRPT classes
 
 Write me!
 
-## Example #4: Polymorphic serialization of user classes
+### Example #4: Polymorphic serialization of user classes
 
 Write me!
 
+
+## Schema (plain-text) serialization (human readable)
+
+An alternative mechanism to serialize objects is based on
+mrpt::serialization::CSchemeArchive and allow objects to be (de)serialized in
+plain text formats like XML, JSON, YAML, etc.
+For now (Aug 2018) only JSON is implemented.
+
+### Example #1: Easy JSON serialization
+
+This method only requires having MRPT built against jsoncpp, but does not
+enforce the user to also depend on that library.
+
+See: \ref serialization_json_example/test.cpp
+\snippet serialization_json_example/test.cpp example
+Output:
+\include serialization_json_example/console.out
+
+### Example #2: JSON serialization with full access to jsoncpp
+
+If you want to have full control on the JSON formatting and other details,
+you may directly depend on jsoncpp and use the following, template-based access
+to MRPT serialization:
+
+See: \ref serialization_json_example/test.cpp
+\snippet serialization_json_example/test.cpp example_raw
+
 */

doc/doxygen-pages/lib_mrpt_typemeta.h

@@ -5,28 +5,33 @@
    | Copyright (c) 2005-2018, Individual contributors, see AUTHORS file        |
    | See: http://www.mrpt.org/Authors - All rights reserved.                   |
    | Released under BSD License. See details in http://www.mrpt.org/License    |
-   +---------------------------------------------------------------------------+ */
+   +---------------------------------------------------------------------------+
+ */
 
 /** \defgroup mrpt_typemeta_grp [mrpt-typemeta]
 
-Metaprogramming header-only library to obtain `constexpr` textual string representations of enum types and type names, including smart pointers and complex STL compound types.
+Metaprogramming header-only library to obtain `constexpr` textual string
+representations of enum types and type names, including smart pointers and
+complex STL compound types.
 
-<small> <a href="index.html#libs">Back to list of all libraries</a> | <a href="modules.html" >See all modules</a> </small>
-<br>
+<small> <a href="index.html#libs">Back to list of all libraries</a> | <a
+href="modules.html" >See all modules</a> </small> <br>
 
 # Library `mrpt-typemeta`
 <small> [New in MRPT 2.0.0] </small>
 
 This library is part of MRPT but has no dependencies, so it can be installed
 in Debian-based systems with:
 
-        sudo apt install libmrpt-typemeta-dev
+		sudo apt install libmrpt-typemeta-dev
+
+[TOC]
 
 ## Example #1: compile-time type/struct/class names to strings
-Use mrpt::typemeta::TTypeName to extract a `constexpr` string with a compiler-independent
-representation of arbitrarily-complex types and STL containers.
-Note that creating objects from a run-time string representation of its type
-is handled in a different library (\ref mrpt_serialization_grp).
+Use mrpt::typemeta::TTypeName to extract a `constexpr` string with a
+compiler-independent representation of arbitrarily-complex types and STL
+containers. Note that creating objects from a run-time string representation of
+its type is handled in a different library (\ref mrpt_serialization_grp).
 
 See: \ref typemeta_TTypeName/test.cpp
 \snippet typemeta_TTypeName/test.cpp example typename

doc/doxygen_project.txt.in

@@ -301,6 +301,8 @@ MARKDOWN_SUPPORT       = YES
 
 AUTOLINK_SUPPORT       = YES
 
+TOC_INCLUDE_HEADINGS   = 3
+
 # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
 # to include (a tag file for) the STL sources as input, then you should set this
 # tag to YES in order to let doxygen match functions declarations and
@@ -1137,6 +1139,7 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
+HTML_EXTRA_STYLESHEET  =
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note

libs/math/include/mrpt/math/CMatrix.h

@@ -22,25 +22,26 @@ namespace mrpt::math
 class CMatrix : public mrpt::serialization::CSerializable, public CMatrixFloat
 {
 	DEFINE_SERIALIZABLE(CMatrix)
+	DEFINE_SCHEMA_SERIALIZABLE()
 
    public:
 	/** Constructor  */
 	CMatrix() : CMatrixFloat(1, 1) {}
 	/** Constructor  */
 	CMatrix(size_t row, size_t col) : CMatrixFloat(row, col) {}
 	/** Copy constructor
-	  */
+	 */
 	CMatrix(const CMatrixFloat& m) : CMatrixFloat(m) {}
 	/** Copy constructor
-	  */
+	 */
 	CMatrix(const CMatrixTemplateNumeric<double>& m) : CMatrixFloat(0, 0)
 	{
 		*this = m.eval().cast<float>();
 	}
 	MRPT_MATRIX_CONSTRUCTORS_FROM_POSES(CMatrix)
 
 	/** Assignment operator for float matrixes
-	*/
+	 */
 	template <class OTHERMAT>
 	inline CMatrix& operator=(const OTHERMAT& m)
 	{
@@ -66,5 +67,4 @@ class CMatrix : public mrpt::serialization::CSerializable, public CMatrixFloat
 mrpt::serialization::CArchive& operator>>(
 	mrpt::serialization::CArchive& in, CMatrix::Ptr& pObj);
 
-}
-
+}  // namespace mrpt::math

libs/math/include/mrpt/math/CMatrixD.h

@@ -23,6 +23,7 @@ class CMatrixD : public mrpt::serialization::CSerializable,
 				 public CMatrixTemplateNumeric<double>
 {
 	DEFINE_SERIALIZABLE(CMatrixD)
+	DEFINE_SCHEMA_SERIALIZABLE()
    public:
 	/** Constructor */
 	CMatrixD() : CMatrixTemplateNumeric<double>(1, 1) {}
@@ -63,5 +64,4 @@ class CMatrixD : public mrpt::serialization::CSerializable,
 mrpt::serialization::CArchive& operator>>(
 	mrpt::serialization::CArchive& in, CMatrixD::Ptr& pObj);
 
-}
-
+}  // namespace mrpt::math

libs/math/src/CMatrix.cpp

@@ -12,6 +12,7 @@
 #include <mrpt/math/CMatrix.h>
 #include <mrpt/math/lightweight_geom_data.h>
 #include <mrpt/serialization/CArchive.h>
+#include <mrpt/serialization/CSchemeArchiveBase.h>
 
 using namespace mrpt;
 using namespace mrpt::math;
@@ -53,3 +54,28 @@ void CMatrix::serializeFrom(mrpt::serialization::CArchive& in, uint8_t version)
 			MRPT_THROW_UNKNOWN_SERIALIZATION_VERSION(version)
 	};
 }
+
+/** Serialize CSerializable Object to CSchemeArchiveBase derived object*/
+void CMatrix::serializeTo(mrpt::serialization::CSchemeArchiveBase& out) const
+{
+	SCHEMA_SERIALIZE_DATATYPE_VERSION(1);
+	out["nrows"] = this->rows();
+	out["ncols"] = this->cols();
+	out["data"] = this->inMatlabFormat();
+}
+/** Serialize CSchemeArchiveBase derived object to CSerializable Object*/
+void CMatrix::serializeFrom(mrpt::serialization::CSchemeArchiveBase& in)
+{
+	uint8_t version;
+	SCHEMA_DESERIALIZE_DATATYPE_VERSION();
+	switch (version)
+	{
+		case 1:
+		{
+			this->fromMatlabStringFormat(static_cast<std::string>(in["data"]));
+		}
+		break;
+		default:
+			MRPT_THROW_UNKNOWN_SERIALIZATION_VERSION(version)
+	}
+}

libs/math/src/CMatrixD.cpp

@@ -12,6 +12,7 @@
 #include <mrpt/math/CMatrixD.h>
 #include <mrpt/math/lightweight_geom_data.h>
 #include <mrpt/serialization/CArchive.h>
+#include <mrpt/serialization/CSchemeArchiveBase.h>
 
 using namespace mrpt;
 using namespace mrpt::math;
@@ -51,3 +52,28 @@ void CMatrixD::serializeFrom(mrpt::serialization::CArchive& in, uint8_t version)
 			MRPT_THROW_UNKNOWN_SERIALIZATION_VERSION(version)
 	};
 }
+
+/** Serialize CSerializable Object to CSchemeArchiveBase derived object*/
+void CMatrixD::serializeTo(mrpt::serialization::CSchemeArchiveBase& out) const
+{
+	SCHEMA_SERIALIZE_DATATYPE_VERSION(1);
+	out["nrows"] = this->rows();
+	out["ncols"] = this->cols();
+	out["data"] = this->inMatlabFormat();
+}
+/** Serialize CSchemeArchiveBase derived object to CSerializable Object*/
+void CMatrixD::serializeFrom(mrpt::serialization::CSchemeArchiveBase& in)
+{
+	uint8_t version;
+	SCHEMA_DESERIALIZE_DATATYPE_VERSION();
+	switch (version)
+	{
+		case 1:
+		{
+			this->fromMatlabStringFormat(static_cast<std::string>(in["data"]));
+		}
+		break;
+		default:
+			MRPT_THROW_UNKNOWN_SERIALIZATION_VERSION(version)
+	}
+}