Description:

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.

Definition at line 19 of file appcli.inl.

Inheritance diagram for alib::app::AppCli:

Public Method Index:
	AppCli ()
	Constructs an instance and registers additional bootstrap states.
Public Method Index: inherited from alib::app::App
virtual void	exceptionDisplay (Exception &exception, AString &target)
virtual void	getConfigFilePathsFromResources (StdVectorMA< ConfigFileDescriptor > &files)
virtual void	getConfigFilePathsMakeAbsolutePaths (StdVectorMA< ConfigFileDescriptor > &files)
String	GetInfo ()
String	GetName ()
virtual lox::textlogger::TextLogger *	GetRLogger ()
virtual lox::Lox *	GetRLox ()
String	GetVersion ()
virtual int	Main (int argc, const char argv, const wchar_t argvw=nullptr)
virtual void	onBsFinalizeBootstrap ()
virtual void	onBsImportConfig ()
virtual void	onBsPrepareConfig ()
virtual void	onBsPrepareResources ()
virtual void	onBsSetCamps ()
virtual void	onBsSetupALox ()
virtual void	onSdAnnounceShutdown ()
virtual void	onSdCleanALox ()
virtual void	onSdExportConfig ()
virtual void	onSdFinalizeShutdown ()
virtual void	onSdOutput ()
virtual void	printConfigFileInfo (Paragraphs &target)

Protected Type Index:
enum class	States { CLIDefine , CLIReadOptions , ReadDryRunOption , ConfigureCLI }
Protected Type Index: inherited from alib::app::App
enum class	Flags { NONE = 0 , CreateReleaseLox =(1<<0) , UseReleaseLoggerForDebugLogging =(1<<1) , ALoxVerbosityExportAllAndWriteBackRelLogger =(1<<2) , ALoxVerbosityExportAllAndWriteBackDbgLogger =(1<<3) }
	Configuration flags used with class App. More...
enum class	States { NOT_STARTED = 0 , SetCamps = 11 , PrepareResources = 12 , SetNameVersionAndInfo = 13 , PrepareConfig = 21 , PreloadVariables = 22 , ImportConfig = 23 , FinalizeBootstrap = 31 , SetupALox = 33 , RunStart =100 , Run =111 , RunEnd =120 , AnnounceShutdown =910 , CleanALox =920 , ExportConfig =930 , Output =940 , FinalizeShutdown =950 , CNTD_BUILTIN_STATES = 16 }

Protected Field Index:
cli::CommandLine	cli
	The command-line parser provided by module ALib CLI.
bool	cliStop =false
	Flag to stop the CLI processing loop.
Protected Field Index: inherited from alib::app::App
camp::Camp *	appCamp =nullptr
String	appInfo =nullptr
String	appName =nullptr
String	appVersion =nullptr
Paragraphs *	cErr =nullptr
	Same as cOut, but used for stream `std::err`.
Paragraphs *	cOut =nullptr
Flags	flags =Flags::NONE
	Various boolean flags used to configure the application.
StateMachine	machine
	The state-machine singleton.
lox::textlogger::TextLogger *	releaseLogger =nullptr
String	releaseLoggerName =A_CHAR("RLOGGER")
lox::Lox *	releaseLox =nullptr
String	releaseLoxName =A_CHAR("RLOX")
StopWatch	stopWatch

Protected Method Index:
virtual void	bsCLIDefine ()
	Implements CLIDefine: define CLI options, flags and commands.
virtual void	bsCLIReadOptions ()
virtual void	bsConfigureCLI ()
	Implements ConfigureCLI: finalize CLI after configuration import.
virtual void	bsReadDryRunOption ()
	Implements ReadDryRunOption: evaluate early flags (e.g., –dry-run).
virtual bool	cliProcessCmd (cli::Command *cmd)
Enum	exceptionToExitCode (Exception &exception) override
virtual void	exitWithHelpOutput (Enum exitCode, const String &helpTopic=NULL_STRING, Box formatParam1=EMPTY_STRING, Box formatParam2=EMPTY_STRING)
void	getConfigFilePaths (StdVectorMA< ConfigFileDescriptor > &files) override
virtual void	getConfigFilePathsFromCLIParam (StdVectorMA< ConfigFileDescriptor > &files)
void	onBsPreloadVariables () override
void	onBsSetNameVersionAndInfo () override
void	onRun () override
void	onRunEnd () override
void	onRunStart () override
Protected Method Index: inherited from alib::app::App
	App (camp::Camp *appCamp)
virtual	~App ()
	Virtual destructor.

Additional Inherited Members
Public Type Index: inherited from alib::app::App
enum class	BuiltInExitCodes { OK = 0 , ErrConfigFileNotFound = 10 , ErrConfigFileNotWritable = 11 , ErrUnknown = 127 }
enum class	Exceptions { ControlledEarlyExit }

Enumeration Details:

◆ States

enum class alib::app::AppCli::States

strongprotected

Additional bootstrap states executed by this class. Extends States with custom phases. The states and their corresponding virtual methods are registered by the constructor.

Enumerator
CLIDefine	Inserted before ImportConfig: define CLI options and commands.
CLIReadOptions	Inserted behind CLIDefine.
ReadDryRunOption	Inserted before SetupALox: evaluate early flags (e.g., dry-run).
ConfigureCLI	Inserted after ImportConfig: finalize CLI setup based on config.

Definition at line 27 of file appcli.inl.

Field Details:

◆ cli

cli::CommandLine alib::app::AppCli::cli

protected

The command-line parser provided by module ALib CLI.

Definition at line 36 of file appcli.inl.

◆ cliStop

bool alib::app::AppCli::cliStop =false

protected

Flag to stop the CLI processing loop.

When set to true, no further commands from the command line are processed. Typical usage is the built-in or custom help command: once help text has been generated and printed, further command processing is not desired.

Definition at line 43 of file appcli.inl.

Constructor(s) / Destructor Details:

◆ AppCli()

alib::app::AppCli::AppCli ( )

Constructs an instance and registers additional bootstrap states.

Definition at line 38 of file appcli.cpp.

Method Details:

◆ bsCLIDefine()

void alib::app::AppCli::bsCLIDefine ( )

protectedvirtual

Implements CLIDefine: define CLI options, flags and commands.

Definition at line 87 of file appcli.cpp.

◆ bsCLIReadOptions()

void alib::app::AppCli::bsCLIReadOptions ( )

protectedvirtual

Implements CLIReadOptions: calls virtual void ReadOptions() on member cli. This is done quite early in the boot sequence to allow option '–config' to change the configuration files used.

Definition at line 95 of file appcli.cpp.

◆ bsConfigureCLI()

void alib::app::AppCli::bsConfigureCLI ( )

protectedvirtual

Implements ConfigureCLI: finalize CLI after configuration import.

Definition at line 97 of file appcli.cpp.

◆ bsReadDryRunOption()

void alib::app::AppCli::bsReadDryRunOption ( )

protectedvirtual

Implements ReadDryRunOption: evaluate early flags (e.g., –dry-run).

Definition at line 109 of file appcli.cpp.

◆ cliProcessCmd()

bool alib::app::AppCli::cliProcessCmd ( cli::Command * cmd )

protectedvirtual

Processes a single parsed CLI command.

Parameters

cmd	The command to execute.

Returns: true if the command was handled successfully; false to indicate that the command was not recognized or could not be executed. Implementations may set cliStop to terminate further processing.

Definition at line 246 of file appcli.cpp.

◆ exceptionToExitCode()

alib::Enum alib::app::AppCli::exceptionToExitCode ( alib::Exception & exception )

overrideprotectedvirtual

Maps an Exception to an application exit code.

Parameters

exception The exception that terminated the run.

Returns: An enumeration value convertible to an integer exit code.

Reimplemented from alib::app::App.

Definition at line 54 of file appcli.cpp.

◆ exitWithHelpOutput()

void alib::app::AppCli::exitWithHelpOutput	(	Enum	exitCode,
		const String &	helpTopic = NULL_STRING,
		Box	formatParam1 = EMPTY_STRING,
		Box	formatParam2 = EMPTY_STRING )

protectedvirtual

Used when errors are detected. May be overwritten, for example to suppress help output and/or otherwise change the standard behavior.

Parameters

exitCode	The exit code to that in field StateMachine machine. Also used to write an error message by retrieving const String & FormatString() .
helpTopic	An optional parameter that defines a topic for the help text written to Paragraphs * cOut.
formatParam1	An optional parameter to be used with the format string.
formatParam2	An optional second parameter to be used with the format string.

Definition at line 191 of file appcli.cpp.

◆ getConfigFilePaths()

void alib::app::AppCli::getConfigFilePaths ( StdVectorMA< ConfigFileDescriptor > & files )

overrideprotectedvirtual

Contributes configuration file locations. CLI arguments may affect which configuration files are considered. Subclasses can override getConfigFilePathsFromCLIParam to implement CLI-based selection.

Parameters

files Output vector to append discovered file descriptors to.

Reimplemented from alib::app::App.

Definition at line 133 of file appcli.cpp.

◆ getConfigFilePathsFromCLIParam()

void alib::app::AppCli::getConfigFilePathsFromCLIParam ( StdVectorMA< ConfigFileDescriptor > & files )

protectedvirtual

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 files.

Parameters

files Output vector to append file descriptors to.

Definition at line 138 of file appcli.cpp.

◆ onBsPreloadVariables()

void alib::app::AppCli::onBsPreloadVariables ( )

overrideprotectedvirtual

Preloads configuration variables, potentially seeding defaults based on early CLI evaluation performed in bsReadDryRunOption.

Reimplemented from alib::app::App.

Definition at line 128 of file appcli.cpp.

◆ onBsSetNameVersionAndInfo()

void alib::app::AppCli::onBsSetNameVersionAndInfo ( )

overrideprotectedvirtual

Called after the application's basic name, version and info have been determined. Allows adjusting CLI-visible metadata accordingly.

Reimplemented from alib::app::App.

Definition at line 77 of file appcli.cpp.

◆ onRun()

void alib::app::AppCli::onRun ( )

overrideprotectedvirtual

Main run method. The default implementation processes CLI commands until cliStop is set or all commands are consumed.

Implements alib::app::App.

Definition at line 200 of file appcli.cpp.

◆ onRunEnd()

void alib::app::AppCli::onRunEnd ( )

overrideprotectedvirtual

Signals the end of the application's run phase. Cleanup that depends on CLI state can be performed here.

Reimplemented from alib::app::App.

Definition at line 234 of file appcli.cpp.

◆ onRunStart()

void alib::app::AppCli::onRunStart ( )

overrideprotectedvirtual

Signals the start of the application's run phase. May initialize CLI-dependent resources just before command processing begins.

Reimplemented from alib::app::App.

Definition at line 163 of file appcli.cpp.

The documentation for this class was generated from the following files:

Description:

Public Method Index:

Protected Type Index:

Protected Field Index:

Protected Method Index:

Additional Inherited Members

Enumeration Details:

◆ States

Field Details:

◆ cli

◆ cliStop

Constructor(s) / Destructor Details:

◆ AppCli()

Method Details:

◆ bsCLIDefine()

◆ bsCLIReadOptions()

◆ bsConfigureCLI()

◆ bsReadDryRunOption()

◆ cliProcessCmd()

◆ exceptionToExitCode()

◆ exitWithHelpOutput()

◆ getConfigFilePaths()

◆ getConfigFilePathsFromCLIParam()

◆ onBsPreloadVariables()

◆ onBsSetNameVersionAndInfo()

◆ onRun()

◆ onRunEnd()

◆ onRunStart()