senf/Utils/Console/Traits.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2008
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   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.
  12 //
  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.
  17 //
  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.
  22
  23 /** \file
  24     \brief Traits public header */
  25
  26 #ifndef HH_SENF_Scheduler_Console_Traits_
  27 #define HH_SENF_Scheduler_Console_Traits_ 1
  28
  29 // Custom includes
  30 #include <iostream>
  31 #include <boost/intrusive_ptr.hpp>
  32 #include <boost/type_traits/is_same.hpp>
  33 #include <senf/Utils/intrusive_refcount.hh>
  34 #include "Parse.hh"
  35
  36 #include "Traits.ih"
  37 //#include "Traits.mpp"
  38 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  39
  40 namespace senf {
  41 namespace console {
  42
  43     /** \brief Customize argument parsing
  44
  45         ArgumentTraits provides argument parsing, Additionally, this class provides a way to get a
  46         string-description of a type and to convert a value back into it's string representation
  47         used to display default values.
  48
  49         The default implementation provided here
  50         \li will use senf_console_parse_argument() to parse a value. This functions default
  51             implementation uses \c boost::lexical_cast and thereby \c iostreams to convert an
  52             argument consisting of a single input token into the required type.
  53         \li will name types by returning the last component of the fully scoped name (e.g. \c
  54             "string" for \c std::string).
  55         \li Will format values (for default value display) by forwarding the value to the
  56             ReturnValueTraits of that type.
  57
  58         To customize just the argument parsing, just provide an implementation of
  59         senf_console_parse_argument(). Alternatively or to customize type naming or default value
  60         formatting, specialize ArgumentTraits  for the type.
  61      */
  62     template <class Type>
  63     struct ArgumentTraits
  64     {
  65         typedef Type type;
  66
  67         static bool const singleToken =
  68             boost::is_same< typeof(senf_console_parse_argument(
  69                                        *static_cast<ParseCommandInfo::TokensRange const *>(0),
  70                                        *static_cast<Type*>(0))),
  71                             bool >::value;
  72
  73         static void parse(ParseCommandInfo::TokensRange const & tokens, Type & out);
  74                                         ///< Parse token range into value
  75                                         /**< This function needs to parse \a tokens and write the
  76                                              parsed value into \a out. This function needs to parse
  77                                              the \e complete list of tokens, additional tokens must
  78                                              be considered as syntax error.
  79                                              \throws SyntaxErrorException
  80                                              \param[in] tokens tokens to parse
  81                                              \param[out] out parsed value */
  82
  83         static std::string description(); ///< String description of type
  84                                         /**< Returns the string description of \a Type. Used to
  85                                              generate online help. */
  86         static std::string str(Type const & value); ///< Stringify value
  87                                         /**< To show default values in the online help, this
  88                                              function converts a value back into a one-line string
  89                                              representation. The default implementation uses the
  90                                              ReturnValueTraits for this conversion. */
  91     };
  92
  93     /** \brief Argument parser
  94
  95         \see ArgumentTraits
  96
  97         \related ArgumentTraits
  98      */
  99     template <class Type>
 100     bool senf_console_parse_argument(ParseCommandInfo::TokensRange const & tokens, Type & out);
 101
 102
 103     /** \brief Customize return value formating
 104
 105         ReturnValueTraits provides return value formatting. The default implementation provided here
 106         will forward the call directly to senf_console_format_value(). The default implementation of
 107         that function will write the \a value to \a os using standard iostream formatting.
 108
 109         To customize this behavior for some type, either provide an implementation of
 110         senf_console_format_value() in the types namespace or provide a specialization of
 111         ReturnValueTraits.
 112
 113         The output should \e not end in a newline since one is added automatically.
 114      */
 115     template <class Type>
 116     struct ReturnValueTraits
 117     {
 118         typedef Type type;
 119
 120         static void format(Type const & value, std::ostream & os);
 121                                         ///< Write \a value to \a os
 122     };
 123
 124     /** \brief Return value formatter
 125
 126         \see ReturnValuetraits
 127
 128         \related ReturnValueTraits
 129      */
 130     template <class Type>
 131     void senf_console_format_value(Type const & value, std::ostream & os);
 132
 133
 134     /** \brief Parse token range
 135
 136         This helper will invoke the correct ArgumentTraits::parse function to parse the input tokens
 137         into the passed in variable.
 138
 139         \see ArgumentTraits
 140      */
 141     template <class Type>
 142     void parse(ParseCommandInfo::TokensRange const & tokens, Type & out);
 143
 144     /** \brief Format value
 145
 146         This helper will call the correct ArgumentTraits::str function to format \a value
 147
 148         \see ArgumentTraits
 149      */
 150     template <class Type>
 151     std::string str(Type const & value);
 152
 153     /** \brief Format return value
 154
 155         This helper will invoke the correct ReturnValueTraits::format function to write \a value
 156         into the \a out stream.
 157
 158         \see ReturnValueTraits
 159      */
 160     template <class Type>
 161     void format(Type const & value, std::ostream & os);
 162
 163
 164     /** \brief Register enum type for argument parsing
 165
 166         Enum types need to be registered explicitly to support parsing.
 167         \code
 168         enum Foo { Foo1, Foo2 };
 169         SENF_CONSOLE_REGISTER_ENUM( Foo, (Foo1)(Foo2) );
 170         \endcode
 171         This macro will register an enum type and it's enumerators defined at namespace scope. See
 172         \ref SENF_CONSOLE_REGISTER_ENUM_MEMBER to register a member enum type.
 173
 174         By default, the keys used to represent the enumerator values in the console are identical to
 175         the enumerator names in C++ (In the example above \c Foo1 and \c Foo2). You may however
 176         override this default key using the
 177         '<tt>key(&quot;</tt><i>key</i><tt>&quot;, </tt><i>enumerator</i><tt>)</tt>' modifier:
 178         \code
 179         enum Foo { Foo1, Foo2 };
 180         SENF_CONSOLE_REGISTER_ENUM( Foo, (key("1", Foo1), Foo2) );
 181         \endcode
 182         This will register the first enumerator \c Foo1 under the name '\c 1'.
 183
 184         \note All enumerator keys must be unique ignoring case.
 185
 186         The enum parser will accept any unique initial substring ignoring case as valid enum value.
 187
 188         \ingroup console_commands
 189      */
 190 #   define SENF_CONSOLE_REGISTER_ENUM(Type, Values) \
 191         SENF_CONSOLE_REGISTER_ENUM_(BOOST_PP_EMPTY(), Type, Values)
 192
 193     /** \brief Register enum type for argument parsing
 194
 195         Enum types need to be registered explicitly to support parsing.
 196         \code
 197         class SomeClass
 198         {
 199             enum Foo { Foo1, Foo2 };
 200         };
 201
 202         SENF_CONSOLE_REGISTER_ENUM_MEMBER( SomeClass, Foo, (Foo1)(Foo2) );
 203         \endcode This macro will register an enum type and it's enumerators defined in a class. See
 204         \ref SENF_CONSOLE_REGISTER_ENUM to register an enum type declared at namespace scope.
 205
 206         \ingroup console_commands
 207      */
 208 #   define SENF_CONSOLE_REGISTER_ENUM_MEMBER(Class, Type, Values) \
 209         SENF_CONSOLE_REGISTER_ENUM_(Class::, Type, Values)
 210
 211
 212     /** \brief Format boolean value as \c true / \c false */
 213     void formatTrueFalse(bool value, std::ostream & os);
 214
 215     /** \brief Format boolean value as \c yes / \c no */
 216     void formatYesNo(bool value, std::ostream & os);
 217
 218     /** \brief Format boolean value as \c enabled / \c disabled */
 219     void formatEnabledDisabled(bool value, std::ostream & os);
 220
 221     /** \brief Format boolean value as \c on / \c off */
 222     void formatOnOff(bool value, std::ostream & os);
 223
 224     /** \brief Format boolean value as \c 1 / \c 0 */
 225     void formatOneZero(bool value, std::ostream & os);
 226
 227
 228 #ifndef DOXYGEN
 229
 230     // Parse bool: true/false, yes/no, enabled/disabled, 0/1
 231     template <>
 232     struct ArgumentTraits<bool>
 233     {
 234         typedef bool type;
 235         static bool const singleToken = true;
 236
 237         static void parse(ParseCommandInfo::TokensRange const & tokens, bool & out);
 238         static std::string description();
 239         static std::string str(bool value);
 240     };
 241
 242     template <>
 243     struct ReturnValueTraits<bool>
 244     {
 245         typedef bool type;
 246
 247         static void format(bool value, std::ostream & os);
 248     };
 249
 250     template <> struct ArgumentTraits<char> : public detail::CharArgumentTraits<char> {};
 251     template <> struct ReturnValueTraits<char> : public detail::CharReturnValueTraits<char> {};
 252     template <> struct ArgumentTraits<signed char> : public detail::CharArgumentTraits<signed char> {};
 253     template <> struct ReturnValueTraits<signed char> : public detail::CharReturnValueTraits<signed char> {};
 254     template <> struct ArgumentTraits<unsigned char> : public detail::CharArgumentTraits<unsigned char> {};
 255     template <> struct ReturnValueTraits<unsigned char> : public detail::CharReturnValueTraits<unsigned char> {};
 256
 257 #endif
 258
 259 }}
 260
 261 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 262 #include "Traits.cci"
 263 #include "Traits.ct"
 264 #include "Traits.cti"
 265 #endif
 266
 267 \f
 268 // Local Variables:
 269 // mode: c++
 270 // fill-column: 100
 271 // comment-column: 40
 272 // c-file-style: "senf"
 273 // indent-tabs-mode: nil
 274 // ispell-local-dictionary: "american"
 275 // compile-command: "scons -u test"
 276 // End: