xentara-plugin v2.0.3
The Xentara Plugin Framework
|
A context used when loading skill elements. More...
#include <xentara/config/Context.hpp>
Classes | |
class | ExternalConfigPath |
A file path used to find an external config file or directory. More... | |
struct | FindExternalConfigOptions |
Options for findExternalConfig() More... | |
class | ReferenceKey |
A key used to resolve a cross reference in the configuration. More... | |
Public Member Functions | |
virtual | ~Context ()=0 |
Virtual destructor. | |
Resolving cross references | |
template<ReferenceResolvable Type, std::invocable< const std::shared_ptr< Type > & > Handler> | |
auto | resolve (ReferenceKey key, Handler handler) -> void |
Submits a request to resolve a cross reference using a shared pointer. | |
template<ReferenceResolvable Type, std::invocable< std::reference_wrapper< Type > > Handler> | |
auto | resolve (ReferenceKey key, Handler handler) -> void |
Submits a request to resolve a cross reference using a reference wrapper. | |
template<ReferenceResolvable Type, typename SharedPointer > requires std::is_assignable_v<SharedPointer &, const std::shared_ptr<Type> &> | |
auto | resolve (ReferenceKey key, std::reference_wrapper< SharedPointer > variable) -> void |
Submits a request to resolve a cross reference using a shared pointer and assign it to a variable. | |
template<ReferenceResolvable Type, typename Reference > requires std::is_assignable_v<Reference &, const std::reference_wrapper<Type> &> | |
auto | resolve (ReferenceKey key, std::reference_wrapper< Reference > variable) -> void |
Submits a request to resolve a cross reference using a reference wrapper and assign it to a variable. | |
template<ReferenceResolvable Type, typename Pointer > requires std::is_assignable_v<Pointer &, Type *> | |
auto | resolve (ReferenceKey key, std::reference_wrapper< Pointer > variable) -> void |
Submits a request to resolve a cross reference using a raw pointer and assign it to a variable. | |
template<CopyResolvable Type, std::invocable< const Type & > Handler> | |
auto | resolve (ReferenceKey key, Handler handler) -> void |
Submits a request to resolve a cross reference using a reference-like object. | |
template<CopyResolvable Type, typename Reference > requires std::is_assignable_v<Reference &, const Type &> | |
auto | resolve (ReferenceKey key, std::reference_wrapper< Reference > variable) -> void |
Submits a request to resolve a cross reference using a reference-like object and assign it to a variable. | |
Creating synthetic children | |
template<std::derived_from< skill::Element > Derived, typename... ConstructorArguments> | |
auto | createSyntheticChild (std::reference_wrapper< const skill::Element::Class > elementClass, std::string name, ConstructorArguments &&...constructorArguments) -> std::shared_ptr< Derived > |
Creates a synthetic child element. | |
template<std::derived_from< skill::Element > Derived, typename... ConstructorArguments> | |
auto | createSyntheticChild (std::string name, ConstructorArguments &&...constructorArguments) -> std::shared_ptr< Derived > |
Creates a synthetic child element, automatically selecting the class object. | |
Finding external configurations | |
auto | findExternalConfig (ExternalConfigPath path, std::string_view parameterDescription, std::string_view fileDescriptionFormat, const FindExternalConfigOptions &options={}) const -> std::optional< std::filesystem::path > |
Finds an external configuration. | |
A context used when loading skill elements.
|
pure virtualdefault |
Virtual destructor.
auto xentara::config::Context::createSyntheticChild | ( | std::reference_wrapper< const skill::Element::Class > | elementClass, |
std::string | name, | ||
ConstructorArguments &&... | constructorArguments | ||
) | -> std::shared_ptr<Derived> |
Creates a synthetic child element.
A synthetic child element is a child element that is automatically created by the parent, and does not appear in the configuration.
Derived | The class of the child element |
elementClass | The meta-information object for the class of the child element |
name | The name of the child element. |
constructorArguments | The arguments for the element’s constructor |
auto xentara::config::Context::createSyntheticChild | ( | std::string | name, |
ConstructorArguments &&... | constructorArguments | ||
) | -> std::shared_ptr<Derived> |
Creates a synthetic child element, automatically selecting the class object.
A synthetic child element is a child element that is automatically created by the parent, and does not appear in the configuration.
This function fetches the meta-information object for the child element class by calling Derived::Class::instance(). It is equivalent the following:
Derived | The class of the child element. The meta-information object for the class must be available using Derived::Class::instance(). |
name | The name of the child element. |
constructorArguments | The arguments for the element’s constructor |
auto xentara::config::Context::findExternalConfig | ( | ExternalConfigPath | path, |
std::string_view | parameterDescription, | ||
std::string_view | fileDescriptionFormat, | ||
const FindExternalConfigOptions & | options = {} |
||
) | const -> std::optional< std::filesystem::path > |
Finds an external configuration.
This function finds an external configuration file by searching the standard configuration directories. This function is intended to find an extended configuration specified in a Xentara model file. By specifying a different file type in options, this function can also be used to find directories, or other file system entries.
The configuration path can be specified as an absolute or a relative path. If the path is absolute, then it is simple used as-is. If the path is relative, this function will search the standard Xentara config directories, as well as any custom directories the user specified on the command line.
If a suitable configuration is found, and the fileType option is not std::filesystem::file_type::none, then the file type of the file system entry is checked. If no suitable configuration is found (either because an absolute path does not exists, or no matching file system entry was found for a relative path), then the behaviour depends on the options allowMissing and useFallback:
path | The relative or absolute path of the configuration. |
parameterDescription | A description of the configuration parameter. This description is used in error messages about an invalid configuration parameter, for example, if the path is an empty string. The description should be a descriptive string like “CODESYS PLC ini file path”, or “token file path in InfluxDB authentication”, and should generally include the word “path”. |
fileDescriptionFormat | An std::format-compatible format string suitable for generating a description of the actual file system entry. The format must have a single replacement field (“{}”) for the path or file name. This description is used in error messages about the path itself, for example, if the the file system entry does not exists, or if it is has the wrong file type. The format should generate a descriptive string with proper context, like “CODESYS PLC ini file "{}"”, or “token file "{}" for InfluxDB authentication”, and should generally not include the word “path”. The replacement field for the path or file name should be enclosed in double quotes. |
options | The search options. You can use these options to specify a subdirectory, to change the file type, |
std::runtime_error | No suitable configuration could be found. If the option allowMissing was set, and no configuration was found at all, no exception is thrown. Instead std::nullopt is returned. |
auto xentara::config::Context::resolve | ( | ReferenceKey | key, |
Handler | handler | ||
) | -> void |
Submits a request to resolve a cross reference using a shared pointer.
This function submits a request to resolve a cross reference using the given key. Once the cross reference has been resolved, a handler will be called with a [const std::shared_ptr<Type> &](std::shared_ptr), as if by:
The reference will not be resolved immediately, but only after the entire configuration has been loaded. This is necessary in order to be able to resolve references to objects that have not been loaded yet.
To submit a request to resolve a Xentara element by calling a member function called setReferredElement(), for example, you can use the following code:
Type | The type of cross reference to resolve. This must be one of the following:
|
key | The primary key of the object to resolve |
handler | The handler that should be called once the reference has been resolved. The handler must remain valid during the entire loading of the Xentara model, not just the [load()](skill::Element::load()] function. |
auto xentara::config::Context::resolve | ( | ReferenceKey | key, |
Handler | handler | ||
) | -> void |
Submits a request to resolve a cross reference using a reference wrapper.
This function submits a request to resolve a cross reference using the given key. Once the cross reference has been resolved, a handler will be called with a [const std::reference_wrapper<Type> &](std::reference_wrapper), as if by:
The reference will not be resolved immediately, but only after the entire configuration has been loaded. This is necessary in order to be able to resolve references to objects that have not been loaded yet.
To submit a request to resolve a Xentara element by calling a member function called setReferredElement(), for example, you can use the following code:
Type | The type of cross reference to resolve. This must be one of the following:
|
key | The primary key of the object to resolve |
handler | The handler that should be called once the reference has been resolved. The handler must remain valid during the entire loading of the Xentara model, not just the [load()](skill::Element::load()] function. |
auto xentara::config::Context::resolve | ( | ReferenceKey | key, |
Handler | handler | ||
) | -> void |
Submits a request to resolve a cross reference using a reference-like object.
This function submits a request to resolve a cross reference using the given key. Once the cross reference has been resolved, a handler will be called with a const Type &, as if by:
The reference will not be resolved immediately, but only after the entire configuration has been loaded. This is necessary in order to be able to resolve references to objects that have not been loaded yet.
To submit a request to resolve a Xentara attribute by calling a member function called setReferredAttribute(), for example, you can use the following code:
Type | The type of cross reference to resolve. This must be one of the following:
|
key | The primary key of the object to resolve |
handler | The handler that should be called once the reference has been resolved. The handler must remain valid during the entire loading of the Xentara model, not just the [load()](skill::Element::load()] function. |
auto xentara::config::Context::resolve | ( | ReferenceKey | key, |
std::reference_wrapper< Pointer > | variable | ||
) | -> void |
Submits a request to resolve a cross reference using a raw pointer and assign it to a variable.
This function submits a request to resolve a cross reference using the given key. Once the cross reference has been resolved, it will be assigned to a variable using a Type *, as if by:
The reference will not be resolved immediately, but only after the entire configuration has been loaded. This is necessary in order to be able to resolve references to objects that have not been loaded yet.
To submit a request to resolve a Xentara element and store it in a member variable named *_referredElement*, for example, you can use the following code:
Type | The type of cross reference to resolve. This must be one of the following:
|
key | The primary key of the object to resolve |
variable | A reference to the variable the resolved object should be assigned to. To enable the compiler to select the correct overload, you should pass this parameter using std::ref. The reference must remain valid during the entire loading of the Xentara model, not just the [load()](skill::Element::load()] function. |
auto xentara::config::Context::resolve | ( | ReferenceKey | key, |
std::reference_wrapper< Reference > | variable | ||
) | -> void |
Submits a request to resolve a cross reference using a reference wrapper and assign it to a variable.
This function submits a request to resolve a cross reference using the given key. Once the cross reference has been resolved, it will be assigned to a variable using a [const std::reference_wrapper<Type> &](std::reference_wrapper), as if by:
The reference will not be resolved immediately, but only after the entire configuration has been loaded. This is necessary in order to be able to resolve references to objects that have not been loaded yet.
To submit a request to resolve a Xentara element and store it in a member variable named *_referredElement*, for example, you can use the following code:
Type | The type of cross reference to resolve. This must be one of the following:
|
key | The primary key of the object to resolve |
variable | A reference to the variable the resolved object should be assigned to. To enable the compiler to select the correct overload, you should pass this parameter using std::ref. The reference must remain valid during the entire loading of the Xentara model, not just the [load()](skill::Element::load()] function. |
auto xentara::config::Context::resolve | ( | ReferenceKey | key, |
std::reference_wrapper< Reference > | variable | ||
) | -> void |
Submits a request to resolve a cross reference using a reference-like object and assign it to a variable.
This function submits a request to resolve a cross reference using the given key. Once the cross reference has been resolved, it will be assigned to a variable using a const Type &, as if by:
The reference will not be resolved immediately, but only after the entire configuration has been loaded. This is necessary in order to be able to resolve references to objects that have not been loaded yet.
To submit a request to resolve a Xentara attribute and store it in a member variable named *_referredAttribute*, for example, you can use the following code:
Type | The type of cross reference to resolve. This must be one of the following:
|
key | The primary key of the object to resolve |
variable | A reference to the variable the resolved object should be assigned to. To enable the compiler to select the correct overload, you should pass this parameter using std::ref. The reference must remain valid during the entire loading of the Xentara model, not just the [load()](skill::Element::load()] function. |
auto xentara::config::Context::resolve | ( | ReferenceKey | key, |
std::reference_wrapper< SharedPointer > | variable | ||
) | -> void |
Submits a request to resolve a cross reference using a shared pointer and assign it to a variable.
This function submits a request to resolve a cross reference using the given key. Once the cross reference has been resolved, it will be assigned to a variable using a [const std::shared_ptr<Type> &](std::shared_ptr), as if by:
The reference will not be resolved immediately, but only after the entire configuration has been loaded. This is necessary in order to be able to resolve references to objects that have not been loaded yet.
To submit a request to resolve a Xentara element and store it in a member variable named *_referredElement*, for example, you can use the following code:
Type | The type of cross reference to resolve. This must be one of the following:
|
key | The primary key of the object to resolve |
variable | A reference to the variable the resolved object should be assigned to. To enable the compiler to select the correct overload, you should pass this parameter using std::ref. The reference must remain valid during the entire loading of the Xentara model, not just the [load()](skill::Element::load()] function. |