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 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     /** \brief Format value
 144
 145         This helper will call the correct ArgumentTraits::str function to format \a value
 146
 147         \see ArgumentTraits
 148      */
 149     template <class Type>
 150     std::string str(Type const & value);
 151
 152     /** \brief Format return value
 153
 154         This helper will invoke the correct ReturnValueTraits::format function to write \a value
 155         into the \a out stream.
 156
 157         \see ReturnValueTraits
 158      */
 159     template <class Type>
 160     void format(Type const & value, std::ostream & os);
 161
 162 #ifndef DOXYGEN
 163
 164     // Parse bool: true/false, yes/no, enabled/disabled, 0/1
 165     template <>
 166     struct ArgumentTraits<bool>
 167     {
 168         typedef bool type;
 169         static bool const singleToken = true;
 170
 171         static void parse(ParseCommandInfo::TokensRange const & tokens, bool & out);
 172         static std::string description();
 173         static std::string str(bool value);
 174     };
 175
 176     template <>
 177     struct ReturnValueTraits<bool>
 178     {
 179         typedef bool type;
 180
 181         static void format(bool value, std::ostream & os);
 182     };
 183
 184     template <>
 185     struct ArgumentTraits<std::string>
 186     {
 187         typedef std::string type;
 188         static bool const singleToken = true;
 189
 190         static void parse(ParseCommandInfo::TokensRange const & tokens, std::string & out);
 191         static std::string description();
 192         static std::string str(std::string const & value);
 193     };
 194
 195 #endif
 196
 197     /** \brief Format boolean value as \c true / \c false */
 198     void formatTrueFalse(bool value, std::ostream & os);
 199
 200     /** \brief Format boolean value as \c yes / \c no */
 201     void formatYesNo(bool value, std::ostream & os);
 202
 203     /** \brief Format boolean value as \c enabled / \c disabled */
 204     void formatEnabledDisabled(bool value, std::ostream & os);
 205
 206     /** \brief Format boolean value as \c on / \c off */
 207     void formatOnOff(bool value, std::ostream & os);
 208
 209     /** \brief Format boolean value as \c 1 / \c 0 */
 210     void formatOneZero(bool value, std::ostream & os);
 211
 212     /** \brief Register enum type for argument parsing
 213
 214         Enum types need to be registered explicitly to support parsing.
 215         \code
 216         enum Foo { Foo1, Foo2 };
 217         SENF_CONSOLE_REGISTER_ENUM( Foo, (Foo1)(Foo2) );
 218         \endcode
 219         This macro will register an enum type and it's enumerators defined at namespace scope. See
 220         \ref SENF_CONSOLE_REGISTER_ENUM_MEMBER to register a member enum type.
 221
 222         \note All enumerator values must be unique ignoring case.
 223
 224         The enum parser will accept any unique initial substring ignoring case as valid enum value.
 225
 226         \ingroup console_commands
 227      */
 228 #   define SENF_CONSOLE_REGISTER_ENUM(Type, Values) \
 229         SENF_CONSOLE_REGISTER_ENUM_(BOOST_PP_EMPTY(), Type, Values)
 230
 231     /** \brief Register enum type for argument parsing
 232
 233         Enum types need to be registered explicitly to support parsing.
 234         \code
 235         class SomeClass
 236         {
 237             enum Foo { Foo1, Foo2 };
 238         };
 239
 240         SENF_CONSOLE_REGISTER_ENUM_MEMBER( SomeClass, Foo, (Foo1)(Foo2) );
 241         \endcode This macro will register an enum type and it's enumerators defined in a class. See
 242         \ref SENF_CONSOLE_REGISTER_ENUM to register an enum type declared at namespace scope.
 243
 244         \ingroup console_commands
 245      */
 246 #   define SENF_CONSOLE_REGISTER_ENUM_MEMBER(Class, Type, Values) \
 247         SENF_CONSOLE_REGISTER_ENUM_(Class::, Type, Values)
 248
 249     /** \brief Bit-mask flag argument type
 250
 251         senf::console::FlagCollection supplies a special argument type for use in registering
 252         console commands. This argument type is used to represent a bit-mask of single flags.
 253
 254         \code
 255         // Function taking a flags argument
 256         void func(unsigned flags);
 257
 258         // Enum containing all the possible flag values
 259         enum MyFlags { Foo = 1,
 260                      Bar = 2,
 261                      Baz = 4,
 262                      Doo = 8 };
 263         SENF_CONSOLE_REGISTER_ENUM(MyFlags, (Foo)(Bar)(Baz)(Boo));
 264
 265         // Register the function with a FlagCollection argument type
 266         consoleDir.add("func", boost::function<void (FlagCollection<MyFlags>)>(&func));
 267         \endcode
 268
 269         To use the FlagCollection class
 270         \li you need a function which takes a bit-mask of flags as argument
 271         \li you define and register an enum with all possible flag values
 272         \li you register the function with a FlagCollection argument type using \c boost::function
 273             for the conversion. This is also possible for return values.
 274
 275         The nice thing is, that \c boot::function supports compatible argument types and does
 276         automatic type conversion. Since a FlagCollection is convertible to and from unsigned long,
 277         this conversion will work.
 278
 279         After registering this function, you can call it with a collection of flags as argument
 280
 281         <pre>
 282         console:/$ help func
 283         Usage:
 284             func arg11:MyFlags
 285         console:/$ func Foo
 286         console:/$ func (Foo Boo)
 287         </pre>
 288      */
 289     template <class Enum>
 290     struct FlagCollection
 291     {
 292         operator unsigned long() const { return value; }
 293         FlagCollection() : value (0) {}
 294         FlagCollection(unsigned long value_) : value (value_) {}
 295         FlagCollection(Enum value_) : value (value_) {}
 296         unsigned long value;
 297     };
 298
 299     template <class Enum>
 300     struct ArgumentTraits< FlagCollection<Enum> >
 301     {
 302         typedef FlagCollection<Enum> type;
 303         static bool const singleToken = false;
 304         static void parse(ParseCommandInfo::TokensRange const & tokens, type & out);
 305         static std::string description();
 306         static std::string str(type const & value);
 307     };
 308
 309     template <class Enum>
 310     struct ReturnValueTraits< FlagCollection<Enum> >
 311     {
 312         typedef FlagCollection<Enum> type;
 313         static void format(type const & value, std::ostream & os);
 314     };
 315
 316 }}
 317
 318 ///////////////////////////////hh.e////////////////////////////////////////
 319 #include "Traits.cci"
 320 #include "Traits.ct"
 321 #include "Traits.cti"
 322 #endif
 323
 324 \f
 325 // Local Variables:
 326 // mode: c++
 327 // fill-column: 100
 328 // comment-column: 40
 329 // c-file-style: "senf"
 330 // indent-tabs-mode: nil
 331 // ispell-local-dictionary: "american"
 332 // compile-command: "scons -u test"
 333 // End: