1 // Copyright Vladimir Prus 2004.
2 // Distributed under the Boost Software License, Version 1.0.
3 // (See accompanying file LICENSE_1_0.txt
4 // or copy at http://www.boost.org/LICENSE_1_0.txt)
6 #ifndef BOOST_VALUE_SEMANTIC_HPP_VP_2004_02_24
7 #define BOOST_VALUE_SEMANTIC_HPP_VP_2004_02_24
9 #include <boost/program_options/config.hpp>
10 #include <boost/program_options/errors.hpp>
12 #include <boost/any.hpp>
13 #include <boost/function/function1.hpp>
14 #include <boost/lexical_cast.hpp>
21 namespace boost { namespace program_options {
23 /** Class which specifies how the option's value is to be parsed
24 and converted into C++ types.
26 class BOOST_PROGRAM_OPTIONS_DECL value_semantic {
28 /** Returns the name of the option. The name is only meaningful
29 for automatic help message.
31 virtual std::string name() const = 0;
33 /** The minimum number of tokens for this option that
34 should be present on the command line. */
35 virtual unsigned min_tokens() const = 0;
37 /** The maximum number of tokens for this option that
38 should be present on the command line. */
39 virtual unsigned max_tokens() const = 0;
41 /** Returns true if the option should only take adjacent token,
42 not one from further command-line arguments.
44 virtual bool adjacent_tokens_only() const = 0;
46 /** Returns true if values from different sources should be composed.
47 Otherwise, value from the first source is used and values from
48 other sources are discarded.
50 virtual bool is_composing() const = 0;
52 /** Returns true if value must be given. Non-optional value
55 virtual bool is_required() const = 0;
57 /** Parses a group of tokens that specify a value of option.
58 Stores the result in 'value_store', using whatever representation
59 is desired. May be be called several times if value of the same
60 option is specified more than once.
62 virtual void parse(boost::any& value_store,
63 const std::vector<std::string>& new_tokens,
67 /** Called to assign default value to 'value_store'. Returns
68 true if default value is assigned, and false if no default
70 virtual bool apply_default(boost::any& value_store) const = 0;
72 /** Called when final value of an option is determined.
74 virtual void notify(const boost::any& value_store) const = 0;
76 virtual ~value_semantic() {}
79 /** Helper class which perform necessary character conversions in the
80 'parse' method and forwards the data further.
83 class value_semantic_codecvt_helper {
84 // Nothing here. Specializations to follow.
87 /** Helper conversion class for values that accept ascii
89 Overrides the 'parse' method and defines new 'xparse'
90 method taking std::string. Depending on whether input
91 to parse is ascii or UTF8, will pass it to xparse unmodified,
92 or with UTF8->ascii conversion.
95 class BOOST_PROGRAM_OPTIONS_DECL
96 value_semantic_codecvt_helper<char> : public value_semantic {
97 private: // base overrides
98 void parse(boost::any& value_store,
99 const std::vector<std::string>& new_tokens,
101 protected: // interface for derived classes.
102 virtual void xparse(boost::any& value_store,
103 const std::vector<std::string>& new_tokens)
107 /** Helper conversion class for values that accept ascii
109 Overrides the 'parse' method and defines new 'xparse'
110 method taking std::wstring. Depending on whether input
111 to parse is ascii or UTF8, will recode input to Unicode, or
115 class BOOST_PROGRAM_OPTIONS_DECL
116 value_semantic_codecvt_helper<wchar_t> : public value_semantic {
117 private: // base overrides
118 void parse(boost::any& value_store,
119 const std::vector<std::string>& new_tokens,
121 protected: // interface for derived classes.
122 #if !defined(BOOST_NO_STD_WSTRING)
123 virtual void xparse(boost::any& value_store,
124 const std::vector<std::wstring>& new_tokens)
129 /** Class which specifies a simple handling of a value: the value will
130 have string type and only one token is allowed. */
131 class BOOST_PROGRAM_OPTIONS_DECL
132 untyped_value : public value_semantic_codecvt_helper<char> {
134 untyped_value(bool zero_tokens = false)
135 : m_zero_tokens(zero_tokens)
138 std::string name() const;
140 unsigned min_tokens() const;
141 unsigned max_tokens() const;
142 bool adjacent_tokens_only() const { return false; }
144 bool is_composing() const { return false; }
146 bool is_required() const { return false; }
148 /** If 'value_store' is already initialized, or new_tokens
149 has more than one elements, throws. Otherwise, assigns
150 the first string from 'new_tokens' to 'value_store', without
153 void xparse(boost::any& value_store,
154 const std::vector<std::string>& new_tokens) const;
157 bool apply_default(boost::any&) const { return false; }
160 void notify(const boost::any&) const {}
165 #ifndef BOOST_NO_RTTI
166 /** Base class for all option that have a fixed type, and are
167 willing to announce this type to the outside world.
168 Any 'value_semantics' for which you want to find out the
169 type can be dynamic_cast-ed to typed_value_base. If conversion
170 succeeds, the 'type' method can be called.
172 class typed_value_base
175 // Returns the type of the value described by this
177 virtual const std::type_info& value_type() const = 0;
178 // Not really needed, since deletion from this
179 // class is silly, but just in case.
180 virtual ~typed_value_base() {}
185 /** Class which handles value of a specific type. */
186 template<class T, class charT = char>
187 class typed_value : public value_semantic_codecvt_helper<charT>
188 #ifndef BOOST_NO_RTTI
189 , public typed_value_base
193 /** Ctor. The 'store_to' parameter tells where to store
194 the value when it's known. The parameter can be NULL. */
195 typed_value(T* store_to)
196 : m_store_to(store_to), m_composing(false),
197 m_implicit(false), m_multitoken(false),
198 m_zero_tokens(false), m_required(false)
201 /** Specifies default value, which will be used
202 if none is explicitly specified. The type 'T' should
203 provide operator<< for ostream.
205 typed_value* default_value(const T& v)
207 m_default_value = boost::any(v);
208 m_default_value_as_text = boost::lexical_cast<std::string>(v);
212 /** Specifies default value, which will be used
213 if none is explicitly specified. Unlike the above overload,
214 the type 'T' need not provide operator<< for ostream,
215 but textual representation of default value must be provided
218 typed_value* default_value(const T& v, const std::string& textual)
220 m_default_value = boost::any(v);
221 m_default_value_as_text = textual;
225 /** Specifies an implicit value, which will be used
226 if the option is given, but without an adjacent value.
227 Using this implies that an explicit value is optional, but if
228 given, must be strictly adjacent to the option, i.e.: '-ovalue'
229 or '--option=value'. Giving '-o' or '--option' will cause the
230 implicit value to be applied.
232 typed_value* implicit_value(const T &v)
234 m_implicit_value = boost::any(v);
235 m_implicit_value_as_text =
236 boost::lexical_cast<std::string>(v);
240 /** Specifies the name used to to the value in help message. */
241 typed_value* value_name(const std::string& name)
247 /** Specifies an implicit value, which will be used
248 if the option is given, but without an adjacent value.
249 Using this implies that an explicit value is optional, but if
250 given, must be strictly adjacent to the option, i.e.: '-ovalue'
251 or '--option=value'. Giving '-o' or '--option' will cause the
252 implicit value to be applied.
253 Unlike the above overload, the type 'T' need not provide
254 operator<< for ostream, but textual representation of default
255 value must be provided by the user.
257 typed_value* implicit_value(const T &v, const std::string& textual)
259 m_implicit_value = boost::any(v);
260 m_implicit_value_as_text = textual;
264 /** Specifies a function to be called when the final value
266 typed_value* notifier(function1<void, const T&> f)
272 /** Specifies that the value is composing. See the 'is_composing'
273 method for explanation.
275 typed_value* composing()
281 /** Specifies that the value can span multiple tokens.
283 typed_value* multitoken()
289 /** Specifies that no tokens may be provided as the value of
290 this option, which means that only presense of the option
291 is significant. For such option to be useful, either the
292 'validate' function should be specialized, or the
293 'implicit_value' method should be also used. In most
294 cases, you can use the 'bool_switch' function instead of
295 using this method. */
296 typed_value* zero_tokens()
298 m_zero_tokens = true;
302 /** Specifies that the value must occur. */
303 typed_value* required()
309 public: // value semantic overrides
311 std::string name() const;
313 bool is_composing() const { return m_composing; }
315 unsigned min_tokens() const
317 if (m_zero_tokens || !m_implicit_value.empty()) {
324 unsigned max_tokens() const {
326 return std::numeric_limits<unsigned>::max BOOST_PREVENT_MACRO_SUBSTITUTION();
327 } else if (m_zero_tokens) {
334 bool adjacent_tokens_only() const { return !m_implicit_value.empty(); }
336 bool is_required() const { return m_required; }
338 /** Creates an instance of the 'validator' class and calls
339 its operator() to perform the actual conversion. */
340 void xparse(boost::any& value_store,
341 const std::vector< std::basic_string<charT> >& new_tokens)
344 /** If default value was specified via previous call to
345 'default_value', stores that value into 'value_store'.
346 Returns true if default value was stored.
348 virtual bool apply_default(boost::any& value_store) const
350 if (m_default_value.empty()) {
353 value_store = m_default_value;
358 /** If an address of variable to store value was specified
359 when creating *this, stores the value there. Otherwise,
361 void notify(const boost::any& value_store) const;
363 public: // typed_value_base overrides
365 #ifndef BOOST_NO_RTTI
366 const std::type_info& value_type() const
376 // Default value is stored as boost::any and not
377 // as boost::optional to avoid unnecessary instantiations.
378 std::string m_value_name;
379 boost::any m_default_value;
380 std::string m_default_value_as_text;
381 boost::any m_implicit_value;
382 std::string m_implicit_value_as_text;
383 bool m_composing, m_implicit, m_multitoken, m_zero_tokens, m_required;
384 boost::function1<void, const T&> m_notifier;
388 /** Creates a typed_value<T> instance. This function is the primary
389 method to create value_semantic instance for a specific type, which
390 can later be passed to 'option_description' constructor.
391 The second overload is used when it's additionally desired to store the
392 value of option into program variable.
404 /** Creates a typed_value<T> instance. This function is the primary
405 method to create value_semantic instance for a specific type, which
406 can later be passed to 'option_description' constructor.
409 typed_value<T, wchar_t>*
415 typed_value<T, wchar_t>*
418 /** Works the same way as the 'value<bool>' function, but the created
419 value_semantic won't accept any explicit value. So, if the option
420 is present on the command line, the value will be 'true'.
422 BOOST_PROGRAM_OPTIONS_DECL typed_value<bool>*
427 BOOST_PROGRAM_OPTIONS_DECL typed_value<bool>*
428 bool_switch(bool* v);
432 #include "boost/program_options/detail/value_semantic.hpp"