Scheduler/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 #ifndef DOXYGEN
 137
 138     // Parse bool: true/false, yes/no, enabled/disabled, 0/1
 139     template <>
 140     struct ArgumentTraits<bool>
 141     {
 142         typedef bool type;
 143
 144         static void parse(ParseCommandInfo::TokensRange const & tokens, bool & out);
 145         static std::string description();
 146         static std::string str(bool value);
 147     };
 148
 149     template <>
 150     struct ReturnValueTraits<bool>
 151     {
 152         typedef bool type;
 153
 154         static void format(bool value, std::ostream & os);
 155     };
 156
 157 #endif
 158
 159     /** \brief Format boolean value as \c true / \c false */
 160     void formatTrueFalse(bool value, std::ostream & os);
 161
 162     /** \brief Format boolean value as \c yes / \c no */
 163     void formatYesNo(bool value, std::ostream & os);
 164
 165     /** \brief Format boolean value as \c enabled / \c disabled */
 166     void formatEnabledDisabled(bool value, std::ostream & os);
 167
 168     /** \brief Format boolean value as \c on / \c off */
 169     void formatOnOff(bool value, std::ostream & os);
 170
 171     /** \brief Format boolean value as \c 1 / \c 0 */
 172     void formatOneZero(bool value, std::ostream & os);
 173
 174     /** \brief Register enum type for argument parsing
 175
 176         Enum types need to be registered explicitly to support parsing.
 177         \code
 178         enum Foo { Foo1, Foo2 };
 179         SENF_CONSOLE_REGISTER_ENUM( Foo, (Foo1)(Foo2) );
 180         \endcode
 181         This macro will register an enum type and it's enumerators defined at namespace scope. See
 182         \ref SENF_CONSOLE_REGISTER_ENUM_MEMBER to register a member enum type.
 183
 184         \ingroup console_commands
 185      */
 186 #   define SENF_CONSOLE_REGISTER_ENUM(Type, Values) \
 187         SENF_CONSOLE_REGISTER_ENUM_(BOOST_PP_EMPTY(), Type, Values)
 188
 189     /** \brief Register enum type for argument parsing
 190
 191         Enum types need to be registered explicitly to support parsing.
 192         \code
 193         class SomeClass
 194         {
 195             enum Foo { Foo1, Foo2 };
 196         };
 197
 198         SENF_CONSOLE_REGISTER_ENUM_MEMBER( SomeClass, Foo, (Foo1)(Foo2) );
 199         \endcode This macro will register an enum type and it's enumerators defined in a class. See
 200         \ref SENF_CONSOLE_REGISTER_ENUM to register an enum type declared at namespace scope.
 201
 202         \ingroup console_commands
 203      */
 204 #   define SENF_CONSOLE_REGISTER_ENUM_MEMBER(Class, Type, Values) \
 205         SENF_CONSOLE_REGISTER_ENUM_(Class::, Type, Values)
 206
 207 }}
 208
 209 ///////////////////////////////hh.e////////////////////////////////////////
 210 #include "Traits.cci"
 211 #include "Traits.ct"
 212 #include "Traits.cti"
 213 #endif
 214
 215 \f
 216 // Local Variables:
 217 // mode: c++
 218 // fill-column: 100
 219 // comment-column: 40
 220 // c-file-style: "senf"
 221 // indent-tabs-mode: nil
 222 // ispell-local-dictionary: "american"
 223 // compile-command: "scons -u test"
 224 // End: