From bc141aa5f74987bdb6869b44a8b59f9937a463c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Franz=20P=C3=B6schel?= Date: Wed, 10 May 2023 17:34:44 +0200 Subject: [PATCH] Add documentation for TOML --- docs/source/backends/json.rst | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/source/backends/json.rst b/docs/source/backends/json.rst index 752497aa09..1132b8b24c 100644 --- a/docs/source/backends/json.rst +++ b/docs/source/backends/json.rst @@ -1,10 +1,10 @@ .. _backends-json: -JSON -==== +JSON/TOML +========= -openPMD supports writing to and reading from JSON files. -The JSON backend is always available. +openPMD supports writing to and reading from JSON and TOML files. +The JSON and TOML backends are always available. JSON File Format @@ -43,9 +43,17 @@ Every such attribute is itself a JSON object with two keys: * ``datatype``: A string describing the type of the value. * ``value``: The actual value of type ``datatype``. +TOML File Format +---------------- + +A TOML file uses the file ending ``.toml``. The TOML backend is chosen by creating a ``Series`` object with a filename that has this file ending. + +The TOML backend internally works with JSON datasets and converts to/from TOML during I/O. +As a result, data layout and usage are equivalent to the JSON backend. -Restrictions ------------- + +JSON Restrictions +----------------- For creation of JSON serializations (i.e. writing), the restrictions of the JSON backend are equivalent to those of the `JSON library by Niels Lohmann `_ @@ -77,6 +85,20 @@ The (keys) names ``"attributes"``, ``"data"`` and ``"datatype"`` are reserved an A parallel (i.e. MPI) implementation is *not* available. +TOML Restrictions +----------------- + +Note that the JSON datatype-specific restrictions do not automatically hold for TOML, as those affect only the representation on disk, not the internal representation. + +TOML supports most numeric types, up to long double and long long types. +Special floating point values such as NaN are also support. + +TOML does not support null values. + +The (keys) names ``"attributes"``, ``"data"`` and ``"datatype"`` are reserved and must not be used for base/mesh/particles path, records and their components. + +A parallel (i.e. MPI) implementation is *not* available. + Example -------