Hold key,value dictionaries for environment variables. More...

#include "environment-variable.h"

Classes
class	Dictionary
	Key, value dictionary for a single environment variable. More...

Public Types
using	KeyFoundType = std::pair< bool, std::string >
	Result of a key lookup. More...

Public Member Functions
Singleton
This class is a singleton, accessed by static member functions, so the Rule of Five functions are all deleted.
	EnvironmentVariable ()=delete

	EnvironmentVariable (const EnvironmentVariable &)=delete

EnvironmentVariable &	operator= (const EnvironmentVariable &)=delete

	EnvironmentVariable (EnvironmentVariable &&)=delete

EnvironmentVariable &	operator= (EnvironmentVariable &&)=delete

Static Public Member Functions
static KeyFoundType	Get (const std::string &envvar, const std::string &key="", const std::string &delim=";")
	Get the value corresponding to a key from an environment variable. More...

static std::shared_ptr< Dictionary >	GetDictionary (const std::string &envvar, const std::string &delim=";")
	Get the dictionary for a particular environment variable. More...

static bool	Set (const std::string &variable, const std::string &value)
	Set an environment variable. More...

static bool	Unset (const std::string &variable)
	Unset an environment variable. More...

Private Types
using	DictionaryList = std::unordered_map< std::string, std::shared_ptr< Dictionary > >
	How Dictionaries are stored. More...

Static Private Member Functions
static void	Clear ()
	Clear the instance, forcing all new lookups. More...

static DictionaryList &	Instance ()
	Access the DictionaryStore instance. More...

Friends
class	tests::EnvVarTestCase

Detailed Description

Hold key,value dictionaries for environment variables.

The environment variable can have multiple key,value pairs separated by a delimiter, which is ";" by default.

Individual pairs are connected by '='. As an extension a bare key will be assigned the empty string "".

For example, ENVVAR="key1=value1;key2;key3=value3".

Definition at line 59 of file environment-variable.h.

Member Typedef Documentation

◆ DictionaryList

using ns3::EnvironmentVariable::DictionaryList = std::unordered_map<std::string, std::shared_ptr<Dictionary> >

private

How Dictionaries are stored.

key: the environment variable name

Dictionary: the parsed Dictionary for the key

Definition at line 214 of file environment-variable.h.

◆ KeyFoundType

using ns3::EnvironmentVariable::KeyFoundType = std::pair<bool, std::string>

Result of a key lookup.

The first is true if the key was found.

The second contains the value associated with the key.

Definition at line 68 of file environment-variable.h.

Constructor & Destructor Documentation

◆ EnvironmentVariable() [1/3]

ns3::EnvironmentVariable::EnvironmentVariable ( )

delete

◆ EnvironmentVariable() [2/3]

ns3::EnvironmentVariable::EnvironmentVariable ( const EnvironmentVariable & )

delete

◆ EnvironmentVariable() [3/3]

ns3::EnvironmentVariable::EnvironmentVariable ( EnvironmentVariable && )

delete

Member Function Documentation

◆ Clear()

void ns3::EnvironmentVariable::Clear ( )

staticprivate

Clear the instance, forcing all new lookups.

Definition at line 143 of file environment-variable.cc.

References Instance().

Referenced by ns3::tests::EnvVarTestCase::SetVariable(), and ns3::tests::EnvVarTestCase::UnsetVariable().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Get()

EnvironmentVariable::KeyFoundType ns3::EnvironmentVariable::Get	(	const std::string &	envvar,
		const std::string &	key = `""`,
		const std::string &	delim = `";"`
	)

static

Get the value corresponding to a key from an environment variable.

If the key is empty just return the environment variable, (or {false, ""} if the variable doesn't exist).

If the key is not empty return the associated value (or {false, ""} if the key is not found). If the key is present but has no value return {true, ""}.

Key-value pairs are separated by delim. Individual keys and values are separated by an = sign. If the = is not present the value returned is the empty string.

Notice that two cases both return {false, ""}:

The environment variable doesn't exist, or
It exists but the (non-empty) key wasn't found.

Notice that two cases both return {true, ""}: the environment variable exists and

The key was empty and the environment variable was empty, or
The (not empty) key was found, but with no value.

In practice neither of these ambiguities is important:

If the return contains false the key doesn't exist.
If the return contains true but the string is empty either the (not empty) key exists with no value, or the key was empty and the environment variable itself is empty.

Parameters

[in]	envvar	The environment variable.
[in]	key	The key to extract from the environment variable.
[in]	delim	The delimiter between key,value pairs.

Returns: Whether the key was found, and its value, as explained above.

Definition at line 172 of file environment-variable.cc.

References GetDictionary().

Referenced by ns3::PrintList::PrintList(), ns3::tests::EnvVarTestCase::CheckGet(), ns3::ObjectBase::ConstructSelf(), ns3::tests::EnvVarTestCase::DoRun(), ns3::LogComponent::EnvVarCheck(), ns3::GlobalValue::InitializeFromEnv(), ns3::SystemPath::MakeTemporaryDirectoryName(), and ns3::CommandLine::PrintDoxygenUsage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetDictionary()

std::shared_ptr< EnvironmentVariable::Dictionary > ns3::EnvironmentVariable::GetDictionary	(	const std::string &	envvar,
		const std::string &	delim = `";"`
	)

static

Get the dictionary for a particular environment variable.

This should be used when one needs to process all key,value pairs, perhaps without knowing the set of possible keys.

Parameters

[in]	envvar	The environment variable.
[in]	delim	The delimiter between key,value pairs.

Returns: The Dictionary.

Definition at line 150 of file environment-variable.cc.

References Instance(), and NS_LOCAL_LOG.

Referenced by ns3::tests::EnvVarTestCase::Check(), ns3::CheckEnvironmentVariables(), and Get().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ Instance()

EnvironmentVariable::DictionaryList & ns3::EnvironmentVariable::Instance ( )

staticprivate

Access the DictionaryStore instance.

Returns: the DictionaryStore.

Definition at line 135 of file environment-variable.cc.

Referenced by Clear(), and GetDictionary().

Here is the caller graph for this function:

◆ operator=() [1/2]

EnvironmentVariable& ns3::EnvironmentVariable::operator= ( const EnvironmentVariable & )

delete

◆ operator=() [2/2]

EnvironmentVariable& ns3::EnvironmentVariable::operator= ( EnvironmentVariable && )

delete

◆ Set()

bool ns3::EnvironmentVariable::Set	(	const std::string &	variable,
		const std::string &	value
	)

static

Set an environment variable.

To set a variable to the empty string use Set(variable, ""). Note: empty environment variables are not portable (unsupported on Windows).

Parameters

[in]	variable	The environment variable to set. Note this may not contain the `=` character.
[in]	value	The value to set. Note this must not be an empty string on Windows.