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 set option editable
277 : *
278 : * Tries to change the flag editable in the given option
279 : *
280 : * Throws an InvalidArgument if the option is not known
281 : *
282 : * @param[in] name The option's name
283 : * @param[in] value editable value (true/false)
284 : * @exception InvalidArgument If option doesn't exist
285 : */
286 : void setOptionEditable(const std::string& name, const bool value);
287 :
288 : /// @}
289 :
290 : /// @name Methods for retrieving information about options
291 : /// @{
292 :
293 : /** @brief Returns the information whether the named option is known
294 : * @return true if an option has been added before under the given name, false otherwise
295 : */
296 : bool exists(const std::string& name) const;
297 :
298 : /** @brief Returns the information whether the named option is set
299 : *
300 : * The named option is tried to be retrieved from the container. If
301 : * it does not exist, an InvalidArgument is thrown. If it could be
302 : * retrieved, the information whether the option has a value stored
303 : * is returned.
304 : *
305 : * An option "is set" if a default value was supplied or a value has been
306 : * set from the command line / the configuration file.
307 : *
308 : * @param[in] name The name of the option to check
309 : * @param[in] failOnNonExistant Whether asking for an unregistered option should trigger an exception
310 : * @return true if the option has a valid value, false otherwise
311 : * @exception InvalidArgument If the named option is not known
312 : */
313 : bool isSet(const std::string& name, bool failOnNonExistant = true) const;
314 :
315 : /** @brief Returns the information whether the named option has still the default value
316 : *
317 : * The named option is tried to be retrieved from the container. If
318 : * it does not exist, an InvalidArgument is thrown. If it could be
319 : * retrieved, the information whether the option still has the default
320 : * value is returned.
321 : *
322 : * An option "is default" if no value has been set from the command line
323 : * / the configuration file.
324 : *
325 : * @return true if the option still has the default value
326 : * @exception InvalidArgument If the named option is not known
327 : */
328 : bool isDefault(const std::string& name) const;
329 :
330 : /** @brief Returns the information whether the option is a boolean option
331 : *
332 : * The option is retrieved from the container, first, what may cause an InvalidArgument
333 : * exception if it is not known. Otherwise, this option's isBool-method is called.
334 : *
335 : * @param[in] name The name of the option to check
336 : * @return Whether the existing named option is a bool option
337 : * @exception InvalidArgument If the option does not exist
338 : */
339 : bool isBool(const std::string& name) const;
340 :
341 : /** @brief Checks whether the named option is usable as a file list (with at least a single file)
342 : *
343 : * The method returns true, if the named option is set with entries containing
344 : * names of accessible files.
345 : *
346 : * Throw an InvalidArgument exception if the option is not known. If the option
347 : * is not set, false is returned. Also, if the list is empty (contains delimiters only)
348 : * or if one of the named files (obtained using getStringVector) does not exist,
349 : * false is returned. Additionally, an error is sent to MsgHandler in both cases.
350 : *
351 : * In the case two delimiters were placed in the option value directly after
352 : * each other, a warning is generated.
353 : *
354 : * @param[in] name The name of the option to check
355 : * @return Whether the option contains names of files which can be accessed (for reading)
356 : * @exception InvalidArgument If the option does not exist or is not a string-option
357 : */
358 : bool isUsableFileList(const std::string& name) const;
359 :
360 : /** @brief Checks whether an option is set, which has options with a prefix depending on it.
361 : *
362 : * The method returns true, if the named option is set or no option depending on it is set.
363 : * Throws an InvalidArgument exception if the option is not known.
364 : *
365 : * @param[in] name The name of the option to check
366 : * @param[in] prefix The prefix of depending options
367 : * @return Whether the dependencies are fulfilled
368 : * @exception InvalidArgument If the option does not exist
369 : */
370 : bool checkDependingSuboptions(const std::string& name, const std::string& prefix) const;
371 :
372 : /** @brief Modifies file name options according to the configuration path
373 : *
374 : * If the configuration path given is a relative one all filenames inside
375 : * are adapted such that they refer to the correct location.
376 : *
377 : * @param[in] configuration The path to the configuration file
378 : */
379 : void relocateFiles(const std::string& configuration) const;
380 :
381 : /** @brief Returns the synonymes of an option name
382 : *
383 : * The named option is extracted, first. An InvalidArgument is thrown if it
384 : * does not exist. Otherwise, other names for the named option are searched
385 : * and returned (the original name is not in the list).
386 : * @param[in] name The name of the option to return synonymes of
387 : * @return List of existing synonymes
388 : * @exception InvalidArgument If the named option does not exist
389 : **/
390 : std::vector<std::string> getSynonymes(const std::string& name) const;
391 :
392 : /** @brief Returns the option description
393 : *
394 : * @param[in] name The name of the option to return the description of
395 : * @return description
396 : * @exception InvalidArgument If the named option does not exist
397 : **/
398 : const std::string& getDescription(const std::string& name) const;
399 :
400 : /** @brief Returns the option category
401 : *
402 : * @param[in] name The name of the option to return the category of
403 : * @return category
404 : * @exception InvalidArgument If the named option does not exist
405 : **/
406 : const std::string& getSubTopic(const std::string& name) const;
407 :
408 : /** @brief Returns the information whether the named option may be set
409 : *
410 : * An option is writable after initialisation, but as soon as it gets set,
411 : * it is no longer writeable. This method returns whether the named option
412 : * is writeable. If the named option is not known, an InvalidArgument
413 : * is thrown.
414 : *
415 : * @param[in] name The name of the option to check
416 : * @return Whether the value can be set
417 : * @exception InvalidArgument If the option does not exist
418 : */
419 : bool isWriteable(const std::string& name);
420 :
421 : /** @brief Returns the information whether the named option is editable
422 : *
423 : * @param[in] name The name of the option to check
424 : * @return Whether the value is editable
425 : * @exception InvalidArgument If the option does not exist
426 : */
427 : bool isEditable(const std::string& name);
428 :
429 : /// @}
430 :
431 : /// @name Methods for retrieving values from options
432 : /// @{
433 :
434 : /** @brief Returns the string-value of the named option (all options)
435 : *
436 : * This method returns the string-value of an existing option.
437 : * If the named option does not exist, an
438 : * InvalidArgument is thrown.
439 : *
440 : * @param[in] name The name of the option to return the string-value of
441 : * @return The string-value of the named, existing option
442 : * @exception InvalidArgument If the option does not exist
443 : */
444 : std::string getValueString(const std::string& name) const;
445 :
446 : /** @brief Returns the string-value of the named option (only for Option_String)
447 : *
448 : * This method returns the string-value of an existing string-option.
449 : * If the named option does not exist or is not a string-option, an
450 : * InvalidArgument is thrown.
451 : *
452 : * @param[in] name The name of the option to return the string-value of
453 : * @return The string-value of the named, existing string-option
454 : * @exception InvalidArgument If the option does not exist or is not a string-option
455 : */
456 : std::string getString(const std::string& name) const;
457 :
458 : /** @brief Returns the double-value of the named option (only for Option_Float)
459 : *
460 : * This method returns the double-value of an existing double-option.
461 : * If the named option does not exist or is not a double-option, an
462 : * InvalidArgument is thrown.
463 : *
464 : * @param[in] name The name of the option to return the double-value of
465 : * @return The double-value of the named, existing double-option
466 : * @exception InvalidArgument If the option does not exist or is not a double-option
467 : */
468 : double getFloat(const std::string& name) const;
469 :
470 : /** @brief Returns the int-value of the named option (only for Option_Integer)
471 : *
472 : * This method returns the int-value of an existing int-option.
473 : * If the named option does not exist or is not a int-option, an
474 : * InvalidArgument is thrown.
475 : *
476 : * @param[in] name The name of the option to return the int-value of
477 : * @return The int-value of the named, existing int-option
478 : * @exception InvalidArgument If the option does not exist or is not a int-option
479 : */
480 : int getInt(const std::string& name) const;
481 :
482 : /** @brief Returns the boolean-value of the named option (only for Option_Bool)
483 : *
484 : * This method returns the boolean-value of an existing boolean-option.
485 : * If the named option does not exist or is not a boolean-option, an
486 : * InvalidArgument is thrown.
487 : *
488 : * @param[in] name The name of the option to return the boolean-value of
489 : * @return The boolean-value of the named, existing boolean-option
490 : * @exception InvalidArgument If the option does not exist or is not a boolean-option
491 : */
492 : bool getBool(const std::string& name) const;
493 :
494 : /** @brief Returns the list of integer-value of the named option (only for Option_IntVector)
495 : *
496 : * This method returns the int-vector-value of an existing int-vector-option.
497 : * If the named option does not exist or is not a int-vector-option, an
498 : * InvalidArgument is thrown.
499 : *
500 : * @param[in] name The name of the option to return the int-vector-value of
501 : * @return The int-vector-value of the named, existing int-vector-option
502 : * @exception InvalidArgument If the option does not exist or is not a int-vector-option
503 : */
504 : const IntVector& getIntVector(const std::string& name) const;
505 :
506 : /** @brief Returns the list of string-value of the named option (only for Option_StringVector)
507 : *
508 : * This method returns the string-vector-value of an existing string-vector-option.
509 : * If the named option does not exist or is not a string-vector-option, an
510 : * InvalidArgument is thrown.
511 : *
512 : * If the legacy-divider ';' is found within the string, a warning is generated.
513 : * The retrieved string is only splitted at ','.
514 : *
515 : * @param[in] name The name of the option to return the string-vector-value of
516 : * @return The string-vector-value of the named, existing string-vector-option
517 : * @exception InvalidArgument If the option does not exist or is not a string-vector-option
518 : * @todo Is it possible to retrieve a const-reference of the string?
519 : * @see getString()
520 : */
521 : const StringVector& getStringVector(const std::string& name) const;
522 :
523 : /** @brief Returns the named option is a list of string values containing the specified item
524 : *
525 : * If the named option is not set, false is returned. Otherwise, the string-vector
526 : * of this option is retrieved using getStringVector what may throw an
527 : * InvalidArgument exception if the named option is not a string option or not
528 : * existing at all.
529 : *
530 : * The given itemName is searched in the obtained string-vector and the
531 : * method returns whether it is stored in the list or not.
532 : *
533 : * @param[in] optionName The name of the option to evaluate entries of
534 : * @param[in] itemName The item to be searched for in the entries of the named option
535 : * @return Whether the named item is set in the named string-option
536 : * @exception InvalidArgument If the option does not exist or is not a string-option
537 : * @see getStringVector()
538 : * @todo Try to optimize - at each call, the vector is rebuilt
539 : */
540 : bool isInStringVector(const std::string& optionName, const std::string& itemName) const;
541 :
542 : /// @}
543 :
544 : /// @name Methods for setting values into options
545 : /// @{
546 :
547 : /** @brief Sets the given value for the named option
548 : *
549 : * The option is retrieved from the container, first, what yields in a InvalidArgument
550 : * exception for not known options.
551 : *
552 : * If the option is not writable (was set before), an error is generated using
553 : * reportDoubleSetting, and false is returned. Otherwise, the option is
554 : * told to set the given value using Option::set. Possible problems herein
555 : * are caught and reported to the error-handler, yielding in returning false.
556 : *
557 : * If the new value could be set, true is returned.
558 : *
559 : * @param[in] name The name of the option to set
560 : * @param[in] value The value to set
561 : * @return Whether the value could be set
562 : * @exception InvalidArgument If the option does not exist
563 : * @see reportDoubleSetting
564 : * @see Option::set(const std::string &)
565 : */
566 : bool set(const std::string& name, const std::string& value, const bool append = false);
567 :
568 : /** @brief Sets the given value for the named option as new default value
569 : *
570 : * The option is retrieved from the container, first, what yields in a InvalidArgument
571 : * exception for not known options.
572 : *
573 : * If the option is not writable (was set before), an error is generated using
574 : * reportDoubleSetting, and false is returned. Otherwise, the option is
575 : * told to set the given value using Option::set. Possible problems herein
576 : * are caught and reported to the error-handler, yielding in returning false.
577 : *
578 : * If the new value could be set, true is returned.
579 : *
580 : * @param[in] name The name of the option to set
581 : * @param[in] value The value to set
582 : * @return Whether the value could be set
583 : * @exception InvalidArgument If the option does not exist
584 : * @see reportDoubleSetting
585 : * @see Option::set(const std::string &)
586 : */
587 : bool setDefault(const std::string& name, const std::string& value);
588 :
589 : /** @brief Sets the given value for the option which can handle the given XML root
590 : *
591 : * The option is retrieved from the container, which yields in an InvalidArgument
592 : * exception if no option is registered for the XML root. Then it uses the
593 : * standard set method.
594 : *
595 : * @param[in] root The name of the XML root element to look for
596 : * @param[in] value The value to set
597 : * @return Whether the value could be set
598 : * @exception InvalidArgument If the root element was not registered or the value could not be set
599 : * @see OptionsCont::set(const std::string &, const std::string &)
600 : */
601 : bool setByRootElement(const std::string& name, const std::string& value);
602 :
603 : /// @}
604 :
605 : /** @brief Resets all options to be writeable
606 : *
607 : * An option is writable after initialisation, but as soon as it gets set,
608 : * it is no longer writeable. This method resets the writable-flag of all
609 : * known options.
610 : */
611 : void resetWritable();
612 :
613 : /// @brief Resets all options to default
614 : void resetDefault();
615 :
616 : /// @brief Reset specific option to default
617 : void resetDefault(const std::string& name);
618 :
619 : /** @brief Output operator
620 : *
621 : * Generates the output used when current option values shall be printed.
622 : *
623 : * @param[in] os The stream to write into
624 : * @param[in] oc The options to print
625 : * @return The stream to write into
626 : */
627 : friend std::ostream& operator<<(std::ostream& os, const OptionsCont& oc);
628 :
629 : /// @brief Removes all information from the container
630 : void clear();
631 :
632 : /** @brief Checks for help and configuration output, returns whether we should exit
633 : *
634 : * Returns false if no error was detected and the application may be executed
635 : * (at least from this point of view). If missingOptions is true, the user is
636 : * informed that they should be supplied (returns true). Otherwise it is checked
637 : * whether help shall be printed what is done if so, returning true. Also, it
638 : * is checked whether the set options shall be printed and the configuration
639 : * template or the current configuration shall be written.
640 : *
641 : * This method throws a ProcessError if the configuration should be saved,
642 : * but the file is not accessible. An error message is supplied.
643 : *
644 : * @param[in] missingOptions Whether no options have been given
645 : * @return Whether the application shall stop
646 : * @exception ProcessError If the configuration file could not be saved
647 : */
648 : bool processMetaOptions(bool missingOptions);
649 :
650 : void localizeDescriptions();
651 :
652 : /// @brief return the list of subtopics
653 : const std::vector<std::string>& getSubTopics() const;
654 :
655 : /// @brief return the list of entries for the given subtopic
656 : std::vector<std::string> getSubTopicsEntries(const std::string& subtopic) const;
657 :
658 : /// @brief return the type name for the given option
659 : std::string getTypeName(const std::string name);
660 :
661 : /// @brief get options full name
662 : const std::string& getFullName() const;
663 :
664 : /// @brief check if options container is empty
665 : bool isEmpty() const;
666 :
667 : /// @brief get begin addresses iterator
668 : std::vector<std::pair<std::string, Option*> >::const_iterator begin() const;
669 :
670 : /// @brief get begin addresses iterator
671 : std::vector<std::pair<std::string, Option*> >::const_iterator end() const;
672 :
673 : /// @brief make a copy of this OptionsCont instance
674 : OptionsCont* clone() const;
675 :
676 : private:
677 : /** @brief Returns the named option
678 : *
679 : * If the named option does not exist, an InvalidArgument is thrown.
680 : *
681 : * @param[in] name The name of the option to return
682 : * @return The named option
683 : */
684 : Option* getSecure(const std::string& name) const;
685 :
686 : /** @brief Reports an error that the option has already been set
687 : *
688 : * Using the given option name, an error string is generated and reported to
689 : * MsgHandler-error instance.
690 : *
691 : * @param[in] name The name of the option that was already set
692 : */
693 : void reportDoubleSetting(const std::string& arg) const;
694 :
695 : /** @brief Converts an abbreviation into a name
696 : *
697 : * Build and returns the string which consists of the given character only.
698 : *
699 : * @param[in] abbr The abbreviation to convert into a string
700 : * @return The abbreviation converted into a string
701 : */
702 : std::string convertChar(char abbr) const;
703 :
704 : /** @brief Writes the given string 'formatted'
705 : *
706 : * The given string is split so that no word-wrapping occurs at line ends.
707 : * The text is wrapped at ';' or ' '.
708 : *
709 : * @param[in] os The stream to write the text into
710 : * @param[in] what The text to write
711 : * @param[in] offset ?
712 : * @param[in] nextOffset ?
713 : * @todo Describe parameter
714 : */
715 : void splitLines(std::ostream& os, std::string what, int offset, int nextOffset);
716 :
717 : /// @brief Whether the descriptino has already been translated to the locale language
718 : bool myAmLocalized = false;
719 :
720 : /// @brief The static options container used
721 : static OptionsCont myOptions;
722 :
723 : /// @brief option-addresses
724 : std::vector<std::pair<std::string, Option*> > myAddresses;
725 :
726 : /// @brief option maps sorted by name (for addresses AND their synonyms)
727 : std::map<std::string, Option*> myValues;
728 :
729 : /// @brief some information on the application
730 : std::string myAppName, myFullName, myAppDescription, myAdditionalMessage;
731 :
732 : /// @brief list of call examples
733 : std::vector< std::pair<std::string, std::string> > myCallExamples;
734 :
735 : /// @brief lists of option subtopics and copyright notices
736 : std::vector<std::string> mySubTopics, myCopyrightNotices;
737 :
738 : /// @brief A map from subtopic to option
739 : std::map<std::string, std::vector<std::string> > mySubTopicEntries;
740 :
741 : /// @brief A map from XML root element to option
742 : std::map<std::string, std::string> myXMLDefaults;
743 :
744 : /// @brief A map from deprecated options to a bool indicating whether we warned about deprecation
745 : mutable std::map<std::string, bool> myDeprecatedSynonymes;
746 :
747 : /// @brief default copy constructor, but private
748 1204 : OptionsCont(const OptionsCont& s) = default;
749 :
750 : /// @brief invalid assignment operator
751 : OptionsCont& operator=(const OptionsCont& s) = delete;
752 : };
|
