// balcl_optiontype.h                                                 -*-C++-*-
#ifndef INCLUDED_BALCL_OPTIONTYPE
#define INCLUDED_BALCL_OPTIONTYPE

#include <bsls_ident.h>
BSLS_IDENT("$Id: $")

//@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
//     }
// }
// ```

#include <balscm_version.h>

#include <bsls_assert.h>
#include <bsls_types.h>  // 'bsls::Types::Int64'

#include <bsl_iosfwd.h>
#include <bsl_string.h>
#include <bsl_vector.h>

#include <bdlt_date.h>
#include <bdlt_datetime.h>
#include <bdlt_time.h>

namespace BloombergLP {


namespace balcl {
                        // =================
                        // struct OptionType
                        // =================

/// This `struct` provides a namespace for enumerating types used for
/// command-line option values.  See {Enumerators} for details.
///
/// This `struct`:
/// * Supports a complete set of *enumeration* operations.
/// * Provides several additional utility functions.
///
/// For terminology see `bsldoc_glossary`.
struct OptionType {

  public:
    // TYPES
    typedef bool                            Bool;
    typedef char                            Char;
    typedef int                             Int;
    typedef bsls::Types::Int64              Int64;
    typedef double                          Double;
    typedef bsl::string                     String;
    typedef bdlt::Datetime                  Datetime;
    typedef bdlt::Date                      Date;
    typedef bdlt::Time                      Time;
    typedef bsl::vector<char>               CharArray;
    typedef bsl::vector<int>                IntArray;
    typedef bsl::vector<bsls::Types::Int64> Int64Array;
    typedef bsl::vector<double>             DoubleArray;
    typedef bsl::vector<bsl::string>        StringArray;
    typedef bsl::vector<bdlt::Datetime>     DatetimeArray;
    typedef bsl::vector<bdlt::Date>         DateArray;

    /// Aliases for each of the supported command-line-option types.
    typedef bsl::vector<bdlt::Time>         TimeArray;

    enum Enum {
        // Enumerate the set of value types available for command-line options.
        e_VOID
      , e_BOOL
      , e_CHAR
      , e_INT
      , e_INT64
      , e_DOUBLE
      , e_STRING
      , e_DATETIME
      , e_DATE
      , e_TIME
      , e_CHAR_ARRAY
      , e_INT_ARRAY
      , e_INT64_ARRAY
      , e_DOUBLE_ARRAY
      , e_STRING_ARRAY
      , e_DATETIME_ARRAY
      , e_DATE_ARRAY
      , e_TIME_ARRAY
    };

    /// `EnumToType<TYPE_ENUMERATOR>::type` is the (C++) type corresponding
    /// to the (template parameter) `TYPE_ENUMERATOR` `Enum` value.  See
    /// `TypeToEnum` for the inverse metafunction.
    template <Enum TYPE_ENUMERATOR>
    struct EnumToType {
    };

    /// `TypeToEnum<TYPE>::value` is the `Enum` value corresponding to the
    /// (template parameter) `TYPE` where `TYPE` matches one of the
    /// `typedef`s defined above or `void`.  See `EnumToType` for the
    /// inverse metafunction.
    template <class TYPE>
    struct TypeToEnum {
    };

    // PUBLIC CLASS DATA

// BDE_VERIFY pragma: -MN04: // Pointer member names must end in '_p'

// BDE_VERIFY pragma: -KS02: // Tag implicitly requires private declaration
                             // These rules not intended for public data.

    static Bool          * const k_BOOL;
    static Char          * const k_CHAR;
    static Int           * const k_INT;
    static Int64         * const k_INT64;
    static Double        * const k_DOUBLE;
    static String        * const k_STRING;
    static Datetime      * const k_DATETIME;
    static Date          * const k_DATE;
    static Time          * const k_TIME;
    static CharArray     * const k_CHAR_ARRAY;
    static IntArray      * const k_INT_ARRAY;
    static Int64Array    * const k_INT64_ARRAY;
    static DoubleArray   * const k_DOUBLE_ARRAY;
    static StringArray   * const k_STRING_ARRAY;
    static DatetimeArray * const k_DATETIME_ARRAY;
    static DateArray     * const k_DATE_ARRAY;

    /// Statically initialized null pointers, one for each supported
    /// command-line-option type.
    static TimeArray     * const k_TIME_ARRAY;

// BDE_VERIFY pragma: +KS02: // Tag implicitly requires private declaration

// BDE_VERIFY pragma: +MN04: // Pointer member names must end in '_p'

    // CLASS METHODS

    /// If `isArrayType(type)` for the specified `type`, then return the type
    /// of the elements of that array `type`; otherwise return `e_VOID`.
    static Enum fromArrayType(Enum type);

    /// Return `true` if the specified `type` corresponds to an array type, and
    /// `false` otherwise.
    static bool isArrayType(Enum type);

    /// If there is an array type whose elements have the specified `type`
    /// then return that array type; otherwise return `e_VOID`.
    /// `e_VOID == toArrayType(e_BOOL)` because an array of boolean values
    /// is not allowed as a command-line-option type.  Note that
    /// `type == fromArrayType(TYPE)` when `TYPE != e_VOID` is returned.
    static Enum toArrayType(Enum type);

                                  // Aspects

    /// Write the string representation of the specified enumeration `value` to
    /// the specified output `stream`, and return a reference to `stream`.
    /// Optionally specify an initial indentation `level`, whose absolute value
    /// is incremented recursively for nested objects.  If `level` is
    /// specified, optionally specify `spacesPerLevel`, whose absolute value
    /// indicates the number of spaces per indentation level for this and all
    /// of its nested objects.  If `level` is negative, suppress indentation of
    /// the first line.  If `spacesPerLevel` is negative, format the entire
    /// output on one line, suppressing all but the initial indentation (as
    /// governed by `level`).  See `toAscii` for what constitutes the string
    /// representation of a `OptionType::Enum` value.
    static bsl::ostream& print(bsl::ostream&    stream,
                               OptionType::Enum value,
                               int              level          = 0,
                               int              spacesPerLevel = 4);

    /// Return the (non-modifiable) string representation corresponding to
    /// the specified enumeration `value`, if it exists, and a unique
    /// (error) string otherwise.  The string representation of `value`
    /// matches its corresponding enumerator name with the `e_` prefix
    /// elided.  For example:
    /// ```
    /// bsl::cout << balcl::OptionType::toAscii(
    ///                                   OptionType::e_STRING);
    /// ```
    /// will print the following on standard output:
    /// ```
    /// STRING
    /// ```
    /// Note that specifying a `value` that does not match any of the
    /// enumerators will result in a string representation that is distinct
    /// from any of those corresponding to the enumerators, but is otherwise
    /// unspecified.
    static const char *toAscii(OptionType::Enum value);
};

// FREE OPERATORS

/// Write the string representation of the specified enumeration `value` to
/// the specified output `stream` in a single-line format, and return a
/// reference to `stream`.  See `toAscii` for what constitutes the string
/// representation of a `OptionType::Enum` value.  Note that this method has
/// the same behavior as:
/// ```
/// balcl::OptionType::print(stream, value, 0, -1);
/// ```
bsl::ostream& operator<<(bsl::ostream& stream, OptionType::Enum value);

// ============================================================================
//                            INLINE DEFINITIONS
// ============================================================================

                             // -----------------
                             // struct OptionType
                             // -----------------

// CLASS METHODS
inline
OptionType::Enum OptionType::fromArrayType(OptionType::Enum type)
{
    BSLS_ASSERT(e_VOID <= type);
    BSLS_ASSERT(type   <= e_TIME_ARRAY);

    if (type < e_CHAR_ARRAY) {
        return e_VOID;                                                // RETURN
    }

    return static_cast<OptionType::Enum>(
                     static_cast<int>(type) - (  static_cast<int>(e_CHAR_ARRAY)
                                               - static_cast<int>(e_CHAR)));
}

inline
bool OptionType::isArrayType(OptionType::Enum type)
{
    BSLS_ASSERT(e_VOID <= type);
    BSLS_ASSERT(type   <= e_TIME_ARRAY);

    return e_CHAR_ARRAY <= type;
}

inline
OptionType::Enum OptionType::toArrayType(OptionType::Enum type)
{
    BSLS_ASSERT(e_VOID <= type);
    BSLS_ASSERT(type   <= e_TIME_ARRAY);

    return e_VOID == type || e_BOOL == type || e_CHAR_ARRAY <= type
         ? e_VOID
         : static_cast<OptionType::Enum>(
                    static_cast<int>(type) + (  static_cast<int>(e_CHAR_ARRAY)
                                              - static_cast<int>(e_CHAR)));
}

}  // close package namespace

// FREE OPERATORS
inline
bsl::ostream& balcl::operator<<(bsl::ostream&    stream,
                                OptionType::Enum value)
{
    return OptionType::print(stream, value, 0, -1);
}

namespace balcl {

                        // -----------------------------
                        // struct OptionType::EnumToType
                        // -----------------------------

// TYPES
template <>
struct OptionType::EnumToType<OptionType::e_VOID> {
    // TYPES
    typedef void type;
};

template <>
struct OptionType::EnumToType<OptionType::e_BOOL> {
    // TYPES
    typedef Bool type;
};

template <>
struct OptionType::EnumToType<OptionType::e_CHAR> {
    // TYPES
    typedef Char type;
};

template <>
struct OptionType::EnumToType<OptionType::e_INT> {
    // TYPES
    typedef Int type;
};

template <>
struct OptionType::EnumToType<OptionType::e_INT64> {
    // TYPES
    typedef Int64 type;
};

template <>
struct OptionType::EnumToType<OptionType::e_DOUBLE> {
    // TYPES
    typedef Double type;
};

template <>
struct OptionType::EnumToType<OptionType::e_STRING> {
    // TYPES
    typedef String type;
};

template <>
struct OptionType::EnumToType<OptionType::e_DATETIME> {
    // TYPES
    typedef Datetime type;
};

template <>
struct OptionType::EnumToType<OptionType::e_DATE> {
    // TYPES
    typedef Date type;
};

template <>
struct OptionType::EnumToType<OptionType::e_TIME> {
    // TYPES
    typedef Time type;
};

template <>
struct OptionType::EnumToType<OptionType::e_CHAR_ARRAY> {
    // TYPES
    typedef CharArray type;
};

template <>
struct OptionType::EnumToType<OptionType::e_INT_ARRAY> {
    // TYPES
    typedef IntArray type;
};

template <>
struct OptionType::EnumToType<OptionType::e_INT64_ARRAY> {
    // TYPES
    typedef Int64Array type;
};

template <>
struct OptionType::EnumToType<OptionType::e_DOUBLE_ARRAY> {
    // TYPES
    typedef DoubleArray type;
};

template <>
struct OptionType::EnumToType<OptionType::e_STRING_ARRAY> {
    // TYPES
    typedef StringArray type;
};

template <>
struct OptionType::EnumToType<OptionType::e_DATETIME_ARRAY> {
    // TYPES
    typedef DatetimeArray type;
};

template <>
struct OptionType::EnumToType<OptionType::e_DATE_ARRAY> {
    // TYPES
    typedef DateArray type;
};

template <>
struct OptionType::EnumToType<OptionType::e_TIME_ARRAY> {
    // TYPES
    typedef OptionType::TimeArray type;
};

                        // -----------------------------
                        // struct OptionType::TypeToEnum
                        // -----------------------------

// TYPES
template <>
struct OptionType::TypeToEnum<void> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::Bool> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::Char> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::Int> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::Int64> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::Double> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::String> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::Datetime> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::Date> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::Time> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::CharArray> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::IntArray> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::Int64Array> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::DoubleArray> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::StringArray> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::DatetimeArray> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::DateArray> {
    // PUBLIC DATA
    static const Enum value;
};

template <>
struct OptionType::TypeToEnum<OptionType::TimeArray> {
    // PUBLIC DATA
    static const Enum value;
};

}  // close package namespace
}  // close enterprise namespace

#endif

// ----------------------------------------------------------------------------
// Copyright 2020 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
