A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ns3::EnvironmentVariable Class Reference

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.
 

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
 
EnvironmentVariableoperator= (const EnvironmentVariable &)=delete
 
 EnvironmentVariable (EnvironmentVariable &&)=delete
 
EnvironmentVariableoperator= (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.
 
static std::shared_ptr< DictionaryGetDictionary (const std::string &envvar, const std::string &delim=";")
 Get the dictionary for a particular environment variable.
 
static bool Set (const std::string &variable, const std::string &value)
 Set an environment variable.
 
static bool Unset (const std::string &variable)
 Unset an environment variable.
 

Private Types

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

Static Private Member Functions

static void Clear ()
 Clear the instance, forcing all new lookups.
 
static DictionaryListInstance ()
 Access the DictionaryStore instance.
 

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]envvarThe environment variable.
[in]keyThe key to extract from the environment variable.
[in]delimThe 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]envvarThe environment variable.
[in]delimThe 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]variableThe environment variable to set. Note this may not contain the = character.
[in]valueThe value to set. Note this must not be an empty string on Windows.
Returns
true if the variable was set successfully

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

Referenced by ns3::tests::EnvVarTestCase::SetVariable().

+ Here is the caller graph for this function:

◆ Unset()

bool ns3::EnvironmentVariable::Unset ( const std::string &  variable)
static

Unset an environment variable.

This removes the variable from the environment. To set a variable to the empty string use Set(variable, "").

Parameters
[in]variableThe environment variable to unset. Note this may not contain the = character.
Returns
true if the variable was unset successfully.

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

Referenced by ns3::tests::EnvVarTestCase::UnsetVariable().

+ Here is the caller graph for this function:

Friends And Related Function Documentation

◆ tests::EnvVarTestCase

friend class tests::EnvVarTestCase
friend

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


The documentation for this class was generated from the following files: