configBase.h

// Copyright 2009-2023 NTESS. Under the terms
// of Contract DE-NA0003525 with NTESS, the U.S.
// Government retains certain rights in this software.
//
// Copyright (c) 2009-2023, NTESS
// All rights reserved.
//
// This file is part of the SST software package. For license
// information, see the LICENSE file in the top level directory of the
// distribution.

#ifndef SST_CORE_CONFIGBASE_H
#define SST_CORE_CONFIGBASE_H

#include "sst/core/sst_types.h"

#include <functional>
#include <getopt.h>
#include <iostream>
#include <map>
#include <string>
#include <vector>

/* Forward declare for Friendship */
extern int main(int argc, char** argv);

namespace SST {

/**
   Struct that holds all the getopt_long options along with the
   docuementation for the option
*/
struct LongOption
{
    struct option                       opt;
    std::string                         argname;
    std::string                         desc;
    std::function<int(const char* arg)> callback;
    bool                                header; // if true, desc is actually the header
    bool                                sdl_avail;
    mutable bool                        set_cmdline;

    LongOption(
        struct option opt, const char* argname, const char* desc, const std::function<int(const char* arg)>& callback,
        bool header, bool sdl_avail, bool set_cmdline) :
        opt(opt),
        argname(argname),
        desc(desc),
        callback(callback),
        header(header),
        sdl_avail(sdl_avail),
        set_cmdline(set_cmdline)
    {}
};


// Macros to make defining options easier.  These must be called
// inside of a member function of a class inheriting from ConfigBase
// Nomenaclature is:

// FLAG - value is either true or false.  FLAG defaults to no arguments allowed
// ARG - value is a string.  ARG defaults to required argument
// OPTVAL - Takes an optional paramater

// longName - multicharacter name referenced using --
// shortName - single character name referenced using -
// text - help text
// func - function called if option is found
#define DEF_FLAG_OPTVAL(longName, shortName, text, func, sdl_avail) \
    addOption({ longName, optional_argument, 0, shortName }, "[BOOL]", text, func, false, sdl_avail);

#define DEF_FLAG(longName, shortName, text, func) \
    addOption({ longName, no_argument, 0, shortName }, "", text, func, false, false);

#define DEF_ARG(longName, shortName, argName, text, func, sdl_avail) \
    addOption({ longName, required_argument, 0, shortName }, argName, text, func, false, sdl_avail);

#define DEF_ARG_OPTVAL(longName, shortName, argName, text, func, sdl_avail) \
    addOption({ longName, optional_argument, 0, shortName }, "[" argName "]", text, func, false, sdl_avail);


#define DEF_SECTION_HEADING(text) \
    addOption({ "", optional_argument, 0, 0 }, "", text, std::function<int(const char* arg)>(), true, false);


/**
 * Base class to parse command line options for SST Simulation
 * Configuration variables.
 *
 * NOTE: This class contains only state for parsing the command line.
 * All options will be stored in classes derived from this class.
 * This means that we don't need to be able to serialize anything in
 * this class.
 */
class ConfigBase
{
protected:
    /**
       ConfigBase constructor.  Meant to only be created by main
       function
     */
    ConfigBase(bool suppress_print, bool suppress_sdl) : suppress_print_(suppress_print), suppress_sdl_(suppress_sdl) {}

    /**
       Default constructor used for serialization.  After
       serialization, the Config object is only used to get the values
       of set options and it can no longer parse arguments.  Given
       that, it will no longer print anything, so set suppress_print_
       to true. None of this class needs to be serialized because it
       it's state is only for parsing the arguments.
     */
    ConfigBase() : suppress_print_(true), suppress_sdl_(true) { options.reserve(100); }


    /**
       Called to print the help/usage message
    */
    int printUsage();


    /**
       Add options to the Config object.  The options will be added in
       the order they are in the input array, and across calls to the
       function.
     */
    void addOption(
        struct option opt, const char* argname, const char* desc, std::function<int(const char* arg)> callback,
        bool header, bool sdl_avail);

    /**
       Called to get the prelude for the help/usage message
     */
    virtual std::string getUsagePrelude();

    // Function that will be called at the end of parsing so that
    // error checking can be done
    virtual int checkArgsAfterParsing();

    // Enable support for everything after -- to be passed to a
    // callback. Each arg will be passed independently to the callback
    // function
    void enableDashDashSupport(std::function<int(const char* arg)> callback);

    // Add support for positional args.  Must be added in the order the
    // args show up on the command line
    void addPositionalCallback(std::function<int(int num, const char* arg)> callback);


    /**
       Get the name of the executable being run.  This is only
       avaialable after parseCmdLine() is called.
     */
    std::string getRunName() { return run_name_; }

    /** Set a configuration string to update configuration values */
    bool setOptionExternal(const std::string& entryName, const std::string& value);

public:
    // Function to uniformly parse boolean values for command line
    // arguments
    static bool parseBoolean(const std::string& arg, bool& success, const std::string& option);

    virtual ~ConfigBase() {}

    /**
       Parse command-line arguments to update configuration values.

       @return Returns 0 if execution should continue.  Returns -1 if
         there was an error.  Returns 1 if run command line only asked
         for information to be print (e.g. --help or -V, for example).
     */
    int parseCmdLine(int argc, char* argv[], bool ignore_unknown = false);


private:
    std::vector<LongOption>                      options;
    std::map<char, int>                          short_options;
    std::string                                  short_options_string;
    size_t                                       longest_option = 0;
    size_t                                       num_options    = 0;
    std::function<int(const char* arg)>          dashdash_callback;
    std::function<int(int num, const char* arg)> positional_args;

    std::string run_name_;
    bool        suppress_print_;
    bool        suppress_sdl_;
};

} // namespace SST

#endif // SST_CORE_CONFIGBASE_H