appcli.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header is part of module \alib_app of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib::app {
 
///TODOX: Check ollama doxing ;-)
/// Application base class with integrated command-line processing.
///
/// This class extends #"App" with a ready-to-use command-line interface (CLI)
/// powered by module \alib_cli. It introduces a small set of additional bootstrap
/// states (methods) to define CLI options/commands, to import configuration influenced by CLI
/// arguments, and to optionally perform an early "dry-run" check. Subclasses typically extend and
/// customize the CLI in #"bsCLIDefine" and #"bsConfigureCLI" and may override the processing
/// loop via #"cliProcessCmd".
class AppCli : public App {
  protected:
 
 
  //--------------------------------------------- Types --------------------------------------------
    /// Additional bootstrap states executed by this class.
    /// Extends #"App::States;*" with custom phases. The states and their corresponding
    /// virtual methods are registered by the constructor.
    enum class States {
        CLIDefine          , ///< Inserted before #"States::ImportConfig": define CLI options and commands.
        CLIReadOptions     , ///< Inserted behind #"CLIDefine".
        ReadDryRunOption   , ///< Inserted before #"States::SetupALox": evaluate early flags (e.g., dry-run).
        ConfigureCLI       , ///< Inserted after  #"States::ImportConfig": finalize CLI setup based on config.
    };
 
  //--------------------------------------------- Fields -------------------------------------------
    /// The command-line parser provided by module \alib_cli.
    cli::CommandLine    cli;
 
    /// \brief Flag to stop the CLI processing loop.
    ///
    /// When set to \c true, no further commands from the command line are processed.
    /// Typical usage is the built-in or custom \c help command: once help text has been
    /// generated and printed, further command processing is not desired.
    bool    cliStop                                                                          =false;
 
  //---------------------------------------- Overriding Built --------------------------------------
    /// Maps an #"excep Exception" to an application exit code.
    /// @param exception The exception that terminated the run.
    /// \return An enumeration value convertible to an integer exit code.
    Enum   exceptionToExitCode( Exception& exception )                         override;
 
    /// Contributes configuration file locations.
    /// CLI arguments may affect which configuration files are considered. Subclasses can
    /// override #"getConfigFilePathsFromCLIParam" to implement CLI-based selection.
    /// @param files Output vector to append discovered file descriptors to.
    void         getConfigFilePaths(StdVectorMA<ConfigFileDescriptor>& files)        override;
 
    /// Called after the application's basic name, version and info have been determined.
    /// Allows adjusting CLI-visible metadata accordingly.
    void         onBsSetNameVersionAndInfo()                                               override;
 
    /// Preloads configuration variables, potentially seeding defaults based on early CLI
    /// evaluation performed in #"bsReadDryRunOption".
    void         onBsPreloadVariables()                                                    override;
 
    /// Signals the start of the application's run phase. May initialize CLI-dependent
    /// resources just before command processing begins.
    void         onRunStart()                                                              override;
 
    /// Main run method. The default implementation processes CLI commands until
    /// #"cliStop" is set or all commands are consumed.
    void         onRun()                                                                   override;
 
    /// Signals the end of the application's run phase. Cleanup that depends on CLI state
    /// can be performed here.
    void         onRunEnd()                                                                override;
 
  //-------------------------------------- New virtual methods -------------------------------------
    /// Implements #"States::CLIDefine": define CLI options, flags and commands.
    virtual void bsCLIDefine();
 
    /// Implements #"States::CLIReadOptions": calls #"CommandLine::ReadOptions;*" on
    /// member #".cli". This is done quite early in the boot sequence to allow option '--config'
    /// to change the configuration files used.
    virtual void bsCLIReadOptions();
 
    /// Implements #"States::ConfigureCLI": finalize CLI after configuration import.
    virtual void bsConfigureCLI();
 
    /// Implements #"States::ReadDryRunOption": evaluate early flags (e.g., --dry-run).
    virtual void bsReadDryRunOption();
 
    /// Used when errors are detected. May be overwritten, for example to suppress help output
    /// and/or otherwise change the standard behavior.
    /// @param exitCode     The exit code to that in field #"App::machine;*". Also used to
    ///                     write an error message by retrieving
    ///                     #"ExitCodeDecl::FormatString;*".
    /// @param helpTopic    An optional parameter that defines a topic for the help text written
    ///                     to #"App::cOut;*".
    /// @param formatParam1 An optional parameter to be used with the format string.
    /// @param formatParam2 An optional second parameter to be used with the format string.
    virtual void exitWithHelpOutput( Enum exitCode, const String& helpTopic= NULL_STRING,
                                     Box formatParam1 = EMPTY_STRING,
                                     Box formatParam2 = EMPTY_STRING );
 
    /// Adds configuration file paths influenced by a dedicated CLI parameter.
    /// Subclasses may parse a CLI option (for example, `--config <file>` or a search path)
    /// and append corresponding #"ConfigFileDescriptor" entries to \p files.
    /// @param files Output vector to append file descriptors to.
    virtual void getConfigFilePathsFromCLIParam(StdVectorMA<ConfigFileDescriptor>& files);
 
    /// Processes a single parsed CLI command.
    /// @param cmd The command to execute.
    /// \return \c true if the command was handled successfully; \c false to indicate that
    ///         the command was not recognized or could not be executed. Implementations
    ///         may set #"cliStop" to terminate further processing.
    virtual bool cliProcessCmd(cli::Command* cmd );
 
 
  public:
    /// \brief Constructs an instance and registers additional bootstrap states.
    AppCli();
};
 
} // namespace [app]