xentara-plugin v2.0.3
The Xentara Plugin Framework
Loading...
Searching...
No Matches
Classes | Public Member Functions | List of all members
xentara::config::Context Class Referenceabstract

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.
 

Detailed Description

A context used when loading skill elements.

See also
skill::Element::load()
Examples
LoadingElementConfig.cpp, and PublishingConfigAttributes.cpp.

Constructor & Destructor Documentation

◆ ~Context()

xentara::config::Context::~Context ( )
pure virtualdefault

Virtual destructor.

Member Function Documentation

◆ createSyntheticChild() [1/2]

template<std::derived_from< skill::Element > Derived, typename... ConstructorArguments>
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.

Template Parameters
DerivedThe class of the child element
Parameters
elementClassThe meta-information object for the class of the child element
nameThe name of the child element.
constructorArgumentsThe arguments for the element’s constructor
Returns
The newly created child element.

◆ createSyntheticChild() [2/2]

template<std::derived_from< skill::Element > Derived, typename... ConstructorArguments>
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:

createSyntheticChild<Derived>(Derived::Class::instance(), name, constructorArguments...);
xentara::config::Context::createSyntheticChild
auto createSyntheticChild(std::reference_wrapper< const skill::Element::Class > elementClass, std::string name, ConstructorArguments &&...constructorArguments) -> std::shared_ptr< Derived >
Creates a synthetic child element.
Definition Context.hpp:697
Template Parameters
DerivedThe class of the child element. The meta-information object for the class must be available using Derived::Class::instance().
Parameters
nameThe name of the child element.
constructorArgumentsThe arguments for the element’s constructor
Returns
The newly created child element.

◆ findExternalConfig()

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:

  1. If you use the default of false for both options, then an exception is thrown.
  2. If you specify useFallback, then a fallback path is returned. For absolute paths, the fallback is just the path itself. For relative paths, the fallback is the path relative to the first suitable config directory.
  3. If you specify allowMissing, then an empty path is returned.
    Parameters
    pathThe relative or absolute path of the configuration.
    parameterDescriptionA 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.

    optionsThe search options. You can use these options to specify a subdirectory, to change the file type,
    Returns
    The resolved absolute path of the external configuration, or std::nullopt if the option allowMissing was set, and no configuration was found. If allowMissing is not set, then std::nullopt is never returned.
    Exceptions
    std::runtime_errorNo 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.

◆ resolve() [1/7]

template<CopyResolvable Type, std::invocable< const Type & > Handler>
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:

const std::shared_ptr<Type> object = resolveReferenceInSomeMysteriousWay(key);
handler(object);

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:

context.resolve<xentara::model::Element>(key, [this](const std::shared_ptr<xentara::model::Element> &element)
{
setReferredElement(element);
});
xentara::model::Element
A generic element within a Xentara model.
Definition Element.hpp:50
Template Parameters
TypeThe type of cross reference to resolve. This must be one of the following:
Parameters
keyThe primary key of the object to resolve
handlerThe 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.
See also
Resolving Cross References

◆ resolve() [2/7]

template<ReferenceResolvable Type, std::invocable< std::reference_wrapper< Type > > Handler>
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:

const std::reference_wrapper<Type> object = resolveReferenceInSomeMysteriousWay(key);
handler(object);

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:

context.resolve<xentara::model::Element>(key, [this](std::reference_wrapper<xentara::model::Element> element)
{
setReferredElement(element);
});
Template Parameters
TypeThe type of cross reference to resolve. This must be one of the following:
Parameters
keyThe primary key of the object to resolve
handlerThe 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.
See also
Resolving Cross References

◆ resolve() [3/7]

template<CopyResolvable Type, std::invocable< const Type & > Handler>
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:

const Type object = resolveReferenceInSomeMysteriousWay(key);
handler(object);

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:

context.resolve<xentara::model::ElementAttribute>(key, [this](const xentara::model::ElementAttribute &attribute)
{
setReferredAttribute(attribute);
});
xentara::model::ElementAttribute
A reference to an attribute of a specific Xentara element.
Definition ElementAttribute.hpp:33
Template Parameters
TypeThe type of cross reference to resolve. This must be one of the following:
Parameters
keyThe primary key of the object to resolve
handlerThe 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.
See also
Resolving Cross References

◆ resolve() [4/7]

template<ReferenceResolvable Type, typename Pointer >
requires std::is_assignable_v<Pointer &, Type *>
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:

Type *object = resolveReferenceInSomeMysteriousWay(key);
variable.get() = object;

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:

context.resolve<xentara::model::Element>(key, std::ref(_referredElement));
std::ref
T ref(T... args)
Template Parameters
TypeThe type of cross reference to resolve. This must be one of the following:
Parameters
keyThe primary key of the object to resolve
variableA 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.
See also
Resolving Cross References

◆ resolve() [5/7]

template<CopyResolvable Type, typename Reference >
requires std::is_assignable_v<Reference &, const std::reference_wrapper<Type> &>
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:

const std::reference_wrapper<Type> object = resolveReferenceInSomeMysteriousWay(key);
variable.get() = object;

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:

context.resolve<xentara::model::Element>(key, std::ref(_referredElement));
Template Parameters
TypeThe type of cross reference to resolve. This must be one of the following:
Parameters
keyThe primary key of the object to resolve
variableA 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.
See also
Resolving Cross References

◆ resolve() [6/7]

template<CopyResolvable Type, typename Reference >
requires std::is_assignable_v<Reference &, const Type &>
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:

const Type object = resolveReferenceInSomeMysteriousWay(key);
variable.get() = object;

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:

context.resolve<xentara::model::ElementAttribute>(key, std::ref(_referredAttribute));
Template Parameters
TypeThe type of cross reference to resolve. This must be one of the following:
Parameters
keyThe primary key of the object to resolve
variableA 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.
See also
Resolving Cross References

◆ resolve() [7/7]

template<ReferenceResolvable Type, typename SharedPointer >
requires std::is_assignable_v<SharedPointer &, const std::shared_ptr<Type> &>
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:

const std::shared_ptr<Type> object = resolveReferenceInSomeMysteriousWay(key);
variable.get() = object;

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:

context.resolve<xentara::model::Element>(key, std::ref(_referredElement));
Template Parameters
TypeThe type of cross reference to resolve. This must be one of the following:
Parameters
keyThe primary key of the object to resolve
variableA 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.
See also
Resolving Cross References