IOption.hpp

#ifndef OPALS_IOPTION_HPP_INCLUDED
#define OPALS_IOPTION_HPP_INCLUDED

///=============================================================================
/// \file   IOption.hpp
/// \brief  Abstract option classes.
/// \author WK
/// \date   20.02.2017
///=============================================================================

#include <opals/fwd.hpp>
#include <opals/UsageLevel.hpp>
#include <opals/ValueSource.hpp>
#include <opals/OptionNames.hpp>
#include <type_traits>

namespace opals { namespace opts
{

  /// Enumerates all option types
  namespace Specs
  {
    enum Type {
      leaf = 1,
      group = leaf << 1,
      vector = group << 1,
      array = vector << 1,
      dim1 = vector | array
    };
  }

  template< Names::Type name_ >
  struct NameT : std::integral_constant< Names::Type, name_ > {};

  struct Void;

  template<class Head_, class Tail_ = Void >
  struct Cons
  {
    typedef Head_ Head;
    typedef Tail_ Tail;
  };

  template< class >
  struct IsCons : std::false_type {};

  template< class Head_, class Tail_ >
  struct IsCons< Cons< Head_, Tail_ > > : std::true_type {};

  /// Base class of all option types.
  struct IBase
  {
    virtual ~IBase() {}
    /// The option name as enumerator.
    virtual Names::Type      enumerator()       const = 0;
    /// The option name as string.
    virtual String           name()             const = 0;
    /// The option name as string, preceded by the names of its parents, if any, interspersed with '.'
    virtual String           path()             const = 0;
    /// One-liner that describes this option.
    virtual String           shortDescription() const = 0;
    /// Longer text that describes this option in more detail.
    virtual String           longDescription()  const = 0;
    /// Returns true if this or any of its parents is read-only.
    virtual bool             readOnly()         const = 0;
    /// For a leaf, this is its own usage level. For a node, this is the minimum usage level of all of its descendants: basic < mid < pro
    virtual UsageLevel::Type minUsageLevel()    const = 0;
    /// The sub-type of this option.
    virtual Specs::Type      specialization()   const = 0;
  };

  /// Base class of all leaves.
  struct ILeafBase
    : IBase
  {
    /// Frequency / expected skills of users that access this leaf.
    virtual UsageLevel ::Type usageLevel()  const = 0;
    /// The context in which the value has been set.
    virtual ValueSource::Type valueSource() const = 0;
    /// If its value has not been set, a leaf is considered empty.
    /** Accessing its value then raises an exception. */
    virtual bool empty() const = 0;
  };

  /// Leaf that holds a read-only value
  /** \tparam name_     The leaf name.
      \tparam readOnly_ If true, then this leaf's value may not be changed.
      \tparam T         The value type. */
  template< Names::Type name_, bool readOnly_, class T >
  struct ILeaf
    : ILeafBase
  {
    typedef NameT<name_> Name;

    /// Get the value.
    virtual const T &get() const = 0;
    /// Get the value or default_ if empty.
    virtual const T &getOr( const T &default_ ) const = 0;
  };

  /// Leaf that holds a read-write value
  /** \tparam name_ The leaf name.
      \tparam T     The value type. */
  template< Names::Type name_, class T >
  struct ILeaf< name_, false, T >
    : ILeafBase
  {
    typedef NameT<name_> Name;
    /// Get the value.
    virtual const T &get() const = 0;
    /// Get the value or default_ if empty.
    virtual const T &getOr( const T &default_ ) const = 0;
    /// Set the value.
    virtual void set( const T &value ) = 0;
  };

#include <opals/IAccess.hpp>

  /// A group of member options
  /** \tparam name_     The group name.
      \tparam readOnly_ If true, then this group and its children may not changed.
      \tparam Opts_     The group members.
      Provides for each member const and non-const access functions of the respective name. */
  template< Names::Type name_, bool readOnly_, class Opts_ >
  struct IGroup
    : IAcc< readOnly_, Opts_ >::Type
  {
    typedef NameT<name_> Name;
  };

  /// A container of read-only options.
  /** \tparam name_     The name of the container and its elements.
      \tparam readOnly_ If true, then this container and its elements may not be changed.
      \tparam Opts_     If a scalar, then the element type is ILeaf, with that scalar as value type.
                        Otherwise, it is IGroup, with the respective sequence of group members.
      Provides access to specific elements and to the default element. */
  template< Names::Type name_, bool readOnly_, class Opts_ >
  struct IContainer
    : IBase
  {
    typedef typename std::conditional<
      IsCons<Opts_>::value,
      IGroup< name_, readOnly_, Opts_ >,
      ILeaf<  name_, readOnly_, Opts_ >
    >::type Element;

    /// The number of actual elements.
    virtual std::size_t size() const = 0;

    /// Access the default element.
    /** Changes to it are applied immediately to all actual elements. */
    virtual const Element &all() const = 0;

    /// Access an actual element.
    virtual const Element &operator[]( std::size_t idx ) const = 0;
  };

  /// A container of read-write options.
  /** \tparam name_     The name of the container and its elements.
      \tparam Opts_     If a scalar, then the element type is ILeaf, with that scalar as value type.
                        Otherwise, it is IGroup, with the respective sequence of group members.
      Provides access to specific elements and to the default element. */
  template< Names::Type name_, class Opts_ >
  struct IContainer< name_, false, Opts_ >
    : IBase
  {
    typedef typename std::conditional<
      IsCons<Opts_>::value,
      IGroup< name_, false, Opts_ >,
      ILeaf<  name_, false, Opts_ >
    >::type Element;

    /// The number of actual elements.
    virtual std::size_t size() const = 0;

    /** \name Default element.
        Changes to it are applied immediately to all actual elements. */
    ///@{
    virtual const Element &all() const = 0;
    virtual       Element &all()       = 0;
    ///}@

    /// \name Access an actual element.
    ///@{
    virtual const Element &operator[]( std::size_t idx ) const = 0;
    virtual       Element &operator[]( std::size_t idx )       = 0;
    ///}@
  };

  /// A vector of dynamic size of read-only options.
  /** \tparam name_     The name of the vector and its elements.
      \tparam readOnly_ If true, then this vector and its elements may not be changed.
      \tparam Opts_     If a scalar, then the element type is ILeaf, with that scalar as value type.
                        Otherwise, it is IGroup, with the respective sequence of group members. */
  template< Names::Type name_, bool readOnly_, class Opts_ >
  struct IVector
    : IContainer< name_, readOnly_, Opts_ >
  {
    typedef NameT<name_> Name;
  };

  /// A vector of dynamic size of read-write options.
  /** \tparam name_     The name of the vector and its elements.
      \tparam Opts_     If a scalar, then the element type is ILeaf, with that scalar as value type.
                        Otherwise, it is IGroup, with the respective sequence of group members. */
  template< Names::Type name_, class Opts_ >
  struct IVector< name_, false, Opts_ >
    : IContainer< name_, false, Opts_ >
  {
    typedef NameT<name_> Name;

    /// Set the number of elements. New elements are initialized with the default element.
    virtual void resize( std::size_t size ) = 0;
  };

  /// An array of fixed size N of options.
  /** \tparam name_     The name of the array and its elements.
      \tparam readOnly_ If true, then this array and its elements may not be changed.
      \tparam N         The number of elements.
      \tparam Opts_     If a scalar, then the element type is ILeaf, with that scalar as value type.
                        Otherwise, it is IGroup, with the respective sequence of group members. */
  template< Names::Type name_, bool readOnly_, std::size_t N, class Opts_ >
  struct IArray
    : IContainer< name_, readOnly_, Opts_ >
  {
    typedef NameT<name_> Name;
  };

} }

#endif