ADIOS2 Access Mode: Fix Dangling Ref (#1674)

* ADIOS2 Access Mode: Fix Dangling Ref

Fix GCC 13.3 warning:
```
/home/runner/work/openPMD-api/openPMD-api/src/IO/ADIOS/ADIOS2IOHandler.cpp: In member function 'adios2::Mode openPMD::ADIOS2IOHandlerImpl::adios2AccessMode(const std::string&)':
/home/runner/work/openPMD-api/openPMD-api/src/IO/ADIOS/ADIOS2IOHandler.cpp:1531:21: warning: possibly dangling reference to a temporary [-Wdangling-reference]
 1531 |         auto const &access_mode_json = m_config["engine"]["access_mode"].json();
      |                     ^~~~~~~~~~~~~~~~
/home/runner/work/openPMD-api/openPMD-api/src/IO/ADIOS/ADIOS2IOHandler.cpp:1531:78: note: the temporary was destroyed at the end of the full expression 'openPMD::json::TracingJSON::operator[](Key&&) [with Key = const char (&)[12]]("access_mode").openPMD::json::TracingJSON::json()'
 1531 |         auto const &access_mode_json = m_config["engine"]["access_mode"].json();
      |                                        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^~
```

* Solve gcc13 false positive at an API level

Introduce an explicit API call for the pattern that gcc13 dislikes.

* Non-template alternative to the previous solution

* Simplify Doxygen

---------

Co-authored-by: Franz Pöschel <[email protected]>

Author: ax3l

include/openPMD/auxiliary/JSON_internal.hpp

@@ -76,10 +76,18 @@ namespace json
          *
          * @return nlohmann::json&
          */
-        inline nlohmann::json &json()
-        {
-            return *m_positionInOriginal;
-        }
+        nlohmann::json &json();
+
+        /**
+         * @brief Access the underlying JSON value
+         *
+         * See args, first arg, used to distinguish this overload.
+         *
+         * @param path Index to some sub-expression. Shortcut for
+         *        `tracingJSON[arg1][arg2][arg3].json()`.
+         * @return nlohmann::json&
+         */
+        nlohmann::json &json(std::vector<std::string> path);
 
         template <typename Key>
         TracingJSON operator[](Key &&key);

src/IO/ADIOS/ADIOS2IOHandler.cpp

@@ -1528,7 +1528,7 @@ adios2::Mode ADIOS2IOHandlerImpl::adios2AccessMode(std::string const &fullPath)
     if (m_config.json().contains("engine") &&
         m_config["engine"].json().contains("access_mode"))
     {
-        auto const &access_mode_json = m_config["engine"]["access_mode"].json();
+        auto const &access_mode_json = m_config.json({"engine", "access_mode"});
         auto maybe_access_mode_string =
             json::asLowerCaseStringDynamic(access_mode_json);
         if (!maybe_access_mode_string.has_value())

src/IO/HDF5/ParallelHDF5IOHandler.cpp

@@ -231,7 +231,7 @@ ParallelHDF5IOHandlerImpl::ParallelHDF5IOHandlerImpl(
                     {
                         return std::nullopt;
                     }
-                    auto const &val = vfd_json_config[key].json();
+                    auto const &val = vfd_json_config.json({key});
                     if (val.is_number_integer())
                     {
                         return val.get<long long>();
@@ -250,7 +250,7 @@ ParallelHDF5IOHandlerImpl::ParallelHDF5IOHandlerImpl(
                     {
                         return std::nullopt;
                     }
-                    auto const &val = vfd_json_config[key].json();
+                    auto const &val = vfd_json_config.json({key});
                     if (auto str_val = json::asLowerCaseStringDynamic(val);
                         str_val.has_value())
                     {

src/auxiliary/JSON.cpp

@@ -60,6 +60,29 @@ TracingJSON::TracingJSON(ParsedConfig parsedConfig)
           std::move(parsedConfig.config), parsedConfig.originallySpecifiedAs}
 {}
 
+nlohmann::json &TracingJSON::json()
+{
+    return *m_positionInOriginal;
+}
+
+nlohmann::json &TracingJSON::json(std::vector<std::string> paths)
+{
+    if (paths.empty())
+    {
+        return json();
+    }
+    auto it = paths.begin();
+    auto end = paths.end();
+    nlohmann::json *res = &m_positionInOriginal->operator[](*it);
+    auto subhandle = this->operator[](*it);
+    for (++it; it != end; ++it)
+    {
+        subhandle = subhandle[*it];
+        res = &(*res)[*it];
+    }
+    return *res;
+}
+
 nlohmann::json const &TracingJSON::getShadow() const
 {
     return *m_positionInShadow;