app.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file 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 { namespace app {
 
//==================================================================================================
/// This is a central class of library module \alib_app_nl.
///
/// For information about general use and features of this class consult the
/// #"alib::app;ALib App User Manual".
//==================================================================================================
class App {
  public:
  //================================================================================================
  // App Inner Types
  //================================================================================================
 
  //=========================================== Exceptions =========================================
    /// Generic Exceptions handled by class #"App".
    /// This enumeration contains only one single entry.
    enum class Exceptions {
        /// This exception is used to support the exception/error/exit code paradigm introduced
        /// by class #"App".
        /// @see A detailed description on the usage of this exception is given in chapter
        ///      #"alib_app_controlledearlyexit" of the Programmer's Manual of the
        ///      module \alib_app.
        ControlledEarlyExit,
    };
 
 
  //=========================================== ExitCodes ==========================================
    /// 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 \c main().<br>
    /// 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_enums_records;ALib Enum Records" assigned and default resources are defined.
    enum class BuiltInExitCodes
    {
        OK                      =   0, ///< Success.
        ErrConfigFileNotFound   =  10, ///< The default configuration file(s), or that (those)
                                       ///< specified by option '--config', could not be found
                                       ///< or read.
        ErrConfigFileNotWritable=  11, ///< The configuration file(s) could not be written.
        ErrUnknown              = 127, ///< An unknown exception occurred.
    };
 
 
  protected:
  //============================================= Flags ============================================
    /// Configuration flags used with class #"App".
    enum class Flags {
        /// No flags set.
        NONE                                          = 0   ,
 
        /// If set, method #"App::onBsSetupALox;*" will create a release #"Lox"
        /// instance available via field #"App::GetRLox;*", as well as an attached logger
        /// available via field #"App::GetRLogger;*".
        CreateReleaseLox                              =(1<<0),
 
        /// If set, method #"App::onBsSetupALox;*" will create and attach the release
        /// logger to the debug \b Lox #"Lox".
        UseReleaseLoggerForDebugLogging               =(1<<1),
 
        /// If set, method #"App::onSdExportConfig;*" adds 'ExportAll' and 'writeback' to the
        /// verbosity variable of the #"App::releaseLogger;*" in the case that this variable
        /// had not been read from the INI file with #"App::onBsImportConfig;*".
        ALoxVerbosityExportAllAndWriteBackRelLogger   =(1<<2),
 
        /// If set, method #"App::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 #"App::onBsImportConfig;*".
        ALoxVerbosityExportAllAndWriteBackDbgLogger   =(1<<3),
    };
 
 
  //============================================= States ===========================================
    /// 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;2".<br>
    /// Custom applications (derived from class \b %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;2" is implemented as type #"boxing::Enum", which may
    /// hold enumeration elements of an arbitrary type.
    ///
    /// Note that the numbering of the enum elements is \b not of importance. The numbers
    /// found here were chosen to be quickly identifiable while debugging.
    /// The simple scheme is:
    /// - 1x: Bootstrap phase resources. (See also #"BootstrapPhases").
    /// - 2x: Bootstrap phase configuration/variables.
    /// - 3x: Bootstrap phase finalization.
    /// - 1xx: running phase.
    /// - 9xx: shutdown phase. (See also #"ShutdownPhases").
    ///
    /// Also, the numbers are \b not defining the order of execution, which is solely defined by
    /// the order in the vector #"StateMachine::Program;2".<br>
    ///
    /// 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 #"boxing::Enum" introduced by module \alib_boxing.
    enum class States {
        /// Initial state before starting the App.
        NOT_STARTED         = 0, ///< The starting state not associated with a method.
 
          //---------------------------------- initialize resources --------------------------------
            SetCamps             = 11 , ///< Invokes the virtual method #"onBsSetCamps".
            PrepareResources     = 12 , ///< Invokes the virtual method #"onBsPrepareResources".
            SetNameVersionAndInfo= 13 , ///< Invokes the virtual method #onBsSetNameVersionAndInfo.
            // 3
          //------------------------ Initialize camps on configuration level -----------------------
            PrepareConfig        = 21, ///< Invokes the virtual method #onBsPrepareConfig.
            PreloadVariables     = 22, ///< Invokes the virtual method #onBsPreloadVariables.
            ImportConfig         = 23, ///< Invokes the virtual method #onBsImportConfig.
            // 6
 
          //--------------------------- After alib::BootstrapPhases::Final -------------------------
            FinalizeBootstrap    = 31, ///< Invokes the virtual method #onBsFinalizeBootstrap.
            SetupALox            = 33, ///< Invokes the virtual method #onBsSetupALox.
            // 9
 
          //------------------------------------ The custom code -----------------------------------
            RunStart             =100, ///< Invokes the virtual method #onRunStart.
            Run                  =111, ///< Invokes the virtual method #onRun.
            RunEnd               =120, ///< Invokes the virtual method #onRunEnd.
            // 12
 
          //---------------------------------------- Shutdown --------------------------------------
            AnnounceShutdown     =910, ///< Invokes the virtual method #onSdAnnounceShutdown.
            CleanALox            =920, ///< Invokes the virtual method #onSdCleanALox.
            ExportConfig         =930, ///< Invokes the virtual method #onSdExportConfig.
            Output               =940, ///< Invokes the virtual method #onSdOutput.
            FinalizeShutdown     =950, ///< Invokes the virtual method #onSdFinalizeShutdown.
            // 16
 
        CNTD_BUILTIN_STATES = 16 ///< The number of built-in states.
                                 ///< Only used for reserving the 'program's' capacity.
    };
 
  //========================================== StateMachine ========================================
    /// This struct is used a single time with the member #machine and comprises all
    /// fields associated with the state of the application and the execution of the 'program'.
    struct StateMachine {
 
      //=================================== StateMachine::Command ==================================
        /// A struct denoting the next state and the corresponding method to execute.
        struct Command {
            /// A union holding either a pointer to a virtual method of class \b App or one to
            /// a non-virtual method of a different type.
            union MethodPointer{
                /// A pointer to a virtual method of class \b %App.
                void (App::*BuiltIn)();
 
                /// A pointer to a method of a custom derived type.
                void      (*Custom )(App&);
 
                /// Constructor accepting a pointer to a virtual method of class \b %App.
                /// @param method   The method to call.
                MethodPointer( void (App::*method)()     ) : BuiltIn(method)                      {}
 
                /// Constructor accepting a pointer to a non-virtual method of a derived type.
                /// @param method   The non-virtual method of a derived type.
                MethodPointer( void (     *method)(App&) ) : Custom (method)                      {}
            };
 
            /// The identifier of the command which is likewise the state of the machine.
            /// During execution, this identifier will be stored in the member
            /// #"StateMachine::State" of the outer class \b %StateMachine.
            /// In case it is a built-in identifier of type #"App::States", it will
            /// be stored in addition in its field
            /// #"App::StateMachine::BuiltInState".
            Enum            State;
 
            /// A pointer union to either a built-in virtual method or a method of the custom
            /// derived type.
            MethodPointer   Method;
 
 
            /// A static helper-function that creates a custom command, i.e. a command that is
            /// not built-in and as such is not executing one of the pre-defined virtual methods
            /// of class #"App".
            /// Instead, it is executing a non-virtual member of the given type \p{TDerived}, which
            /// is usually the descendant singleton-type, that is implementing the custom
            /// application.
            /// \note For technical reasons, the invocation of this static function is a little
            ///       counter-intuitive. The two template parameters have to be explicitly provided,
            ///       where the second is the address of the custom method! (This is C++ 20 magic).
            ///       The only normal parameter then is the custom enumeration element.
            /// @tparam TDerived        The enclosing type of the method. This usually is the
            ///                         custom implementation type of class \b %App.
            /// @tparam TMethodAddress  The address of the member which is to be called with this
            ///                         command.
            /// @param  state           The enum element (of a custom type) to identify the command
            ///                         and define the state of the machine during execution.
            /// @return The command object.
            template<typename TDerived, auto TMethodAddress >
            static Command MakeCustom(Enum state) {
 
                struct Helper {
                    static void Wrapper(App& base) {
                        auto& self = static_cast<TDerived&>(base);
                        (self.*TMethodAddress)();
                    }
                };
 
                return Command { state, &Helper::Wrapper };
            }
        };
 
      //================================= StateMachine::CommandList ================================
        /// A list of pairs of states and corresponding methods to process.
        /// This struct is used only once, namely with the field #"StateMachine::Program;2".
        /// The constructor of class \b App fills this list with all commands defined in the
        /// enumeration #"App::States;*".
        /// While the insertion methods #"CommandList::AddBefore" and #"CommandList::AddAfter"
        /// are provided for convenience, more complex manipulation of the list is allowed using
        /// the interface inherited from <c>std::vector</c>.
        struct CommandList : std::vector<Command> {
 
            /// Adds a custom execution command (and state) before the given \p{cmd}.
            /// @see The helper-method #"App::StateMachine::Command::MakeCustom;*"
            ///      should be used to create the command that is to be provided as parameter
            ///      \p{cmd}.
            /// @param anchor The associated state to search in this vector and use as the
            ///               insertion place.<br>
            ///               If \c nullptr is passed, \p{cmd} will be inserted at the end of the
            ///               list.
            /// @param cmd    The command to be added.
            void AddBefore( Enum anchor, const Command& cmd ) {
                auto it= end();
                if ( anchor.IsNotNull()  )
                    for ( it= begin() ; it!= end() && it->State != anchor ; ++it)
                        ;
 
                ALIB_ASSERT_ERROR(anchor.IsNull() || it!=end(), "APP","Command anchor not found")
 
                insert(it, cmd );
            }
            /// Adds a custom execution command (and state) after the given \p{cmd}.
            /// @see The helper-method #"App::StateMachine::Command::MakeCustom;*"
            ///      should be used to create the command that is to be provided as parameter
            ///      \p{cmd}.
            /// @param anchor The associated state to search in this vector and use as the
            ///               insertion place.<br>
            ///               If \c nullptr is passed, \p{cmd} will be inserted at the beginning of
            ///               the list.
            /// @param cmd    The command to be added.
            void AddAfter( Enum anchor, const Command& cmd ) {
                auto it= begin();
                if ( anchor.IsNotNull()  )
                    for ( ; it!= end() && it->State != anchor ; ++it)
                        ;
 
                ALIB_ASSERT_ERROR(anchor.IsNull() || it!=end(), "APP","Command anchor not found")
 
                insert(it== end() ? begin() : it + 1, cmd );
            }
        };
 
      //==================================== StateMachine Fields ===================================
      protected:
        /// The exit code. Only the first set is stored and returned later.
        Enum    exitCode                                                      =BuiltInExitCodes::OK;
 
        #if ALIB_DEBUG
        /// This vector collects exit codes which are not used, as they got set
        /// after a first code was given. This field is available in debug-compilations only.
        std::vector<Enum> dbgFurtherExitCodes;
        #endif
        
      //=================================== StateMachine Interface =================================
      public:
        /// The list of commands to execute.
        CommandList  Program;
 
        /// The current state in respect to the built-in program commands. Note that this is
        /// not of type #"boxing::Enum", but uses the original C++ enum type.
        /// Consequently, this is only updated when a built-in command is processed.
        /// With that, methods may check for a more general state without getting "confused"
        /// by custom insertions which often are not relevant for the decision-making.
        States  BuiltInState                                                   =States::NOT_STARTED;
 
        /// The current state. Either a built-in state enumeration or a custom one.
        /// @see Field #BuiltInState, which is more appropriate to use in most cases.
        Enum    State                                                          =States::NOT_STARTED;
 
        /// Emergency stopper. As soon as this gets set, the execution of the application
        /// will stop. The only thing that is still performed is the standard
        /// #"alib::Shutdown;ALib shutdown procedure", but not the shutdown procedure defined
        /// by this app (or its derived type). I.e., no configuration files are written.
        bool    EmergencyStop                                                                =false;
 
        /// Sets this applications' cli-exit code (the result of the method \c main()).
        /// If the given \p{pExitCode}'s integral value is \c 0, nothing is done.
        ///
        /// Only the value of the first call is used. Later calls will not overwrite the first
        /// given value. In debug-builds, the method #DbgDumpFurtherExitCodes may be used
        /// to display later given codes, what the default implementation of the method
        /// #"App::onSdFinalizeShutdown;*" does.
        /// @param pExitCode The exit code to set.
        ///
        void SetExitCode(Enum pExitCode) {
            if ( pExitCode.Integral() == 0)
                return;
 
            if ( exitCode.IsNull() || exitCode.Integral() == 0 )
                exitCode= pExitCode;
            #if ALIB_DEBUG
                else
                    dbgFurtherExitCodes.push_back(pExitCode);
            #endif
        }
 
        /// Returns this applications' cli-exit code (the result of the method \c main()).
        /// @return The first value given with #SetExitCode.
        Enum GetExitCode()                                                      { return exitCode; }
 
        /// Writes exit codes not respected by the method #SetExitCode (because an earlier code
        /// was already set) to the \p{target} string. Then clears the debug-field
        /// #dbgFurtherExitCodes.
        /// This method is called by the default implementations of the methods
        /// #exceptionDisplay and #onSdOutput<br>.
        /// In release-builds, this method is pruned.
        /// @param target The target string.
        void DbgDumpFurtherExitCodes(AString& target) {
            #if ALIB_DEBUG
                for ( auto& ec : dbgFurtherExitCodes )
                    target << "Unused (later) exit-code: " << ec << NEW_LINE;
                dbgFurtherExitCodes.clear();
            #else
                (void) target;
            #endif
        }
    };
 
  //====================================== ConfigFileDescriptor ====================================
    /// A record collecting information about configuration files. A vector of this type is
    /// created by the method #"App::getConfigFilePaths;*".
    struct ConfigFileDescriptor {
        /// The resolved full path to the file.
        Path      Pathname;
 
        /// A comma-separated list of variables (and especially variable tree paths) to be
        /// explicitly exported to this configuration file.
        String    Exports;
 
        /// The files' main comment to set, in case it does not exist, yet.
        String    Comment;
 
        /// If set, the file name (and maybe path) came from option '--CONFIG'.
        bool      FromCfgOption                                                              =false;
 
        /// If set, the file did not exist or was empty at the start of the application.
        bool      WasEmpty                                                                   =false;
    };
 
 
  //================================================================================================
  // App Fields
  //================================================================================================
 
    /// The state-machine singleton.
    StateMachine machine;
 
    /// A stop-watch usable for measuring performance of different steps of an application.
    /// Time is taken in the constructor.
    StopWatch                       stopWatch;
 
    /// The main camp of the application. This is where resources are loaded from.
    /// @see Notes are given in the #"App::App;constructor".
    camp::Camp*                     appCamp                                                =nullptr;
 
    /// The name of the application.
    /// If not set from the descendant, it is tried to be loaded from resource <c>"AppName"</c>
    /// by the default implementation of #onBsSetNameVersionAndInfo.
    String                          appName                                                =nullptr;
 
    /// A version string of the application.
    /// If not set from the descendant, it is tried to be loaded from resource <c>"AppVersion"</c>
    /// by the default implementation of #onBsSetNameVersionAndInfo.
    String                          appVersion                                             =nullptr;
 
    /// Some short information and probably copyright message of the application.
    /// If not set from the descendant, it is tried to be loaded from resource <c>"AppInfo"</c>
    /// by the default implementation of #onBsSetNameVersionAndInfo.
    String                          appInfo                                                =nullptr;
 
    /// Used to assemble and collect the output for standard output character stream \c std::cout
    /// during the run of this application.<br>
    /// 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.
    Paragraphs*                     cOut                                                   =nullptr;
 
    /// Same as #cOut, but used for stream \c std::err.
    Paragraphs*                     cErr                                                   =nullptr;
 
 
  //============================================== ALox ============================================
    /// This will be the name of the release \b Lox.
    /// The name defaults to <c>"RLOX"</c> and may be changed prior to the call to the method
    /// #onBsSetupALox.<br>
    String                          releaseLoxName                                  =A_CHAR("RLOX");
 
    /// This will be the name of the release logger attached to the release \b Lox.
    /// The name defaults to <c>"RLOGGER"</c> and may be changed prior to the call to the method
    /// #onBsSetupALox.<br>
    String                          releaseLoggerName                            =A_CHAR("RLOGGER");
 
    /// The release \b Lox used by the application.
    /// @see Method onBsSetupALox.
    lox::Lox*                       releaseLox                                             =nullptr;
 
    /// The release logger used by the application.
    /// @see Method onBsSetupALox.
    lox::textlogger::TextLogger*    releaseLogger                                          =nullptr;
 
    /// Various boolean flags used to configure the application.
    Flags                           flags                                              =Flags::NONE;
 
  //================================================================================================
  // Constructors/destructor
  //================================================================================================
    /// Constructor.
    /// Initializes this app. Mainly by filling the vector #".StateMachine::Program;2" with all
    /// states found in the enumeration #States along with the corresponding virtual methods.<br>
    ///
    /// While the parameter \p{appCamp} is optional, it is intentionally not provided with a default
    /// value of \c nullptr. Derived types should create and provide a custom camp here
    /// (See the #"alib_mod_camp;Programmer's Manual" of the module \alibcamp_nl).
    /// If it is missing, many default implementations of the virtual methods render useless, and
    /// return instantly.<br>
    /// 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.
    ///
    /// @param appCamp An optional camp instance to search resources in.
    ALIB_DLL
    App(camp::Camp* appCamp);
 
 
    /// Virtual destructor.
    ALIB_DLL
    virtual ~App();
 
  //================================================================================================
  // Public Interface
  //================================================================================================
  public:
    /// Stores cli-parameters and executes this app.
    /// @param argc  The number of command-line arguments.
    /// @param argv  List of command-line arguments, given as single byte character strings.
    /// @param argvw The CLI arguments on platforms that use wide command-line strings.
    ///              Defaults to \c nullptr. If given, parameter \p{argv} has to be nulled.
    /// @return The exit code to be returned by C/C++ \c main().
    ALIB_DLL
    virtual int Main( int argc, const char** argv, const wchar_t** argvw= nullptr );
 
    /// Has to return the \b Lox instance used with release-logging.
    /// @return This implementation returns field #releaseLox.
    virtual lox::Lox*                       GetRLox()                         { return releaseLox; }
 
    /// Has to return the \b Logger instance used with release-logging.
    /// @return This implementation returns field #releaseLogger.
    virtual lox::textlogger::TextLogger*    GetRLogger()                   { return releaseLogger; }
 
    /// Returns the name of this application.
    /// This default implementation returns the field #appName.
    /// This is not necessarily equal to the process module name which can be received with
    /// <c>ProcessInfo::Current().ExecFileName</c>.
    /// @return This application's name.
    String                                  GetName()                            { return appName; }
 
    /// Returns the version of this application.
    /// This default implementation returns the field #appVersion.
    /// @return A string containing version information of this application.
    String                                  GetVersion()                      { return appVersion; }
 
    /// Returns the version of this application.
    /// This default implementation returns the field #appVersion.
    /// @return A usually multi-line string containing information about this application.
    String                                  GetInfo()                            { return appInfo; }
 
  //================================================================================================
  // Helper Hooks usable by the Program Methods
  //================================================================================================
    /// 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 #"CLIUtil::GetExitCode;*" 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.<br>
    /// 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 <c>BuiltInExitCodes::ErrUnknown</c>, perform their own translation
    /// in that case and probably debug-assert on failure.
    /// @param exception The exception that was thrown.
    /// @return On success, the exit-code resulting from the given \p{exception}.
    ///         Otherwise a \e nulled \b Enum.
    virtual Enum   exceptionToExitCode( alib::Exception& exception );
 
    /// Writes exception information to \c std::cerr<br>.
    /// @param exception The exception that was thrown.
    /// @param target    The target string to write into. An option is to pass <c>cErr->Buffer</c>
    ///                  here. Of course a custom buffer might be passed, i.e. if the text is to be
    ///                  logged with \alox.
    virtual void    exceptionDisplay( Exception& exception, AString& target );
 
    /// Writes configuration file information into the given \p{target}.
    /// @param target The target to write into. The common option is to pass #"cOut" here.
    virtual void    printConfigFileInfo( Paragraphs& target );
 
    /// This default implementation in turn calls the virtual helper methods
    /// #getConfigFilePathsFromResources and #getConfigFilePathsMakeAbsolutePaths.
    /// @param files A pointer to an object of type <c>StdVectorMA<ConfigFileDescriptor></c> that
    ///              is to be filled by this method.
    ALIB_DLL
    virtual void        getConfigFilePaths(StdVectorMA<ConfigFileDescriptor>& files);
 
    /// If the given vector \p{files} is empty, this method tries resources named
    /// <c>"CFGF_NAME_1"</c>, <c>"CFGF_NAME_2"</c>, <c>"CFGF_NAME_3"</c> and so forth until
    /// a first name is not found. For all names found, an entry in vector \p{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 <c>"CFGF_CMT_"</c> and the number of the entry. If found, the resource is assigned
    /// to the field #"App::ConfigFileDescriptor::Comment;*".
    ///
    /// Then for each entry resources named <c>"CFGF_EXP_"</c> and the number of the entry
    /// are searched. If found, the field #"App::ConfigFileDescriptor::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.
    /// @param files The vector of file paths that is to be filled or modified by this method.
    ALIB_DLL
    virtual void      getConfigFilePathsFromResources  (StdVectorMA<ConfigFileDescriptor>& files);
 
    /// Checks all filenames in the given vector and converts them to an absolute path.
    /// @param files The vector of file paths that is to be modified by this method.
    ALIB_DLL
    virtual void      getConfigFilePathsMakeAbsolutePaths(StdVectorMA<ConfigFileDescriptor>& files);
 
 
  //================================================================================================
  // Virtual Methods called by the State-Machine Program  -  Bootstrap
  //================================================================================================
    /// Called on transition to state #"App::States::SetCamps".<br>
    /// This default implementation calls the #"alib::BootstrapAddDefaultCamps" and then
    /// adds camp #appCamp to the end of that list. In case field #appCamp is \e nulled, rather
    /// the opposite is done: the field is set to point to the end of the list.
    ALIB_DLL
    virtual void        onBsSetCamps();
 
    /// Called on transition to state #"App::States::PrepareResources".<br>
    /// This default implementation
    /// - calls the #"alib::Bootstrap(BootstrapPhases)" passing
    ///   #"BootstrapPhases::PrepareResources;2" as its parameter.
    /// - creates instances for fields #cOut and #cErr inside the global allocator.
    /// - if configuration macro #"ALIB_DEBUG_RESOURCES" is set, then the field
    ///   #"LocalResourcePool::DbgResourceLoadObserver;*" is set to <c>std::cout</c>.
    ALIB_DLL
    virtual void        onBsPrepareResources();
 
    /// Called on transition to state #"App::States::SetNameVersionAndInfo".<br>
    /// This default implementation tries resources <c>"AppName"</c>, <c>"AppVersion"</c>, and
    /// <c>"AppInfo"</c> 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.
    ALIB_DLL
    virtual void        onBsSetNameVersionAndInfo();
 
 
    /// Called on transition to state #"App::States::PrepareConfig".<br>
    /// This default implementation just calls the function #"alib::Bootstrap(BootstrapPhases)"
    /// passing #"BootstrapPhases::PrepareConfig;2" as the parameter.
    ALIB_DLL
    virtual void        onBsPrepareConfig();
 
    /// Called on transition to state #"App::States::PreloadVariables".<br>
    /// 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.<br>
    /// This default implementation calls #"Configuration::PreloadVariables;*"
    /// on the variables found with the enumeration #"lox::Variables".
    ALIB_DLL
    virtual void        onBsPreloadVariables();
 
    /// Called on transition to state #"App::States::ImportConfig".<br>
    /// This default implementation creates the vector of file descriptors using
    /// #getConfigFilePaths and then uses type #"IniFileFeeder" to import the
    /// variables from the INI-files.
    ALIB_DLL
    virtual void        onBsImportConfig();
 
    /// Called on transition to state #"App::States::FinalizeBootstrap".<br>
    /// This default implementation just calls the function #"alib::Bootstrap(BootstrapPhases)"
    /// passing #"BootstrapPhases::Final;2" as the parameter.
    ALIB_DLL
    virtual void        onBsFinalizeBootstrap();
 
    /// Called on transition to state #"App::States::SetupALox".<br>
    /// If this method returns an error, bootstrapping is aborted.
    /// This default implementation interprets the flags
    /// #"App::Flags::CreateReleaseLox" and
    /// #"App::Flags::UseReleaseLoggerForDebugLogging", and furthermore
    /// uses the fields #releaseLoxName and #releaseLoggerName
    /// into account and potentially creates #releaseLox and #releaseLogger.
    ALIB_DLL
    virtual void        onBsSetupALox();
 
  //================================================================================================
  // Virtual Methods called by the State-Machine Program  -  Run
  //================================================================================================
    /// 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.<br>
    ALIB_DLL
    virtual void onRunStart()                                                                     {}
 
    /// 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.
    virtual void onRun()                                                                         =0;
 
    /// 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.
    ALIB_DLL
    virtual void onRunEnd()                                                                       {}
 
  //================================================================================================
  // Virtual Methods called by the State-Machine Program  -  Shutdown
  //================================================================================================
    /// Called on transition to state #"App::States::AnnounceShutdown".<br>
    /// This default implementation just calls the function #"alib::Shutdown" passing
    /// #"ShutdownPhases::Announce;2" as the parameter.
    ALIB_DLL
    virtual void        onSdAnnounceShutdown();
 
    /// Called on transition to state #"App::States::CleanALox".<br>
    /// This default implementation checks the flags
    /// #"App::Flags::ALoxVerbosityExportAllAndWriteBackRelLogger", and
    /// #"App::Flags::ALoxVerbosityExportAllAndWriteBackDbgLogger" and calls
    /// #"Logger::SetVerbosityExport;*" if set.<br>
    /// Then, if set, the release logger and \b Lox are deleted.
    ALIB_DLL
    virtual void        onSdCleanALox();
 
    /// Called on transition to state #"App::States::ExportConfig".<br>
    /// 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.<br>
    /// This is done for all variables (and variable trees) determined by the field
    /// #"App::ConfigFileDescriptor::Exports;*".
    ALIB_DLL
    virtual void        onSdExportConfig();
 
    /// 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 <em>onSd</em> and scheduled at
    /// the end of the #"StateMachine::Program;2" - 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.
    ALIB_DLL
    virtual void        onSdOutput();
 
    /// Called on transition to state #"App::States::FinalizeShutdown".<br>
    /// This default implementation calls the function #"alib::Shutdown" passing
    /// #"ShutdownPhases::Destruct;2" as the parameter.<br>
    /// Prior to that, some memory cleaning and debug exercises are done.
    ALIB_DLL
    virtual void        onSdFinalizeShutdown();
 
 
}; // class App
 
/// The application singleton-instance. This defaults to \c nullptr and is set by the
/// constructor of class #"App".
ALIB_DLL extern App*    APP_SINGLETON;
 
/// Convenience function that returns the singleton instance of an \alib application.
/// @tparam TApp The app type to cast to.
/// @return The dereferenced pointer to #"APP_SINGLETON".
template<typename TApp= app::App>
inline TApp&    Get()                           { return *dynamic_cast<TApp*>(app::APP_SINGLETON); }
 
} // namespace alib[::app]
 
 
 
} // namespace [alib]
 
ALIB_ENUMS_MAKE_BITWISE( alib::app::App::Flags )
 
#if !DOXYGEN
#   undef  LOX_LOX
#   define LOX_LOX  (*::alib::app::APP_SINGLETON->GetRLox())
#endif