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