balcl_optiontype

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Enumerators
  • Usage
    • Example 1: Basic Syntax
    • Example 2: Utility Methods

Purpose

Enumerate the types supported for command-line-option values.

Classes

• balcl::OptionType: command-line option types enum and utilities

See also

balcl_optionvalue, balcl_commandline

Description

This component provides a struct, balcl::OptionType, that is a namespace for:

• A typedef for each of the types allowed for command-line-option values.
• An enumerator that represents each of those types.
• A statically-initialized null pointer for each of those types.
• Utility functions.

The enumerator values are used to control type-dependent operations where the type is not known until runtime.

The names of related symbols are similar to each other. For example, the supported option-value type bsl::vector<bdlt::Datetime> has:

Symbol                               Description
------------------------------------ --------------------------------
balcl::OptionType::DatetimeArray     alias ('typedef')
balcl::OptionType::e_DATETIME_ARRAY  enumerator
balcl::OptionType::k_DATETIME_ARRAY  statically-initialized null pointer

The null pointer symbols are typically used with the constructor of balcl::TypeInfo. They provide a clearly named way to select the constructor to create an object having the desired type attribute. See balcl_typeinfo and balcl_commandline .

In addition to the conventional enumeration methods, this component also provides some utility functions that categorize the represented types. For example, given an enumerator representing a scalar type, the balcl::OptionType::toArrayType method returns the enumerator representing an array of that scalar type.

Enumerators

Enumerator       Type Alias    Type
---------------- ------------- -------------------------------
e_VOID           n/a           void
e_BOOL           Bool          bool
e_CHAR           Char          char
e_INT            Int           int
e_INT64          Int64         bsls::Types::Int64
e_DOUBLE         Double        double
e_STRING         String        bsl::string
e_DATETIME       Datetime      bdlt::Datetime
e_DATE           Date          bdlt::Date
e_TIME           Time          bdlt::Time
e_CHAR_ARRAY     CharArray     bsl::vector<char>
e_INT_ARRAY      IntArray      bsl::vector<int>
e_INT64_ARRAY    Int64Array    bsl::vector<bsls::Types::Int64>
e_DOUBLE_ARRAY   DoubleArray   bsl::vector<double>
e_STRING_ARRAY   StringArray   bsl::vector<bsl::string>
e_DATETIME_ARRAY DatetimeArray bsl::vector<bdlt::Datetime>
e_DATE_ARRAY     DateArray     bsl::vector<bdlt::Date>
e_TIME_ARRAY     TimeArray     bsl::vector<bdlt::Time>

Usage

This section illustrates intended use of this component.

Example 1: Basic Syntax

The following snippets of code provide a simple illustration of balcl::OptionType usage.

First, we create a variable value of type balcl::OptionType::Enum and initialize it to the value balcl::OptionType::e_STRING:

balcl::OptionType::Enum value = balcl::OptionType::e_STRING;

Next, we store a pointer to its ASCII representation in a variable asciiValue of type const char *:

const char *asciiValue = balcl::OptionType::toAscii(value);
assert(0 == bsl::strcmp(asciiValue, "STRING"));

Finally, we print the value to bsl::cout:

bsl::cout << value << bsl::endl;

This statement produces the following output on stdout:

STRING

Example 2: Utility Methods

In a software system devoted to assembling option values of various types, the code is often governed in terms of the enumerated values (balcl::OptionType::Enum) corresponding to the various types. In particular, in order to assemble an option value of one of the array types (e.g., balcl::OptionType::e_STRING_ARRAY), one must first construct the constitute elements.

Suppose we have a class, MyMultitypeValue, that can, at runtime, be set to contain a value of one of the types named by balcl::OptionType. We may want to initialize a MyMultitypeValue object from an input stream using a utility function MyMultitypeValueUtil::parse:

int MyMultitypeValueUtil::parse(MyMultitypeValue        *result,
                                bsl::ostream&            input,
                                balcl::OptionType::Enum  type)
{
    BSLS_ASSERT(result);
 
    result->setType(type);

If type is not one of the array types, as determined by the balcl::OptionType::isArrayType method, one calls MyMultitypeValueUtil::parseScalar:

    if (!balcl::OptionType::isArrayType(type)) {
        return MyMultitypeValueUtil::parseScalar(result, input, type);
                                                                  // RETURN
    } else {

Otherwise, we have an array type. In this case, we must call parseScalar repeatedly and build a vector of those scalar values. The scalar type can be calculated from the given array type by the balcl::OptionType::fromArrayType method:

        balcl::OptionType::Enum scalarType =
                                    balcl::OptionType::fromArrayType(type);
 
        MyMultitypeValue element(scalarType);
 
        int rc;
        while (0 == (rc = MyMultitypeValueUtil::parseScalar(&element,
                                                            input,
                                                            scalarType))) {
            result->append(element);
        }
        return rc;                                                // RETURN
    }
}