MongoDB  2.7.0
option_description.h
1 /* Copyright 2013 10gen Inc.
2  *
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #pragma once
17 
18 #include <boost/shared_ptr.hpp>
19 #include <iostream>
20 
21 #include "mongo/base/status.h"
22 #include "mongo/util/options_parser/constraints.h"
23 #include "mongo/util/options_parser/value.h"
24 
25 namespace mongo {
26 namespace optionenvironment {
27 
31  enum OptionType {
32  StringVector, // po::value< std::vector<std::string> >
33  StringMap, // po::value< std::vector<std::string> > (but in "key=value" format)
34  Bool, // po::value<bool>
35  Double, // po::value<double>
36  Int, // po::value<int>
37  Long, // po::value<long>
38  String, // po::value<std::string>
39  UnsignedLongLong, // po::value<unsigned long long>
40  Unsigned, // po::value<unsigned>
41  Switch // po::bool_switch
42  };
43 
47  enum OptionSources {
48  SourceCommandLine = 1,
49  SourceINIConfig = 2,
50  SourceYAMLConfig = 4,
51  SourceAllConfig = SourceINIConfig | SourceYAMLConfig,
52  SourceAllLegacy = SourceINIConfig | SourceCommandLine,
53  SourceAll = SourceCommandLine | SourceINIConfig | SourceYAMLConfig
54  };
55 
62  public:
63  OptionDescription(const std::string& dottedName,
64  const std::string& singleName,
65  const OptionType type,
66  const std::string& description)
67  : _dottedName(dottedName),
68  _singleName(singleName),
69  _type(type),
70  _description(description),
71  _isVisible(true),
72  _default(Value()),
73  _implicit(Value()),
74  _isComposing(false),
75  _sources(SourceAll),
76  _positionalStart(-1),
77  _positionalEnd(-1) { }
78 
79  /*
80  * The following functions are part of the chaining interface for option registration. See
81  * comments below for what each of these attributes mean, and the OptionSection class for
82  * more details on the chaining interface.
83  */
84 
92  /*
93  * Make this option hidden so it does not appear in command line help
94  */
96 
97  /*
98  * Add a default value for this option if it is not specified
99  *
100  * throws DBException on errors, such as trying to set a default that does not have the same
101  * type as the option, or trying to set a default for a composing option.
102  */
103  OptionDescription& setDefault(Value defaultValue);
104 
105  /*
106  * Add an implicit value for this option if it is specified with no argument
107  *
108  * throws DBException on errors, such as trying to set an implicit value that does not have
109  * the same type as the option, or trying to set an implicit value for a composing option.
110  */
111  OptionDescription& setImplicit(Value implicitValue);
112 
113  /*
114  * Make this option composing so that the different sources add their values instead of
115  * overriding (eg. setParameter values in the config file and on the command line all get
116  * aggregated together)
117  *
118  * throws DBException on errors, such as trying to make an option that is not a vector type
119  * composing, or or trying to set an implicit or default value for a composing option.
120  */
121  OptionDescription& composing();
122 
123  /*
124  * Specify the allowed sources for this option, such as CommandLine, JSONConfig, or
125  * INIConfig. The default is SourceAll which means the option can be present in any source
126  */
127  OptionDescription& setSources(OptionSources sources);
128 
129  /*
130  * Specify that this is a positional option. "start" should be the first position the
131  * option can be found in, and "end" is the last position, inclusive. The positions start
132  * at index 1 (after the executable name). If "start" is greater than "end", then the
133  * option must be able to support multiple values. Specifying -1 for the "end" means that
134  * the option can repeat forever. Any "holes" in the positional ranges will result in an
135  * error during parsing.
136  *
137  * Examples:
138  *
139  * .positional(1,1) // Single positional argument at position 1
140  * ...
141  * .positional(2,3) // More positional arguments at position 2 and 3 (multivalued option)
142  * ...
143  * .positional(4,-1) // Can repeat this positional option forever after position 4
144  *
145  *
146  * (sverch) TODO: When we can support it (i.e. when we can get rid of boost) add a
147  * "positionalOnly" attribute that specifies that it is not also a command line flag. In
148  * boost program options, the only way to have a positional argument is to register a flag
149  * and mark it as also being positional.
150  */
151  OptionDescription& positional(int start, int end);
152 
164  OptionDescription& validRange(long min, long max);
165 
172  OptionDescription& incompatibleWith(const std::string& otherDottedName);
173 
179  OptionDescription& requires(const std::string& otherDottedName);
180 
186  OptionDescription& format(const std::string& regexFormat, const std::string& displayFormat);
187 
196 
197  std::string _dottedName; // Used for JSON config and in Environment
198  std::string _singleName; // Used for boost command line and INI
199  OptionType _type; // Storage type of the argument value, or switch type (bool)
200  // (required by boost)
201  std::string _description; // Description of option printed in help output
202  bool _isVisible; // Visible in help output
203  Value _default; // Value if option is not specified
204  Value _implicit; // Value if option is specified with no argument
205  bool _isComposing; // Aggregate values from different sources instead of overriding
206  OptionSources _sources; // Places where an option can be specified (current sources are
207  // command line, json config, and ini config)
208  int _positionalStart; // The starting position if this is a positional option. -1 otherwise.
209  int _positionalEnd; // The ending position if this is a positional option. -1 if unlimited.
210 
211  // TODO(sverch): We have to use pointers to keep track of the Constrants because we rely on
212  // inheritance to make Constraints work. We have to use shared_ptrs because the
213  // OptionDescription is sometimes copied and because it is stored in a std::list in the
214  // OptionSection. We should think about a better solution for the ownership semantics of
215  // these classes. Note that the Environment (the storage for results of option parsing) has
216  // to know about the constraints for all the options, which is another factor to consider
217  // when thinking about ownership.
218  std::vector<boost::shared_ptr<Constraint> > _constraints; // Constraints that must be met
219  // for this option to be valid
220  };
221 
222 } // namespace optionenvironment
223 } // namespace mongo
A Constraint validates an Environment.
Definition: constraints.h:32
OptionDescription & hidden()
Parsing Attributes.
Definition: option_description.cpp:84
boolean type
Definition: bsontypes.h:63
A simple container interface for storing various C++ values.
Definition: options_parser/value.h:54
OptionDescription & addConstraint(Constraint *c)
Adds a constraint for this option.
Definition: option_description.cpp:199
OptionDescription & format(const std::string &regexFormat, const std::string &displayFormat)
Specifies that this option is required to match the given format, specified as a regular expression...
Definition: option_description.cpp:228
The OptionDescription class is a container for information about the options we are expecting either ...
Definition: option_description.h:61
OptionDescription & requires(const std::string &otherDottedName)
Specifies that this option is requires another option to be specified.
Definition: option_description.cpp:224
OptionDescription & validRange(long min, long max)
Validation Constraints.
Definition: option_description.cpp:204
OptionDescription & incompatibleWith(const std::string &otherDottedName)
Specifies that this option is incompatible with another option.
Definition: option_description.cpp:220
character string, stored in utf8
Definition: bsontypes.h:51