IOption.hpp

#pragma once
 
///=============================================================================
/// \file
/// \brief  Abstract option classes.
/// \author WK
/// \date   29.02.2020
///=============================================================================
 
#include <opals/fwd.hpp>
#include <opals/UsageLevel.hpp>
#include <opals/ValueSource.hpp>
#include <opals/OptionNames.hpp>
#include <type_traits>
 
namespace opals
{
  /// Contains the public interface of OPALS option types.
  namespace opts
  {
 
    /// Enumerates all option types
    enum struct Specs
    {
      leaf = 1,
      group = leaf << 1,
      vector = group << 1,
      array = vector << 1,
      dim1 = vector | array
    };
 
    template< Names nam >
    using NameT = std::integral_constant< Names, nam >;
 
    /// Base class of all option types.
    struct IBase
    {
      /// The option name as enumerator.
      virtual Names      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 minUsageLevel()    const = 0;
      /// The sub-type of this option.
      virtual Specs      specialization()   const = 0;
    protected:
      virtual ~IBase() {}
    };
 
    /// Leaf that holds a read-only value
    /** \tparam nam    The leaf name.
        \tparam rdOnly If true, then this leaf's value may not be changed.
        \tparam T      The value type. */
    template< Names nam, bool rdOnly, class T >
    struct ILeaf
      : IBase
    {
      typedef NameT<nam> Name;
 
      /// Frequency / expected skills of users that access this leaf.
      virtual UsageLevel usageLevel()  const = 0;
      /// The context in which the value has been set.
      virtual ValueSource 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;
 
      /// 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 nam  The leaf name.
        \tparam T    The value type. */
    template< Names nam, class T >
    struct ILeaf< nam, false, T >
      : ILeaf< nam, true, T >
    {
      /// Set the value.
      virtual void set(const T& value) = 0;
    };
 
  }
}
 
#include <opals/IAccess.hpp>
 
namespace opals
{
  namespace opts
  {
 
    /// A group of options
    /** \tparam nam    The group name.
        \tparam rdOnly If true, then the group provides only constant access to its members. Otherwise, also non-constant.
        \tparam Opts   The group members. */
    template< Names nam, bool rdOnly, class... Opts >
    struct IGroup
      : IAcc< rdOnly, Opts... >
    {
      typedef NameT<nam> Name;
    };
 
    /// A container of read-only options.
    /** \tparam nam    The name of the container and its elements.
        \tparam rdOnly If true, then this container provides only constant access to its elements. Otherwise, also non-constant.
        \tparam Opts   The sequence of group members.
        Provides access to specific elements and to the default element. */
    template< Names nam, bool rdOnly, class... Opts >
    struct IContainer
      : IBase
    {
      typedef NameT<nam> Name;
      typedef IGroup< nam, rdOnly, Opts... > 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.
    template< Names nam, class... Opts >
    struct IContainer< nam, false, Opts... >
      : IBase
    {
      typedef NameT<nam> Name;
      typedef IGroup< nam, false, Opts... > 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 a variable number of read-only options.
    /** \tparam nam    The name of the vector and its elements.
        \tparam rdOnly If true, then this vector provides only constant access to its elements. Otherwise, also non-constant.
        \tparam Opts   The sequence of group members. */
    template< Names nam, bool rdOnly, class... Opts >
    struct IVector
      : IContainer< nam, rdOnly, Opts... >
    {
    };
 
    /// A vector of a variable number of read-write options.
    template< Names nam, class... Opts >
    struct IVector< nam, false, Opts... >
      : IContainer< nam, false, Opts... >
    {
      /// Set the number of elements. New elements are initialized with the default element.
      virtual void resize( std::size_t size ) = 0;
    };
 
    /// An array of N options.
    /** \tparam nam    The name of the array and its elements.
        \tparam rdOnly If true, then this array provides only constant access to its elements. Otherwise, also non-constant.
        \tparam N      The number of elements.
        \tparam Opts   The sequence of group members. */
    template< Names nam, bool rdOnly, std::size_t N, class... Opts >
    struct IArray
      : IContainer< nam, rdOnly, Opts... >
    {
    };
 
  }
}