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 "../../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 return value formating
  45
  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.
  49
  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
  52         ReturnValueTraits.
  53
  54         The output should \e not end in a newline since one is added automatically.
  55      */
  56     template <class Type>
  57     struct ReturnValueTraits
  58     {
  59         typedef Type type;
  60
  61         static void format(Type const & value, std::ostream & os);
  62                                         ///< Write \a value to \a os
  63     };
  64
  65     /** \brief Return value formatter
  66
  67         \see ReturnValuetraits
  68
  69         \related ReturnValueTraits
  70      */
  71     template <class Type>
  72     void senf_console_format_value(Type const & value, std::ostream & os);
  73
  74     /** \brief Customize argument parsing
  75
  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.
  79
  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.
  88
  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.
  92      */
  93     template <class Type>
  94     struct ArgumentTraits
  95     {
  96         typedef Type type;
  97
  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))),
 102                             bool >::value;
 103
 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 */
 113
 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. */
 122     };
 123
 124     /** \brief Argument parser
 125
 126         \see ArgumentTraits
 127
 128         \related ArgumentTraits
 129      */
 130     template <class Type>
 131     bool senf_console_parse_argument(ParseCommandInfo::TokensRange const & tokens, Type & out);
 132
 133     /** \brief Parse token range
 134
 135         This helper will invoke the correct ArgumentTraits::parse function to parse the input tokens
 136         into the passed in variable.
 137
 138         \see ArgumentTraits
 139      */
 140     template <class Type>
 141     void parse(ParseCommandInfo::TokensRange const & tokens, Type & out);
 142
 143     template <class Type>
 144     void format(Type const & value, std::ostream & os);
 145
 146 #ifndef DOXYGEN
 147
 148     // Parse bool: true/false, yes/no, enabled/disabled, 0/1
 149     template <>
 150     struct ArgumentTraits<bool>
 151     {
 152         typedef bool type;
 153         static bool const singleToken = true;
 154
 155         static void parse(ParseCommandInfo::TokensRange const & tokens, bool & out);
 156         static std::string description();
 157         static std::string str(bool value);
 158     };
 159
 160     template <>
 161     struct ReturnValueTraits<bool>
 162     {
 163         typedef bool type;
 164
 165         static void format(bool value, std::ostream & os);
 166     };
 167
 168 #endif
 169
 170     /** \brief Format boolean value as \c true / \c false */
 171     void formatTrueFalse(bool value, std::ostream & os);
 172
 173     /** \brief Format boolean value as \c yes / \c no */
 174     void formatYesNo(bool value, std::ostream & os);
 175
 176     /** \brief Format boolean value as \c enabled / \c disabled */
 177     void formatEnabledDisabled(bool value, std::ostream & os);
 178
 179     /** \brief Format boolean value as \c on / \c off */
 180     void formatOnOff(bool value, std::ostream & os);
 181
 182     /** \brief Format boolean value as \c 1 / \c 0 */
 183     void formatOneZero(bool value, std::ostream & os);
 184
 185     /** \brief Register enum type for argument parsing
 186
 187         Enum types need to be registered explicitly to support parsing.
 188         \code
 189         enum Foo { Foo1, Foo2 };
 190         SENF_CONSOLE_REGISTER_ENUM( Foo, (Foo1)(Foo2) );
 191         \endcode
 192         This macro will register an enum type and it's enumerators defined at namespace scope. See
 193         \ref SENF_CONSOLE_REGISTER_ENUM_MEMBER to register a member enum type.
 194
 195         \note All enumerator values must be unique ignoring case.
 196
 197         The enum parser will accept any unique initial substring ignoring case as valid enum value.
 198
 199         \ingroup console_commands
 200      */
 201 #   define SENF_CONSOLE_REGISTER_ENUM(Type, Values) \
 202         SENF_CONSOLE_REGISTER_ENUM_(BOOST_PP_EMPTY(), Type, Values)
 203
 204     /** \brief Register enum type for argument parsing
 205
 206         Enum types need to be registered explicitly to support parsing.
 207         \code
 208         class SomeClass
 209         {
 210             enum Foo { Foo1, Foo2 };
 211         };
 212
 213         SENF_CONSOLE_REGISTER_ENUM_MEMBER( SomeClass, Foo, (Foo1)(Foo2) );
 214         \endcode This macro will register an enum type and it's enumerators defined in a class. See
 215         \ref SENF_CONSOLE_REGISTER_ENUM to register an enum type declared at namespace scope.
 216
 217         \ingroup console_commands
 218      */
 219 #   define SENF_CONSOLE_REGISTER_ENUM_MEMBER(Class, Type, Values) \
 220         SENF_CONSOLE_REGISTER_ENUM_(Class::, Type, Values)
 221
 222     /** \brief Bit-mask flag argument type
 223
 224         senf::console::FlagCollection supplies a special argument type for use in registering
 225         console commands. This argument type is used to represent a bit-mask of single flags.
 226
 227         \code
 228         // Function taking a flags argument
 229         void func(unsigned flags);
 230
 231         // Enum containing all the possible flag values
 232         enum MyFlags { Foo = 1,
 233                      Bar = 2,
 234                      Baz = 4,
 235                      Doo = 8 };
 236         SENF_CONSOLE_REGISTER_ENUM(MyFlags, (Foo)(Bar)(Baz)(Boo));
 237
 238         // Register the function with a FlagCollection argument type
 239         consoleDir.add("func", boost::function<void (FlagCollection<MyFlags>)>(&func));
 240         \endcode
 241
 242         To use the FlagCollection class
 243         \li you need a function which takes a bit-mask of flags as argument
 244         \li you define and register an enum with all possible flag values
 245         \li you register the function with a FlagCollection argument type using \c boost::function
 246             for the conversion. This is also possible for return values.
 247
 248         The nice thing is, that \c boot::function supports compatible argument types and does
 249         automatic type conversion. Since a FlagCollection is convertible to and from unsigned long,
 250         this conversion will work.
 251
 252         After registering this function, you can call it with a collection of flags as argument
 253
 254         <pre>
 255         console:/$ help func
 256         Usage:
 257             func arg11:MyFlags
 258         console:/$ func Foo
 259         console:/$ func (Foo Boo)
 260         </pre>
 261      */
 262     template <class Enum>
 263     struct FlagCollection
 264     {
 265         operator unsigned long() const { return value; }
 266         FlagCollection() : value (0) {}
 267         FlagCollection(unsigned long value_) : value (value_) {}
 268         FlagCollection(Enum value_) : value (value_) {}
 269         unsigned long value;
 270     };
 271
 272     template <class Enum>
 273     struct ArgumentTraits< FlagCollection<Enum> >
 274     {
 275         typedef FlagCollection<Enum> type;
 276         static bool const singleToken = false;
 277         static void parse(ParseCommandInfo::TokensRange const & tokens, type & out);
 278         static std::string description();
 279         static std::string str(type const & value);
 280     };
 281
 282     template <class Enum>
 283     struct ReturnValueTraits< FlagCollection<Enum> >
 284     {
 285         typedef FlagCollection<Enum> type;
 286         static void format(type const & value, std::ostream & os);
 287     };
 288
 289 }}
 290
 291 ///////////////////////////////hh.e////////////////////////////////////////
 292 #include "Traits.cci"
 293 #include "Traits.ct"
 294 #include "Traits.cti"
 295 #endif
 296
 297 \f
 298 // Local Variables:
 299 // mode: c++
 300 // fill-column: 100
 301 // comment-column: 40
 302 // c-file-style: "senf"
 303 // indent-tabs-mode: nil
 304 // ispell-local-dictionary: "american"
 305 // compile-command: "scons -u test"
 306 // End: