Line data Source code
1 : /****************************************************************************/
2 : // Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
3 : // Copyright (C) 2001-2025 German Aerospace Center (DLR) and others.
4 : // This program and the accompanying materials are made available under the
5 : // terms of the Eclipse Public License 2.0 which is available at
6 : // https://www.eclipse.org/legal/epl-2.0/
7 : // This Source Code may also be made available under the following Secondary
8 : // Licenses when the conditions for such availability set forth in the Eclipse
9 : // Public License 2.0 are satisfied: GNU General Public License, version 2
10 : // or later which is available at
11 : // https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html
12 : // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
13 : /****************************************************************************/
14 : /// @file OptionsCont.h
15 : /// @author Daniel Krajzewicz
16 : /// @author Jakob Erdmann
17 : /// @author Michael Behrisch
18 : /// @author Walter Bamberger
19 : /// @date Mon, 17 Dec 2001
20 : ///
21 : // A storage for options (typed value containers)
22 : /****************************************************************************/
23 : #pragma once
24 : #include <config.h>
25 :
26 : #include <map>
27 : #include <string>
28 : #include <vector>
29 : #include <iostream>
30 : #include "Option.h"
31 :
32 :
33 : // ===========================================================================
34 : // class definitions
35 : // ===========================================================================
36 : /**
37 : * @class OptionsCont
38 : * @brief A storage for options typed value containers)
39 : *
40 : * This container stores options (typed value containers) by their names.
41 : * In the case of command line tools, this container is the main interface
42 : * between a user's definitions about what to do (command line options,
43 : * configuration files) and the application.
44 : *
45 : * At the begin, the application should initialise the container. Because
46 : * the OptionsCont is also responsible for printing the help screen, one
47 : * should name and describe the application, first. This means that the
48 : * first usage of this container should look similar to this:
49 : * @code
50 : * OptionsCont &oc = OptionsCont::getOptions();
51 : * // give some application descriptions
52 : * oc.setApplicationDescription(<ONE_LINE_DESCRIPTION>);
53 : * oc.setApplicationName(<APPLICATION_NAME>, "SUMO <APPLICATION_NAME> Version " + (string)VERSION_STRING);
54 : * @endcode
55 : * @see setApplicationDescription
56 : * @see setApplicationName
57 : *
58 : * Then, you may also add some example calls using addCallExample.
59 : * @see addCallExample
60 : *
61 : * In the next step, option subtopics are registered. This is needed
62 : * for the help screen and for writing the templates/saving configurations.
63 : * A subtopic is added using addOptionSubTopic(<SUBTOPIC_NAME>).
64 : * @see addOptionSubTopic
65 : *
66 : * After this, you may add options to the container. This is done using
67 : * doRegister. This method requires a long name for the option and
68 : * the value container. The value container must be an instance of
69 : * one of the classes derived from "Option". Do not use Option itself!
70 : * This is a base class which is meant to supply a default behaviour,
71 : * but this default behaviour throws exceptions only!
72 : * @see Option
73 : * @see doRegister
74 : * @see addSynonyme
75 : *
76 : * Once stored inside this container, options will not be visible to the
77 : * world and are deleted by the container. Only values and stati of the
78 : * options may be returned. While accessing the options, the programmer
79 : * must assure that he asks for the right value (only Option_Bool is able
80 : * to return a boolean value, other option types will throw exceptions).
81 : * Further, options added to the container must not be deleted outside
82 : * this container (the container becomes the owner).
83 : *
84 : * For being printed in the help screen, a description together with the
85 : * subtopic the option belongs to must be given to OptionsCont. This is
86 : * done using addDescription(<OPTION_NAME>, <SUBTOPIC>, <DESCRIPTION>).
87 : * @see addDescription
88 : */
89 : class OptionsCont {
90 :
91 : public:
92 : /// @brief Retrieves the options
93 : static OptionsCont& getOptions();
94 :
95 : /// @brief empty option container
96 : static OptionsCont EMPTY_OPTIONS;
97 :
98 : /// @brief Constructor
99 : OptionsCont();
100 :
101 : /// @brief Destructor
102 : ~OptionsCont();
103 :
104 : /// @name Methods setting and getting information about the appplication and currently set options
105 : /// @{
106 :
107 : /** @brief Sets the application name
108 : *
109 : * @param[in] name The name of the excutable
110 : * @param[in] v The name of the executable with version information
111 : */
112 : void setApplicationName(const std::string& appName, const std::string& fullName);
113 :
114 : /** @brief Sets the application description
115 : *
116 : * @param[in] appDesc A description of the application
117 : */
118 : void setApplicationDescription(const std::string& appDesc);
119 :
120 : /** @brief Add a call example
121 : *
122 : * @param[in] example A call example (without the app name)
123 : * @param[in] desc A verbose description
124 : */
125 : void addCallExample(const std::string& example, const std::string& desc);
126 :
127 : /** @brief Sets an additional message to be printed at the begin of the help screen
128 : *
129 : * @param[in] example Some additional information about how to use the application
130 : */
131 : void setAdditionalHelpMessage(const std::string& add);
132 :
133 : /** @brief Adds a copyright notice to the help output
134 : *
135 : * @param[in] copyrightLine The line to put out as a copyright notice
136 : */
137 : void addCopyrightNotice(const std::string& copyrightLine);
138 :
139 : /** @brief Removes all copyright information
140 : */
141 : void clearCopyrightNotices();
142 :
143 : /** @brief Adds an option subtopic
144 : *
145 : * Sub-topics are used to join several options into one thematic field.
146 : * They are used on writing the help screen and the configuration. They have
147 : * no further meaning besides making the outputs better readable.
148 : *
149 : * @param[in] topic The options sub topic
150 : */
151 : void addOptionSubTopic(const std::string& topic);
152 :
153 : /** @brief Prints the help
154 : *
155 : * @param[in] os The stream to write the help into
156 : */
157 : void printHelp(std::ostream& os);
158 :
159 : /** @brief Prints help on the given topic
160 : *
161 : * @param[in] topic The topic name
162 : * @param[in] os The stream to write the help into
163 : */
164 : void printHelpOnTopic(const std::string& topic, int tooLarge, int maxSize, std::ostream& os);
165 :
166 : /** @brief Writes the configuration
167 : *
168 : * The configuration is written as XML into the given stream, allowing
169 : * to reload it on a next run.
170 : *
171 : * @param[in] os The stream to write the configuration into
172 : * @param[in] filled Whether only set (and not default) options shall be written
173 : * @param[in] complete Whether all options shall be written
174 : * @param[in] addComments Whether comments (option descriptions) shall be written
175 : * @param[in] inComment Whether -- in input shall be converted to -- (semantically equivalent but allowed in XML comments)
176 : */
177 : void writeConfiguration(std::ostream& os, const bool filled,
178 : const bool complete, const bool addComments, const std::string& relativeTo = "",
179 : const bool forceRelative = false, const bool inComment = false, const std::string& indent = "") const;
180 :
181 : /** @brief Writes the xml schema for the configuration
182 : *
183 : * The schema for the configuration is written as XML into the given stream,
184 : * allowing to validate the configuration against.
185 : *
186 : * @param[in] os The stream to write the schema into
187 : */
188 : void writeSchema(std::ostream& os);
189 :
190 : /** @brief Writes a standard XML header, including the configuration
191 : *
192 : * The header consists of the xml-declaration with encoding as defined
193 : * by SUMOSAXAttributes::ENCODING, followed by a note which contains
194 : * the current date and time and the application configuration (set values).
195 : *
196 : * @param[in] os The stream to write the header into
197 : */
198 : void writeXMLHeader(std::ostream& os, const bool includeConfig = true) const;
199 :
200 : /// @}
201 :
202 : /// @name Methods for registering options
203 : /// @{
204 :
205 : /** @brief Adds an option under the given name
206 : * @param[in] name The (long) name of the option
207 : * @param[in] o The option (typed value storage)
208 : * @exception InvalidArgument If the name is already used
209 : */
210 : void doRegister(const std::string& name, Option* o);
211 :
212 : /** @brief Adds an option under the given name and the given abbreviation
213 : *
214 : * Adds the option under both names using void doRegister(const std::string &name, Option *v);
215 : *
216 : * @param[in] name The (long) name of the option
217 : * @param[in] abbr The (short) name of the option
218 : * @param[in] v The option (typed value storage)
219 : * @exception InvalidArgument If one of the names is already used
220 : */
221 : void doRegister(const std::string& name, char abbr, Option* o);
222 :
223 : /** @brief Adds a synonyme for an options name (any order)
224 : *
225 : * Tries to find one of the synonymes. If both are known and the option differs
226 : * for both, an InvalidArgument exception is thrown. If none is known, also.
227 : *
228 : * If one of the synonymes is known and the other not, the option from the known
229 : * one is made accessible by the other.
230 : *
231 : * In the case both synonymes are known and have the same option assigned, nothing
232 : * is done.
233 : *
234 : * @param[in] name1 The first synonyme
235 : * @param[in] name2 The second synonyme
236 : * @param[in] isDeprecated whether the synonyme is considered deprecated
237 : * @exception InvalidArgument If none of the synonymes or both synonymes with different options were registered before
238 : */
239 : void addSynonyme(const std::string& name1, const std::string& name2, bool isDeprecated = false);
240 :
241 : /** @brief Adds an XML root element to handle by default. The special root "" denotes the default handler.
242 : *
243 : * @param[in] name The option name
244 : * @param[in] xmlRoot The name of the xml root element to handle
245 : */
246 : void addXMLDefault(const std::string& name, const std::string& xmlRoot = "");
247 :
248 : /** @brief Adds a description for an option
249 : *
250 : * Tries to retrieve the named option and to set the given description. Adds
251 : * the name to the list of option names to be located in the named subtopic.
252 : *
253 : * Throws an InvalidArgument if the option is not known or already has
254 : * a description set.
255 : *
256 : * @param[in] name The option's name
257 : * @param[in] subtopic The subtopic to locate the description within
258 : * @param[in] description The description
259 : * @exception InvalidArgument If none of the synonymes or both synonymes with different options were registered before
260 : */
261 : void addDescription(const std::string& name, const std::string& subtopic, const std::string& description);
262 :
263 : /** @brief mark option as required
264 : *
265 : * Tries to retrieve the named option and set as required. Adds
266 : * the name to the list of option names to be located in the named subtopic.
267 : *
268 : * Throws an InvalidArgument if the option is not known
269 : *
270 : * @param[in] name The option's name
271 : * @param[in] subtopic The subtopic to locate the description within
272 : * @exception InvalidArgument If none of the synonymes or both synonymes with different options were registered before
273 : */
274 : void setFurtherAttributes(const std::string& name, const std::string& subtopic, bool required, bool positional, const std::string& listSep);
275 :
276 : /** @brief Adds a category for an option
277 : *
278 : * Tries to retrieve the named option and to set the given category. Adds
279 : * the name to the list of option names to be located in the named subtopic.
280 : *
281 : * Throws an InvalidArgument if the option is not known or already has
282 : * a category set.
283 : *
284 : * @param[in] name The option's name
285 : * @param[in] subtopic The subtopic to locate the category within
286 : * @param[in] category The category
287 : * @exception InvalidArgument If none of the synonymes or both synonymes with different options were registered before
288 : */
289 : void addCategory(const std::string& name, const std::string& subtopic, const std::string& category);
290 :
291 : /// @}
292 :
293 : /// @name Methods for retrieving information about options
294 : /// @{
295 :
296 : /** @brief Returns the information whether the named option is known
297 : * @return true if an option has been added before under the given name, false otherwise
298 : */
299 : bool exists(const std::string& name) const;
300 :
301 : /** @brief Returns the information whether the named option is set
302 : *
303 : * The named option is tried to be retrieved from the container. If
304 : * it does not exist, an InvalidArgument is thrown. If it could be
305 : * retrieved, the information whether the option has a value stored
306 : * is returned.
307 : *
308 : * An option "is set" if a default value was supplied or a value has been
309 : * set from the command line / the configuration file.
310 : *
311 : * @param[in] name The name of the option to check
312 : * @param[in] failOnNonExistant Whether asking for an unregistered option should trigger an exception
313 : * @return true if the option has a valid value, false otherwise
314 : * @exception InvalidArgument If the named option is not known
315 : */
316 : bool isSet(const std::string& name, bool failOnNonExistant = true) const;
317 :
318 : /** @brief Returns the information whether the named option has still the default value
319 : *
320 : * The named option is tried to be retrieved from the container. If
321 : * it does not exist, an InvalidArgument is thrown. If it could be
322 : * retrieved, the information whether the option still has the default
323 : * value is returned.
324 : *
325 : * An option "is default" if no value has been set from the command line
326 : * / the configuration file.
327 : *
328 : * @return true if the option still has the default value
329 : * @exception InvalidArgument If the named option is not known
330 : */
331 : bool isDefault(const std::string& name) const;
332 :
333 : /** @brief Returns the information whether the option is a boolean option
334 : *
335 : * The option is retrieved from the container, first, what may cause an InvalidArgument
336 : * exception if it is not known. Otherwise, this option's isBool-method is called.
337 : *
338 : * @param[in] name The name of the option to check
339 : * @return Whether the existing named option is a bool option
340 : * @exception InvalidArgument If the option does not exist
341 : */
342 : bool isBool(const std::string& name) const;
343 :
344 : /** @brief Checks whether the named option is usable as a file list (with at least a single file)
345 : *
346 : * The method returns true, if the named option is set with entries containing
347 : * names of accessible files.
348 : *
349 : * Throw an InvalidArgument exception if the option is not known. If the option
350 : * is not set, false is returned. Also, if the list is empty (contains delimiters only)
351 : * or if one of the named files (obtained using getStringVector) does not exist,
352 : * false is returned. Additionally, an error is sent to MsgHandler in both cases.
353 : *
354 : * In the case two delimiters were placed in the option value directly after
355 : * each other, a warning is generated.
356 : *
357 : * @param[in] name The name of the option to check
358 : * @return Whether the option contains names of files which can be accessed (for reading)
359 : * @exception InvalidArgument If the option does not exist or is not a string-option
360 : */
361 : bool isUsableFileList(const std::string& name) const;
362 :
363 : /** @brief Checks whether an option is set, which has options with a prefix depending on it.
364 : *
365 : * The method returns true, if the named option is set or no option depending on it is set.
366 : * Throws an InvalidArgument exception if the option is not known.
367 : *
368 : * @param[in] name The name of the option to check
369 : * @param[in] prefix The prefix of depending options
370 : * @return Whether the dependencies are fulfilled
371 : * @exception InvalidArgument If the option does not exist
372 : */
373 : bool checkDependingSuboptions(const std::string& name, const std::string& prefix) const;
374 :
375 : /** @brief Modifies file name options according to the configuration path
376 : *
377 : * If the configuration path given is a relative one all filenames inside
378 : * are adapted such that they refer to the correct location.
379 : *
380 : * @param[in] configuration The path to the configuration file
381 : */
382 : void relocateFiles(const std::string& configuration) const;
383 :
384 : /** @brief Returns the synonymes of an option name
385 : *
386 : * The named option is extracted, first. An InvalidArgument is thrown if it
387 : * does not exist. Otherwise, other names for the named option are searched
388 : * and returned (the original name is not in the list).
389 : * @param[in] name The name of the option to return synonymes of
390 : * @return List of existing synonymes
391 : * @exception InvalidArgument If the named option does not exist
392 : **/
393 : std::vector<std::string> getSynonymes(const std::string& name) const;
394 :
395 : /** @brief Returns the option description
396 : *
397 : * @param[in] name The name of the option to return the description of
398 : * @return description
399 : * @exception InvalidArgument If the named option does not exist
400 : **/
401 : const std::string& getDescription(const std::string& name) const;
402 :
403 : /** @brief Returns the option category
404 : *
405 : * @param[in] name The name of the option to return the category of
406 : * @return category
407 : * @exception InvalidArgument If the named option does not exist
408 : **/
409 : const std::string& getSubTopic(const std::string& name) const;
410 :
411 : /** @brief Returns the information whether the named option may be set
412 : *
413 : * An option is writable after initialisation, but as soon as it gets set,
414 : * it is no longer writeable. This method returns whether the named option
415 : * is writeable. If the named option is not known, an InvalidArgument
416 : * is thrown.
417 : *
418 : * @param[in] name The name of the option to check
419 : * @return Whether the value can be set
420 : * @exception InvalidArgument If the option does not exist
421 : */
422 : bool isWriteable(const std::string& name);
423 :
424 : /// @}
425 :
426 : /// @name Methods for retrieving values from options
427 : /// @{
428 :
429 : /** @brief Returns the string-value of the named option (all options)
430 : *
431 : * This method returns the string-value of an existing option.
432 : * If the named option does not exist, an
433 : * InvalidArgument is thrown.
434 : *
435 : * @param[in] name The name of the option to return the string-value of
436 : * @return The string-value of the named, existing option
437 : * @exception InvalidArgument If the option does not exist
438 : */
439 : std::string getValueString(const std::string& name) const;
440 :
441 : /** @brief Returns the string-value of the named option (only for Option_String)
442 : *
443 : * This method returns the string-value of an existing string-option.
444 : * If the named option does not exist or is not a string-option, an
445 : * InvalidArgument is thrown.
446 : *
447 : * @param[in] name The name of the option to return the string-value of
448 : * @return The string-value of the named, existing string-option
449 : * @exception InvalidArgument If the option does not exist or is not a string-option
450 : */
451 : std::string getString(const std::string& name) const;
452 :
453 : /** @brief Returns the double-value of the named option (only for Option_Float)
454 : *
455 : * This method returns the double-value of an existing double-option.
456 : * If the named option does not exist or is not a double-option, an
457 : * InvalidArgument is thrown.
458 : *
459 : * @param[in] name The name of the option to return the double-value of
460 : * @return The double-value of the named, existing double-option
461 : * @exception InvalidArgument If the option does not exist or is not a double-option
462 : */
463 : double getFloat(const std::string& name) const;
464 :
465 : /** @brief Returns the int-value of the named option (only for Option_Integer)
466 : *
467 : * This method returns the int-value of an existing int-option.
468 : * If the named option does not exist or is not a int-option, an
469 : * InvalidArgument is thrown.
470 : *
471 : * @param[in] name The name of the option to return the int-value of
472 : * @return The int-value of the named, existing int-option
473 : * @exception InvalidArgument If the option does not exist or is not a int-option
474 : */
475 : int getInt(const std::string& name) const;
476 :
477 : /** @brief Returns the boolean-value of the named option (only for Option_Bool)
478 : *
479 : * This method returns the boolean-value of an existing boolean-option.
480 : * If the named option does not exist or is not a boolean-option, an
481 : * InvalidArgument is thrown.
482 : *
483 : * @param[in] name The name of the option to return the boolean-value of
484 : * @return The boolean-value of the named, existing boolean-option
485 : * @exception InvalidArgument If the option does not exist or is not a boolean-option
486 : */
487 : bool getBool(const std::string& name) const;
488 :
489 : /** @brief Returns the list of integer-value of the named option (only for Option_IntVector)
490 : *
491 : * This method returns the int-vector-value of an existing int-vector-option.
492 : * If the named option does not exist or is not a int-vector-option, an
493 : * InvalidArgument is thrown.
494 : *
495 : * @param[in] name The name of the option to return the int-vector-value of
496 : * @return The int-vector-value of the named, existing int-vector-option
497 : * @exception InvalidArgument If the option does not exist or is not a int-vector-option
498 : */
499 : const IntVector& getIntVector(const std::string& name) const;
500 :
501 : /** @brief Returns the list of string-value of the named option (only for Option_StringVector)
502 : *
503 : * This method returns the string-vector-value of an existing string-vector-option.
504 : * If the named option does not exist or is not a string-vector-option, an
505 : * InvalidArgument is thrown.
506 : *
507 : * If the legacy-divider ';' is found within the string, a warning is generated.
508 : * The retrieved string is only splitted at ','.
509 : *
510 : * @param[in] name The name of the option to return the string-vector-value of
511 : * @return The string-vector-value of the named, existing string-vector-option
512 : * @exception InvalidArgument If the option does not exist or is not a string-vector-option
513 : * @todo Is it possible to retrieve a const-reference of the string?
514 : * @see getString()
515 : */
516 : const StringVector& getStringVector(const std::string& name) const;
517 :
518 : /** @brief Returns the named option is a list of string values containing the specified item
519 : *
520 : * If the named option is not set, false is returned. Otherwise, the string-vector
521 : * of this option is retrieved using getStringVector what may throw an
522 : * InvalidArgument exception if the named option is not a string option or not
523 : * existing at all.
524 : *
525 : * The given itemName is searched in the obtained string-vector and the
526 : * method returns whether it is stored in the list or not.
527 : *
528 : * @param[in] optionName The name of the option to evaluate entries of
529 : * @param[in] itemName The item to be searched for in the entries of the named option
530 : * @return Whether the named item is set in the named string-option
531 : * @exception InvalidArgument If the option does not exist or is not a string-option
532 : * @see getStringVector()
533 : * @todo Try to optimize - at each call, the vector is rebuilt
534 : */
535 : bool isInStringVector(const std::string& optionName, const std::string& itemName) const;
536 :
537 : /// @}
538 :
539 : /// @name Methods for setting values into options
540 : /// @{
541 :
542 : /** @brief Sets the given value for the named option
543 : *
544 : * The option is retrieved from the container, first, what yields in a InvalidArgument
545 : * exception for not known options.
546 : *
547 : * If the option is not writable (was set before), an error is generated using
548 : * reportDoubleSetting, and false is returned. Otherwise, the option is
549 : * told to set the given value using Option::set. Possible problems herein
550 : * are caught and reported to the error-handler, yielding in returning false.
551 : *
552 : * If the new value could be set, true is returned.
553 : *
554 : * @param[in] name The name of the option to set
555 : * @param[in] value The value to set
556 : * @return Whether the value could be set
557 : * @exception InvalidArgument If the option does not exist
558 : * @see reportDoubleSetting
559 : * @see Option::set(const std::string &)
560 : */
561 : bool set(const std::string& name, const std::string& value, const bool append = false);
562 :
563 : /** @brief Sets the given value for the named option as new default value
564 : *
565 : * The option is retrieved from the container, first, what yields in a InvalidArgument
566 : * exception for not known options.
567 : *
568 : * If the option is not writable (was set before), an error is generated using
569 : * reportDoubleSetting, and false is returned. Otherwise, the option is
570 : * told to set the given value using Option::set. Possible problems herein
571 : * are caught and reported to the error-handler, yielding in returning false.
572 : *
573 : * If the new value could be set, true is returned.
574 : *
575 : * @param[in] name The name of the option to set
576 : * @param[in] value The value to set
577 : * @return Whether the value could be set
578 : * @exception InvalidArgument If the option does not exist
579 : * @see reportDoubleSetting
580 : * @see Option::set(const std::string &)
581 : */
582 : bool setDefault(const std::string& name, const std::string& value);
583 :
584 : /** @brief Sets the given value for the option which can handle the given XML root
585 : *
586 : * The option is retrieved from the container, which yields in an InvalidArgument
587 : * exception if no option is registered for the XML root. Then it uses the
588 : * standard set method.
589 : *
590 : * @param[in] root The name of the XML root element to look for
591 : * @param[in] value The value to set
592 : * @return Whether the value could be set
593 : * @exception InvalidArgument If the root element was not registered or the value could not be set
594 : * @see OptionsCont::set(const std::string &, const std::string &)
595 : */
596 : bool setByRootElement(const std::string& name, const std::string& value);
597 :
598 : /// @}
599 :
600 : /** @brief Resets all options to be writeable
601 : *
602 : * An option is writable after initialisation, but as soon as it gets set,
603 : * it is no longer writeable. This method resets the writable-flag of all
604 : * known options.
605 : */
606 : void resetWritable();
607 :
608 : /// @brief Resets all options to default
609 : void resetDefault();
610 :
611 : /// @brief Reset specific option to default
612 : void resetDefault(const std::string& name);
613 :
614 : /** @brief Output operator
615 : *
616 : * Generates the output used when current option values shall be printed.
617 : *
618 : * @param[in] os The stream to write into
619 : * @param[in] oc The options to print
620 : * @return The stream to write into
621 : */
622 : friend std::ostream& operator<<(std::ostream& os, const OptionsCont& oc);
623 :
624 : /// @brief Removes all information from the container
625 : void clear();
626 :
627 : /** @brief Checks for help and configuration output, returns whether we should exit
628 : *
629 : * Returns false if no error was detected and the application may be executed
630 : * (at least from this point of view). If missingOptions is true, the user is
631 : * informed that they should be supplied (returns true). Otherwise it is checked
632 : * whether help shall be printed what is done if so, returning true. Also, it
633 : * is checked whether the set options shall be printed and the configuration
634 : * template or the current configuration shall be written.
635 : *
636 : * This method throws a ProcessError if the configuration should be saved,
637 : * but the file is not accessible. An error message is supplied.
638 : *
639 : * @param[in] missingOptions Whether no options have been given
640 : * @return Whether the application shall stop
641 : * @exception ProcessError If the configuration file could not be saved
642 : */
643 : bool processMetaOptions(bool missingOptions);
644 :
645 : void localizeDescriptions();
646 :
647 : /// @brief return the list of subtopics
648 : const std::vector<std::string>& getSubTopics() const;
649 :
650 : /// @brief return the list of entries for the given subtopic
651 : std::vector<std::string> getSubTopicsEntries(const std::string& subtopic) const;
652 :
653 : /// @brief return the type name for the given option
654 : std::string getTypeName(const std::string name);
655 :
656 : /// @brief get options full name
657 : const std::string& getFullName() const;
658 :
659 : /// @brief check if options container is empty
660 : bool isEmpty() const;
661 :
662 : /// @brief get begin addresses iterator
663 : std::vector<std::pair<std::string, Option*> >::const_iterator begin() const;
664 :
665 : /// @brief get begin addresses iterator
666 : std::vector<std::pair<std::string, Option*> >::const_iterator end() const;
667 :
668 : /// @brief make a copy of this OptionsCont instance
669 : OptionsCont* clone() const;
670 :
671 : private:
672 : /** @brief Returns the named option
673 : *
674 : * If the named option does not exist, an InvalidArgument is thrown.
675 : *
676 : * @param[in] name The name of the option to return
677 : * @return The named option
678 : */
679 : Option* getSecure(const std::string& name) const;
680 :
681 : /** @brief Reports an error that the option has already been set
682 : *
683 : * Using the given option name, an error string is generated and reported to
684 : * MsgHandler-error instance.
685 : *
686 : * @param[in] name The name of the option that was already set
687 : */
688 : void reportDoubleSetting(const std::string& arg) const;
689 :
690 : /** @brief Converts an abbreviation into a name
691 : *
692 : * Build and returns the string which consists of the given character only.
693 : *
694 : * @param[in] abbr The abbreviation to convert into a string
695 : * @return The abbreviation converted into a string
696 : */
697 : std::string convertChar(char abbr) const;
698 :
699 : /** @brief Writes the given string 'formatted'
700 : *
701 : * The given string is split so that no word-wrapping occurs at line ends.
702 : * The text is wrapped at ';' or ' '.
703 : *
704 : * @param[in] os The stream to write the text into
705 : * @param[in] what The text to write
706 : * @param[in] offset ?
707 : * @param[in] nextOffset ?
708 : * @todo Describe parameter
709 : */
710 : void splitLines(std::ostream& os, std::string what, int offset, int nextOffset);
711 :
712 : /// @brief Whether the descriptino has already been translated to the locale language
713 : bool myAmLocalized = false;
714 :
715 : /// @brief The static options container used
716 : static OptionsCont myOptions;
717 :
718 : /// @brief option-addresses
719 : std::vector<std::pair<std::string, Option*> > myAddresses;
720 :
721 : /// @brief option maps sorted by name (for addresses AND their synonyms)
722 : std::map<std::string, Option*> myValues;
723 :
724 : /// @brief some information on the application
725 : std::string myAppName, myFullName, myAppDescription, myAdditionalMessage;
726 :
727 : /// @brief list of call examples
728 : std::vector< std::pair<std::string, std::string> > myCallExamples;
729 :
730 : /// @brief lists of option subtopics and copyright notices
731 : std::vector<std::string> mySubTopics, myCopyrightNotices;
732 :
733 : /// @brief A map from subtopic to option
734 : std::map<std::string, std::vector<std::string> > mySubTopicEntries;
735 :
736 : /// @brief A map from XML root element to option
737 : std::map<std::string, std::string> myXMLDefaults;
738 :
739 : /// @brief A map from deprecated options to a bool indicating whether we warned about deprecation
740 : mutable std::map<std::string, bool> myDeprecatedSynonymes;
741 :
742 : /// @brief default copy constructor, but private
743 1204 : OptionsCont(const OptionsCont& s) = default;
744 :
745 : /// @brief invalid assignment operator
746 : OptionsCont& operator=(const OptionsCont& s) = delete;
747 : };
|
