JSON_internal.hpp

/* Copyright 2020-2025 Franz Poeschel, Axel Huebl
 *
 * This file is part of openPMD-api.
 *
 * openPMD-api is free software: you can redistribute it and/or modify
 * it under the terms of of either the GNU General Public License or
 * the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * openPMD-api is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License and the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * and the GNU Lesser General Public License along with openPMD-api.
 * If not, see <http://www.gnu.org/licenses/>.
 */
 
#pragma once
 
#include "openPMD/config.hpp"
 
#include <deque>
#include <nlohmann/json.hpp>
#include <toml.hpp>
 
#include <optional>
 
#if openPMD_HAVE_MPI
#include <mpi.h>
#endif
 
#include <memory> // std::shared_ptr
#include <utility> // std::forward
 
namespace openPMD
{
namespace json
{
    enum class SupportedLanguages
    {
        JSON,
        TOML
    };
 
    struct ParsedConfig
    {
        nlohmann::json config = nlohmann::json::object();
        SupportedLanguages originallySpecifiedAs{SupportedLanguages::JSON};
    };

    class TracingJSON
    {
    public:
        TracingJSON();
        TracingJSON(nlohmann::json, SupportedLanguages);
        TracingJSON(ParsedConfig);

        nlohmann::json &json();

        nlohmann::json &json(std::vector<std::string> path);
 
        template <typename Key>
        TracingJSON operator[](Key &&key);

        nlohmann::json const &getShadow() const;
        nlohmann::json &getShadow();

        nlohmann::json invertShadow() const;

        void declareFullyRead();
 
        SupportedLanguages originallySpecifiedAs{SupportedLanguages::JSON};
 
    private:
        std::shared_ptr<nlohmann::json> m_originalJSON;
        std::shared_ptr<nlohmann::json> m_shadow;
        nlohmann::json *m_positionInOriginal;
        nlohmann::json *m_positionInShadow;
        std::deque<std::string> m_positionForErrorMessages;
        bool m_trace = true;
 
        void invertShadow(
            nlohmann::json &result, nlohmann::json const &shadow) const;
 
        TracingJSON(
            std::shared_ptr<nlohmann::json> originalJSON,
            std::shared_ptr<nlohmann::json> shadow,
            nlohmann::json *positionInOriginal,
            nlohmann::json *positionInShadow,
            std::deque<std::string> positionForErrorMessages,
            SupportedLanguages originallySpecifiedAs,
            bool trace);
 
        void init();
        /*
         * Called upon each traced access of a location in the JSON value, along
         * with the matching subtree of the shadow.
         * This implements the `dont_warn_unused_keys` functionality.
         */
        static void init(
            nlohmann::json const &original,
            nlohmann::json &shadow,
            std::deque<std::string> &positionForErrorMessages);
    };
 
    template <typename Key>
    TracingJSON TracingJSON::operator[](Key &&key)
    {
        nlohmann::json *newPositionInOriginal =
            &m_positionInOriginal->operator[](key);
        // If accessing a leaf in the JSON tree from an object (not an array!)
        // erase the corresponding key
        static nlohmann::json nullvalue;
        nlohmann::json *newPositionInShadow = &nullvalue;
        if (m_trace && m_positionInOriginal->is_object())
        {
            newPositionInShadow = &m_positionInShadow->operator[](key);
        }
        bool traceFurther = newPositionInOriginal->is_object();
        auto new_path = m_positionForErrorMessages;
        new_path.push_back(std::forward<Key>(key));
        return TracingJSON(
            m_originalJSON,
            m_shadow,
            newPositionInOriginal,
            newPositionInShadow,
            std::move(new_path),
            originallySpecifiedAs,
            traceFurther);
    }
 
    nlohmann::json tomlToJson(toml::value const &val);
    toml::value jsonToToml(nlohmann::json const &val);

    ParsedConfig parseOptions(
        std::string const &options,
        bool considerFiles,
        bool convertLowercase = true);
 
#if openPMD_HAVE_MPI

    ParsedConfig parseOptions(
        std::string const &options,
        MPI_Comm comm,
        bool considerFiles,
        bool convertLowercase = true);
 
#endif

    nlohmann::json &lowerCase(nlohmann::json &);

    std::optional<std::string> asStringDynamic(nlohmann::json const &);

    std::optional<std::string> asLowerCaseStringDynamic(nlohmann::json const &);

    constexpr std::array<char const *, 4> backendKeys{
        "adios2", "json", "toml", "hdf5"};

    void warnGlobalUnusedOptions(TracingJSON const &config);

    nlohmann::json &merge_internal(
        nlohmann::json &defaultVal,
        nlohmann::json const &overwrite,
        bool do_prune);
 
    nlohmann::json &filterByTemplate(
        nlohmann::json &defaultVal, nlohmann::json const &positiveMask);
 
    template <typename toml_t>
    std::string format_toml(toml_t &&);
} // namespace json
} // namespace openPMD