vpJsonArgumentParser.h

/*
 * ViSP, open source Visual Servoing Platform software.
 * Copyright (C) 2005 - 2025 by Inria. All rights reserved.
 *
 * This software is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * See the file LICENSE.txt at the root directory of this source
 * distribution for additional information about the GNU GPL.
 *
 * For using ViSP with software that can not be combined with the GNU
 * GPL, please contact Inria about acquiring a ViSP Professional
 * Edition License.
 *
 * See https://visp.inria.fr for more information.
 *
 * This software was developed at:
 * Inria Rennes - Bretagne Atlantique
 * Campus Universitaire de Beaulieu
 * 35042 Rennes Cedex
 * France
 *
 * If you have questions regarding the use of this file, please contact
 * Inria at visp@inria.fr
 *
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 *
 * Description:
 * An argument parser that can both use JSON files and command line arguments as inputs.
 */
 
#ifndef VP_JSON_ARGUMENT_PARSER_H
#define VP_JSON_ARGUMENT_PARSER_H
 
#include <visp3/core/vpConfig.h>
 
#if defined(VISP_HAVE_NLOHMANN_JSON)
#include VISP_NLOHMANN_JSON(json.hpp)
#include <visp3/core/vpException.h>
#include <sstream>
 

 
template<typename T>
nlohmann::json convertCommandLineArgument(const std::string &arg)
{
  nlohmann::json j = nlohmann::json::parse(arg);
  return j;
}

template<>
nlohmann::json convertCommandLineArgument<std::string>(const std::string &arg)
{
  nlohmann::json j = arg;
  return j;
}
 
BEGIN_VISP_NAMESPACE

class VISP_EXPORT vpJsonArgumentParser
{
public:
 
  enum vpJsonArgumentType
  {
    WITH_FIELD = 0,
    FLAG = 1
  };

  vpJsonArgumentParser(const std::string &description, const std::string &jsonFileArgumentName, const std::string &nestSeparator);

  std::string help() const;

  template<typename T>
  vpJsonArgumentParser &addArgument(const std::string &name, T &parameter, const bool required = true, const std::string &help = "No description")
  {
    m_argumentType[name] = WITH_FIELD;
    const auto getter = [name, this](nlohmann::json &j, bool create) -> nlohmann::json * {
      size_t pos = 0;
      nlohmann::json *f = &j;
      std::string token;
      std::string name_copy = name;
 
      while ((pos = name_copy.find(m_nestSeparator)) != std::string::npos) {
        token = name_copy.substr(0, pos);
 
        name_copy.erase(0, pos + m_nestSeparator.length());
        if (create && !f->contains(token)) {
          (*f)[token] = {};
        }
        else if (!f->contains(token)) {
          return nullptr;
        }
        f = &(f->at(token));
      }
      if (create && !f->contains(name_copy)) {
        (*f)[name_copy] = {};
      }
      else if (!f->contains(name_copy)) {
        return nullptr;
      }
      f = &(f->at(name_copy));
      return f;
      };
 
    m_parsers[name] = [&parameter, required, getter, name](nlohmann::json &j) {
      const nlohmann::json *field = getter(j, false);
      const bool fieldHasNoValue = field == nullptr || (field != nullptr && field->is_null());
      if (required && fieldHasNoValue) {
        std::stringstream ss;
        ss << "Argument " << name << " is required, but no value was provided" << std::endl;
        throw vpException(vpException::badValue, ss.str());
      }
      else if (!fieldHasNoValue) {
        field->get_to(parameter);
      }
      };
 
    m_updaters[name] = [getter](nlohmann::json &j, const std::string &s) {
      nlohmann::json *field = getter(j, true);
      *field = convertCommandLineArgument<T>(s);
      };
 
    m_helpers[name] = [help, parameter, required]() -> std::string {
      std::stringstream ss;
      nlohmann::json repr = parameter;
      ss << help << std::endl << "Default: " << repr;
      if (required) {
        ss << std::endl << "Required";
      }
      else {
        ss << std::endl << "Optional";
      }
      return ss.str();
      };
 
    nlohmann::json *exampleField = getter(m_exampleJson, true);
    *exampleField = parameter;
 
    return *this;
  }

  vpJsonArgumentParser &addFlag(const std::string &name, bool &parameter, const std::string &help = "No description");

  void parse(int argc, const char *argv[]);
 
private:
  std::string m_description; // Program description
  std::string m_jsonFileArgumentName; // Name of the argument  that points to the json file: ./program --config settings.json. Here jsonFileArgumentName == "--config"
  std::string m_nestSeparator; // JSON nesting delimiter character. Used to access JSON nested objects from a single string
  std::map<std::string, std::function<void(nlohmann::json &)>> m_parsers; // Functions that update the variables with the values contained in the JSON document (should be used after calling updaters)
  std::map<std::string, vpJsonArgumentType> m_argumentType; // Update the base json document with command line arguments
  std::map<std::string, std::function<void(nlohmann::json &, const std::string &)>> m_updaters; // Update the base json document with command line arguments
  std::map<std::string, std::function<std::string()>> m_helpers; // Functions that output the usage and description of command line arguments: used when the help flag is given as argument
  nlohmann::json m_exampleJson; // Example JSON argument file: displayed when user calls for help
};
 
END_VISP_NAMESPACE
 
#endif // VISP_HAVE_NLOHMANN_JSON
 
#endif