cmd_line_parser.hpp

Go to the documentation of this file.

#ifndef CMD_LINE_PARSER_HPP
#define CMD_LINE_PARSER_HPP
 
/**
 * \file cmd_line_parser.hpp
 * \brief Command-line argument parsing and validation.
 * \author Le Bars, Yoann
 * \ingroup AppConfiguration
 *
 * This file is part of the pure C++ benchmark.
 *
 * This program 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 3 of the License, or (at your option)
 * any later version.
 *
 * This program 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 for
 * more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
#include <QCoreApplication>
#include <QDebug>
#include <QObject>
#include <QString>
#include <boost/program_options.hpp>
#include <config.hpp>
#include <cstddef>
#include <iostream>
#include <memory>
#include <sstream>
#include <string>
 
#include "constants.hpp"
 
namespace po = boost::program_options;
 
/// \brief Namespace for command-line parsing logic.
namespace CmdLine {
    /// \brief Exit codes for the application.
    enum class ExitCode : int {
        Success = 0,
        CmdLineError = -1,
        NotEnoughIterations = -2,
        NotEnoughBodies = -3,
        NegativeDensity = -4,
        NegativeTimeStep = -5,
        NegativeGravity = -6,
        NegativeEpsilon = -7,
        OutOfRange = -8,
        BadAlloc = -9,
        StdException = -10,
        UnknownException = -11,
    };
 
    /// \brief Log level for the application.
    enum class LogLevel {
        Debug,
        Info,
        Warning,
        Critical,
        Fatal,
    };
 
    /**
     * \brief Overload of `operator<<` for `LogLevel` to enable streaming.
     *
     * This is required by `boost::program_options` for displaying default
     * values in the help message.
     *
     * \param os The output stream.
     * \param level The `LogLevel` enum to stream.
     * \return The output stream.
     */
    inline std::ostream& operator<<(std::ostream& os, const LogLevel& level) {
        switch (level) {
            case LogLevel::Debug:
                return os << "debug";
            case LogLevel::Info:
                return os << "info";
            case LogLevel::Warning:
                return os << "warning";
            case LogLevel::Critical:
                return os << "critical";
            case LogLevel::Fatal:
                return os << "fatal";
        }
        return os;  // Should not be reached
    }
 
    /**
     * \brief Converts a double to a string with a specified precision for
     *        display.
     *
     * \param value The double value to convert.
     * \param precision The number of digits of precision.
     * \param use_scientific If true, uses scientific notation; otherwise,
     *                       uses fixed.
     *
     * \return A string representation of the double.
     */
    inline std::string toStringWithPrecision(
        double value, int precision = 1,
        bool use_scientific = true) {  // NOLINT
        std::ostringstream out;
        out.precision(precision);
        if (use_scientific) {
            out << std::scientific;
        } else {
            out << std::fixed;
        }
        out << value;
        return out.str();
    }
 
    // Forward declaration for the custom validator.
    void validateIsPositive(const std::size_t& value,
                            const std::string& option_name,
                            const std::function<QString(const char*)>& tr_func);
 
    /**
     * \brief Overload of `operator>>` for Boost.Program_Options to parse
     *        `LogLevel`.
     *
     * \param is The input stream.
     * \param level The `LogLevel` enum to populate.
     * \return The input stream.
     */
    inline std::istream& operator>>(std::istream& is, LogLevel& level) {
        std::string token;
        is >> token;
        if (token == "debug")
            level = LogLevel::Debug;
        else if (token == "info")
            level = LogLevel::Info;
        else if (token == "warning")
            level = LogLevel::Warning;
        else if (token == "critical")
            level = LogLevel::Critical;
        else if (token == "fatal")
            level = LogLevel::Fatal;
        else
            is.setstate(std::ios_base::failbit);
        return is;
    }
 
    /**
     * \brief A struct to hold the definition of a single command-line option.
     *
     * This data-driven approach makes adding or modifying arguments much
     * cleaner than a long chain of `add_options()` calls.
     */
    struct OptionDefinition {
        /// \brief The flags for the option (e.g., "help,h").
        std::string flags;
        /// \brief The help text for the option.
        std::string help_text;
        /**
         * \brief A function that returns the Boost.Program_Options value
         * semantic. This allows us to handle different types (int, double,
         * bool_switch) in a uniform way.
         */
        std::function<po::value_semantic*()> value_factory;
    };
 
    /**
     * \brief Holds and parses command-line arguments.
     *
     * This struct inherits from QObject to gain access to the `tr()` function
     * for internationalisation.
     * \ingroup AppConfiguration
     */
    struct CmdLineArgs {
       public:
        /// \brief The number of iterations to run the simulation.
        std::size_t n_iter_;
 
        /// \brief The number of bodies in the simulation.
        std::size_t n_bodies_;
 
        /// \brief The density of the bodies.
        double dens_;
 
        /// \brief The time step for each simulation iteration.
        double dt_;
 
        /// \brief The universal gravitational constant.
        double G_;
 
        /// \brief The numerical precision for floating-point comparisons.
        double epsilon_;
 
        /// \brief The seed for the random number generator.
        unsigned int seed_;
 
        /// \brief Flag to enable diagnostic output.
        bool debug_console_;
 
        /// \brief File path for logging.
        std::string debug_file_;
 
        /// \brief Identifier for syslog logging.
        std::string debug_syslog_;
 
        /// \brief Log level filter.
        LogLevel log_level_;
 
        /// \brief Frequency of energy log output.
        std::size_t log_freq_;
 
        /// \brief Coefficient of restitution for collisions.
        double restitution_;
 
        /// \brief Coefficient of kinetic (sliding) friction.
        double friction_;
 
        /// \brief Coefficient of static friction.
        double static_friction_;
 
        /// \brief Damping factor for linear velocity.
        double linear_damping_;
 
        /// \brief Damping factor for angular velocity.
        double angular_damping_;
 
        /// \brief Flag to display torque vectors in the UI.
        bool show_torque_arrow_;
 
        /// \brief Flag to display angular acceleration vectors in the UI.
        bool show_alpha_arrow_;
 
        /// \brief Cleanup strategy: "fast" (deferred) or "strict" (sync).
        std::string cleanup_mode_;
 
        /**
         * \brief Creates a SimulationConfig object from the parsed arguments.
         *
         * \return A populated SimulationConfig struct.
         */
        [[nodiscard]] Configuration::SimulationConfig toSimulationConfig()
            const {
            return {
                .n_iter = n_iter_,
                .n_bodies = n_bodies_,
                .dens = dens_,
                .universal_g = G_,
                .epsilon = epsilon_,
                .seed = seed_,
                .max_dt = dt_,
                .coeff_restitution = restitution_,
                .coeff_friction = friction_,
                .coeff_static_friction = static_friction_,
                .linear_damping = linear_damping_,
                .angular_damping = angular_damping_,
                .diagnostics_enabled = debug_console_,
                .log_freq = log_freq_,
                .show_torque_arrow = show_torque_arrow_,
                .show_alpha_arrow = show_alpha_arrow_,
            };
        }
 
        /**
         * \brief Validates the parsed command-line arguments.
         * \throws po::validation_error if any argument is invalid.
         */
        void validate(
            // TRANSLATOR CmdLine
            // TR_CONTEXT main
            const std::function<QString(const char*)>& tr_func) const {
            validateIsPositive(n_iter_, "niter", tr_func);
            validateIsPositive(n_bodies_, "nbodies", tr_func);
            validateIsPositive(log_freq_, "log-freq", tr_func);
 
            if (dens_ <= 0.) {
                throw po::validation_error(
                    po::validation_error::invalid_option_value,
                    //: TRANSLATOR: Error message for a command-line option.
                    tr_func(
                        QT_TRANSLATE_NOOP(
                            "CmdLine::CmdLineArgs",
                            "The value for option 'dens' must be positive."))
                        .toStdString());
            }
            if (dt_ <= 0.) {
                throw po::validation_error(
                    po::validation_error::invalid_option_value,
                    //: TRANSLATOR: Error message for a command-line option.
                    tr_func(QT_TRANSLATE_NOOP(
                                "CmdLine::CmdLineArgs",
                                "The value for option 'dt' must be positive."))
                        .toStdString());
            }
            if (G_ <= 0.) {
                throw po::validation_error(
                    po::validation_error::invalid_option_value,
                    //: TRANSLATOR: Error message for a command-line option.
                    tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                              "The value for option "
                                              "'universalg' must be positive."))
                        .toStdString());
            }
            if (epsilon_ <= 0.) {
                throw po::validation_error(
                    po::validation_error::invalid_option_value,
                    //: TRANSLATOR: Error message for a command-line option.
                    tr_func(
                        QT_TRANSLATE_NOOP(
                            "CmdLine::CmdLineArgs",
                            "The value for option 'epsilon' must be positive."))
                        .toStdString());
            }
            if (restitution_ < 0.) {
                throw po::validation_error(
                    po::validation_error::invalid_option_value,
                    //: TRANSLATOR: Error message for a command-line option.
                    tr_func(QT_TRANSLATE_NOOP(
                                "CmdLine::CmdLineArgs",
                                "The value for option 'restitution' must be "
                                "non-negative."))
                        .toStdString());
            }
            if (friction_ < 0.) {
                throw po::validation_error(
                    po::validation_error::invalid_option_value,
                    //: TRANSLATOR: Error message for a command-line option.
                    tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                              "The value for option 'friction' "
                                              "must be non-negative."))
                        .toStdString());
            }
            if (static_friction_ < 0.) {
                throw po::validation_error(
                    po::validation_error::invalid_option_value,
                    //: TRANSLATOR: Error message for a command-line option.
                    tr_func(QT_TRANSLATE_NOOP(
                                "CmdLine::CmdLineArgs",
                                "The value for option 'static-friction' must "
                                "be non-negative."))
                        .toStdString());
            }
            if (linear_damping_ < 0. || angular_damping_ < 0.) {
                throw po::validation_error(
                    po::validation_error::invalid_option_value,
                    //: TRANSLATOR: Error message for a command-line option.
                    tr_func(QT_TRANSLATE_NOOP(
                                "CmdLine::CmdLineArgs",
                                "Damping values must be non-negative."))
                        .toStdString());
            }
            if (cleanup_mode_ != "fast" && cleanup_mode_ != "strict") {
                throw po::validation_error(
                    po::validation_error::invalid_option_value,
                    //: TRANSLATOR: Error message for a command-line option.
                    tr_func(QT_TRANSLATE_NOOP(
                                "CmdLine::CmdLineArgs",
                                "The value for option 'cleanup-mode' must be "
                                "'fast' or 'strict'."))
                        .toStdString());
            }
        }
        /**
         * \brief Parses and validates command-line arguments.
         *
         * \param argc The argument count from main().
         * \param argv The argument vector from main().
         *
         * \return A `unique_ptr` to a `CmdLineArgs` struct on success, or
         *         `nullptr` if --help or --version was requested, or if an
         *         error occurred.
         */
        static std::unique_ptr<CmdLineArgs> parse(
            // TRANSLATOR CmdLine
            // TR_CONTEXT main
            const QStringList& q_args,
            const std::function<QString(const char*)>& tr_func) {
            auto args = std::make_unique<CmdLineArgs>();
 
            // Convert QStringList to std::vector<std::string> for Boost
            std::vector<std::string> std_args;
            std_args.reserve(q_args.size());
            for (const auto& arg : q_args) {
                std_args.push_back(arg.toStdString());
            }
 
            const std::vector<OptionDefinition> definitions = {
                {"help,h",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Display this help message."))
                     .toStdString(),
                 nullptr},
                {"version,V",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Display program version."))
                     .toStdString(),
                 nullptr},
                {"diagnostics,D",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Enable diagnostic output (alias "
                                           "for --debugConsole)."))
                     .toStdString(),
                 [&] { return po::bool_switch(); }},
                {"debugConsole,c",
                 tr_func(QT_TRANSLATE_NOOP(
                             "CmdLine::CmdLineArgs",
                             "Enable logs through the standard output."))
                     .toStdString(),
                 [&] {
                     return po::bool_switch(&args->debug_console_)
                         ->default_value(false);
                 }},
                {"debugFile,f",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Enable logs into a file."))
                     .toStdString(),
                 [&] {
                     return po::value<std::string>(&args->debug_file_)
                         ->default_value("");
                 }},
                {"debugSyslog,S",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Enable logs through Syslog."))
                     .toStdString(),
                 [&] {
                     return po::value<std::string>(&args->debug_syslog_)
                         ->default_value("");
                 }},
                {"cleanup-mode",
                 tr_func(
                     QT_TRANSLATE_NOOP(
                         "CmdLine::CmdLineArgs",
                         "Cleanup strategy: 'fast' (deferred destruction, "
                         "best performance) or 'strict' (synchronous "
                         "destruction, conservative)."))
                     .toStdString(),
                 [&] {
                     return po::value<std::string>(&args->cleanup_mode_)
                         ->default_value("fast");
                 }},
                {"level,l",
                 tr_func(QT_TRANSLATE_NOOP(
                             "CmdLine::CmdLineArgs",
                             "Log level filter (debug, info, warning, "
                             "critical, fatal)."))
                     .toStdString(),
                 [&] {
                     return po::value<LogLevel>(&args->log_level_)
                         ->default_value(LogLevel::Critical);
                 }},
                {"niter,i",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Number of iterations."))
                     .toStdString(),
                 [&] {
                     return po::value<std::size_t>(&args->n_iter_)
                         ->default_value(500);
                 }},
                {"nbodies,n",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Number of bodies."))
                     .toStdString(),
                 [&] {
                     return po::value<std::size_t>(&args->n_bodies_)
                         ->default_value(20);
                 }},
                {"dens,d",
                 tr_func(QT_TRANSLATE_NOOP(
                             "CmdLine::CmdLineArgs",
                             "Object density (proportionality coefficient "
                             "between mass and radius)."))
                     .toStdString(),
                 [&] {
                     return po::value<double>(&args->dens_)
                         ->default_value(0.1,
                                         toStringWithPrecision(0.1, 1, false));
                 }},
                {"dt,t",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Model time step (in s)."))
                     .toStdString(),
                 [&] {
                     return po::value<double>(&args->dt_)
                         ->default_value(0.5,
                                         toStringWithPrecision(0.5, 1, false));
                 }},
                {"universalg,g",
                 tr_func(
                     QT_TRANSLATE_NOOP(
                         "CmdLine::CmdLineArgs",
                         "Universal gravitational constant (in m³ / kg / s²)."))
                     .toStdString(),
                 [&] {
                     return po::value<double>(&args->G_)->default_value(
                         Model::G, toStringWithPrecision(Model::G, 5));
                 }},
                {"seed,s",
                 tr_func(QT_TRANSLATE_NOOP(
                             "CmdLine::CmdLineArgs",
                             "Seed for random number generation. If 0, a "
                             "random seed is used."))
                     .toStdString(),
                 [&] {
                     return po::value<unsigned int>(&args->seed_)
                         ->default_value(0);
                 }},
                {"epsilon,e",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Computing precision."))
                     .toStdString(),
                 [&] {
                     return po::value<double>(&args->epsilon_)
                         ->default_value(
                             Model::EPSILON,
                             toStringWithPrecision(Model::EPSILON, 0));
                 }},
                {"log-freq",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Frequency of energy log output "
                                           "(every N iterations)."))
                     .toStdString(),
                 [&] {
                     return po::value<std::size_t>(&args->log_freq_)
                         ->default_value(Model::DEFAULT_LOG_FREQ);
                 }},
                {"restitution,r",
                 tr_func(QT_TRANSLATE_NOOP(
                             "CmdLine::CmdLineArgs",
                             "Coefficient of restitution for collisions."))
                     .toStdString(),
                 [&] {
                     return po::value<double>(&args->restitution_)
                         ->default_value(
                             Model::COEFF_RESTITUTION,
                             toStringWithPrecision(Model::COEFF_RESTITUTION, 1,
                                                   false));
                 }},
                {"friction,F",
                 tr_func(QT_TRANSLATE_NOOP(
                             "CmdLine::CmdLineArgs",
                             "Coefficient of kinetic (sliding) friction."))
                     .toStdString(),
                 [&] {
                     return po::value<double>(&args->friction_)
                         ->default_value(Model::COEFF_FRICTION,
                                         toStringWithPrecision(
                                             Model::COEFF_FRICTION, 1, false));
                 }},
                {"static-friction,T",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Coefficient of static friction."))
                     .toStdString(),
                 [&] {
                     return po::value<double>(&args->static_friction_)
                         ->default_value(
                             Model::COEFF_STATIC_FRICTION,
                             toStringWithPrecision(Model::COEFF_STATIC_FRICTION,
                                                   1, false));
                 }},
                {"linear-damping,L",
                 tr_func(
                     QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                       "Damping factor for linear velocity."))
                     .toStdString(),
                 [&] {
                     return po::value<double>(&args->linear_damping_)
                         ->default_value(Model::LINEAR_DAMPING,
                                         toStringWithPrecision(
                                             Model::LINEAR_DAMPING, 3, false));
                 }},
                {"angular-damping,a",
                 tr_func(
                     QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                       "Damping factor for angular velocity."))
                     .toStdString(),
                 [&] {
                     return po::value<double>(&args->angular_damping_)
                         ->default_value(Model::ANGULAR_DAMPING,
                                         toStringWithPrecision(
                                             Model::ANGULAR_DAMPING, 3, false));
                 }},
                {"show-torque-arrow",
                 tr_func(QT_TRANSLATE_NOOP(
                             "CmdLine::CmdLineArgs",
                             "Show torque vectors as arrows in the UI."))
                     .toStdString(),
                 [&] {
                     return po::bool_switch(&args->show_torque_arrow_)
                         ->default_value(false);
                 }},
                {"show-alpha-arrow",
                 tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                           "Show angular acceleration vectors "
                                           "as arrows in the UI."))
                     .toStdString(),
                 [&] {
                     return po::bool_switch(&args->show_alpha_arrow_)
                         ->default_value(false);
                 }},
            };
 
            po::options_description desc(
                tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                          "Supported options"))
                    .toStdString(),
                100);
            for (const auto& def : definitions) {
                if (def.value_factory) {
                    desc.add_options()(def.flags.c_str(), def.value_factory(),
                                       def.help_text.c_str());
                } else {
                    desc.add_options()(def.flags.c_str(),
                                       def.help_text.c_str());
                }
            }
 
            po::variables_map vm;
            try {
                po::store(po::command_line_parser(std_args).options(desc).run(),
                          vm);
                po::notify(vm);
 
                // Handle the --diagnostics alias
                if (vm.count("diagnostics")) {
                    args->debug_console_ = true;
                }
            }
 
            catch (const po::error& e) {
                /* Catch validation errors from notifiers and other parsing
                   errors. */
                qCritical().noquote()
                    << tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                                 "Command line error: %1"))
                           .arg(e.what());
                std::cout << desc << std::endl;
                return nullptr;
            }
            if (vm.count("help")) {
                std::stringstream desc_stream;
                desc_stream << desc;
                qInfo().noquote()
                    <<
                    //: TRANSLATOR: A short description of the application.
                    tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                              "A benchmark for C++ using Qt "
                                              "framework."))  // NOLINT
                    << "\n\n"
                    //: TRANSLATOR: A label for the command-line usage example.
                    << tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                                 "Command line:"))
                    << "\n\t"
                    << QCoreApplication::applicationFilePath()  // NOLINT
                    //: TRANSLATOR: A placeholder for command-line options.
                    << tr_func(QT_TRANSLATE_NOOP("CmdLine::CmdLineArgs",
                                                 " [Options]"))
                    << "\n\n"
                    << desc_stream.str().c_str();
                return nullptr;
            }
 
            if (vm.count("version")) {
                qInfo().noquote()
                    << QString("%1 version %2.%3.%4")
                           .arg(QCoreApplication::applicationName())
                           .arg(Configuration::VERSION_MAJOR)
                           .arg(Configuration::VERSION_MINOR)
                           .arg(Configuration::PATCH_VERSION);
                return nullptr;
            }
 
            args->validate(tr_func);
            return args;
        }
    };
 
    // --- Custom Validators for Boost.Program_Options ---
    /**
     * \brief Validates that an unsigned integer option is greater than zero.
     *
     * \param value The value of the option to validate.
     * \param option_name The name of the option, used for the error message.
     *
     * \throws po::validation_error if the value is zero.
     *
     * This is a custom validator for use with Boost.Program_Options.
     */
    inline void validateIsPositive(
        // TRANSLATOR CmdLine
        // TR_CONTEXT main
        const std::size_t& value, const std::string& option_name,
        const std::function<QString(const char*)>& tr_func) {
        if (value == 0) {
            /* Throw a validation error with a specific, translatable message.
               This function is defined after CmdLineArgs so it can call
               CmdLineArgs::tr(). */
            throw po::validation_error(
                po::validation_error::invalid_option_value,
                //: TRANSLATOR: Error message for a command-line option. %1 is
                //: the option name.
                tr_func(QT_TRANSLATE_NOOP(
                            "CmdLine::CmdLineArgs",
                            "The value for option '%1' must be positive."))
                    .arg(QString::fromStdString(option_name))
                    .toStdString());
        }
    }
}  // namespace CmdLine
 
#endif  // CMD_LINE_PARSER_HPP