goptions.cc

Go to the documentation of this file.

 
// goptions
#include "goptions.h"
#include "goptionsConventions.h"
#include "gversion.h"
 
// gemc
#include "gutilities.h"
 
// c++
#include <algorithm>
#include <iostream>
#include <cstring>
#include <cctype>
#include <cstdlib>
#include <filesystem>
 
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;
}
 
std::string geant4_installation() {
    const char* path_environment = std::getenv("PATH");
    if (path_environment == nullptr) {
        return "geant4-config not found (PATH is not set)";
    }
 
    const std::string path = path_environment;
    std::size_t       start = 0;
    while (start <= path.size()) {
        const std::size_t end = path.find(':', start);
        const std::string directory = path.substr(start, end - start);
        const auto candidate = std::filesystem::path(directory.empty() ? "." : directory) / "geant4-config";
        std::error_code error;
        if (std::filesystem::is_regular_file(candidate, error)) {
            auto resolved = std::filesystem::canonical(candidate, error);
            if (error) {
                resolved = candidate;
            }
            return resolved.parent_path().parent_path().string();
        }
        if (end == std::string::npos) {
            break;
        }
        start = end + 1;
    }
 
    return "geant4-config not found in PATH";
}
}
 
// 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("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);
 
    // 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) {
            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);
        }
    }
 
    // finds and parse the yaml files
    // YAML file tokens are treated as inputs, not as "invalid command-line arguments".
    yaml_files = findYamls(argc, argv);
    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] == '-') {
            string argStr = candidate.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.find(keyPart) != switches.end()) {
                    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 {
                        cerr << "The option " << mainOption << " is not known to this system." << endl;
                        exit(goptions::EC__NOOPTIONFOUND);
                    }
                }
                else {
                    // Standard option syntax: -name=value
                    if (doesOptionExist(keyPart)) {
                        setOptionValuesFromCommandLineArgument(keyPart, valuePart);
                    }
                    else {
                        cerr << "The option " << keyPart << " is not known to this system." << endl;
                        exit(goptions::EC__NOOPTIONFOUND);
                    }
                }
            }
            else {
                // Treat as a switch: -gui, -i, etc.
                const string& possibleSwitch = argStr;
                if (switches.find(possibleSwitch) != switches.end()) {
                    switches[possibleSwitch].turnOn();
                }
                else {
                    cerr << "The switch " << possibleSwitch << " is not known to this system." << endl;
                    exit(goptions::EC__NOOPTIONFOUND);
                }
            }
        }
        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.find(name) == switches.end()) {
        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::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);
        }
    }
    cerr << guts::FATALERRORL << "The " << guts::YELLOWHHL << tag << guts::RSTHHR
        << " option is not known to this system." << endl;
    exit(goptions::EC__NOOPTIONFOUND);
}
 
// 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;
    auto ends_with = [](const string& s, const string& suffix) {
        return s.size() >= suffix.size() &&
               s.compare(s.size() - suffix.size(), suffix.size(), suffix) == 0;
    };
    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 (ends_with(arg, ".yaml") || ends_with(arg, ".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.find(option_name) == switches.end()) {
                cerr << guts::FATALERRORL << "The option or switch " << guts::YELLOWHHL << option_name << guts::RSTHHR
                    << " is not known to this system." << endl;
                exit(goptions::EC__NOOPTIONFOUND);
            }
            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;
    cout << " " << guts::KGRN << guts::KBOLD << executableName << guts::RST << "  version: " << guts::KGRN
         << gversion << guts::RST << endl;
    cout << " Called from: " << guts::KGRN << executableCallingDir << guts::RST << endl;
    cout << " Install: " << guts::KGRN << installDir << guts::RST << endl;
    cout << " Geant4 Installation: " << guts::KGRN << geant4_installation() << guts::RST << endl;
    cout << " Released on: " << guts::KGRN << grelease_date << guts::RST << 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 << " Plugin path: " << guts::KGRN << combined << guts::RST << endl;
    }
 
    cout << " GEMC Reference: " << guts::KGRN << greference << guts::RST << endl;
    cout << " GEMC Homepage: " << guts::KGRN << gweb << guts::RST << endl;
    cout << " Author: " << guts::KGRN << gauthor << guts::RST << 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;
}