4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
8 // This program is free software; you can redistribute it and/or modify
9 // it under the terms of the GNU General Public License as published by
10 // the Free Software Foundation; either version 2 of the License, or
11 // (at your option) any later version.
13 // This program is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License
19 // along with this program; if not, write to the
20 // Free Software Foundation, Inc.,
21 // 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24 \brief Traits public header */
26 #ifndef HH_SENF_Scheduler_Console_Traits_
27 #define HH_SENF_Scheduler_Console_Traits_ 1
31 #include <boost/intrusive_ptr.hpp>
32 #include <boost/type_traits/is_same.hpp>
33 #include <senf/Utils/intrusive_refcount.hh>
38 //#include "Traits.mpp"
39 ///////////////////////////////hh.p////////////////////////////////////////
44 /** \brief Customize return value formating
46 ReturnValueTraits provides return value formatting. The default implementation provided here
47 will forward the call directly to senf_console_format_value(). The default implementation of
48 that function will write the \a value to \a os using standard iostream formatting.
50 To customize this behavior for some type, either provide an implementation of
51 senf_console_format_value() in the types namespace or provide a specialization of
54 The output should \e not end in a newline since one is added automatically.
57 struct ReturnValueTraits
61 static void format(Type const & value, std::ostream & os);
62 ///< Write \a value to \a os
65 /** \brief Return value formatter
67 \see ReturnValuetraits
69 \related ReturnValueTraits
72 void senf_console_format_value(Type const & value, std::ostream & os);
74 /** \brief Customize argument parsing
76 ArgumentTraits provides argument parsing, Additionally, this class provides a way to get a
77 string-description of a type and to convert a value back into it's string representation
78 used to display default values.
80 The default implementation provided here
81 \li will use senf_console_parse_argument() to parse a value. This functions default
82 implementation uses \c boost::lexical_cast and thereby \c iostreams to convert an
83 argument consisting of a single input token into the required type.
84 \li will name types by returning the last component of the fully scoped name (e.g. \c
85 "string" for \c std::string).
86 \li Will format values (for default value display) by forwarding the value to the
87 ReturnValueTraits of that type.
89 To customize just the argument parsing, just provide an implementation of
90 senf_console_parse_argument(). Alternatively or to customize type naming or default value
91 formatting, specialize ArgumentTraits for the type.
98 static bool const singleToken =
99 boost::is_same< typeof(senf_console_parse_argument(
100 *static_cast<ParseCommandInfo::TokensRange const *>(0),
101 *static_cast<Type*>(0))),
104 static void parse(ParseCommandInfo::TokensRange const & tokens, Type & out);
105 ///< Parse token range into value
106 /**< This function needs to parse \a tokens and write the
107 parsed value into \a out. This function needs to parse
108 the \e complete list of tokens, additional tokens must
109 be considered as syntax error.
110 \throws SyntaxErrorException
111 \param[in] tokens tokens to parse
112 \param[out] out parsed value */
114 static std::string description(); ///< String description of type
115 /**< Returns the string description of \a Type. Used to
116 generate online help. */
117 static std::string str(Type const & value); ///< Stringify value
118 /**< To show default values in the online help, this
119 function converts a value back into a one-line string
120 representation. The default implementation uses the
121 ReturnValueTraits for this conversion. */
124 /** \brief Argument parser
128 \related ArgumentTraits
130 template <class Type>
131 bool senf_console_parse_argument(ParseCommandInfo::TokensRange const & tokens, Type & out);
133 /** \brief Parse token range
135 This helper will invoke the correct ArgumentTraits::parse function to parse the input tokens
136 into the passed in variable.
140 template <class Type>
141 void parse(ParseCommandInfo::TokensRange const & tokens, Type & out);
143 /** \brief Format value
145 This helper will call the correct ArgumentTraits::str function to format \a value
149 template <class Type>
150 std::string str(Type const & value);
152 /** \brief Format return value
154 This helper will invoke the correct ReturnValueTraits::format function to write \a value
155 into the \a out stream.
157 \see ReturnValueTraits
159 template <class Type>
160 void format(Type const & value, std::ostream & os);
164 // Parse bool: true/false, yes/no, enabled/disabled, 0/1
166 struct ArgumentTraits<bool>
169 static bool const singleToken = true;
171 static void parse(ParseCommandInfo::TokensRange const & tokens, bool & out);
172 static std::string description();
173 static std::string str(bool value);
177 struct ReturnValueTraits<bool>
181 static void format(bool value, std::ostream & os);
185 struct ArgumentTraits<std::string>
187 typedef std::string type;
188 static bool const singleToken = true;
190 static void parse(ParseCommandInfo::TokensRange const & tokens, std::string & out);
191 static std::string description();
192 static std::string str(std::string const & value);
197 /** \brief Format boolean value as \c true / \c false */
198 void formatTrueFalse(bool value, std::ostream & os);
200 /** \brief Format boolean value as \c yes / \c no */
201 void formatYesNo(bool value, std::ostream & os);
203 /** \brief Format boolean value as \c enabled / \c disabled */
204 void formatEnabledDisabled(bool value, std::ostream & os);
206 /** \brief Format boolean value as \c on / \c off */
207 void formatOnOff(bool value, std::ostream & os);
209 /** \brief Format boolean value as \c 1 / \c 0 */
210 void formatOneZero(bool value, std::ostream & os);
212 /** \brief Register enum type for argument parsing
214 Enum types need to be registered explicitly to support parsing.
216 enum Foo { Foo1, Foo2 };
217 SENF_CONSOLE_REGISTER_ENUM( Foo, (Foo1)(Foo2) );
219 This macro will register an enum type and it's enumerators defined at namespace scope. See
220 \ref SENF_CONSOLE_REGISTER_ENUM_MEMBER to register a member enum type.
222 \note All enumerator values must be unique ignoring case.
224 The enum parser will accept any unique initial substring ignoring case as valid enum value.
226 \ingroup console_commands
228 # define SENF_CONSOLE_REGISTER_ENUM(Type, Values) \
229 SENF_CONSOLE_REGISTER_ENUM_(BOOST_PP_EMPTY(), Type, Values)
231 /** \brief Register enum type for argument parsing
233 Enum types need to be registered explicitly to support parsing.
237 enum Foo { Foo1, Foo2 };
240 SENF_CONSOLE_REGISTER_ENUM_MEMBER( SomeClass, Foo, (Foo1)(Foo2) );
241 \endcode This macro will register an enum type and it's enumerators defined in a class. See
242 \ref SENF_CONSOLE_REGISTER_ENUM to register an enum type declared at namespace scope.
244 \ingroup console_commands
246 # define SENF_CONSOLE_REGISTER_ENUM_MEMBER(Class, Type, Values) \
247 SENF_CONSOLE_REGISTER_ENUM_(Class::, Type, Values)
249 /** \brief Bit-mask flag argument type
251 senf::console::FlagCollection supplies a special argument type for use in registering
252 console commands. This argument type is used to represent a bit-mask of single flags.
255 // Function taking a flags argument
256 void func(unsigned flags);
258 // Enum containing all the possible flag values
259 enum MyFlags { Foo = 1,
263 SENF_CONSOLE_REGISTER_ENUM(MyFlags, (Foo)(Bar)(Baz)(Boo));
265 // Register the function with a FlagCollection argument type
266 consoleDir.add("func", boost::function<void (FlagCollection<MyFlags>)>(&func));
269 To use the FlagCollection class
270 \li you need a function which takes a bit-mask of flags as argument
271 \li you define and register an enum with all possible flag values
272 \li you register the function with a FlagCollection argument type using \c boost::function
273 for the conversion. This is also possible for return values.
275 The nice thing is, that \c boot::function supports compatible argument types and does
276 automatic type conversion. Since a FlagCollection is convertible to and from unsigned long,
277 this conversion will work.
279 After registering this function, you can call it with a collection of flags as argument
286 console:/$ func (Foo Boo)
289 template <class Enum>
290 struct FlagCollection
292 operator unsigned long() const { return value; }
293 FlagCollection() : value (0) {}
294 FlagCollection(unsigned long value_) : value (value_) {}
295 FlagCollection(Enum value_) : value (value_) {}
299 template <class Enum>
300 struct ArgumentTraits< FlagCollection<Enum> >
302 typedef FlagCollection<Enum> type;
303 static bool const singleToken = false;
304 static void parse(ParseCommandInfo::TokensRange const & tokens, type & out);
305 static std::string description();
306 static std::string str(type const & value);
309 template <class Enum>
310 struct ReturnValueTraits< FlagCollection<Enum> >
312 typedef FlagCollection<Enum> type;
313 static void format(type const & value, std::ostream & os);
318 ///////////////////////////////hh.e////////////////////////////////////////
319 #include "Traits.cci"
321 #include "Traits.cti"
328 // comment-column: 40
329 // c-file-style: "senf"
330 // indent-tabs-mode: nil
331 // ispell-local-dictionary: "american"
332 // compile-command: "scons -u test"