File options.hxx

Defines

__OPTIONS_H__
OPTION(options, var, def)

Define for reading options which passes the variable name.

OPTION2(options, var1, var2, def)
OPTION3(options, var1, var2, var3, def)
OPTION4(options, var1, var2, var3, var4, def)
OPTION5(options, var1, var2, var3, var4, var5, def)
OPTION6(options, var1, var2, var3, var4, var5, var6, def)
VAROPTION(options, var, def)

Functions

template<>
std::string as<std::string>(const std::string &similar_to) const

Specialised as routines.

class Options
#include <options.hxx>

Class to represent hierarchy of options.

Getting and setting values

Each Options object represents a collection of key-value pairs which can be used as a map.

Options options;

// Set values
options["key"] = 1.0;

// Get values. Throws BoutException if not found
int val = options["key"]; // Sets val to 1 

// Return as specified type. Throws BoutException if not found
BoutReal var = options["key"].as<BoutReal>();

// A default value can be used if key is not found
BoutReal value = options["pi"].withDefault(3.14);

// Assign value with source label. Throws if already has a value from same source
options["newkey"].assign(1.0, "some source");

// Force assign a new value
options["newkey"].force(2.0, "some source");

A legacy interface is also supported:

options.set("key", 1.0, "code"); // Sets a key from source "code"

int val;
options.get("key", val, 0); // Sets val to 1, default to 0 if not found

If a variable has not been set then the default value is used

int other;
options.get("otherkey", other, 2.0); // Sets other to 2 because "otherkey" not found

Conversion is performed silently:

options.set("value", "2.34", "here"); // Set a string

BoutReal value;
options.get("value", value, 0.0); // Sets value to 2.34

If a conversion cannot be done, then an exception is thrown

Sections

Each Options object can also contain any number of sections, which are themselves Options objects.

Options &section = options["section"];

which can be nested:

options["section"]["subsection"]["value"] = 3;

This always succeeds; if the section does not exist then it is created.

The legacy interface uses pointers:

Options *section = options.getSection("section");

e.g. options->getSection(“section”)->getSection(“subsection”)->set(“value”, 3);

Options also know about their parents:

Options &parent = section.parent();

or

Options *parent = section->getParent();

Root options object

For convenience, to avoid having to pass Options objects around everywhere, there is a global singleton Options object which can be accessed with a static function

Options &root = Options::root();

or

Options *root = Options::getRoot();

This is used to represent all the options passed to BOUT++ either in a file or on the command line.

Public Types

using ValueType = bout::utils::variant<bool, int, BoutReal, std::string, Field2D, Field3D, Array<BoutReal>, Matrix<BoutReal>, Tensor<BoutReal>>

The type used to store values.

using ValuesMap = std::map<std::string, OptionValue>

Read-only access to internal options and sections to allow iteration over the tree

Public Functions

Options()

Constructor. This is called to create the root object.

Options(Options *parent_instance, std::string full_name)

Constructor used to create non-root objects

Parameters
  • parent: Parent object
  • sectionName: Name of the section, including path from the root

Options(const Options &other)

Copy constructor.

~Options()
Options &operator[](const std::string &name)

Get a sub-section or value

Example:

Options parent; auto child = parent[“child”];

parent is now a section.

Options &operator[](const char *name)
const Options &operator[](const std::string &name) const

Get a sub-section or value If this object is not a section, or if name is not a child, then a BoutException will be thrown

const Options &operator[](const char *name) const
template<typename T>
T operator=(T inputvalue)

Assignment from any type T Note: Using this makes this object a value.

Tries to stream the input to a std::stringstream and then saves the resulting string.

Options &operator=(const Options &other)

Copy assignment

This replaces the value, attributes and all children

Note that if only the value is desired, then that can be copied using the value member directly e.g. option2.value = option1.value;

template<typename T>
void assign(T val, const std::string source = "")

Assign a value to the option. This will throw an exception if already has a value

Example:

Options option; option[“test”].assign(42, “some source”);

Note: Specialised versions for types stored in ValueType

template<typename T>
void force(T val, const std::string source = "")

Force to a value Overwrites any existing setting

bool isSet() const

Test if a key is set by the user. Values set via default values are ignored.

template<typename T>
operator T() const

Cast operator, which allows this class to be assigned to type T

Example:

Options option; option[“test”] = 2.0; int value = option[“test”];

template<typename T>
T as(const T &similar_to = {}) const

Get the value as a specified type If there is no value then an exception is thrown Note there are specialised versions of this template for some types.

Example:

Options option; option[“test”] = 2.0; int value = option[“test”].as<int>();

An optional argument is an object which the result should be similar to. The main use for this is in Field2D and Field3D specialisations, where the Mesh and cell location are taken from this input.

template<typename T>
T withDefault(T def)

Get the value of this option. If not found, set to the default value

std::string withDefault(const char *def)

Overloaded version for const char* Note: Different from template since return type is different to input

Options &withDefault(const Options &def)

Overloaded version to copy from another option.

template<typename T>
T withDefault(T def) const

Get the value of this option. If not found, return the default value but do not set

Options &parent()

Get the parent Options object.

template<typename T>
bool operator==(const T &other) const

Equality operator Converts to the same type and compares This conversion may fail, throwing std::bad_cast

bool operator==(const char *other) const

Overloaded equality operator for literal strings.

template<typename T>
bool operator<(const T &other) const

Comparison operator.

bool operator<(const char *other) const

Overloaded comparison operator for literal strings.

template<typename T>
void set(const std::string &key, T val, const std::string &source = "", bool force = false)
template<typename T>
void forceSet(const std::string &key, T t, const std::string &source = "")
bool isSet(const std::string &key) const

Test if a key is set by the user. Values set via default values are ignored.

template<typename T, typename U>
void get(const std::string &key, T &val, U def, bool log = false)

Get options, passing in a reference to a variable which will be set to the requested value.

template<typename T, typename U>
void get(const std::string &key, T &val, U def, bool log = false) const
Options *getSection(const std::string &name)

Creates new section if doesn’t exist.

const Options *getSection(const std::string &name) const
Options *getParent() const
std::string str() const

Print string representation of this object and all sections in a tree structure

void printUnused() const

Print the options which haven’t been used.

std::map<std::string, Options::OptionValue> values() const
std::map<std::string, const Options *> subsections() const
const std::map<std::string, Options> &getChildren() const
bool isValue() const
bool isSection(const std::string &name = "") const
bool valueUsed() const

If the option value has been used anywhere.

Options &doc(const std::string &docstring)

Set a documentation string as an attribute “doc” Returns a reference to this, to allow chaining

template<>
void assign(bool val, const std::string source)
template<>
void assign(int val, const std::string source)
template<>
void assign(BoutReal val, const std::string source)
template<>
void assign(std::string val, const std::string source)
template<>
void assign(const char *val, const std::string source)
template<>
void assign(Field2D val, const std::string source)
template<>
void assign(Field3D val, const std::string source)
template<>
void assign(Array<BoutReal> val, const std::string source)
template<>
void assign(Matrix<BoutReal> val, const std::string source)
template<>
void assign(Tensor<BoutReal> val, const std::string source)
template<>
int as(const int &similar_to) const
template<>
BoutReal as(const BoutReal &similar_to) const
template<>
bool as(const bool &similar_to) const
template<>
Field2D as(const Field2D &similar_to) const
template<>
Field3D as(const Field3D &similar_to) const

Public Members

ValueType value

The value stored.

std::map<std::string, AttributeType> attributes

A collection of attributes belonging to the value Special attributes:

  • time_dimension [string] If this is set then changes to the value do not need to be forced. The string will be used when writing the output as the name of the time dimension (unlimited first dimension in NetCDF files).
  • source [string] Describes where the value came from e.g. a file name, or “default”.
  • type [string] The type the Option is converted to when used.
  • doc [string] Documentation, describing what the variable does

Public Static Functions

Options &root()

Get a reference to the only root instance.

void cleanup()

Free all memory.

static Options *getRoot()

Get a pointer to the only root instance (singleton)

void cleanCache()

clean the cache of parsed options

Private Functions

template<typename T>
void _set(T val, std::string source, bool force)
template<typename T>
bool similar(T a, T b) const

Tests if two values are similar.

template<>
bool similar(BoutReal a, BoutReal b) const

Specialised similar comparison methods.

Private Members

Options *parent_instance = {nullptr}
std::string full_name
bool is_section = false

An Option object can be a section and/or a value, or neither (empty)

Is this Options object a section?

std::map<std::string, Options> children

If a section then has children.

bool is_value = false

Is this Options object a value?

bool value_used = false

Record whether this value is used.

Private Static Attributes

const std::string DEFAULT_SOURCE = {_("default")}

The source label given to default values.

Options *root_instance = {nullptr}

Only instance of the root section.

class AttributeType : public mpark::variant<bool, int, BoutReal, std::string>
#include <options.hxx>

The type used to store attributes Extends the variant class so that cast operator can be implemented and assignment operator overloaded

Note: Due to default initialisation rules, if an attribute is used without being set, it will be false, 0, 0.0 and throw std::bad_cast if cast to std::string

Public Types

using Base = bout::utils::variant<bool, int, BoutReal, std::string>

Public Functions

AttributeType()

Constructor.

AttributeType(const AttributeType &other)

Copy constructor.

AttributeType(AttributeType &&other)

Move constructor.

~AttributeType()

Destructor.

AttributeType &operator=(const char *str)

Assignment from const char*.

template<typename T>
operator T() const

Cast operator, which allows this class to be assigned to type T This will throw std::bad_cast if it can’t be done

template<typename T>
T as() const

Get the value as a specified type This will throw std::bad_cast if it can’t be done

struct OptionValue
#include <options.hxx>

Class used to store values, together with information about their origin and usage

Public Functions

OptionValue(std::string value, std::string source, bool used)

This constructor needed for map::emplace Can be removed in C++17 with map::insert and brace initialisation

Public Members

std::string value
std::string source
bool used = false