GCC Code Coverage Report


Directory: ./
Coverage: low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%
Coverage Exec / Excl / Total
Lines: 57.1% 8 / 1 / 15
Functions: 57.1% 8 / 1 / 15
Branches: 36.4% 16 / 1 / 45

src/measure/OSArgument.hpp
Line Branch Exec Source
1 /***********************************************************************************************************************
2 * OpenStudio(R), Copyright (c) Alliance for Energy Innovation, LLC.
3 * See also https://openstudio.net/license
4 ***********************************************************************************************************************/
5
6 #ifndef MEASURE_OSARGUMENT_HPP
7 #define MEASURE_OSARGUMENT_HPP
8
9 #include "MeasureAPI.hpp"
10
11 #include "../utilities/idf/Workspace.hpp"
12 #include "../utilities/idd/IddEnums.hpp"
13 #include "../utilities/core/Path.hpp"
14 #include "../utilities/core/Enum.hpp"
15 #include "../utilities/core/Logger.hpp"
16
17 #include <variant>
18
19 namespace Json {
20 class Value;
21 }
22
23 namespace openstudio {
24 namespace measure {
25
26 // clang-format off
27
28 /** \class OSArgumentType
29 * \brief Listing of OSArgument data types. Quantity type is deprecated (will map to Double instead).
30 * \details See the OPENSTUDIO_ENUM documentation in utilities/core/Enum.hpp. The actual
31 * macro call is:
32 * \code
33 OPENSTUDIO_ENUM( OSArgumentType,
34 ((Boolean)(Bool)(0))
35 ((Double)(Double)(1))
36 ((Quantity)(Quantity)(2))
37 ((Integer)(Int)(3))
38 ((String)(String)(4))
39 ((Choice)(Choice)(5))
40 ((Path)(Path)(6))
41 ((Separator)(Separator)(7))
42 );
43 * \endcode */
44
8/22
openstudio::measure::OSArgumentType::buildStringVec[abi:cxx11](bool):
✗ Branch 0 not taken.
✓ Branch 1 taken 248 times.
✗ Branch 3 not taken.
✗ Branch 6 not taken.
✗ Branch 7 not taken.
✗ Branch 9 not taken.
✗ Branch 12 not taken.
✓ Branch 17 taken 248 times.
✓ Branch 20 taken 248 times.
✓ Branch 23 taken 217 times.
✓ Branch 24 taken 62 times.
✓ Branch 25 taken 31 times.
✓ Branch 26 taken 31 times.
✗ Branch 27 not taken.
✓ Branch 28 taken 31 times.
openstudio::measure::OSArgumentType::enumName[abi:cxx11]():
✗ Branch 1 not taken.
openstudio::measure::operator<<(std::ostream&, openstudio::measure::OSArgumentType const&):
✗ Branch 1 not taken.
✗ Branch 4 not taken.
✗ Branch 7 not taken.
✗ Branch 10 not taken.
✗ Branch 13 not taken.
✗ Branch 16 not taken.
1132 OPENSTUDIO_ENUM(OSArgumentType,
45 ((Boolean)(Bool)(0))
46 ((Double)(Double)(1))
47 ((Quantity)(Quantity)(2))
48 ((Integer)(Int)(3))
49 ((String)(String)(4))
50 ((Choice)(Choice)(5))
51 ((Path)(Path)(6))
52 ((Separator)(Separator)(7))
53 );
54
55 // ETH@20121211 - Perhaps add MeanStdDev or StatisticalMoments. Could even tack on an
56 // UncertaintyDescriptionType string, or move the whole UncertaintyDescription class down
57 // into measure.
58
59 /** \class OSDomainType
60 * \brief Methods for restricting the domain of an OSArgument.
61 * \details Numerical OSArguments (Double, Integer) can be given either an Interval
62 * (range) or an Enumeration. The other OSArgument types can only be enumerated.
63 *
64 * See the OPENSTUDIO_ENUM documentation in utilities/core/Enum.hpp. The actual macro call is:
65 * \code
66 OPENSTUDIO_ENUM( OSDomainType,
67 ((Interval))
68 ((Enumeration)(Enum))
69 );
70 * \endcode */
71
8/22
openstudio::measure::OSDomainType::buildStringVec[abi:cxx11](bool):
✗ Branch 0 not taken.
✓ Branch 1 taken 62 times.
✗ Branch 3 not taken.
✗ Branch 6 not taken.
✗ Branch 7 not taken.
✗ Branch 9 not taken.
✗ Branch 12 not taken.
✓ Branch 17 taken 62 times.
✓ Branch 20 taken 62 times.
✓ Branch 23 taken 31 times.
✓ Branch 24 taken 62 times.
✓ Branch 25 taken 31 times.
✓ Branch 26 taken 31 times.
✗ Branch 27 not taken.
✓ Branch 28 taken 31 times.
openstudio::measure::OSDomainType::enumName[abi:cxx11]():
✗ Branch 1 not taken.
openstudio::measure::operator<<(std::ostream&, openstudio::measure::OSDomainType const&):
✗ Branch 1 not taken.
✗ Branch 4 not taken.
✗ Branch 7 not taken.
✗ Branch 10 not taken.
✗ Branch 13 not taken.
✗ Branch 16 not taken.
956 OPENSTUDIO_ENUM(OSDomainType,
72 ((Interval))
73 ((Enumeration)(Enum))
74 );
75
76 // clang-format on
77
78 /** Preserves old name for OSArgumentType. \deprecated */
79 // TODO: JM 2018-11-28: Time to remove no?
80 using UserScriptArgumentType = OSArgumentType;
81
82 /** OSArgument is an argument to an OSMeasure. **/
83 class MEASURE_API OSArgument
84 {
85 public:
86 /** @name Constructors and Destructors */
87 //@{
88
89 // ETH@20121211 - Consider adding a constructor or otherwise tweaking the code to fix
90 // the issue of having to explicitly call clone (at least in Ruby) in order to setValue.
91 // It would be incorrect to always clone on copy since these objects go back and forth
92 // to ProjectDatabase.
93
94 OSArgument();
95 OSArgument(const std::string& name, const OSArgumentType& type, bool required, bool modelDependent);
96
97 /** Creates a copy with new UUIDs. */
98 OSArgument clone() const;
99
100 //@}
101
102 /** @name Factory methods */
103 //@{
104
105 /** Creates an OSArgument for bool values. Defaults domainType() to OSDomainType::Enumeration. */
106 static OSArgument makeBoolArgument(const std::string& name, bool required = true, bool modelDependent = false);
107
108 /** Creates an OSArgument for double values. Defaults domaintType() to OSDomainType::Interval. */
109 static OSArgument makeDoubleArgument(const std::string& name, bool required = true, bool modelDependent = false);
110
111 /** Creates an OSArgument for int values. Defaults domaintType() to OSDomainType::Interval. */
112 static OSArgument makeIntegerArgument(const std::string& name, bool required = true, bool modelDependent = false);
113
114 /** Creates an OSArgument for string values. Defaults domainType() to
115 * OSDomainType::Enumeration. */
116 static OSArgument makeStringArgument(const std::string& name, bool required = true, bool modelDependent = false);
117
118 /** Creates an OSArgument for choice values. Defaults domainType() to
119 * OSDomainType::Enumeration. */
120 static OSArgument makeChoiceArgument(const std::string& name, const std::vector<std::string>& choices, bool required = true,
121 bool modelDependent = false);
122
123 /** Creates an OSArgument for choice values. Defaults domainType() to
124 * OSDomainType::Enumeration. */
125 static OSArgument makeChoiceArgument(const std::string& name, const std::vector<std::string>& choices,
126 const std::vector<std::string>& displayNames, bool required = true, bool modelDependent = false);
127
128 static OSArgument makeChoiceArgument(const std::string& name, const std::map<std::string, std::string>& choices_to_display_values_map,
129 bool required = true, bool modelDependent = false);
130
131 /** Creates an OSArgument for path values. Defaults domainType() to OSDomainType::Enumeration. */
132 static OSArgument makePathArgument(const std::string& name, bool isRead, const std::string& extension, bool required = true,
133 bool modelDependent = false);
134
135 /** Creates a separator OSArgument, cannot be used to store a value, cannot be required. */
136 static OSArgument makeSeparatorArgument(const std::string& name, bool modelDependent = false);
137
138 //@}
139
140 /** @name Getters */
141 //@{
142
143 //openstudio::UUID uuid() const;
144
145 //openstudio::UUID versionUUID() const;
146
147 /** Returns the name of this argument. */
148 std::string name() const;
149
150 /** Returns the display name of this argument. */
151 std::string displayName() const;
152
153 /** Returns the description of this argument. */
154 boost::optional<std::string> description() const;
155
156 /** Returns this argument's type. */
157 OSArgumentType type() const;
158
159 /** Returns the units of this argument. */
160 boost::optional<std::string> units() const;
161
162 /** Returns true if this argument is required, that is, if the argument must have a value or
163 * default value for the measure to run properly. */
164 bool required() const;
165
166 /** Returns true if this argument's properties can changed based on the specific model used in the
167 * measure. A choice argument which lists objects in the model would be model dependent. */
168 bool modelDependent() const;
169
170 /** Returns true if this argument's value has been set. */
171 bool hasValue() const;
172
173 /** Returns this argument's value as a bool. Throws if not hasValue() or if type() !=
174 * OSArgumentType::Boolean. */
175 bool valueAsBool() const;
176
177 /** Returns this argument's value as a double. Throws if not hasValue() or if type() !=
178 * OSArgumentType::Double. */
179 double valueAsDouble() const;
180
181 /** Returns this argument's value as an int. Throws if not hasValue() or if type() !=
182 * OSArgumentType::Integer. */
183 int valueAsInteger() const;
184
185 /** Returns this argument's value as a std::string. If type() != OSArgumentType::String, prints
186 * this argument's value to produce the result. Throws if not hasValue(). */
187 std::string valueAsString() const;
188
189 /** Returns this argument's value as an openstudio::path. Throws if not hasValue() or if
190 * type() != OSArgumentType::Path. */
191 openstudio::path valueAsPath() const;
192
193 /** Returns this argument's value as a Json::Value. Will convert nicely to ruby/python native types.
194 * Returns nullValue if it doesn't have one */
195 Json::Value valueAsJSON() const;
196
197 /** Returns true if this argument's default value has been set. */
198 bool hasDefaultValue() const;
199
200 /** Returns this argument's default value as a bool. Throws if not hasDefaultValue() or if
201 * type() != OSArgumentType::Boolean. */
202 bool defaultValueAsBool() const;
203
204 /** Returns this argument's default value as a double. Throws if not hasDefaultValue() or if
205 * type() != OSArgumentType::Double. */
206 double defaultValueAsDouble() const;
207
208 /** Returns this argument's default value as an int. Throws if not hasDefaultValue() or if
209 * type() != OSArgumentType::Integer. */
210 int defaultValueAsInteger() const;
211
212 /** Returns this argument's default value as a std::string. If type() != OSArgumentType::String,
213 * prints this argument's default value to produce the result. Throws if not hasDefaultValue(). */
214 std::string defaultValueAsString() const;
215
216 /** Returns this argument's default value as an openstudio::path. Throws if not
217 * hasDefaultValue() or if type() != OSArgumentType::Path. */
218 openstudio::path defaultValueAsPath() const;
219
220 /** Returns this argument's default value as a Json::Value. Will convert nicely to ruby/python native types.
221 * Returns nullValue if it doesn't have one */
222 Json::Value defaultValueAsJSON() const;
223
224 /** Returns true if this argument has a non-null domain. */
225 bool hasDomain() const;
226
227 /** Returns the OSDomainType, which is defaulted to a particular value for each type().
228 * If domainType == OSDomainType::Interval then the domain getters will return two
229 * elements. The first will be the minimum value, and the second will be the maximum. If
230 * domainType == OSDomainType::Enumeration, then all of the possible/acceptable values
231 * will be explicitly listed. */
232 OSDomainType domainType() const;
233
234 /** Returns the domain as a vector of bools. Will throw if not hasDomain() or type() !=
235 * OSArgumentType::Boolean. */
236 std::vector<bool> domainAsBool() const;
237
238 /** Returns the domain as a vector of doubles. Will throw if not hasDomain() or type() !=
239 * OSArgumentType::Double. */
240 std::vector<double> domainAsDouble() const;
241
242 /** Returns the domain as a vector of ints. Will throw if not hasDomain() or type() !=
243 * OSArgumentType::Integer. */
244 std::vector<int> domainAsInteger() const;
245
246 /** Returns the domain as a vector of strings. Will throw if not hasDomain(). */
247 std::vector<std::string> domainAsString() const;
248
249 /** Returns the domain as a vector of paths. Will throw if not hasDomain() or type() !=
250 * OSArgumentType::Path. */
251 std::vector<openstudio::path> domainAsPath() const;
252
253 /** Returns this argument's domain as a Json::Value. Will convert nicely to ruby/python native types.
254 * Returns nullValue if it doesn't have one, Json::arrayValue otherwise */
255 Json::Value domainAsJSON() const;
256
257 //@}
258 /** @name Choice Argument Getters */
259 //@{
260
261 /** If this is an argument of type() OSArgument::Choice, returns the allowable values.
262 * Otherwise the returned vector will be .empty(). */
263 std::vector<std::string> choiceValues() const;
264
265 /** Returns a vector the same length as choiceValues() that can be used to display
266 * choices to a user. Each element is the explicit choice display name, if that
267 * exists, or the actual choice value, otherwise. */
268 std::vector<std::string> choiceValueDisplayNames() const;
269
270 /** Returns the display name or actual value for arguments of type() OSArgument::Choice,
271 * if a value is set. Otherwise throws. */
272 std::string valueDisplayName() const;
273
274 /** Returns the display name or actual default value for arguments of type()
275 * OSArgument::Choice, if a default value is set. Otherwise throws. */
276 std::string defaultValueDisplayName() const;
277
278 //@}
279 /** @name Path Argument Getters */
280 //@{
281
282 /** Returns true if type() == OSArgumentType::Path and if the path is to a file that is to be
283 * read. */
284 bool isRead() const;
285
286 /** If type() == OSArgumentType::Path, returns the expected file extension of the path.
287 * Otherwise, the return value is .empty(). */
288 std::string extension() const;
289
290 //@}
291 /** @name Setters */
292 //@{
293
294 /** Set the display name of this argument. */
295 void setDisplayName(const std::string& displayName);
296
297 /** Set the description of this argument. */
298 void setDescription(const std::string& description);
299
300 /** Set the units for this argument. */
301 void setUnits(const std::string& units);
302
303 /** Set the value of this argument by passing in data of a particular type. The method will do
304 * nothing and return false if the data is of an incorrect type. These methods do not check
305 * value against the domain (if set), as the domain is just a guideline for users. The string
306 * setter will try to convert the string to the correct type for this argument. Integers can
307 * be used to set the values of arguments of type double. A double that is really an int (eg: 1.0)
308 * can also be accepted to set integer arguments. */
309 bool setValue(bool value);
310 /// \overload
311 bool setValue(double value);
312 /// \overload
313 bool setValue(int value);
314 /// \overload forwards to std::string& one
315 bool setValue(const char* value);
316 /// \overload
317 bool setValue(const std::string& value);
318 /// \overload
319 bool setValue(const openstudio::path& value);
320
321 void clearValue();
322
323 /** Set the default value of this argument by passing in data of a particular type. The method
324 * will do nothing and return false if the data is of an incorrect type. These methods do not
325 * check defaultValue against the domain (if set), as the domain is just a guideline for users.
326 * The string setter will try to convert the string to the correct type for this argument.
327 * Integers can be used to set the default values of arguments of type double.
328 * A double that is really an int (eg: 1.0) can also be accepted to set integer arguments. */
329 bool setDefaultValue(bool defaultValue);
330 /// \overload
331 bool setDefaultValue(double defaultValue);
332 /// \overload
333 bool setDefaultValue(int defaultValue);
334 /// \overload forwards to std::string& one
335 bool setDefaultValue(const char* defaultValue);
336 /// \overload
337 bool setDefaultValue(const std::string& defaultValue);
338 /// \overload
339 bool setDefaultValue(const openstudio::path& defaultValue);
340
341 /** Sets the domainType and returns true if domainType is consistent with type, otherwise returns
342 * false. If the domainType changes, the domain will be cleared before returning. */
343 bool setDomainType(const OSDomainType& domainType);
344
345 /** Sets the domain of this argument by passing in data of a particular type. The method will do
346 * nothing and return false if the data is of an incorrect type or size. A vector of size 2 is
347 * expected for OSDomainType::Interval. */
348 bool setDomain(const std::vector<bool>& domain);
349 /// \overload
350 bool setDomain(const std::vector<double>& domain);
351 /// \overload
352 bool setDomain(const std::vector<int>& domain);
353 /// \overload
354 bool setDomain(const std::vector<std::string>& domain);
355 /// \overload
356 bool setDomain(const std::vector<openstudio::path>& domain);
357
358 void clearDomain();
359
360 /** Sets the domain type to OSDomainType::Interval and sets minimum value.
361 * Preserves existing maximum value or sets it to infinity if it does not exist.
362 * Does not check for compatibility with current value, default value, or that min < max. */
363 bool setMinValue(double minValue);
364 /// \overload
365 bool setMinValue(int minValue);
366
367 /** Sets the domain type to OSDomainType::Interval and sets maximum value.
368 * Preserves existing minimum value or sets it to infinity if it does not exist. */
369 bool setMaxValue(double maxValue);
370 bool setMaxValue(int maxValue);
371
372 void setRequired(bool required);
373
374 //@}
375 /** @name Serialization */
376 //@{
377
378 /** Prints argument data for debugging purposes. */
379 std::string print() const;
380
381 /** Returns this argument's value printed to string. If printDefault, returns the default value if
382 * in the case of !hasValue() && hasDefaultValue(). If there is no value to print, the returned
383 * string will be .empty(). */
384 std::string printValue(bool printDefault = true) const;
385
386 /** Returns this argument's default value printed to string, if possible. If there is no default
387 * value, the string will be .empty(). */
388 std::string printDefaultValue() const;
389
390 Json::Value toJSON() const;
391 std::string toJSONString() const;
392
393 //@}
394 private:
395 − REGISTER_LOGGER("openstudio.measure.OSArgument");
396
397 // ETH@20121211 - Why are these friend declarations here?!
398 // JMT@20130124 - Because all of the constructors are private and the SWIG wrapper for pair needs
399 // some constructors
400
401 friend class std::map<std::string, OSArgument>;
402 friend struct std::pair<std::string, OSArgument>;
403
404 #ifdef _LIBCPP_VERSION
405 friend struct std::allocator_traits<std::allocator<std::__tree_node<std::__value_type<std::string, OSArgument>, void*>>>;
406 #endif
407
408 #if _MSC_VER >= 1800
409 friend struct std::pair<const std::string, OSArgument>;
410 #elif _MSC_VER >= 1600
411 friend struct std::pair<const std::string, OSArgument>;
412 friend struct std::_Pair_base<std::string, OSArgument>;
413 #endif
414
415 // Note JM 2018-11-28:
416 // typedef for the std::variant we will use for value, default value, and domain
417 // we add std::monostate to allow the variant to be empty basically
418 using OSArgumentVariant = std::variant<std::monostate, bool, double, int, std::string, openstudio::path>;
419
420 bool setStringInternal(OSArgumentVariant& argVar, const std::string& value);
421
422 static std::string printOSArgumentVariant(const OSArgumentVariant& argVar);
423
424 static Json::Value argumentVariantToJSONValue(const OSArgumentVariant& argVar);
425
426 // This also OS App related
427 void onChange();
428
429 openstudio::UUID m_uuid;
430 openstudio::UUID m_versionUUID;
431 std::string m_name;
432 std::string m_displayName;
433 boost::optional<std::string> m_description;
434 OSArgumentType m_type;
435 boost::optional<std::string> m_units;
436 bool m_required = false;
437 bool m_modelDependent = false;
438 OSArgumentVariant m_value;
439 OSArgumentVariant m_defaultValue;
440 OSDomainType m_domainType;
441 std::vector<OSArgumentVariant> m_domain;
442 std::vector<std::string> m_choices;
443 std::vector<std::string> m_choiceDisplayNames;
444 bool m_isRead = false;
445 std::string m_extension;
446 };
447
448 /** \relates OSArgument */
449 using OptionalOSArgument = boost::optional<OSArgument>;
450
451 /** \relates OSArgument */
452 using OSArgumentVector = std::vector<OSArgument>;
453
454 /** \relates OSArgument */
455 using OSArgumentMap = std::map<std::string, OSArgument>;
456
457 /** \relates OSArgument */
458 using UserScriptInfo = std::pair<openstudio::path, std::vector<OSArgument>>;
459
460 /** Prints argument data to ostream for debugging purposes. \relates OSArgument */
461 MEASURE_API std::ostream& operator<<(std::ostream& os, const OSArgument& arg);
462
463 /** Creates a choice argument with object handles as its values and object names as
464 * its display names by querying workspace for all of its objects of type iddObjectType.
465 * The resulting argument does not attempt to preserve workspace, so the handles and
466 * names will only be valid if the workspace to which the argument is applied is the same
467 * or closely related to workspace. \relates OSArgument */
468 MEASURE_API OSArgument makeChoiceArgumentOfWorkspaceObjects(const std::string& name, const IddObjectType& iddObjectType, const Workspace& workspace,
469 bool required = true);
470
471 /** Creates a choice argument with object handles as its values and object names as
472 * its display names by querying workspace for all of its objects with reference
473 * referenceName. The resulting argument does not attempt to preserve workspace, so the
474 * handles and names will only be valid if the workspace to which the argument is applied
475 * is the same or closely related to workspace. \relates OSArgument */
476 MEASURE_API OSArgument makeChoiceArgumentOfWorkspaceObjects(const std::string& name, const std::string& referenceName, const Workspace& workspace,
477 bool required = true);
478
479 /** Converts a vector of OSArgument to a map of OSArgument using name as the key. \relates OSArgument */
480 MEASURE_API std::map<std::string, OSArgument> convertOSArgumentVectorToMap(const std::vector<OSArgument>& arguments);
481
482 } // namespace measure
483 } // namespace openstudio
484
485 #endif // MEASURE_OSARGUMENT_HPP
486