extended readme and docs

docs/source/cpp_specifics.rst

@@ -138,6 +138,67 @@ Here is an exerpt from a ``CMakeLists.txt`` corresponding to the schema given in
 
 Implementation Details
 ----------------------
+Representation
+^^^^^^^^^^^^^^
+Mapry represents the types defined in the schema as closely as possible
+in C++. The following tables list how different types are represented in
+generated C++ code.
+
+.. list-table:: Type Mapping
+
+    *   - Mapry type
+        - C++ type
+    *   - Boolean
+        - ``bool``
+    *   - Integer
+        - ``int64_t``
+    *   - Float
+        - ``double``
+    *   - String
+        - ``std::string``
+    *   - Path
+        - ``std::filesystem::path`` or ``boost::filesystem::path``
+          (depending on ``path_as`` setting)
+    *   - Date
+        - ``struct tm`` or ``date::local_days``
+          (depending on ``datetime_library`` setting)
+    *   - Time
+        - ``struct tm`` or ``date::time_of_day<std::chrono::seconds>``
+          (depending on ``datetime_library`` setting)
+    *   - Datetime
+        - ``struct tm`` or ``date::local_seconds``
+          (depending on ``datetime_library`` setting)
+    *   - Time zone
+        - ``std::string`` or ``const date::time_zone*``
+          (depending on ``datetime_library`` setting)
+    *   - Duration
+        - ``std::chrono::nanoseconds``
+
+.. list-table:: Aggregated Types (of a generic type T)
+
+    *   - Mapry type
+        - C++ type
+    *   - Array
+        - ``std::vector<T>``
+    *   - Map
+        - ``std::map<std::string, T>``
+
+.. list-table:: Composite Types
+
+    *   - Mapry type
+        - C++ type
+    *   - Reference to an instance of class T
+        ``T*``
+    *   - Embeddable structure T
+        ``struct T``
+
+.. list-table:: Graph-Specific Structures
+
+    *   - Mapry type
+        - C++ type
+    *   - Registry of instances of class T
+        - ``std::map<std::string, T>``
+
 Numbers
 ^^^^^^^
 Mapry depends on the underlying JSON library for the representation of numbers.
@@ -221,6 +282,9 @@ Time zone
     `schema <https://github.com/Parquery/mapry/blob/master/test_cases/cpp/datetime_library_date/time_zone/schema.json>`_
     `code <https://github.com/Parquery/mapry/tree/master/test_cases/cpp/datetime_library_date/time_zone/cpp/test_generate>`_
 
+TODO: considerations about fractions of second -- does it even work? how is it represented?
+TODO: since ctime does not support it, discouraged!
+
 Duration
 ^^^^^^^^
 Mapry uses standard

docs/source/go_specifics.rst

@@ -89,6 +89,63 @@ Assuming the deserialized ``pipeline``, you serialize it back into a JSONable
 
 Implementation Details
 ----------------------
+Representation
+^^^^^^^^^^^^^^
+Go representation of Mapry types tries to be as straight-forward as possible.
+The following tables show how Mapry types are mapped to Go types in generated
+Go code.
+
+.. list-table:: Primitive Types
+
+    *   - Mapry type
+        - Go type
+    *   - Boolean
+        - ``bool``
+    *   - Integer
+        - ``int64``
+    *   - Float
+        - ``float64``
+    *   - String
+        - ``string``
+    *   - Path
+        - ``string``
+    *   - Date
+        - ``time.Time``
+    *   - Time
+        - ``time.Time``
+    *   - Datetime
+        - ``time.Time``
+    *   - Time zone
+        - ``*time.Location``
+    *   - Duration
+        - ``time.Duration``
+
+.. list-table:: Aggregated Types (of a generic type T)
+
+    *   - Mapry type
+        - Go type
+    *   - Array
+        - ``[]T``
+    *   - Map
+        - ``map[string]T``
+
+.. list-table:: Composite Types
+
+    *   - Mapry type
+        - Go type
+    *   - Reference to an instance of class T
+        ``*T``
+    *   - Embeddable structure T
+        ``struct T``
+
+.. list-table:: Graph-Specific Structures
+
+    *   - Mapry type
+        - Go type
+    *   - Registry of instances of class T
+        - ``map[string]*T``
+
+
 Numbers
 ^^^^^^^
 The standard `encoding/json <https://golang.org/pkg/encoding/json/>`_ package
@@ -134,6 +191,10 @@ Furthermore, Mapry representation of integers with 64-bits restricts the range
 of representable integers to [-2^64, 2^64 - 1] (-9,223,372,036,854,775,808 to
 9,223,372,036,854,775,807). In contrast, JSONable representation uses
 ``float64`` and hence can represent the above-mentioned wider range of
-``float64``. Due to this difference in representations, Mapry-generated code
-will raise an error if a number needs to be parsed into an integer that is out
-of 64-bit range.
+``float64`` (-1.8e+308 to 1.8e+308). Due to this difference in representations,
+Mapry-generated code will raise an error if a number needs to be parsed into an
+integer that is out of 64-bit range.
+
+TODO: strftime format restrictions
+TODO: fraction of second representation
+TODO: nanosecond representation for duration

docs/source/py_specifics.rst

@@ -102,8 +102,99 @@ from the standard library:
 
     text = json.dumps(jsonable)
 
+Implementation Details
+----------------------
+Representation
+^^^^^^^^^^^^^^
+Mapry directly maps its types to corresponding Python types. The mapping is
+presented in The following tables.
+
+.. list-table:: Primitive Types
+
+    *   - Mapry type
+        - Python type
+    *   - Boolean
+        - ``bool``
+    *   - Integer
+        - ``int``
+    *   - Float
+        - ``float``
+    *   - String
+        - ``str``
+    *   - Path
+        - ``str`` or ``pathlib.Path``
+          (dependening on ``path_as`` setting)
+    *   - Date
+        - ``datetime.date``
+    *   - Time
+        - ``datetime.time``
+    *   - Datetime
+        - ``datetime.datetime``
+    *   - Time zone
+        - ``str`` or ``datetime.tzinfo``
+          (depending on ``timezone_as`` setting)
+    *   - Duration
+        - ``datetime.timedelta``
+
+.. list-table:: Aggregated Types (of a generic type T)
+
+    *   - Mapry type
+        - Python type
+    *   - Array
+        - ``typing.List[T]``
+    *   - Map
+        - ``typing.MutableMapping[str, T]``
+
+
+.. list-table:: Graph-Specific Structures
+
+    *   - Mapry type
+        - Python type
+    *   - Registry of instances of class T
+        - ``typing.MutableMapping[str, T]``
+
+Unordered and Ordered Mappings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+When parsing a JSONable, Mapry inspects the types of the mappings to decide
+whether to keep or ignore the order of the keys. Namely, if the mapping
+is an instance of ``collections.OrderedDict``, the corresponding Mapry
+representation will also be ``collections.OrderedDict``. Analogously for an
+unordered mapping, if the JSONable mapping is given as ``dict``, Mapry will also
+represent it as ``dict``. This distinction is applied both to Mapry maps as well
+as registries of class instances.
+
+When you serialize a Mapry structure to a JSONable, it is up to you to decide
+whether you want the mappings ordered or not. This is specified with the
+``ordered`` argument. For example, consider a function generated to serialize
+the graph from :doc:`longer_example`:
+
+.. code-block:: Python
+
+    def serialize_pipeline(
+            instance: book.address.Pipeline,
+            ordered: bool = False
+    ) -> typing.MutableMapping[str, typing.Any]:
+        """
+        serializes an instance of Pipeline to a JSONable.
+
+        :param instance: the instance of Pipeline to be serialized
+        :param ordered:
+            If set, represents the instance properties and class registries
+            as a ``collections.OrderedDict``.
+            Otherwise, they are represented as a ``dict``.
+        :return: JSONable representation
+        """
+        if ordered:
+            target = (
+                collections.OrderedDict()
+            )  # type: typing.MutableMapping[str, typing.Any]
+        else:
+            target = dict()
+
+        ...
+
+        return target
 
 
 
-TODO: objects expected as instances of ``dict``, arrays as instances of ``list``.
-For example, there is no problem with collections.OrderedDict.
+TODO: there are considerations for durations, numbers and date/times with fractions

docs/source/schema.rst

@@ -84,22 +84,32 @@ The available settings are explained for each language in the
 
 Data Types
 ----------
-Mapry defines three families of data types: composite data types (*composites*),
-aggregated data types (*aggregated*) and primitive data types (*primitives*).
+Mapry defines three families of data types: primitive data types (*primitives*),
+aggregated data types (*aggregated*) and composite data types (*composites*).
 
-**Composites** represent data structures which contain **properties**. Each
-property of a composite has a name and a corresponding data type. Two types of
-composites are available in Mapry: classes and embeddable structures (see
-below).
+**Primitives** are the basic data types such as booleans and integers.
 
 **Aggregated** represent data structures which contain other data structures as
 values. Mapry provides two aggregated data types: arrays and maps.
 
-**Primitives** are the finest types of the data such as booleans or integers.
+**Composites** represent data structures which contain **properties**. Each
+property of a composite has a name and a corresponding data type. Three types of
+composites are available in Mapry: classes, embeddable structures and a graph.
+
+The following subsections describe the data types, how to specify them in the
+schema and available constraints you can impose. For implementation details
+in different languages, please consult: :doc:`cpp_specifics`,
+:doc:`go_specifics` and :doc:`py_specifics`.
 
 Class
 ^^^^^
 Composites
 with unique identity are called **classes** and can be referenced from other
 data structures.
-TODO: continue here
+
+TODO: finish go specifics
+TODO: finish py specifics
+TODO: primitive data types with options, add a section on Date/time Format,
+TODO:   add considerations about the subset and Go)
+TODO: aggregated types with considerations
+TODO: classes, embeds, graph

mapry/cpp/generate/__init__.py

@@ -69,10 +69,10 @@ def type_repr(a_type: mapry.Type, cpp: mapry.Cpp) -> str:
                 "Unhandled datetime library: {}".format(cpp.datetime_library))
 
     elif isinstance(a_type, mapry.Time):
-        if cpp.datetime_library == 'date.h':
-            return "date::time_of_day<std::chrono::seconds>"
-        elif cpp.datetime_library == 'ctime':
+        if cpp.datetime_library == 'ctime':
             return "struct tm"
+        elif cpp.datetime_library == 'date.h':
+            return "date::time_of_day<std::chrono::seconds>"
         else:
             raise NotImplementedError(
                 "Unhandled datetime library: {}".format(cpp.datetime_library))
@@ -87,10 +87,10 @@ def type_repr(a_type: mapry.Type, cpp: mapry.Cpp) -> str:
                 "Unhandled datetime library: {}".format(cpp.datetime_library))
 
     elif isinstance(a_type, mapry.TimeZone):
-        if cpp.datetime_library == 'date.h':
-            return "const date::time_zone*"
-        elif cpp.datetime_library == 'ctime':
+        if cpp.datetime_library == 'ctime':
             return "std::string"
+        elif cpp.datetime_library == 'date.h':
+            return "const date::time_zone*"
         else:
             raise NotImplementedError(
                 "Unhandled datetime library: {}".format(cpp.datetime_library))