optionmanager.h

Pegasus is an open-source implementationof the DMTF CIM and WBEM standards. It is designed to be por

    /** Print Complete Help Text message including header before the options
        help and trailer after the options help
    */
    void printOptionsHelpTxt(const String& header, const String& trailer) const;


private:

    /** Lookup the option by its commandLineOptionName.
        @return 0 if no such option.
    */
    Option* _lookupOptionByCommandLineOptionName(const String& name);

    Array<Option*> _options;
};

//////////////////////////////////////////////////////////////////
//    OPTION CLASS
//////////////////////////////////////////////////////////////////

/** The Option class is used to specify information about an Option.

    See the OptionManager class for more details.
*/
class PEGASUS_COMMON_LINKAGE Option
{
public:

    /** Valid value types. */
    enum Type
    {
        // (..., -3, -2, -1, 0, 1, 2, 3, ...)
        INTEGER,

        // (1, 2, 3, ...)
        NATURAL_NUMBER,

        // (0, 1, 2, 3, ...)
        WHOLE_NUMBER,

        // "true" or "false"
        BOOLEAN,

        // Anything
        STRING
    };

    /** Constructor.

        @param optionName the name of this option.

        @param defaultValue the default value of this option.

        @param required whether the value of this option is required.

        @param type type of the value. This is used to validate the value.

        @param domain list of legal value for this option. If this list
            is empty, then no domain is enforced.

        @param commandLineOptionName name of the corresponding command line
            option (which may be different from the option name).

        @param optionHelpMessage Text message that defines option. To be used
            in Usage messages.
    */
    Option(
        const String& optionName,
        const String& defaultValue,
        Boolean required,
        Type type,
        const Array<String>& domain = Array<String>(),
        const String& commandLineOptionName = String(),
        const String& optionHelpMessage = String());

    Option(const Option& x);

    virtual ~Option();

    Option& operator=(const Option& x);

    /** Accessor */
    const String& getOptionName() const
    {
        return _optionName;
    }

    /** Modifier */
    void setOptionName(const String& optionName)
    {
        _optionName = optionName;
    }

    /** Accessor */
    const String& getDefaultValue() const
    {
        return _defaultValue;
    }

    /** Modifier. */
    void setDefaultValue(const String& defaultValue)
    {
        _defaultValue = defaultValue;
    }

    /** Accessor
        @return - Returns string representation of value
    */
    const String& getValue() const
    {
        return _value;
    }

    /** Modifier */
    void setValue(const String& value)
    {
        _value = value;
        _resolved = true;
    }

    /** Accessor */
    Boolean getRequired() const
    {
        return _required;
    }

    /** Modifier */
    void setRequired(Boolean required)
    {
        _required = required;
    }

    /** Accessor */
    Type getType() const
    {
        return _type;
    }

    /** Modifier */
    void setType(Type type)
    {
        _type = type;
    }

    /** Accessor */
    const Array<String>& getDomain() const;

    /** Modifier */
    void setDomain(const Array<String>& domain);

    /** Accessor */
    const String& getCommandLineOptionName() const
    {
        return _commandLineOptionName;
    }

    /** Accessor */
    const String& getOptionHelpMessage() const
    {
        return _optionHelpMessage;
    }

    /** Modifier */
    void setCommandLineOptionName(const String& commandLineOptionName)
    {
        _commandLineOptionName = commandLineOptionName;
    }

    /** Accesor. Returns true if an option value was ever obtained for
        this option.
    */
    Boolean isResolved() const
    {
        return _resolved;
    }

    /** Checks to see if the given value is valid or not. This method may be
        overriden by derived classes to do special purpose validation of the
        value. This implementation just checks the domain and type.
    */
    virtual Boolean isValid(const String& value) const;

private:
    String _optionName;
    String _defaultValue;
    String _value;
    Boolean _required;
    Type _type;
    Array<String> _domain;
    String _commandLineOptionName;
    String _optionHelpMessage;
    Boolean _resolved;
};

///////////////////////////////////////////////////////////////////////
//  OptionRow
///////////////////////////////////////////////////////////////////'//

/** The OptionRow provides a declarative way of defining Option objects.
    For the declarative programming enthusiast, we provide this structure.
    It provides a declarative way of defining options for the OptionManager
    class. Some developers prefer this since it makes all the options visible
    in a kind of table like structure. Here is an example of how it can be
    used to define a port number and hostname options. We also show how to
    register one of these option lists with an OptionManager.

    <pre>
        static OptionRow options[] =
        {
            { "port", "80", false, Option::NATURAL_NUMBER },
            { "hostname", "", true, Option::STRING }
        };

        ...

        OptionManager om;
        om.registerOptions(options, sizeof(options) / sizeof(options[0]));
    </pre>

    Recall that static memory areas are initialized with zeros so that the
    members that are not initialized explicitly in the example above are
    initialized implicitly with zeros (which the OptionManager used to
    determine that they are not used).

    It is possible to specify domains as well. For example, suppose we
    want to define a "color" option that can be in the following set:
    {"red", "green", "blue"}. Here is how to express that:

    <pre>
        static const char* colors[] = { "red", "green", "blue" };
        static const Uint32 NUM_COLORS = sizeof(colors) / sizeof(colors[0]);

        static OptionRow options[] =
        {
            { "color", "red", false, Option::STRING, colors, NUM_COLORS }
        };
    </pre>
    When a domain is defined, any of the keywords in that domain are legal
    option keywords.  For example.  With the domain defined above,  a command
    line or config file entry that includes -c blue sets the option "color" to
    blue. Note that this requires a space between -c and blue.
 */
struct OptionRow
{
    const char* optionName;
    const char* defaultValue;
    int required;
    Option::Type type;
    char** domain;
    Uint32 domainSize;
    const char* commandLineOptionName;
    const char* optionHelpMessage;
};
/* NOTE: The "required" object must be an int rather than a Boolean because
    bool on some platforms is not defined so that we cannot use a Boolean here
    with a static object.
*/

/** Exception class */
class PEGASUS_COMMON_LINKAGE OMMissingCommandLineOptionArgument
    : public Exception
{
public:

    OMMissingCommandLineOptionArgument(const String& optionName)
        : Exception(MessageLoaderParms(
              "Common.OptionManager.MISSING_CMD_LINE_OPTION",
              "Missing command line option argument: $0",
              optionName))
    {
    }
};

/** Exception class */
class PEGASUS_COMMON_LINKAGE OMInvalidOptionValue : public Exception
{
public:

    OMInvalidOptionValue(const String& name, const String& value)
        : Exception(MessageLoaderParms(
              "Common.OptionManager.INVALID_OPTION_VALUE",
              "Invalid option value: $0=\"$1\"",
              name,
              value))
    {
    }
};

/** Exception class */
class PEGASUS_COMMON_LINKAGE OMDuplicateOption : public Exception
{
public:
    OMDuplicateOption(const String& name)
        : Exception(MessageLoaderParms(
              "Common.OptionManager.DUPLICATE_OPTION",
              "Duplicate option: $0",
              name))
    {
    }
};

/** Exception class */
class PEGASUS_COMMON_LINKAGE OMConfigFileSyntaxError : public Exception
{
public:

    OMConfigFileSyntaxError(const String& file, Uint32 line)
        : Exception(_formatMessage(file, line)) { }

    static String _formatMessage(const String& file, Uint32 line);
};

/** Exception class */
class PEGASUS_COMMON_LINKAGE OMUnrecognizedConfigFileOption : public Exception
{
public:
    OMUnrecognizedConfigFileOption(const String& name)
        : Exception(MessageLoaderParms(
              "Common.OptionManager.UNRECOGNIZED_CONFIG_FILE_OPTION",
              "Unrecognized config file option: $0",
              name))
    {
    }
};

/** Exception class */
class PEGASUS_COMMON_LINKAGE OMMissingRequiredOptionValue : public Exception
{
public:
    OMMissingRequiredOptionValue(const String& name)
        : Exception(MessageLoaderParms(
              "Common.OptionManager.MISSING_REQUIRED_OPTION",
              "Missing required option value: $0",
              name))
    {
    }
};

/** Exception class */
class PEGASUS_COMMON_LINKAGE OMMBadCmdLineOption : public Exception
{
public:
    OMMBadCmdLineOption(const String& name)
        : Exception(MessageLoaderParms(
              "Common.OptionManager.PARAMETER_NOT_VALID",
              "Parameter not Valid: $0",
              name))
    {
    }
};

PEGASUS_NAMESPACE_END

#endif /* Pegasus_OM_h */