|
ALib C++ Framework
|
by |  |
|
Loading...
Searching...
No Matches
|
ALib C++ Framework
|
by | |
|
This is a central class of library module ALib App.
For information about general use and features of this class consult the ALib App User Manual.
Inner Type Index: | |
| struct | ConfigFileDescriptor |
| struct | StateMachine |
Public Type Index: | |
| enum class | BuiltInExitCodes { OK = 0 , ErrConfigFileNotFound = 10 , ErrConfigFileNotWritable = 11 , ErrUnknown = 127 } |
| enum class | Exceptions { ControlledEarlyExit } |
Protected Type Index: | |
| 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: | |
| 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: | |
| App (camp::Camp *appCamp) | |
| virtual | ~App () |
| Virtual destructor. | |
|
strong |
Built-in exit-codes of the ALib application. The underlying integer values may be used by a descendant application as the result of C/C++ method main().
They are provided here rather as a sample and to be able to provide a default implementation of the method exceptionToExitCode. In the case that an application desires to use different exit codes, the latter method has to be overridden.
When using the derived class AppCli, this enumeration gets the according ALib Enum Records assigned and default resources are defined.
|
strong |
Generic Exceptions handled by class App. This enumeration contains only one single entry.
| Enumerator | |
|---|---|
| ControlledEarlyExit | This exception is used to support the exception/error/exit code paradigm introduced by class App.
|
|
strongprotected |
Configuration flags used with class App.
| Enumerator | |
|---|---|
| NONE | No flags set. |
| CreateReleaseLox | If set, method virtual void onBsSetupALox() will create a release Lox instance available via field virtual lox::Lox * GetRLox() , as well as an attached logger available via field virtual lox::textlogger::TextLogger * GetRLogger() . |
| UseReleaseLoggerForDebugLogging | If set, method virtual void onBsSetupALox() will create and attach the release logger to the debug Lox Lox. |
| ALoxVerbosityExportAllAndWriteBackRelLogger | If set, method virtual void onSdExportConfig() adds 'ExportAll' and 'writeback' to the verbosity variable of the lox::textlogger::TextLogger * releaseLogger in the case that this variable had not been read from the INI file with virtual void onBsImportConfig() . |
| ALoxVerbosityExportAllAndWriteBackDbgLogger | If set, method virtual void onSdExportConfig() adds 'ExportAll' and 'writeback' to the verbosity variable of the debug-logger in the case that this variable had not been read from the INI file with virtual void onBsImportConfig() . |
|
strongprotected |
The predefined states of the simple linear state-machine implemented by outer class App. For each state, a corresponding virtual function exists. The pairs of states and the corresponding virtual functions are collected in the field StateMachine::Program.
Custom applications (derived from class App) define their own enum type in case they want to insert additional pairs of state/methods into the program. This is possible because the collection of states in the field StateMachine::Program is implemented as type Enum, which may hold enumeration elements of an arbitrary type.
Note that the numbering of the enum elements is not of importance. The numbers found here were chosen to be quickly identifiable while debugging. The simple scheme is:
Also, the numbers are not defining the order of execution, which is solely defined by the order in the vector StateMachine::Program.
The custom enumeration type used for potential custom states may but does not need to align. It even may have the same integral values as given here. This flexibility is gained by the little magic of class Enum introduced by module ALib Boxing.
| Enumerator | |
|---|---|
| NOT_STARTED | Initial state before starting the App. The starting state not associated with a method. |
| SetCamps | Invokes the virtual method onBsSetCamps. |
| PrepareResources | Invokes the virtual method onBsPrepareResources. |
| SetNameVersionAndInfo | Invokes the virtual method onBsSetNameVersionAndInfo. |
| PrepareConfig | Invokes the virtual method onBsPrepareConfig. |
| PreloadVariables | Invokes the virtual method onBsPreloadVariables. |
| ImportConfig | Invokes the virtual method onBsImportConfig. |
| FinalizeBootstrap | Invokes the virtual method onBsFinalizeBootstrap. |
| SetupALox | Invokes the virtual method onBsSetupALox. |
| RunStart | Invokes the virtual method onRunStart. |
| Run | Invokes the virtual method onRun. |
| RunEnd | Invokes the virtual method onRunEnd. |
| AnnounceShutdown | Invokes the virtual method onSdAnnounceShutdown. |
| CleanALox | Invokes the virtual method onSdCleanALox. |
| ExportConfig | Invokes the virtual method onSdExportConfig. |
| Output | Invokes the virtual method onSdOutput. |
| FinalizeShutdown | Invokes the virtual method onSdFinalizeShutdown. |
| CNTD_BUILTIN_STATES | The number of built-in states. Only used for reserving the 'program's' capacity. |
|
protected |
The main camp of the application. This is where resources are loaded from.
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
Used to assemble and collect the output for standard output character stream std::cout during the run of this application.
The collected output is scheduled to be written by the method onSdOutput. This method, may also be "manually" invoked at any time to flush the current buffers to the output streams.
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
Constructor. Initializes this app. Mainly by filling the vector StateMachine::Program with all states found in the enumeration States along with the corresponding virtual methods.
While the parameter appCamp is optional, it is intentionally not provided with a default value of nullptr. Derived types should create and provide a custom camp here (See the Programmer's Manual of the module ALib Camp). If it is missing, many default implementations of the virtual methods render useless, and return instantly.
If not given, it will be set in the default implementation of the method onBsSetCamps to the last camp in the list CAMPS. If given that default implementation will add it to the end of this list.
| appCamp | An optional camp instance to search resources in. |
|
protectedvirtual |
|
virtual |
Writes exception information to std::cerr
.
| exception | The exception that was thrown. |
| target | The target string to write into. An option is to pass cErr->Buffer here. Of course a custom buffer might be passed, i.e. if the text is to be logged with ALox. |
|
virtual |
Todo: This implementation does not do the same as CLIUtil::GetExitCode. Das muss noch eingebaut werden, oder? Oder wir bauen es lieber nicht ein und ändern den Text hier. Schließlich kann das die AppCLi machen. TODO(251208 17:30): Also insgesamt ist das noch ne größere Baustelle/Design Problem!!! Zusammen mit der nächsten method exceptionDisplay Es ist wirklich schwierig. Wo ist es am besten Exit codes zu erzeugen und den cErr Text dazu? Exceptions zu werfen ist schon blöd. Dann muss man sich die ganzen Infos wieder rausziehen. Andererseits hat man es dann wirklich an einer stelle. Aber an dieser Stelle fehlen dann manche dinge. Zb. File not open. Tja, ok nicht nur welches file? Manchmal gibt es auch von file-typen mehrere. Zb. beim DoxygenXLinks mehrere tag-files. Es wäre dann schon schön zu wissen woher die Info über das Tag-file käme. Also bewegt man sich na oben im callstack zur stelle wo es auftritt, und wirft erst gar keine Exception. Tja, dann muss man den ganzen Stack alleine abbauen (also überall den exit code durchreichen und ihn abfragen. Das geht nicht. Dazhu sind ja exceptions da. Vielleicht sollte man eine einzige Exception zulassen, nämlich eine built-in "Handled Exception" Bevor die geworfen wird, wird eine ordentlich Ausgabe ins CErr geworfen und der ExitCode wird als parameter in die exception mit reingegeben. Ja, das ist ein guter Ansatz. Die App muss dann cOut und cErr public freigeben. Dass kann aber auch die abgeleitete MyApp machen. Aber so ginge es: überall wo ein ExitCode auftritt wird dieser in einer Exception gekapselt und diese exception wird geworfen. Und diese zwei Funktionen hier können ja dennoch da bleiben. Vielleicht etwas hübscher ...hab schon mal angefangen damit und die exception eingebaut.
Translates exceptions to exit-codes of the application. This default implementation performs similarly to static integer GetExitCode(CommandLine&, Exception&) to convert command-line exceptions to exit-codes. Thus, if all exceptions have an exit-code conversion defined, there is no need to override this method.
Implementations should call this method first and, if necessary, perform their own conversions then. If they do so, they should check whether this default version returned BuiltInExitCodes::ErrUnknown, perform their own translation in that case and probably debug-assert on failure.
| exception | The exception that was thrown. |
Reimplemented in alib::app::AppCli.
|
virtual |
This default implementation in turn calls the virtual helper methods getConfigFilePathsFromResources and getConfigFilePathsMakeAbsolutePaths.
| files | A pointer to an object of type StdVectorMA<ConfigFileDescriptor> that is to be filled by this method. |
Reimplemented in alib::app::AppCli.
|
virtual |
If the given vector files is empty, this method tries resources named "CFGF_NAME_1", "CFGF_NAME_2", "CFGF_NAME_3" and so forth until a first name is not found. For all names found, an entry in vector files is created.
Then, for each entry in the vector (regardless if they were preexisting or created with this method), comment information is loaded from resources. The resource name is composed from "CFGF_CMT_" and the number of the entry. If found, the resource is assigned to the field String Comment.
Then for each entry resources named "CFGF_EXP_" and the number of the entry are searched. If found, the field String Exports is set. If more resources (with higher numbers) are existing, such additional exports are appended to the list of the last config file entry.
| files | The vector of file paths that is to be filled or modified by this method. |
|
virtual |
|
inline |
|
inline |
|
inlinevirtual |
|
inlinevirtual |
|
inline |
|
virtual |
Stores cli-parameters and executes this app.
| argc | The number of command-line arguments. |
| argv | List of command-line arguments, given as single byte character strings. |
| argvw | The CLI arguments on platforms that use wide command-line strings. Defaults to nullptr. If given, parameter argv has to be nulled. |
main().
|
virtual |
Called on transition to state FinalizeBootstrap.
This default implementation just calls the function Bootstrap passing BootstrapPhases::Final as the parameter.
|
virtual |
Called on transition to state ImportConfig.
This default implementation creates the vector of file descriptors using getConfigFilePaths and then uses type IniFileFeeder to import the variables from the INI-files.
|
virtual |
Called on transition to state PreloadVariables.
Preloading variables allows later fetching and exporting those variables into a configuration file (if freshly created), even if they have not been read/used in the first run of an application.
This default implementation calls void PreloadVariables() on the variables found with the enumeration Variables.
Reimplemented in alib::app::AppCli.
|
virtual |
Called on transition to state PrepareConfig.
This default implementation just calls the function Bootstrap passing BootstrapPhases::PrepareConfig as the parameter.
|
virtual |
Called on transition to state PrepareResources.
This default implementation
std::cout.
|
virtual |
Called on transition to state SetCamps.
This default implementation calls the BootstrapAddDefaultCamps and then adds camp appCamp to the end of that list. In case field appCamp is nulled, rather the opposite is done: the field is set to point to the end of the list.
|
virtual |
Called on transition to state SetNameVersionAndInfo.
This default implementation tries resources "AppName", "AppVersion", and "AppInfo" to set fields appName, appVersion, and appInfo. The latter is supported with three placeholders: the name, the version, and the current year and is created using the method Paragraphs & AddMarked(const BoxedObjects& ...) .
A string that is set before this method is called, is not replaced.
Reimplemented in alib::app::AppCli.
|
virtual |
Called on transition to state SetupALox.
If this method returns an error, bootstrapping is aborted. This default implementation interprets the flags CreateReleaseLox and UseReleaseLoggerForDebugLogging, and furthermore uses the fields releaseLoxName and releaseLoggerName into account and potentially creates releaseLox and releaseLogger.
|
pure virtual |
This is the main execution method of the application. The default-implementation is not just empty, but is (the only) abstract method of this class.
Implemented in alib::app::AppCli.
|
inlinevirtual |
This method is following the main execution method onRun. Overwriting this method is useful to collect code which has to be executed at the end of all (or most) execution paths of the custom implementation of onRun.
Reimplemented in alib::app::AppCli.
|
inlinevirtual |
This method is preceding the main execution method onRun. When this is called, all bootstrapping is done. Final preparations might be performed here to unclutter onRun.
Reimplemented in alib::app::AppCli.
|
virtual |
Called on transition to state AnnounceShutdown.
This default implementation just calls the function Shutdown passing ShutdownPhases::Announce as the parameter.
|
virtual |
Called on transition to state CleanALox.
This default implementation checks the flags ALoxVerbosityExportAllAndWriteBackRelLogger, and ALoxVerbosityExportAllAndWriteBackDbgLogger and calls bool SetVerbosityExport(Lox*, bool, Priority) if set.
Then, if set, the release logger and Lox are deleted.
|
virtual |
Called on transition to state ExportConfig.
This default implementation creates the vector of file descriptors using getConfigFilePaths and then uses type IniFileFeeder to export variables that are either not existing yet, or which have a writeback flag set, into the INI-files.
This is done for all variables (and variable trees) determined by the field String Exports.
|
virtual |
Called on transition to state FinalizeShutdown.
This default implementation calls the function Shutdown passing ShutdownPhases::Destruct as the parameter.
Prior to that, some memory cleaning and debug exercises are done.
|
virtual |
Flushes what is collected in the fields cOut and cErr to their respective streams and clears the buffers. With that, this method - while named with the prefix onSd and scheduled at the end of the StateMachine::Program - may be directly called by descendants whenever they wish to flush the current collected output stream, for example, after important milestones, before long-running operations, or prior to program termination when early partial output is desired.
|
virtual |