arguments.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_cli of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software License".
//==================================================================================================
ALIB_EXPORT namespace alib::cli {
 
/// Struct used as parent for types
/// - \alib{cli;Command},
/// - \alib{cli;Option}, and
/// - \alib{cli;Parameter}.
///
/// Stores
/// - a pointer to the \alib{cli;CommandLine} object,
/// - the position in \alib{ARG_VN}, respectively \alib{ARG_VW} where the object was found, and
/// - the number of arguments consumed when reading the object.
///
/// \note
///   For technical reasons, other members that are shared between the derived types named above,
///   have to be declared (each three times) with the types themselves.
struct Parsed
{
    /// The cli command line.
    CommandLine* CmdLine;
 
    /// The index in \alib{ARG_VN}, respectively \alib{ARG_VW}, that this instance (derived option
    /// or parameter ) was found at.
    integer      Position;
 
    /// The number of command line arguments that a command consumed. This includes the command name
    /// itself. If the method \b Read of derived types leaves this to <c>0</c>, then the option or
    /// parameter was not found.
    integer      ConsumedArguments;
 
    /// Constructor
    /// @param cmdLine   The command line instance.
    Parsed( CommandLine* cmdLine )
    : CmdLine        (cmdLine)
    , Position       ((std::numeric_limits<integer>::max)())
    , ConsumedArguments(0)                                                                        {}
};
 
 
//##################################################################################################
// Decl and Def versions of commands, options, parameters and ExitCodes
//##################################################################################################
 
 
/// \ref alib_enums_records "ALib Enum Record" type used by class \alib{cli;ParameterDecl}.
struct ERParameterDecl : public enumrecords::ERSerializable {
    /// The identifier of the parameter.
    String      identifier;
 
    /// An optional separator string (usually "=") that separates the parameter name from a
    /// value given within the parameter itself.
    String      valueSeparator;
 
    /// A separator character for parsing multiple values.
    /// If set to <c>'C'</c>, method \alib{cli;ParameterDecl::ValueListSeparator} will return
    /// <c>','</c> instead.
    nchar       valueListSeparator;
 
    /// The number of arguments to consume and store in \alib{cli;Parameter::Args}.
    /// If negative, parsing stops. If previous field, separator string is set and this
    /// value is equal or greater to \c 1, then a missing separator string leads to
    /// a parsing exception.
    int         RequiredArguments;
 
    /// Denotes if this is an optional parameter.
    bool        isOptional;
 
    /// Default constructor leaving the record undefined. (Implementation required as documented
    /// \alib{enumrecords;EnumRecordPrototype::EnumRecordPrototype();here}.)
    ERParameterDecl()                                                             noexcept =default;
 
    /// Implementation of \alib{enumrecords;EnumRecordPrototype::Parse}.
    ALIB_DLL
    void Parse();
 };
 
/// A parameter of a \alib{cli;CommandDecl}.
///
/// Construction is done by passing a custom enum element of an enum type equipped with
/// \ref alib_enums_records "ALib Enum Records" of type \alib{cli;ERParameterDecl}.
///
/// When bootstrapping \alib_cli_nl, method \alib{cli;CommandLine::DefineParameters} has to be
/// invoked for (each) enum type.
class ParameterDecl
{
  protected:
    /// The enumeration element given with construction.
    Enum            declElement;
 
    /// A copy (!) of the enum record.
    ERParameterDecl record;
 
    /// The resource information of the enumeration type given with construction.
    ResourceInfo    resourceInfo;
 
  public:
    /// Templated constructor which takes an enum element of a custom type equipped with
    /// \ref alib_enums_records "ALib Enum Records" of type \alib{cli;ERParameterDecl}.
    ///
    /// @tparam TEnum    C++ enum type equipped with corresponding \alib Enum Records.
    /// @param element   The enum element
    template<typename TEnum>
    ParameterDecl( TEnum element )
    : declElement( element )
    , resourceInfo(element) {
        // make a copy of the resourced record
        record= enumrecords::GetRecord(element);
 
        // fix separator character
        if( record.valueListSeparator == 'C' )
            record.valueListSeparator= ',';
    }
 
    /// Returns the type and integral value of the enumeration element used with construction.
    /// @return The enumeration element used with construction.
    const Enum&     Element()                                          const { return declElement; }
 
    /// Returns the name of the parameter. This is not the identifier. The name is just for
    /// help and configuration output.
    ///
    /// \see Method #Identifier.
    ///
    /// @return The name of the enum element.
    const String&   Name()                                        { return record.EnumElementName; }
 
    /// Returns the identifier of the parameter. If this is empty, the parameter is not optional
    /// and hence has no identifier.
    ///
    /// @return The name of the enum element.
    const String&   Identifier()                                       { return record.identifier; }
 
    /// Returns the minimum parse length of the identifier.
    /// @return The minimum characters to satisfy the parameter.
    int             MinimumRecognitionLength()           { return record.MinimumRecognitionLength; }
 
    /// An optional separator string (usually "="), that separates the parameter name from a
    /// parameter value.
    /// @return The separator string.
    const String&   ValueSeparator()                               { return record.valueSeparator; }
 
    /// A separator character for parsing multiple values.
    /// @return The separator character.
    nchar           ValueListSeparator()
    { return record.valueListSeparator != 'C' ? record.valueListSeparator : ','; }
 
    /// The number of CLI arguments to consume and store in \alib{cli;Option::Args} with method
    /// \alib{cli;Parameter::Read}.
    ///
    /// @return The parameter identifier.
    int             QtyExpectedArgsFollowing()                  { return record.RequiredArguments; }
 
    /// Returns \c true if the parameter is optional. The information about this attribute is
    /// used to create help messages and usage format strings only. It does not automatically
    /// raise an exception if a parameter is not given. Such exception or other error treatment
    /// is up to the user code.
    /// @return \c true if the parameter is optional, \c false otherwise.
    bool IsOptional()                                                  { return record.isOptional; }
 
    /// Returns the short help text.
    /// Loads the string from #resourceInfo using resource name \c "THelpParShtNN",
    /// where \c NN is the enum element's integral value.
    /// @return The help text.
    const String&   GetHelpTextShort()
    { return resourceInfo.Get( NString64("THlpParSht_" ) << Name()  ALIB_DBG(, true) ); }
 
    /// Returns the long help text.
    /// Loads the string from #resourceInfo using resource name \c "THelpParLngNN",
    /// where \c NN is the enum element's integral value.
    /// @return The help text.
    const String&   GetHelpTextLong()
    { return resourceInfo.Get( String64("THlpParLng_" ) << Name() ALIB_DBG(, true)); }
}; // ParameterDecl
 
/// A declaration for a \alib{cli::Parameter}.
struct Parameter : public Parsed
{
    /// The underlying declaration.
    ParameterDecl*                                  Declaration                           = nullptr;
 
    /// Arguments belonging to us.
    ListMA<String, Recycling::Shared>  Args;
 
    /// Constructor
    /// @param cmdLine   The command line instance.
    inline
    Parameter( CommandLine* cmdLine );
 
    /// Tries to read the object from the front of \alib{cli;CommandLine::ArgsLeft}.
    /// Success is indicated by setting inherited fields \alib{cli;Parsed::Position} and
    /// \alib{cli;Parsed::ConsumedArguments} to values greater than \c 0.
    ///
    /// If it could not be decided if the actual CLI argument contains this parameter, \c false
    /// is returned to indicate that parsing commands has to stop now.
    ///
    /// This is done in the following cases:
    /// - When \alib{cli;ParameterDecl::Identifier} is empty and the parameter is
    ///   \alib{cli;ParameterDecl::IsOptional} gives \c true.
    /// - When it was successfully read, but \alib{cli;ParameterDecl::QtyExpectedArgsFollowing}
    ///   is defined \c -1.
    ///
    /// See \alib{cli;CommandLine;ReadNextCommands} for details
    ///
    /// @param decl   The declaration used for reading
    /// @return The \c true on success, \c false indicates that parsing has to end here.
    ALIB_DLL
    bool    Read( ParameterDecl& decl );
};
 
/// \ref alib_enums_records "ALib Enum Record" type used by class \alib{cli;OptionDecl}.
struct EROptionDecl : public enumrecords::ERSerializable
{
    /// The name of the option as parsed from command line if single hyphen <c>'-'</c> is used.
    /// Defined as string to be able to have empty strings, which disables single character
    /// options.
    String  identifierChar;
 
    /// An optional separator string (usually "=") that separates the option name from a value
    /// within the first argument itself.
    /// If this is not given, field #RequiredArguments has to be \c 0.
    String  valueSeparator;
 
    /// The number of arguments to consume and store in \alib{cli;Option::Args}.
    /// If this field is set and this value is not \c 0, then a missing separator string leads
    /// to a parsing exception.
    integer RequiredArguments;
 
    /// If not empty, the argument string will be replaced by this and the search for next options
    /// continues.
    /// Note: Shortcut options have to occur earlier in the enumeration's resource definition.
    String  shortcutReplacementString;
 
    /// Defaulted constructor leaving the record undefined.
    /// (Implementation required as documented
    /// \alib{enumrecords;EnumRecordPrototype::EnumRecordPrototype();here}.)
    EROptionDecl()                                                                noexcept =default;
 
    /// Implementation of \alib{enumrecords;EnumRecordPrototype::Parse}.
    ALIB_DLL
    void Parse();
};
 
/// A declaration for an \alib{cli::Option}.
///
/// Construction is done by passing a custom enum element of an enum type equipped with
/// \ref alib_enums_records "ALib Enum Records" of type \alib{cli;EROptionDecl}.
///
/// When bootstrapping \alib_cli_nl, method \alib{cli;CommandLine::DefineOptions} has to be
/// invoked for (each) enum type.
///
class OptionDecl
{
  protected:
    /// The enumeration element given with construction.
    Enum            declElement;
 
    /// A copy (!) of the enum record.
    EROptionDecl    record;
 
    /// The resource information of the enumeration type given with construction.
    ResourceInfo    resourceInfo;
 
 
  public:
    /// Templated constructor which takes an enum element of a custom type equipped with
    /// \ref alib_enums_records "ALib Enum Records" of type \alib{cli;EROptionDecl}.
    ///
    /// @tparam TEnum    C++ enum type equipped with corresponding \alib Enum Records.
    /// @param element   The enum element
    template<typename TEnum>
    OptionDecl( TEnum element )
    : declElement( element )
    , resourceInfo(element)
    {
        // make a copy of the resourced record
        record= enumrecords::GetRecord(element);
    }
 
    /// Returns the type and integral value of the enumeration element used with construction.
    /// @return The enumeration element used with construction.
    const Enum&     Element()                                          const { return declElement; }
 
    /// Returns the identifier of the option if double hyphen <c>'--'</c> is used.
    /// @return The option identifier.
    const String&   Identifier()                                  { return record.EnumElementName; }
 
    /// Returns the minimum parse length of the identifier if double hyphen <c>'--'</c> is used.
    /// @return The minimum characters to satisfy the option.
    int             MinimumRecognitionLength()           { return record.MinimumRecognitionLength; }
 
    /// Returns the identifier of the option if single hyphen <c>'-'</c> is used.
    /// @return The option identifier.
    character       IdentifierChar()
    {
        return record.identifierChar.IsNotEmpty() ? record.identifierChar.CharAtStart()
                                                  : '\0';
    }
 
    /// An optional separator string (usually "="), that separates the parameter name from a
    /// parameter value.
    /// @return The separator string.
    const String&   ValueSeparator()                               { return record.valueSeparator; }
 
    /// The number of CLI arguments to consume and store in \alib{cli;Option::Args} with method
    /// \alib{cli;Option::Read}.
    /// @return The option identifier.
    integer         QtyExpectedArgsFollowing()                  { return record.RequiredArguments; }
 
    /// If an option is a shortcut to another one, this string replaces the argument given.
    /// @return The option identifier.
    const String&   ShortcutReplacementString()         { return record.shortcutReplacementString; }
 
 
    /// Returns a formal description of the usage.
    /// Loads the string from #resourceInfo using resource name \c "TOptUsgNN",
    /// where \c NN is the enum element's integral value.
    /// @return The help text.
    const String&   HelpUsageLine()
    { return resourceInfo.Get( NString64("TOptUsg_" ) << Identifier()   ALIB_DBG(, true) ); }
 
    /// Returns the help text.
    /// Loads the string from #resourceInfo using resource name \c "TOptHlpNN",
    /// where \c NN is the enum element's integral value.
    /// @return The help text.
    const String&   HelpText()
    { return resourceInfo.Get( NString64("TOptHlp_" ) << Identifier()   ALIB_DBG(, true) ); }
}; // OptionDecl
 
/// An option of a command line. Options are read "automatically" using their declaration
/// information defined with externalized strings (resources) accessed through
/// \ref alib_enums_records "ALib Enum Records" associated with enum elements of enum custom types.
///
/// However, such automatic read is limited due to the fact, that the simple values and flags
/// defined with \alib{cli;OptionDecl}, cannot provide the flexibility needed to perfectly
/// parse options with a complex syntax.
///
/// In this case, the way out is to use custom code that invokes \alib{cli;CommandLine;ReadOptions}
/// and then processes all options that may have remaining arguments left in the list.
/// Using field #Position further arguments may be consumed from \alib{cli;CommandLine::ArgsLeft}.<br>
/// Note, "processing all options" may mean a nested loop. The outer is over the option types
/// of \alib{cli;CommandLine;OptionsFound}, the inner is over the vector of options per type.
///
struct Option : public Parsed
{
    /// The declaration struct.
    OptionDecl*                                     Declaration                           = nullptr;
 
    /// Arguments belonging to this option.
    ListMA<String, Recycling::Shared>  Args;
 
    /// Constructor
    /// @param cmdLine   The command line main object.
    inline
    Option( CommandLine* cmdLine );
 
    /// Tries to read the object from the current CLI arg(s).
    /// \note
    ///   Unlike the read methods \alib{cli;Command::Read} and \alib{cli;Parameter::Read}, this
    ///   method expects the argument to test not only by number with \p{argNo} but as well
    ///   with string parameter \p{arg}.<br>
    ///   This redundancy is needed to easily implement shortcut options, that just
    ///   replace a shortcut option read to another one, probably with a preset argument included.
    ///
    /// @param decl   The declaration used for reading.
    /// @param arg    The argument string starting with one or two hyphens.
    /// @param argNo  The position of reading.
    /// @return The \c true on success, \c false otherwise.
    ALIB_DLL
    bool  Read( OptionDecl& decl, String& arg, const integer argNo );
};
 
/// \ref alib_enums_records "ALib Enum Record" type used by class \alib{cli;CommandDecl}.
struct ERCommandDecl : public enumrecords::ERSerializable
{
    /// List of parameters attached. Separated by <c>'/'</c>.
    String      parameters;
 
    /// Default constructor leaving the record undefined.
    /// (Implementation required as documented
    /// \alib{enumrecords;EnumRecordPrototype::EnumRecordPrototype();here}.)
    ERCommandDecl()                                                               noexcept =default;
 
    /// Implementation of \alib{enumrecords;EnumRecordPrototype::Parse}.
    ALIB_DLL
    void Parse();
};
 
/// A declaration for a \alib{cli::Command}.
///
/// Construction is done by passing a custom enum element of an enum type equipped with
/// \ref alib_enums_records "ALib Enum Records" of type \alib{cli;ERCommandDecl}.
///
/// When bootstrapping \alib_cli_nl, method \alib{cli;CommandLine::DefineCommands} has to be
/// invoked for (each) enum type.
///
class CommandDecl
{
  protected:
    /// The enumeration element given with construction.
    Enum                                declElement;
 
    /// A copy (!) of the enum record.
    ERCommandDecl                       record;
 
    /// The resource information of the enumeration type given with construction.
    ResourceInfo                        resourceInfo;
 
  public :
    /// The command line instance we belong to.
    CommandLine&                        CmdLine;
 
    /// Command parameters.
    ListMA<ParameterDecl*> Parameters;
 
    /// Templated constructor which takes an enum element of a custom type equipped with
    /// \ref alib_enums_records "ALib Enum Records" of type \alib{cli;ERCommandDecl}.
    ///
    /// Field #Parameters is filled as specified in the enum record.
    ///
    /// @tparam TEnum    C++ enum type equipped with corresponding \alib Enum Records.
    /// @param element   The enum element
    /// @param cmdLine   The command line  object. Will be stored.
    template<typename TEnum>
    inline
    CommandDecl( TEnum element, CommandLine& cmdLine );
 
    /// Returns the type and integral value of the enumeration element used with construction.
    /// @return The enumeration element used with construction.
    const Enum&     Element()                                          const { return declElement; }
 
    /// Returns the identifier (name) of the command
    /// @return The command identifier.
    const String&   Identifier()                                  { return record.EnumElementName; }
 
    /// Returns the minimum parse length of the identifier.
    /// @return The minimum characters to satisfy the command to be parsed.
    int             MinimumRecognitionLength()           { return record.MinimumRecognitionLength; }
 
    /// Returns the short version of the help text.
    /// Loads the string from #resourceInfo using resource name \c "THlpCmdShtNN",
    /// where \c NN is the enum element's integral value.
    /// @return The help text.
    const String&   HelpTextShort()
    { return resourceInfo.Get( NString64("THlpCmdSht_" ) << Identifier()  ALIB_DBG(, true) ); }
 
    /// Returns the long version of the help text.
    /// Loads the string from #resourceInfo using resource name \c "THlpCmdLngNN",
    /// where \c NN is the enum element's integral value.
    /// @return The help text.
    const String&   HelpTextLong()
    { return resourceInfo.Get( NString64("THlpCmdLng_" ) << Identifier()  ALIB_DBG(, true) ); }
 
    /// Searches in #Parameters for the declaration of parameter \p{name}.
    /// @param name   The declaration name of the parameter.
    /// @return A pointer to the parameter's declaration, \c nullptr if parameter was not
    ///         declared.
    ALIB_DLL
    ParameterDecl* GetParameterDecl(const String& name );
 
  protected:
    /// Called from the constructor. Parses field \alib{cli;ERCommandDecl::parameters} of the
    /// enum record, and loads the corresponding parameters.
    ALIB_DLL
    void addParamDecls();
};
 
/// A command of a \alib_cli_nl command line.
struct Command  : public Parsed
{
    /// The underlying declaration.
    CommandDecl*                                        Declaration                       = nullptr;
 
    /// Mandatory parameters parsed.
    ListMA<Parameter*, Recycling::Shared>  ParametersMandatory;
 
    /// Optional parameters parsed.
    ListMA<Parameter*, Recycling::Shared>  ParametersOptional;
 
    /// Constructor
    /// @param cmdLine   The command line instance.
    inline
    Command( CommandLine* cmdLine );
 
    /// Tries to read the object from the front of \alib{cli;CommandLine::ArgsLeft}.
    /// @param decl   The declaration used for reading.
    /// @return The \c true on success, \c false otherwise.
    ALIB_DLL
    bool  Read( CommandDecl& decl );
 
    /// Searches in #ParametersMandatory and #ParametersOptional for parameter \p{name}.
    /// @param name   The declaration name of the parameter.
    /// @return A pointer to the parameter, \c nullptr if parameter was not parsed.
    ALIB_DLL
    Parameter* GetParsedParameter(const String& name );
 
    /// Searches in #ParametersMandatory and #ParametersOptional for parameter \p{name} and returns
    /// its (first) argument.
    /// @param name   The declaration name of the parameter.
    /// @return The argument string, \b NULL_STRING if parameter was not parsed if not given.
    ALIB_DLL
    String GetParsedParameterArg( const String& name );
};
 
/// \ref alib_enums_records "ALib Enum Record" type used by class \alib{cli;ExitCodeDecl}.
/// \note Field \alib{enumrecords;ERSerializable::MinimumRecognitionLength} is not read from the string,
///       but set to fixed value \c 0.
struct ERExitCodeDecl : public enumrecords::ERSerializable
{
    /// The CLI module exception associated to this exit code.
    int         associatedCLIException;
 
    /// Default constructor leaving the record undefined.
    /// (Implementation required as documented
    /// \alib{enumrecords;EnumRecordPrototype::EnumRecordPrototype();here}.)
    ERExitCodeDecl()                                                            noexcept
    : ERSerializable()                                                                            {}
 
    /// Implementation of \alib{enumrecords;EnumRecordPrototype::Parse}.
    ALIB_DLL
    void Parse();
};
 
/// An exit code of a cli application.
///
/// Construction is done by passing a custom enum element of an enum type equipped with
/// \ref alib_enums_records "ALib Enum Records" of type \alib{cli;ERExitCodeDecl}.
///
/// When bootstrapping \alib_cli_nl, method \alib{cli;CommandLine::DefineExitCodes} has to be
/// invoked for (each) enum type.
///
/// Announcing the main application's exit codes to the \alib_cli_nl module has two reasons:
/// - The exit codes are included in the help output text utility methods provided by class
///   \alib{cli;CommandLine}.
/// - \alib_cli_nl module exit codes can be translated to valid exit codes using
///   method \alib{cli;CLIUtil::GetExitCode}.
class ExitCodeDecl
{
  protected:
    /// The enumeration element given with construction.
    Enum            declElement;
 
    /// A copy (!) of the enum record.
    ERExitCodeDecl  record;
 
    /// The resource information of the enumeration type given with construction.
    ResourceInfo    resourceInfo;
 
 
  public:
    /// Templated constructor which takes an enum element of a custom type equipped with
    /// \ref alib_enums_records "ALib Enum Records" of type \alib{cli;ERExitCodeDecl}.
    ///
    /// @tparam TEnum    C++ enum type equipped with corresponding \alib Enum Records.
    /// @param element   The enum element.
    template<typename TEnum>
    ExitCodeDecl( TEnum element )
    : declElement( element )
    , resourceInfo(element)
    {
        // make a copy of the resourced record
        record= enumrecords::GetRecord(element);
    }
 
    /// Returns the name of the enum element
    /// @return The name of the enum element.
    const String&   Name()                                        { return record.EnumElementName; }
 
    /// If an element of enum type \alib{cli;Exceptions} is associated with this exit code, it
    /// is returned. Otherwise <c>cli::ExitCodes(-1)</c>.
    ///
    /// \see Method \alib{cli;CLIUtil::GetExitCode}.
    /// @return The associated element of cli::Exceptions.
    cli::Exceptions AssociatedCLIException()
    { return cli::Exceptions( record.associatedCLIException ); }
 
    /// Returns the format string associated with this exit code.
    /// Loads the string from #resourceInfo using resource name \c "TExitNN",
    /// where \c NN is the enum element's integral value.
    /// @return The format string.
    const String&   FormatString()
    { return resourceInfo.Get( NString64("TExit" ) << declElement.Integral() ALIB_DBG(,true)); }
};
 
} // namespace [alib::cli]