plugins.mpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of the \aliblong.
/// With supporting legacy or module builds, .mpp-files are either recognized by the build-system
/// as C++20 Module interface files, or are included by the
/// #"alib_manual_modules_impludes;import/include headers".
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
#if !defined(ALIB_C20_MODULES) || ((ALIB_C20_MODULES != 0) && (ALIB_C20_MODULES != 1))
#   error "Configuration MACRO ALIB_C20_MODULES has to be given to the compiler as either 0 or 1"
#endif
#if ALIB_C20_MODULES
    module;
#endif
//========================================= Global Fragment ========================================
#include "alib/boxing/boxing.prepro.hpp"
#include "alib/variables/variables.prepro.hpp"
 
#include "ALib.Strings.Vector.H"
#if ALIB_DEBUG_BOXING
#    include <vector>
#endif
//============================================== Module ============================================
#if ALIB_C20_MODULES
    /// This is a <em><b>C++ Module</b></em> of the \aliblong.
    /// Due to the dual-compile option (either as C++20 Modules or using legacy C++ inclusion),
    /// the C++20 Module names are not of further interest or use.<br>
    /// In general, the names equal the names of the header files listed in the chapter
    /// #"alib_manual_modules_impludes" of the \alib User Manual.
    ///
    /// @see The documentation of the <em><b>"ALib Module"</b></em> given with the corresponding
    ///      Programmer's Manual \alib_variables.
    export module ALib.Variables.Plugins;
    import        ALib.Variables;
    import        ALib.Monomem;
    import        ALib.Strings;
#else
#include "ALib.Variables.H"
#include "ALib.Monomem.H"
#include "ALib.Strings.H"
#endif
 
//============================================= Exports ============================================
ALIB_EXPORT namespace alib::variables {
 
//==================================================================================================
/// Specialization of abstract interface class #"ConfigurationPlugin", which reads command-line
/// parameters from namespace globals #"alib::ARG_C;2" and #"alib::ARG_VN;2" / #"ARG_VW" on request.
/// Its priority value usually is #"Priority::CLI", which is higher
/// than all other default plug-ins provided.
///
/// To recognize variables, the separation character <c>'/'</c> of the configuration tree is
/// converted to underscore character <c>'_'</c>. For example, the \alib locale variable with path
///         ALIB/LOCALE
/// is recognized as
///         ALIB_LOCALE
///
/// Variable names are insensitive in respect to character case.
///
/// Command line variables may be passed with either one hyphen ('-') or two ('--').
/// Both are accepted.
///
/// An application can specify one or more "default categories" by adding their string names to
/// public field #".DefaultCategories". Variables of these categories are recognized by the plug-in
/// also when given without the name prefix of category name and underscore \c '_'.
//==================================================================================================
class CLIVariablesPlugin : public ConfigurationPlugin
{
  public:
    /// If any value is added to this vector, its values are used as the source of command-line
    /// arguments instead of using \alib namespace variables #"ARG_C" and
    /// #"ARG_VN"/#"ARG_VW".<br>
    /// This mechanic provides an alternative method to set the command-line argument list.
    ///
    /// Applications that have a dedicated (more sophisticated) CLI interface which performs
    /// more complex processing of CLI arguments, may collect any unrecognized
    /// CLI argument here to be duly recognized as a configuration variable instead
    StringVectorMA      AlternativeArgs;
 
    /// An application can specify one or more "default categories" by adding a prefix of the
    /// variable path here. Variables of these "categories" are recognized by the plug-in also
    /// when given without this prefix.<br>
    /// Please note, that if \alib and \alox variables should be abbreviatable, for example, that
    /// the locale can be given with
    ///             --locale=de_DE.UTF-8
    /// instead of
    ///             --alib_locale=de_DE.UTF-8
    /// this vector has to be populated during bootstrap phase #"BootstrapPhases::PrepareConfig".
    /// See chapter #"alib_mod_bs_customize" for more information on how to
    /// customize \alib bootstrapping.
    StringVectorMA      DefaultCategories;
 
    /// Determines whether zero, one or two introducing hyphen characters <c>'-'</c> are mandatory.
    /// An command-line argument is ignored if the number of leading hyphens is smaller than
    /// the value set here.<br>
    /// Defaults to \c 0.
    /// @see Sibling option #"QtyOptionalHyphens".
    uint8_t                 QtyMandatoryHyphens                                                 = 0;
 
    /// Determines whether zero, one or two optional hyphen characters <c>'-'</c> might be given.
    /// An command-line argument is ignored if the number of leading hyphens is greater than
    /// the value set here.<br>
    /// Defaults to \c 2.
    /// @see Sibling option #"QtyMandatoryHyphens".
    uint8_t                 QtyOptionalHyphens                                                  = 2;
 
    /// Constructor.
    /// @param ma         The monotonic allocator to use. This usually is the one of the
    ///                   configuration instance.
    /// @param pPriority  The priority that this plug-in uses. Defaults to #"Priority::CLI".
    ALIB_DLL
    CLIVariablesPlugin( MonoAllocator& ma, Priority pPriority= Priority::CLI );
 
    /// Virtual Destructor.
    virtual ~CLIVariablesPlugin()                                                        override {}
 
    /// @return The plug-in name, in this case, we read resource variable "CFGPlgCLI".
    ALIB_DLL virtual String      Name()                                              const override;
 
    /// Searches the variable in the command-line parameters.
    /// @param      name    The name of the variable to retrieve.
    /// @param[out] target  A reference to the buffer to write the variable's exported value to.
    /// @return \c true if variable was found, \c false if not.
    ALIB_DLL virtual bool        Get( const String& name, AString& target )                override;
};
 
//==================================================================================================
/// Specialization of abstract interface class #"ConfigurationPlugin", retrieves configuration
/// data from the system environment.
///
/// The priority value of this plug-in usually is #"Priority::Environment",
/// which is higher than #"var Priority::Standard" but lower than #"Priority::CLI".
///
/// To recognize variables, the separation character <c>'/'</c> of the configuration tree is
/// converted to underscore character <c>'_'</c>. For example, the \alib locale variable with path
///         ALIB/LOCALE
/// is recognized as
///         ALIB_LOCALE
///
/// Category and Variable names are insensitive in respect to character case.
//==================================================================================================
class EnvironmentVariablesPlugin : public ConfigurationPlugin
{
  public:
    /// An application can specify one or more "default categories" by adding a prefix of the
    /// variable path here. Variables of these "categories" are recognized by the plug-in also
    /// when given without this prefix.<br>
    /// Please note, that if \alib and \alox variables should be abbreviatable, for example, that
    /// the locale can be given with
    ///             --locale=de_DE.UTF-8
    /// instead of
    ///             --alib_locale=de_DE.UTF-8
    /// this vector has to be populated during bootstrap phase #"BootstrapPhases::PrepareConfig".
    /// See chapter #"alib_mod_bs_customize" for more information on how to
    /// customize \alib bootstrapping.
    StringVectorMA          DefaultCategories;
 
    /// Constructor.
    /// @param ma         The monotonic allocator to use. This usually is the one of the
    ///                   configuration instance.
    /// @param pPriority  The priority that this plug-in uses. Defaults to #"Priority::Environment".
    ALIB_DLL EnvironmentVariablesPlugin( MonoAllocator& ma,
                                         Priority      pPriority      = Priority::Environment );
 
    /// Virtual Destructor.
    virtual                 ~EnvironmentVariablesPlugin()                                override {}
 
    /// @return The name of the plug-in, in this case, the value of the resource variable
    ///         \b "CFGPlgEnv".
    ALIB_DLL virtual String Name()                                                   const override;
 
    /// Searches the variable in the environment.
    /// @param      name    The name of the variable to retrieve.
    /// @param[out] target  A reference to the buffer to write the variable's exported value to.
    /// @return \c true if variable was found, \c false if not.
    ALIB_DLL virtual bool   Get( const String& name, AString& target )                     override;
};
 
} // namespace [alib::variables]