Line data    Source code

       1             : //* This file is part of the MOOSE framework
       2             : //* https://mooseframework.inl.gov
       3             : //*
       4             : //* All rights reserved, see COPYRIGHT for full restrictions
       5             : //* https://github.com/idaholab/moose/blob/master/COPYRIGHT
       6             : //*
       7             : //* Licensed under LGPL 2.1, please see LICENSE for details
       8             : //* https://www.gnu.org/licenses/lgpl-2.1.html
       9             : 
      10             : #pragma once
      11             : 
      12             : // C++ includes
      13             : #include <string>
      14             : #include <set>
      15             : #include <vector>
      16             : #include <map>
      17             : 
      18             : // MOOSE includes
      19             : #include "MooseEnumItem.h"
      20             : 
      21             : /**
      22             :  * The base class for both the MooseEnum and MultiMooseEnum classes.
      23             :  */
      24             : class MooseEnumBase
      25             : {
      26             : public:
      27             :   /**
      28             :    * Constructor that takes a list of enumeration values, and a
      29             :    * separate string to set a default for this instance.
      30             :    * @param names - a list of names for this enumeration
      31             :    * @param allow_out_of_range - determines whether this enumeration will accept values outside of
      32             :    *                             its range of defined values.
      33             :    */
      34             :   MooseEnumBase(std::string names, bool allow_out_of_range = false);
      35             : 
      36             :   /**
      37             :    * Copy Constructor for use when creating vectors of MooseEnumBases
      38             :    * @param other_enum - The other enumeration to copy state from
      39             :    */
      40             :   MooseEnumBase(const MooseEnumBase & other_enum);
      41             : 
      42             :   /**
      43             :    * Copy Assignment operator must be explicitly defined when a copy ctor exists and this
      44             :    * method is used.
      45             :    */
      46   104773256 :   MooseEnumBase & operator=(const MooseEnumBase & other_enum) = default;
      47             : 
      48             :   /**
      49             :    * This class must have a virtual destructor since it has derived classes.
      50             :    */
      51   160359074 :   virtual ~MooseEnumBase() = default;
      52             : 
      53             :   /**
      54             :    * Deprecates various options in the MOOSE enum. For each deprecated option,
      55             :    * you may supply an optional new option that will be used in a message telling
      56             :    * the user which new option replaces the old one.
      57             :    */
      58             :   virtual void deprecate(const std::string & name, const std::string & raw_name = "");
      59             : 
      60             :   /**
      61             :    * Method for returning a vector of all valid enumeration names for this instance
      62             :    * @return a vector of names
      63             :    */
      64             :   std::vector<std::string> getNames() const;
      65             : 
      66             :   /**
      67             :    * Method for returning the raw name strings for this instance
      68             :    * @return a space separated list of names
      69             :    */
      70             :   std::string getRawNames() const;
      71             : 
      72             :   /**
      73             :    * Method for returning a vector of ids for this instance
      74             :    * @return a vector of ints containing the possible ids for this enumeration
      75             :    */
      76             :   std::vector<int> getIDs() const;
      77             : 
      78             :   /**
      79             :    * IsValid
      80             :    * @return - a Boolean indicating whether this Enumeration has been set
      81             :    */
      82             :   virtual bool isValid() const = 0;
      83             : 
      84             :   /**
      85             :    * isOutOfRangeAllowed
      86             :    * @return - a Boolean indicating whether enum names out of range are allowed
      87             :    */
      88      578782 :   bool isOutOfRangeAllowed() const { return _allow_out_of_range; }
      89             : 
      90             :   /**
      91             :    * Return the complete set of available flags.
      92             :    */
      93       54183 :   const std::set<MooseEnumItem> & items() const { return _items; }
      94             : 
      95             :   /**
      96             :    * Add an item documentation string
      97             :    */
      98             :   void addDocumentation(const std::string & name, const std::string & doc);
      99             : 
     100             :   /**
     101             :    * Get the map containing each item's documentation string
     102             :    */
     103             :   const std::map<MooseEnumItem, std::string> & getItemDocumentation() const;
     104             : 
     105             :   ///@{
     106             :   /**
     107             :    * Locate an item.
     108             :    */
     109             :   std::set<MooseEnumItem>::const_iterator find(const MooseEnumItem & other) const;
     110             :   std::set<MooseEnumItem>::const_iterator find(const std::string & name) const;
     111             :   std::set<MooseEnumItem>::const_iterator find(int id) const;
     112             :   ///@}
     113             : 
     114             :   /**
     115             :    * Compute the next valid ID.
     116             :    */
     117             :   int getNextValidID() const;
     118             : 
     119             :   /**
     120             :    * Adds an enumeration item from name
     121             :    */
     122             :   MooseEnumBase & operator+=(const std::string & name);
     123             :   /**
     124             :    * Adds enumeration items from a list of names
     125             :    */
     126             :   MooseEnumBase & operator+=(const std::initializer_list<std::string> & names);
     127             : 
     128             : protected:
     129             :   MooseEnumBase();
     130             : 
     131             :   ///@{
     132             :   /**
     133             :    * Methods to add possible enumeration value to the enum.
     134             :    *
     135             :    * The MooseEnum/MultiMooseEnum are not designed to be modified, with respect to the list
     136             :    * of possible values. However, this is not the case for the ExecFlagEnum which is a special
     137             :    * type of MultiMooseEnum for managing the "execute_on" flags. These methods are used by
     138             :    * ExecFlagEnum to allow users to modify the available execute flags for their object.
     139             :    */
     140             :   void addEnumerationNames(const std::string & names);
     141             :   const MooseEnumItem & addEnumerationName(const std::string & raw_name);
     142             :   const MooseEnumItem & addEnumerationName(const std::string & name, const int & value);
     143             :   const MooseEnumItem & addEnumerationItem(const MooseEnumItem & item);
     144             :   ///@}
     145             : 
     146             :   /**
     147             :    * Method that must be implemented to check derived class values against the _deprecated_names
     148             :    */
     149             :   virtual void checkDeprecated() const = 0;
     150             : 
     151             :   /**
     152             :    * Check and warn deprecated values
     153             :    */
     154             :   void checkDeprecated(const MooseEnumItem & item) const;
     155             : 
     156             :   /// Storage for the assigned items
     157             :   std::set<MooseEnumItem> _items;
     158             : 
     159             :   /// The map of deprecated names and optional replacements
     160             :   std::map<MooseEnumItem, MooseEnumItem> _deprecated_items;
     161             : 
     162             :   /// Flag to enable enumeration items not previously defined
     163             :   bool _allow_out_of_range;
     164             : 
     165             :   /// The map of items and their respective documentation strings
     166             :   std::map<MooseEnumItem, std::string> _item_documentation;
     167             : };