SpECTRE Documentation Coverage Report
Current view: top level - __w/spectre/spectre/docs/DevGuide - OptionParsing.md Hit Total Coverage
Commit: f1ddee3e40d81480e49140855d2b0e66fafaa908 Lines: 0 1 0.0 %
Date: 2020-12-02 17:35:08
Legend: Lines: hit not hit

          Line data    Source code
       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : # Option Parsing {#dev_guide_option_parsing}
       6             : 
       7             : SpECTRE can read YAML configuration files at runtime to set parameters
       8             : and choose between classes implementing an interface.  %Options are
       9             : parsed during code initialization and can be used to construct objects
      10             : placed in the Parallel::GlobalCache and options passed to the
      11             : parallel components.  The types necessary to mark objects for parsing
      12             : are declared in `Options/Options.hpp`.
      13             : 
      14             : ## General option format
      15             : 
      16             : An option is defined by an "option tag", represented by a `struct`.  At minimum,
      17             : the struct must declare the type of the object to be parsed and provide a brief
      18             : description of the meaning.  The name of the option in the input file
      19             : defaults to the name of the struct (excluding any template parameters
      20             : and scope information), but can be overridden by providing a static
      21             : `name()` function.  Several other pieces of information, such as
      22             : defaults, limits and grouping, may be provided if desired.  This information is
      23             : all included in the generated help output.
      24             : 
      25             : Examples:
      26             : \snippet Test_Options.cpp options_example_scalar_struct
      27             : \snippet Test_Options.cpp options_example_vector_struct
      28             : 
      29             : The option type can be any type understood natively by yaml-cpp
      30             : (fundamentals, `std::string`, and `std::map`, `std::vector`,
      31             : `std::list`, `std::array`, and `std::pair` of parsable types) and
      32             : types SpECTRE adds support for.  SpECTRE adds `std::unordered_map`
      33             : (but only with ordered keys), and various classes marked as
      34             : constructible in their declarations.
      35             : 
      36             : An option tag can be placed in a group by adding a `group` type alias to the
      37             : struct. The alias should refer to a type that, like option tags, defines a help
      38             : string and may override a static `name()` function.
      39             : 
      40             : Example:
      41             : \snippet Test_Options.cpp options_example_group
      42             : 
      43             : ## Constructible classes
      44             : 
      45             : A class that defines `static constexpr Options::String help` and a
      46             : typelist of option structs `options` can be created by the option
      47             : parser.  When the class is requested, the option parser will parse
      48             : each of the options in the `options` list, and then supply them to the
      49             : constructor of the class.  (See [Custom parsing](#custom-parsing)
      50             : below for more general creation mechanisms.)
      51             : 
      52             : Unlike option descriptions, which should be brief, the class help
      53             : string has no length limits and should give a description of the class
      54             : and any necessary discussion of its options beyond what can be
      55             : described in their individual help strings.
      56             : 
      57             : Creatable classes must be default constructible and move assignable.
      58             : 
      59             : The `Options::Context` is an optional argument to the constructor that should be
      60             : used when the constructor checks for validity of the input. If the input is
      61             : invalid, `PARSE_ERROR` is used to propagate the error message back through the
      62             : options ensuring that the error message will have a full backtrace so it is easy
      63             : for the user to diagnose. Finally, after the `Options::Context` the constructor
      64             : may optionally take the Metavariables struct, which is effectively the compile
      65             : time input file, and the constructor can use the Metavariables for whatever it
      66             : wants, including additional option parsing.
      67             : 
      68             : Example:
      69             : \snippet Test_CustomTypeConstruction.cpp class_creation_example
      70             : 
      71             : ## Factory
      72             : 
      73             : The factory interface creates an object of type
      74             : `std::unique_ptr<Base>` containing a pointer to some class derived
      75             : from `Base`.  The base class must define a type alias listing the
      76             : derived classes that can be created.
      77             : \code{cpp}
      78             :  using creatable_classes = tmpl::list<Derived1, ...>;
      79             : \endcode
      80             : The requested derived class is created in the same way as an
      81             : explicitly constructible class.
      82             : 
      83             : ## <a name="custom-parsing"></a>Custom parsing
      84             : 
      85             : Occasionally, the requirements imposed by the default creation
      86             : mechanism are too stringent.  In these cases, the construction
      87             : algorithm can be overridden by providing a specialization of the
      88             : struct
      89             : \code{cpp}
      90             : template <typename T>
      91             : struct Options::create_from_yaml {
      92             :   template <typename Metavariables>
      93             :   static T create(const Options::Option& options);
      94             : };
      95             : \endcode
      96             : The create function can perform any operations required to construct
      97             : the object.
      98             : 
      99             : Example of using a specialization to parse an enum:
     100             : \snippet Test_CustomTypeConstruction.cpp enum_creation_example
     101             : 
     102             : Note that in the case where the `create` function does *not* need to use the
     103             : `Metavariables` it is recommended that a general implementation forward to an
     104             : explicit instantiation with `void` as the `Metavariables` type. The reason for
     105             : using `void` specialization is to reduce compile time. Since we only need one
     106             : full implementation of the function independent of what type `Metavariables` is,
     107             : we should only parse and compile it once. By having a specialization on `void`
     108             : (or some other non-metavariables type like `NoSuchType`) we can handle the
     109             : metavariables-independent case efficiently. As a concrete example, the general
     110             : definition and forward declaration of the `void` specialization in the header
     111             : file would be:
     112             : 
     113             : \snippet Test_CustomTypeConstruction.cpp enum_void_creation_header_example
     114             : 
     115             : while in the `cpp` file the definition of the `void` specialization is:
     116             : 
     117             : \snippet Test_CustomTypeConstruction.cpp enum_void_creation_cpp_example

Generated by: LCOV version 1.14