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