goptions.cc

Go to the documentation of this file.

 
// goptions
#include "goptions.h"
#include "goptionsConventions.h"
#include "gversion.h"
 
// gemc
#include "gutilities.h"
#include <gemc/glogging/gmessageCatalog.h>
 
// c++
#include <algorithm>
#include <iostream>
#include <cstring>
#include <cctype>
#include <cstdlib>
 
using namespace std;
 
namespace {
// Parse a human-friendly boolean token used for switches (-switch=value and YAML switch values).
// Accepts, case-insensitively: true/1/yes/y/on and false/0/no/n/off. Returns false if @p raw is
// not a recognized token, leaving @p out untouched.
bool parse_bool_token(const std::string& raw, bool& out) {
    std::string v = raw;
    std::transform(v.begin(), v.end(), v.begin(),
                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
    if (v == "true" || v == "1" || v == "yes" || v == "y" || v == "on") { out = true; return true; }
    if (v == "false" || v == "0" || v == "no" || v == "n" || v == "off") { out = false; return true; }
    return false;
}
 
}
 
// See goptions.h for full constructor API documentation.
/*
 * Parsing precedence implemented here:
 * 1. YAML file(s), applied in argv order
 * 2. Command-line tokens override YAML values
 *
 * Notes:
 * - "help <option>" is treated as an immediate action and exits after printing.
 * - Dot-notation routes structured updates to the owning option via GOption::set_sub_option_value().
 */
GOptions::GOptions(int argc, char* argv[], const GOptions& user_defined_options) {
    executableName       = gutilities::getFileFromPath(argv[0]);
    executableCallingDir = gutilities::getDirFromPath(argv[0]);
    installDir           = gutilities::executable_path().parent_path().string();
    cout << endl;
 
    // Add user-defined options.
    addGOptions(user_defined_options);
 
    // switches for all everyone
    defineSwitch("gui", "run with the graphical user interface (Qt window)");
    defineSwitch("i", "drop into the interactive Geant4 terminal session (non-GUI mode)");
    defineOption(GVariable("language", "auto",
                           "language for GEMC logging messages, startup banner, and GUI text"),
                 "Supported values:\n"
                 "  auto: detect your language automatically (default).\n"
                 "  en: English (original English messages).\n"
                 "  it: italiano (Italian).\n"
                 "  ja: 日本語 (Japanese).\n"
                 "  fr: français (French).\n"
                 "  zh: 中文 (Chinese).\n\n"
                 "Automatic selection checks GEMC_LANGUAGE, LC_ALL, LC_MESSAGES, LANG, then system settings.\n"
                 "Use -language=<code> or YAML language: <code> to override automatic selection.\n"
                 "Regional tags such as it_IT.UTF-8 are accepted; missing regional entries use the base language.\n"
                 "Missing languages or messages fall back to English. C and POSIX locales select English.\n"
                 "Numeric formatting is unchanged.\n");
    defineOption(
        GVariable("conf_yaml", "saved_configuration", "infix for the YAML file that records the resolved options"),
        "On exit the resolved configuration is written to <executable>.<conf_yaml>.yaml,\n"
        "so the default value produces, for example, gemc.saved_configuration.yaml.\n \n"
        "Example: -conf_yaml=run12   ->   saves to gemc.run12.yaml\n \n");
 
    // add test timeout for the tests
    defineOption(GVariable("tt", 500, "GUI test timeout (ms)"),
                 "Milliseconds a GUI-based test waits before it auto-closes, so the module\n"
                 "example/test programs can run unattended in CI.\n \n"
                 "Example: -tt=1000\n \n");
 
    // version is a special option, not settable by the user
    // it is set by the gversion.h file
    // we add it here so it can be saved to the yaml file
    vector<GVariable> version = {
        {"release", gversion, "release version number"},
        {"release_date", grelease_date, "release date"},
        {"Reference", greference, "article reference"},
        {"Homepage", gweb, "homepage"},
        {"Author", gauthor, "author"}
    };
    defineOption(goptions::GVERSION_STRING, "version information", version,
                 "Version information. Not settable by user.");
 
    // verbosity option: convention used across modules consuming verbosity levels
    string help = "Levels: \n \n";
    help        += " - 0: (default) = shush\n";
    help        += " - 1: log detailed information\n";
    help        += " - 2: log extra detailed information\n \n";
    help        += "Each key names a class or module; run 'help verbosity' to list the available keys.\n \n";
    help        += "Example (one key):      -verbosity.gemc=1\n";
    help        += "Example (several keys): -verbosity=\"[{gemc: 1}, {<another_key>: 2}]\"\n \n";
    help        += "Equivalent YAML:\n";
    help        += "   verbosity:\n";
    help        += "     - gemc: 1\n";
    help        += "     - <another_key>: 2\n \n";
    defineOption("verbosity", "Sets the log verbosity for various classes", option_verbosity_names, help);
 
    // debug option: boolean or integer, depending on consumer expectations
    help = "Debug information Types: \n \n";
    help += " - false: (default): do not print debug information\n";
    help += " - true: print debug information\n\n";
    help += "Each key names a class or module; run 'help debug' to list the available keys.\n \n";
    help += "Example (on/off):       -debug.gemc=true\n";
    help += "Example (several keys): -debug=\"[{gemc: true}, {<another_key>: 1}]\"\n \n";
    help += "Equivalent YAML:\n";
    help += "   debug:\n";
    help += "     - gemc: true\n \n";
    defineOption("debug", "Sets the debug level for various classes", option_verbosity_names, help);
 
    // Locate YAML input files up front so they can be excluded from command-line validation.
    yaml_files = findYamls(argc, argv);
 
    // Validate every command-line token before acting on any early-exit flag (-v, help, ...).
    // This ensures a typo such as --language=fr is reported instead of being silently ignored
    // when it accompanies a flag that would otherwise print and exit immediately.
    validateCommandLineArguments(argc, argv, yaml_files);
 
    // Process help/version command-line arguments.
    // These are handled early and exit immediately (they do not proceed to parse YAML/options).
    for (int i = 1; i < argc; i++) {
        if (strcmp(argv[i], "-h") == 0 || strcmp(argv[i], "--h") == 0 ||
            strcmp(argv[i], "-help") == 0 || strcmp(argv[i], "--help") == 0) {
            printHelp();
        }
        else if (strcmp(argv[i], "-hweb") == 0) {
            printWebHelp();
        }
        else if (strcmp(argv[i], "-v") == 0 || strcmp(argv[i], "--v") == 0 ||
            strcmp(argv[i], "-version") == 0 || strcmp(argv[i], "--version") == 0) {
            // Version remains an early action, but its language override may appear anywhere in argv.
            for (int argument = 1; argument < argc; ++argument) {
                string candidate = argv[argument];
                if (candidate.starts_with("--language=")) candidate.erase(0, 1); // --language= -> -language=
                if (candidate.starts_with("-language=")) {
                    string value = candidate.substr(string("-language=").size());
                    if (value.size() >= 2 && value.front() == '"' && value.back() == '"') {
                        value = value.substr(1, value.size() - 2);
                    }
                    setOptionValuesFromCommandLineArgument("language", value);
                }
            }
            print_version();
            exit(EXIT_SUCCESS);
        }
        else if (strcmp(argv[i], "help") == 0) {
            // "gemc help <topic>" shows topic help; bare "gemc help" shows the general help index.
            if (i + 1 < argc) { printOptionOrSwitchHelp(argv[i + 1]); }
            else { printHelp(); }
            exit(EXIT_SUCCESS);
        }
        else if (strcmp(argv[i], "search") == 0) {
            // "gemc search <value>" lists options/switches whose name or description contains <value>.
            if (i + 1 < argc) { printSearch(argv[i + 1]); }
            else { printHelp(); }
            exit(EXIT_SUCCESS);
        }
    }
 
    // Parse the yaml files located above.
    // YAML file tokens are treated as inputs, not as "invalid command-line arguments".
    for (auto& yaml_file : yaml_files) {
        cout << " Parsing " << yaml_file << endl;
        setOptionsValuesFromYamlFile(yaml_file);
    }
 
    // Parse command-line arguments (supports both standard YAML–style and dot–notation).
    for (int i = 1; i < argc; i++) {
        string candidate = argv[i];
        if (candidate.empty()) continue;
 
        // Skip YAML file tokens: they were already handled above.
        if (find(yaml_files.begin(), yaml_files.end(), candidate) != yaml_files.end()) continue;
 
        if (candidate[0] == '-') {
            // Accept a long form (--name) by normalizing it to the canonical single-dash form,
            // so both -language=fr and --language=fr behave identically and error messages do
            // not carry a spurious leading dash.
            string argStr = candidate.substr(1);
            if (!argStr.empty() && argStr[0] == '-') argStr = argStr.substr(1);
            size_t eqPos  = argStr.find('=');
 
            if (eqPos != string::npos) {
                string keyPart   = argStr.substr(0, eqPos);
                string valuePart = argStr.substr(eqPos + 1);
 
                // Switch with an explicit boolean value: -gui=false / -gui=true. This gives the
                // CLI a way to turn a switch off, honoring the documented CLI-over-YAML precedence.
                if (switches.contains(keyPart)) {
                    bool on = false;
                    if (parse_bool_token(valuePart, on)) { on ? switches[keyPart].turnOn() : switches[keyPart].turnOff(); }
                    else {
                        cerr << "The switch " << keyPart << " accepts only true/false/yes/no/on/off/1/0." << endl;
                        exit(goptions::EC__NOOPTIONFOUND);
                    }
                    continue;
                }
 
                // Strip outer quotes if present (e.g., -gstreamer="[...]")
                if (!valuePart.empty() && valuePart.front() == '"' && valuePart.back() == '"') {
                    valuePart = valuePart.substr(1, valuePart.length() - 2);
                }
 
                // Dot-notation targets a subkey in a structured option (e.g., verbosity.gemc).
                size_t dotPos = keyPart.find('.');
                if (dotPos != string::npos) {
                    string mainOption = keyPart.substr(0, dotPos);
                    string subOption  = keyPart.substr(dotPos + 1);
 
                    if (doesOptionExist(mainOption)) {
                        auto it = getOptionIterator(mainOption);
                        it->set_sub_option_value(subOption, valuePart);
                    }
                    else { reportUnknownNameAndExit("option", mainOption); }
                }
                else {
                    // Standard option syntax: -name=value
                    if (doesOptionExist(keyPart)) {
                        setOptionValuesFromCommandLineArgument(keyPart, valuePart);
                    }
                    else { reportUnknownNameAndExit("option", keyPart); }
                }
            }
            else {
                // Treat as a switch: -gui, -i, etc.
                const string& possibleSwitch = argStr;
                if (switches.contains(possibleSwitch)) {
                    switches[possibleSwitch].turnOn();
                }
                else { reportUnknownNameAndExit("switch", possibleSwitch); }
            }
        }
        else {
            cerr << "The command-line argument \"" << candidate << "\" is not valid." << endl;
            exit(goptions::EC__NOOPTIONFOUND);
        }
    }
 
    // Always print version information.
    print_version();
 
    // Save the final configuration to a YAML file.
    string yamlConf_filename = executableName + "." + getRequiredScalarString("conf_yaml") + ".yaml";
    cout << " Saving options to " << yamlConf_filename << endl << endl;
    yamlConf = new std::ofstream(yamlConf_filename);
    saveOptions();
}
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
void GOptions::defineSwitch(const std::string& name, const std::string& description, bool default_status) {
    if (!switches.contains(name)) {
        switches[name] = GSwitch(description, default_status);
    }
    else {
        std::cerr << guts::FATALERRORL << "The " << guts::YELLOWHHL << name << guts::RSTHHR
            << " switch is already present." << std::endl;
        exit(goptions::EC__DEFINED_SWITCHALREADYPRESENT);
    }
}
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
void GOptions::defineOption(const GVariable& gvar, const std::string& help) {
    if (doesOptionExist(gvar.name)) {
        std::cerr << guts::FATALERRORL << "The " << guts::YELLOWHHL << gvar.name << guts::RSTHHR
            << " option is already present." << std::endl;
        exit(goptions::EC__DEFINED_OPTION_ALREADY_PRESENT);
    }
    else {
        goptions.emplace_back(gvar, help);
    }
}
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
void GOptions::defineOption(const std::string&            name, const std::string& description,
                            const std::vector<GVariable>& gvars,
                            const std::string&            help) {
    if (doesOptionExist(name)) {
        std::cerr << guts::FATALERRORL << "The " << guts::YELLOWHHL << name << guts::RSTHHR
            << " option is already present." << std::endl;
        exit(goptions::EC__DEFINED_OPTION_ALREADY_PRESENT);
    }
    else {
        goptions.emplace_back(name, description, gvars, help);
    }
}
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
int GOptions::getRequiredScalarInt(const std::string& tag) const {
    auto it = getOptionIterator(tag);
    if (it == goptions.end()) {
        cerr << guts::FATALERRORL << "The option " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not found." << endl;
        exit(goptions::EC__NOOPTIONFOUND);
    }
    const YAML::Node node = it->value.begin()->second;
    if (!node.IsDefined() || node.IsNull()) {
        cerr << guts::FATALERRORL << "The required option " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not provided." << endl;
        exit(goptions::EC__MANDATORY_NOT_FILLED);
    }
    return node.as<int>();
}
 
std::optional<int> GOptions::getOptionalScalarInt(const std::string& tag) const {
    auto it = getOptionIterator(tag);
    if (it == goptions.end()) {
        cerr << guts::FATALERRORL << "The option " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not found." << endl;
        exit(goptions::EC__NOOPTIONFOUND);
    }
    const YAML::Node node = it->value.begin()->second;
    if (!node.IsDefined() || node.IsNull()) return std::nullopt;
    return node.as<int>();
}
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
double GOptions::getRequiredScalarDouble(const std::string& tag) const {
    auto it = getOptionIterator(tag);
    if (it == goptions.end()) {
        cerr << guts::FATALERRORL << "The option " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not found." << endl;
        exit(goptions::EC__NOOPTIONFOUND);
    }
    const YAML::Node node = it->value.begin()->second;
    if (!node.IsDefined() || node.IsNull()) {
        cerr << guts::FATALERRORL << "The required option " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not provided." << endl;
        exit(goptions::EC__MANDATORY_NOT_FILLED);
    }
    return node.as<double>();
}
 
std::optional<double> GOptions::getOptionalScalarDouble(const std::string& tag) const {
    auto it = getOptionIterator(tag);
    if (it == goptions.end()) {
        cerr << guts::FATALERRORL << "The option " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not found." << endl;
        exit(goptions::EC__NOOPTIONFOUND);
    }
    const YAML::Node node = it->value.begin()->second;
    if (!node.IsDefined() || node.IsNull()) return std::nullopt;
    return node.as<double>();
}
 
std::string GOptions::getRequiredScalarString(const std::string& tag) const {
    auto it = getOptionIterator(tag);
    if (it == goptions.end()) {
        cerr << guts::FATALERRORL << "The option " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not found." << endl;
        exit(goptions::EC__NOOPTIONFOUND);
    }
    const YAML::Node node = it->value.begin()->second;
    if (!node.IsDefined() || node.IsNull()) {
        cerr << guts::FATALERRORL << "The required option " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not provided." << endl;
        exit(goptions::EC__MANDATORY_NOT_FILLED);
    }
    return node.as<std::string>();
}
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
std::optional<std::string> GOptions::getOptionalScalarString(const std::string& tag) const {
    auto it = getOptionIterator(tag);
    if (it == goptions.end()) {
        std::cerr << guts::FATALERRORL << "The option " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not found." << std::endl;
        std::exit(goptions::EC__NOOPTIONFOUND);
    }
    const YAML::Node node = it->value.begin()->second;
    if (!node.IsDefined() || node.IsNull()) return std::nullopt;
    return node.as<std::string>();
}
 
 
// Private method: see header. Kept undocumented here to avoid duplicate param docs.
void GOptions::reportUnknownNameAndExit(const std::string& kind, const std::string& name) const {
    // Build the pool of known names (options + switches) to search for a close match.
    vector<string> known;
    known.reserve(goptions.size() + switches.size());
    for (const auto& option : goptions) {
        if (option.name != goptions::GVERSION_STRING) known.push_back(option.name);
    }
    for (const auto& s : switches) known.push_back(s.first);
 
    cerr << guts::FATALERRORL << "The " << kind << " " << guts::YELLOWHHL << name << guts::RSTHHR
        << " is not known to this system." << endl;
 
    if (auto suggestion = gutilities::closestMatch(name, known)) {
        cerr << guts::TPOINTITEM << "Did you mean " << guts::KGRN << "-" << *suggestion << guts::RST << "?" << endl;
    }
    cerr << guts::TPOINTITEM << "Run " << guts::KGRN << executableName << " -h" << guts::RST
        << " for the list of options and switches." << endl;
    exit(goptions::EC__NOOPTIONFOUND);
}
 
// Private method: see header. Kept undocumented here to avoid duplicate param docs.
void GOptions::validateCommandLineArguments(int argc, char* argv[], const vector<string>& yamls) const {
    // Tokens handled by the early help/version loop; they are legal on their own.
    static const vector<string> meta = {
        "-h", "--h", "-help", "--help", "-hweb", "-v", "--v", "-version", "--version"
    };
 
    for (int i = 1; i < argc; i++) {
        string candidate = argv[i];
        if (candidate.empty()) continue;
 
        // "help"/"search" consume the following token as their argument (topic / search text).
        if (candidate == "help" || candidate == "search") {
            if (i + 1 < argc) ++i;
            continue;
        }
        if (find(meta.begin(), meta.end(), candidate) != meta.end()) continue;
        if (find(yamls.begin(), yamls.end(), candidate) != yamls.end()) continue;
 
        if (candidate[0] == '-') {
            // Normalize a leading long form (--name -> -name) before extracting the key.
            string argStr = candidate.substr(1);
            if (!argStr.empty() && argStr[0] == '-') argStr = argStr.substr(1);
 
            const size_t eqPos   = argStr.find('=');
            const bool   hasValue = eqPos != string::npos;
            string       keyPart = hasValue ? argStr.substr(0, eqPos) : argStr;
 
            // Dot-notation (verbosity.gemc) is validated against the owning option.
            const size_t dotPos = keyPart.find('.');
            if (dotPos != string::npos) keyPart = keyPart.substr(0, dotPos);
 
            if (switches.contains(keyPart) || doesOptionExist(keyPart)) continue;
            reportUnknownNameAndExit(hasValue ? "option" : "switch", keyPart);
        }
        else {
            cerr << guts::FATALERRORL << "The command-line argument " << guts::YELLOWHHL << candidate
                << guts::RSTHHR << " is not valid." << endl;
            exit(goptions::EC__NOOPTIONFOUND);
        }
    }
}
 
// Private method: see header. Kept undocumented here to avoid duplicate param docs.
void GOptions::printOptionOrSwitchHelp(const std::string& tag) const {
    auto switchIt = switches.find(tag);
    if (switchIt != switches.end()) {
        cout << guts::KGRN << "-" << tag << guts::RST << ": " << switchIt->second.getDescription() << endl << endl;
        cout << guts::TPOINTITEM << "Default value is " << (switchIt->second.getStatus() ? "on" : "off") << endl
             << endl;
        exit(EXIT_SUCCESS);
    }
    for (const auto& goption : goptions) {
        if (goption.name == tag) {
            goption.printHelp(true);
            exit(EXIT_SUCCESS);
        }
    }
    reportUnknownNameAndExit("option", tag);
}
 
// Private method: see header. Kept undocumented here to avoid duplicate param docs.
void GOptions::printSearch(const std::string& tag) const {
    // Case-insensitive substring match against switch/option names and descriptions.
    auto to_lower = [](string s) {
        transform(s.begin(), s.end(), s.begin(), [](unsigned char c) { return std::tolower(c); });
        return s;
    };
    const string needle = to_lower(tag);
    auto         matches = [&](const string& a, const string& b) {
        return to_lower(a).find(needle) != string::npos || to_lower(b).find(needle) != string::npos;
    };
 
    long int fill_width = string(goptions::HELPFILLSPACE).size() + 1;
    cout.fill('.');
    cout << guts::KGRN << guts::KBOLD << " Options and switches matching \"" << tag << "\":" << guts::RST
         << endl
         << endl;
 
    bool found = false;
    for (auto& s : switches) {
        if (matches(s.first, s.second.getDescription())) {
            found = true;
            cout << guts::KGRN << " " << left;
            cout.width(fill_width);
            cout << "-" + s.first + guts::RST + " " << ": " << s.second.getDescription() << endl;
        }
    }
    for (auto& option : goptions) {
        if (option.name != goptions::GVERSION_STRING && matches(option.name, option.description)) {
            found = true;
            option.printHelp(false);
        }
    }
    if (!found) { cout << guts::TPOINTITEM << "no match found." << endl; }
    cout << endl
         << " Use " << guts::KGRN << "help <value>" << guts::RST << " for the detailed help of a single option."
         << endl
         << endl;
}
 
// Private method: see header. Kept undocumented here to avoid duplicate param docs.
vector<string> GOptions::findYamls(int argc, char* argv[]) {
    vector<string> yaml_files;
    for (int i = 1; i < argc; i++) {
        string arg = argv[i];
        // Match a trailing .yaml/.yml extension, not any substring, so option values such as
        // -prefix=run.yaml.bak are not mistaken for input files (and silently dropped).
        if (arg.ends_with(".yaml") || arg.ends_with(".yml")) yaml_files.push_back(arg);
    }
    return yaml_files;
}
 
// checks if the option exists
// Public API docs are in goptions.h; doxygen param docs are kept only there.
bool GOptions::doesOptionExist(const std::string& tag) const {
    // [&tag] ensures we're referencing the original tag passed to the function
    return std::any_of(goptions.begin(), goptions.end(),
                       [&tag](const auto& option) {
                           return option.name == tag;
                       });
}
 
// Private method: behavior described in header and top-of-file overview.
void GOptions::setOptionsValuesFromYamlFile(const std::string& yaml) {
    YAML::Node config;
    try {
        config = YAML::LoadFile(yaml);
    }
    catch (YAML::BadFile& e) {
        cerr << guts::FATALERRORL << "Cannot open yaml file " << guts::YELLOWHHL << yaml << guts::RSTHHR
            << ". Check the path and spelling." << endl;
        exit(goptions::EC__YAML_PARSING_ERROR);
    }
    catch (YAML::ParserException& e) {
        cerr << guts::FATALERRORL << "Error parsing " << guts::YELLOWHHL << yaml << guts::RSTHHR
            << " yaml file." << endl;
        cerr << e.what() << endl;
        cerr << "Try validating the yaml file with an online yaml validator, e.g., https://www.yamllint.com" << endl;
        exit(goptions::EC__YAML_PARSING_ERROR);
    }
 
    for (auto it = config.begin(); it != config.end(); ++it) {
        auto option_name = it->first.as<std::string>();
        auto option_it   = getOptionIterator(option_name);
 
        // If it is not an option, it may still be a switch.
        if (option_it == goptions.end()) {
            if (!switches.contains(option_name)) { reportUnknownNameAndExit("option or switch", option_name); }
            else {
                // A bare key (null value) means "present" -> on; an explicit boolean value is honored,
                // so a default-on switch can be turned off from YAML (e.g. print_summary: false).
                bool on = true;
                if (it->second.IsScalar() && !parse_bool_token(it->second.as<std::string>(), on)) {
                    cerr << guts::FATALERRORL << "The switch " << guts::YELLOWHHL << option_name << guts::RSTHHR
                        << " accepts only true/false/yes/no/on/off/1/0." << endl;
                    exit(goptions::EC__NOOPTIONFOUND);
                }
                on ? switches[option_name].turnOn() : switches[option_name].turnOff();
            }
        }
        else {
            YAML::NodeType::value type = it->second.Type();
            switch (type) {
            case YAML::NodeType::Scalar:
                option_it->set_scalar_value(it->second.as<std::string>());
                break;
            case YAML::NodeType::Sequence:
                option_it->set_value(it->second);
                break;
            case YAML::NodeType::Map:
                option_it->set_value(it->second);
                break;
            default:
                break;
            }
        }
    }
}
 
// Private method: behavior described in header and top-of-file overview.
void GOptions::setOptionValuesFromCommandLineArgument(const std::string& optionName,
                                                      const std::string& possibleYamlNode) {
    auto option_it = getOptionIterator(optionName);
    if (possibleYamlNode.empty()) {
        option_it->set_scalar_value("");
        return;
    }
 
    YAML::Node node = YAML::Load(possibleYamlNode);
 
    if (node.Type() == YAML::NodeType::Scalar) {
        option_it->set_scalar_value(possibleYamlNode);
    }
    else {
        option_it->set_value(node);
    }
}
 
void GOptions::setOptionValueFromString(const std::string& optionName,
                                        const std::string& possibleYamlNode) {
    setOptionValuesFromCommandLineArgument(optionName, possibleYamlNode);
}
 
// Private method (private API): do not \ref; use \c getOptionIterator() in docs if needed.
std::vector<GOption>::iterator GOptions::getOptionIterator(const std::string& name) {
    return std::find_if(goptions.begin(), goptions.end(),
                        [&name](GOption& option) { return option.name == name; });
}
 
// Private method (private API): do not \ref; use \c getOptionIterator() in docs if needed.
std::vector<GOption>::const_iterator GOptions::getOptionIterator(const std::string& name) const {
    return std::find_if(goptions.begin(), goptions.end(),
                        [&name](const GOption& option) { return option.name == name; });
}
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
bool GOptions::getSwitch(const std::string& tag) const {
    auto it = switches.find(tag);
    if (it != switches.end()) {
        return it->second.getStatus();
    }
    else {
        std::cerr << guts::FATALERRORL << "The switch " << guts::YELLOWHHL << tag << guts::RSTHHR
            << " was not found." << std::endl;
        exit(goptions::EC__NOOPTIONFOUND);
    }
}
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
YAML::Node GOptions::getOptionMapInNode(const string& option_name, const string& map_key) const {
    auto sequence_node = getOptionNode(option_name);
 
    for (auto seq_item : sequence_node) {
        for (auto map_item = seq_item.begin(); map_item != seq_item.end(); ++map_item) {
            if (map_item->first.as<string>() == map_key) {
                return map_item->second;
            }
        }
    }
 
    cerr << guts::FATALERRORL << "The key " << guts::YELLOWHHL << map_key << guts::RSTHHR
        << " was not found in " << guts::YELLOWHHL << option_name << guts::RSTHHR << endl;
    exit(goptions::EC__NOOPTIONFOUND);
}
 
// Template documentation lives in the header to avoid duplicate \param blocks.
template <typename T>
T GOptions::get_variable_in_option(const YAML::Node& node, const std::string& variable_name, const T& default_value) {
    if (node[variable_name]) {
        return node[variable_name].as<T>();
    }
    return default_value;
}
 
template <typename T>
T GOptions::get_required_variable_in_option(const YAML::Node& node, const std::string& variable_name) {
    if (!node[variable_name] || node[variable_name].IsNull()) {
        std::cerr << guts::FATALERRORL << "The mandatory key " << guts::YELLOWHHL << variable_name
            << guts::RSTHHR << " was not provided." << std::endl;
        std::exit(goptions::EC__MANDATORY_NOT_FILLED);
    }
    return node[variable_name].as<T>();
}
 
template <typename T>
std::optional<T> GOptions::get_optional_variable_in_option(
    const YAML::Node& node, const std::string& variable_name) {
    if (!node[variable_name] || node[variable_name].IsNull()) return std::nullopt;
    return node[variable_name].as<T>();
}
 
// Explicit template instantiations.
template int GOptions::get_variable_in_option<int>(const YAML::Node& node, const std::string& variable_name,
                                                   const int&        default_value);
template double GOptions::get_variable_in_option<double>(const YAML::Node& node, const std::string& variable_name,
                                                         const double&     default_value);
template string GOptions::get_variable_in_option<string>(const YAML::Node& node, const std::string& variable_name,
                                                         const string&     default_value);
template bool GOptions::get_variable_in_option<bool>(const YAML::Node& node, const std::string& variable_name,
                                                     const bool&       default_value);
template int GOptions::get_required_variable_in_option<int>(const YAML::Node&, const std::string&);
template double GOptions::get_required_variable_in_option<double>(const YAML::Node&, const std::string&);
template string GOptions::get_required_variable_in_option<string>(const YAML::Node&, const std::string&);
template bool GOptions::get_required_variable_in_option<bool>(const YAML::Node&, const std::string&);
template std::optional<int> GOptions::get_optional_variable_in_option<int>(
    const YAML::Node&, const std::string&);
template std::optional<double> GOptions::get_optional_variable_in_option<double>(const YAML::Node&,
                                                                                  const std::string&);
template std::optional<string> GOptions::get_optional_variable_in_option<string>(const YAML::Node&,
                                                                                  const std::string&);
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
int GOptions::getVerbosityFor(const std::string& tag) const {
    YAML::Node verbosity_node = getOptionNode("verbosity");
    for (auto v : verbosity_node) {
        if (v.begin()->first.as<string>() == tag) {
            return v.begin()->second.as<int>();
        }
    }
 
    // not found. error
    std::cerr << guts::KRED << " Invalid verbosity or debug requested: " << tag << guts::RST << std::endl;
    exit(goptions::EC__NOOPTIONFOUND);
}
 
// Implementation note: public API docs are in goptions.h (avoid duplicate \param blocks).
int GOptions::getDebugFor(const std::string& tag) const {
    YAML::Node debug_node = getOptionNode("debug");
    for (auto d : debug_node) {
        if (d.begin()->first.as<string>() == tag) {
            YAML::Node valNode = d.begin()->second;
            if (valNode.IsScalar()) {
                auto s = valNode.as<string>();
                if (s == "true") return 1;
                if (s == "false") return 0;
            }
            try {
                return valNode.as<int>();
            }
            catch (const YAML::BadConversion&) {
                std::cerr << "Invalid debug value for " << tag << std::endl;
                exit(goptions::EC__BAD_CONVERSION);
            }
        }
    }
    // not found. error
    std::cerr << guts::KRED << " Invalid verbosity or debug requested: " << tag << guts::RST << std::endl;
    exit(goptions::EC__NOOPTIONFOUND);
}
 
// Private method: no Doxygen block here to avoid duplicate \param docs.
void GOptions::printHelp() const {
    long int fill_width = string(goptions::HELPFILLSPACE).size() + 1;
    cout.fill('.');
    cout << guts::KGRN << guts::KBOLD << " " << executableName << guts::RST << " [options] [yaml files]" << endl
         << endl;
    cout << " Switches: " << endl << endl;
    for (auto& s : switches) {
        string help = "-" + s.first + guts::RST + " ";
        cout << guts::KGRN << " " << left;
        cout.width(fill_width);
        cout << help;
        cout << ": " << s.second.getDescription() << endl;
    }
    cout << endl;
    cout << " Options: " << endl << endl;
    for (auto& option : goptions) {
        option.printHelp(false);
    }
    cout << endl;
    cout << endl << " Help / Search / Introspection: " << endl << endl;
    vector<string> helps = {
        string("-h, --h, -help, --help") + guts::RST,
        string("print this help and exit"),
        string("-hweb") + guts::RST,
        string("print this help in web format and exit"),
        string("-v, --v, -version, --version") + guts::RST,
        string("print the version and exit\n"),
        string("help <value>") + guts::RST,
        string("print detailed help for option <value> and exit"),
        string("search <value>") + guts::RST,
        string("list all options/switches whose name or description contains <value> and exit\n")
    };
    unsigned half_help = helps.size() / 2;
    for (unsigned i = 0; i < half_help; i++) {
        cout << guts::KGRN << " " << left;
        cout.width(fill_width);
        cout << helps[i * 2] << ": " << helps[i * 2 + 1] << endl;
    }
    cout << endl;
    cout << " Note: command line options overwrite YAML file(s)." << endl << endl;
    exit(EXIT_SUCCESS);
}
 
// Private method: no Doxygen block here to avoid duplicate \param docs.
void GOptions::printWebHelp() const {
    exit(EXIT_SUCCESS);
}
 
// Private method: no Doxygen block here to avoid duplicate \param docs.
void GOptions::saveOptions() const {
    for (auto& s : switches) {
        string status = s.second.getStatus() ? "true" : "false";
        *yamlConf << s.first + ": " + status << "," << endl;
    }
    for (const auto& option : goptions) {
        option.saveOption(yamlConf);
    }
    yamlConf->close();
}
 
// Private method: no Doxygen block here to avoid duplicate \param docs.
void GOptions::print_version() {
    string asterisks = "*******************************************************************";
    cout << endl << asterisks << endl;
    const auto catalog = GMessageCatalog::load(this);
    const auto colored = [](const string& value) { return string(guts::KGRN) + value + guts::RST; };
    const string executable = string(guts::KGRN) + guts::KBOLD + executableName + guts::RST;
    cout << catalog->format(" %1  version: %2", executable, colored(gversion)) << endl;
    cout << catalog->format(" Called from: %1", colored(executableCallingDir)) << endl;
    cout << catalog->format(" Install: %1", colored(installDir)) << endl;
    cout << catalog->format(" Released on: %1", colored(grelease_date)) << endl;
 
    // Report the plugin search path when one was provided, either through the
    // -plugin_path option (or a plugin_path: YAML key) or the GEMC_PLUGIN_PATH
    // environment variable.
    string plugin_path = doesOptionExist("plugin_path")
                         ? getOptionalScalarString("plugin_path").value_or("")
                         : "";
    const char* plugin_env = std::getenv("GEMC_PLUGIN_PATH");
    if (!plugin_path.empty() || (plugin_env != nullptr && plugin_env[0] != '\0')) {
        string combined = plugin_path;
        if (plugin_env != nullptr && plugin_env[0] != '\0') {
            if (!combined.empty()) combined += ':';
            combined += plugin_env;
        }
        cout << catalog->format(" Plugin path: %1", colored(combined)) << endl;
    }
 
    cout << catalog->format(" GEMC Reference: %1", colored(greference)) << endl;
    cout << catalog->format(" GEMC Homepage: %1", colored(gweb)) << endl;
    cout << catalog->format(" Author: %1", colored(gauthor)) << endl << endl;
    cout << asterisks << endl << endl;
}
 
// Operator documentation is provided in goptions.h; do not duplicate it here.
GOptions& operator+=(GOptions& gopts, const GOptions& goptions_to_add) {
    gopts.addGOptions(goptions_to_add);
    return gopts;
}