A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
environment-variable.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2022 Lawrence Livermore National Laboratory
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Peter D. Barnes, Jr. <pdbarnes@llnl.gov>
7 */
8
9#ifndef ENVIRONMENT_VARIABLE_H
10#define ENVIRONMENT_VARIABLE_H
11
12/**
13 * \file
14 * \ingroup core-environ
15 * Class Environment declaration.
16 */
17
18#include <memory> // shared_ptr
19#include <string>
20#include <unordered_map>
21#include <utility> // pair
22
23namespace ns3
24{
25
26/// \todo Reconsider the name?
27/// Rename to just EnvironmentVariableDictionary?
28/// System::EnvironmentVariable?
29
30// Forward declaration
31namespace tests
32{
33class EnvVarTestCase;
34}
35
36/**
37 * \ingroup core-environ
38 * Hold key,value dictionaries for environment variables.
39 *
40 * The environment variable can have multiple key,value pairs
41 * separated by a delimiter, which is ";" by default.
42 *
43 * Individual pairs are connected by '='. As an extension a bare key
44 * will be assigned the empty string \c "".
45 *
46 * For example, `ENVVAR="key1=value1;key2;key3=value3"`.
47 */
49{
50 public:
51 /**
52 * Result of a key lookup.
53 * The \p first is \c true if the key was found.
54 *
55 * The \p second contains the value associated with the key.
56 */
57 using KeyFoundType = std::pair<bool, std::string>;
58
59 /**
60 * Get the value corresponding to a key from an environment variable.
61 *
62 * If the \p key is empty just return the environment variable,
63 * (or `{false, ""}` if the variable doesn't exist).
64 *
65 * If the \p key is not empty return the associated value
66 * (or `{false, ""}` if the key is not found).
67 * If the key is present but has no value return `{true, ""}`.
68 *
69 * Key-value pairs are separated by \p delim. Individual keys and
70 * values are separated by an `=` sign. If the `=` is not present
71 * the value returned is the empty string.
72 *
73 * Notice that two cases both return `{false, ""}`:
74 * * The environment variable doesn't exist, or
75 * * It exists but the (non-empty) \p key wasn't found.
76 *
77 * Notice that two cases both return `{true, ""}`: the environment
78 * variable exists and
79 * * The \p key was empty and the environment variable was empty, or
80 * * The (not empty) key was found, but with no value.
81 *
82 * In practice neither of these ambiguities is important:
83 * * If the return contains \c false the key doesn't exist.
84 * * If the return contains \c true but the string is empty either the
85 * (not empty) key exists with no value, or the key was empty and the
86 * environment variable itself is empty.
87 *
88 * \param [in] envvar The environment variable.
89 * \param [in] key The key to extract from the environment variable.
90 * \param [in] delim The delimiter between key,value pairs.
91 * \returns Whether the key was found, and its value, as explained above.
92 */
93 static KeyFoundType Get(const std::string& envvar,
94 const std::string& key = "",
95 const std::string& delim = ";");
96
97 // Forward
98 class Dictionary;
99
100 /**
101 * Get the dictionary for a particular environment variable.
102 *
103 * This should be used when one needs to process all key,value
104 * pairs, perhaps without knowing the set of possible keys.
105 *
106 * \param [in] envvar The environment variable.
107 * \param [in] delim The delimiter between key,value pairs.
108 * \returns The Dictionary.
109 */
110 static std::shared_ptr<Dictionary> GetDictionary(const std::string& envvar,
111 const std::string& delim = ";");
112
113 /** Key, value dictionary for a single environment variable. */
115 {
116 public:
117 /**
118 * Constructor.
119 *
120 * Parse an environment variable containing keys and optional values.
121 *
122 * Keys in the environment variable are separated by the
123 * \p delim character. Keys may be assigned values by following
124 * the key with the `=` character; any remaining text up to the next
125 * delimiter will be taken as the value. If no `=`
126 * is given the enpty string will be stored as the value.
127 *
128 * \param [in] envvar The environment variable.
129 * \param [in] delim The delimiter between key,value pairs.
130 */
131 Dictionary(const std::string& envvar, const std::string& delim = ";");
132
133 /**
134 * Get the value corresponding to a key from this dictionary.
135 * If the \p key is empty return the full environment variable value.
136 * \param [in] key The key to extract from the environment variable.
137 * \returns \c true if the key was found, and the associated value.
138 */
139 KeyFoundType Get(const std::string& key = "") const;
140
141 /** Key, value store type. */
142 using KeyValueStore = std::unordered_map<std::string, std::string>;
143
144 /** Get the underlying store, for iterating.
145 * \returns The key, value store.
146 */
147 KeyValueStore GetStore() const;
148
149 private:
150 /** Whether the environment variable exists in the environment. */
152 /** The raw environment variable. */
153 std::string m_variable;
154 /** The key, value store. */
156
157 }; // class Dictionary
158
159 /**
160 * Set an environment variable.
161 *
162 * To set a variable to the empty string use `Set(variable, "")`.
163 * Note: empty environment variables are not portable (unsupported on Windows).
164 *
165 * \param [in] variable The environment variable to set. Note this may not contain the `=`
166 * character. \param [in] value The value to set. Note this must not be an empty string on
167 * Windows. \returns \c true if the variable was set successfully
168 */
169 static bool Set(const std::string& variable, const std::string& value);
170
171 /**
172 * Unset an environment variable.
173 * This removes the variable from the environment.
174 * To set a variable to the empty string use `Set(variable, "")`.
175 *
176 * \param [in] variable The environment variable to unset. Note this may not contain the `=`
177 * character. \returns \c true if the variable was unset successfully.
178 */
179 static bool Unset(const std::string& variable);
180
181 /**
182 * \name Singleton
183 *
184 * This class is a singleton, accessed by static member functions,
185 * so the Rule of Five functions are all deleted.
186 */
187 /** @{ */
193 /** @} */
194
195 private:
196 /**
197 * How Dictionaries are stored.
198 *
199 * \p key: the environment variable name
200 *
201 * \p Dictionary: the parsed Dictionary for the \p key
202 */
203 using DictionaryList = std::unordered_map<std::string, std::shared_ptr<Dictionary>>;
204
205 /**
206 * Access the DictionaryStore instance.
207 * \returns the DictionaryStore.
208 */
209 static DictionaryList& Instance();
210
211 // Test needs to clear the instance
213
214 /** Clear the instance, forcing all new lookups. */
215 static void Clear();
216
217}; // class EnvironmentVariable
218
219} // namespace ns3
220
221#endif /* ENVIRONMENT_VARIABLE_H */
Key, value dictionary for a single environment variable.
Dictionary(const std::string &envvar, const std::string &delim=";")
Constructor.
KeyFoundType Get(const std::string &key="") const
Get the value corresponding to a key from this dictionary.
std::unordered_map< std::string, std::string > KeyValueStore
Key, value store type.
std::string m_variable
The raw environment variable.
bool m_exists
Whether the environment variable exists in the environment.
KeyValueStore m_dict
The key, value store.
KeyValueStore GetStore() const
Get the underlying store, for iterating.
Hold key,value dictionaries for environment variables.
EnvironmentVariable & operator=(const EnvironmentVariable &)=delete
static DictionaryList & Instance()
Access the DictionaryStore instance.
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.
EnvironmentVariable & operator=(EnvironmentVariable &&)=delete
static bool Unset(const std::string &variable)
Unset an environment variable.
std::pair< bool, std::string > KeyFoundType
Result of a key lookup.
static void Clear()
Clear the instance, forcing all new lookups.
std::unordered_map< std::string, std::shared_ptr< Dictionary > > DictionaryList
How Dictionaries are stored.
static bool Set(const std::string &variable, const std::string &value)
Set an environment variable.
EnvironmentVariable(EnvironmentVariable &&)=delete
static std::shared_ptr< Dictionary > GetDictionary(const std::string &envvar, const std::string &delim=";")
Get the dictionary for a particular environment variable.
EnvironmentVariable(const EnvironmentVariable &)=delete
Every class exported by the ns3 library is enclosed in the ns3 namespace.