ITokens#

Fully qualified name: carb::tokens::ITokens

Defined in carb/tokens/detail/ITokens2.h

class ITokens#

Interface for storing tokens and resolving strings containing them.

Tokens are string pairs {name, value} that can be referenced in a string as "some text ${token_name} some other text", where the token name starts with a sequence "${" and end with a first closing "}".

If a token with the name <token_name> has a defined value, then it will be substituted with its value. If the token does not have a defined value, an empty string will be used for the replacement. This interface will use the ISetting interface, if available, as storage and in such case tokens will be stored under the ‘/app/tokens’ node.

Note: The “$” symbol is considered to be special by the tokenizer and should be escaped by doubling it (“$” -> “$$”) in order to be processed as just a symbol “$” Ex: “some text with $ sign” -> “some text with $$ sign”

Single unescaped “$” signs are considered to be a bad practice to be used for token resolution but they are acceptable and will be resolved into single “$” signs and no warning will be given about it.

Ex: “$” -> “$”, “$$” -> “$”, “$$$” -> “$$”

It’s better to use the helper function “escapeString” from the “TokensUtils.h” to produce a string that doesn’t have any parts that could participate in tokenization. As a token name start with “${” and ends with the first encountered “}” it can contain “$” (same rules about escaping it apply) and “{” characters, however such cases will result in a warning being output to the log. Ex: for the string “${bar$${}” the token resolution process will consider the token name to be “bar${” (note that “$$” is reduced into a single “$”) and a warning will be outputted into the log.

Tokens are resolved recursively unless an error occurs. For instance, given:

setValue("a", "${b}");
setValue("b", "${c}");
setValue("c", "hello ${d}");
setValue("d", "world");

resolveString(tokens, "${a}"); // will return "hello world"

Environment variables are automatically available as tokens, if defined. These are specified with the text ${env:<var name>} where <var name> is the name of the environment variable. The env: prefix is a reserved name, so any call to ITokens::setValue() or ITokens::setInitialValue() with a name that starts with env: will be rejected. The environment variable is read when needed and not cached in any way. An undefined environment variable behaves as an undefined token.

Thread Safety: All functions in ITokens are thread-safe unless otherwise specified. By “thread-safe,” this means that individual calls to an ITokens API function will fully complete in a thread-safe manner; however this does not mean that multiple calls together will be thread-safe as another thread may act on the token database between the API calls. In order to ensure thread-safety across multiple calls, use std::unique_lock or std::lock_guard with the ITokens interface (which conforms to BasicLockable). The tokens database uses a global mutex to ensure thread safety.

Public Functions

virtual bool setValue( cpp::string_view name, cpp::string_view value, ) noexcept = 0#

Sets a new value for the specified token, if the token didn’t exist it will be created.

Parameters:

name – token name not enclosed in “${” and “}”
value – new value for the token

Returns:

true if the operation was successful, false if an error occurred during the operation

virtual bool setInitialValue( cpp::string_view name, cpp::string_view value, ) noexcept = 0#

Creates a token with the given name and value if it was non-existent.

Otherwise does nothing.

Parameters:

name – Name of a token
value – Value of a token

virtual bool deleteValue(cpp::string_view name) noexcept = 0#

A function to delete a token.

Parameters:: name – token name not enclosed in “${” and “}”
Returns:: true if the operation was successful or token with such name didn’t exist, false if an error occurred

inline omni::expected<omni::string, ResolveError> resolveString( cpp::string_view source, ResolveFlags resolveFlags = kResolveFlagNone, ) const noexcept#

Tries to resolve all tokens in the source string and returns the result.

Parameters:

source – the source string to resolve tokens in
resolveFlags – flags that modify token resolution process

Returns:

The resolved string if successful, or an unexpected containing the ResolveError error code

virtual omni::expected<void, ResolveError> resolveString( cpp::string_view source, omni::string &out, ResolveFlags resolveFlags = kResolveFlagNone, ) const noexcept = 0#

Tries to resolve all tokens in the source string and places the result into the output string.

Parameters:

source – the source string to resolve tokens in
out – the output string where the resolved result will be stored. Will reuse any pre-allocated memory reserved in the string. If an error is returned, this string is in a valid but undefined state.
resolveFlags – flags that modify token resolution process

Returns:

void on success, or an unexpected containing the ResolveError on failure

virtual bool exists(cpp::string_view tokenName) const noexcept = 0#

Check the existence of a token.

Parameters:: tokenName – the name of a token that will be checked for existence
Returns:: true if the token with the specified name exists, false is returned if there is no token with such name

virtual cpp::optional<omni::string> getValue( cpp::string_view name, ) const noexcept = 0#

Gets the value of a token.

Parameters:: name – token name not enclosed in “${” and “}”
Returns:: The value of the token if it exists, or cpp::nullopt if the token doesn’t exist

virtual void lock() const noexcept = 0#

Locks the tokens database.

Mutex-locks the tokens database for exclusive access. This is only necessary if you are doing multiple read/write operations and require thread-safe consistency across the multiple operations. unlock() must be called once the lock is no longer needed.

ITokens conforms to BasicLockable, so prefer using std::unique_lock or std::lock_guard instead of calling lock() directly.

auto tokens = carb::getCachedInterface<carb::tokens::ITokens>();
std::lock_guard<carb::tokens::ITokens> lock(*tokens);
// Multiple operations are now atomic
if (!tokens->exists("my_token"))
    tokens->setValue("my_token", "value");