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_Traits_
  27 #define HH_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     /** \brief Register enum type for argument parsing
 137
 138         Enum types need to be registered explicitly to support parsing.
 139         \code
 140         enum Foo { Foo1, Foo2 };
 141         SENF_CONSOLE_REGISTER_ENUM( Foo, (Foo1)(Foo2) );
 142         \endcode
 143         This macro will register an enum type and it's enumerators defined at namespace scope. See
 144         \ref SENF_CONSOLE_REGISTER_ENUM_MEMBER to register a member enum type.
 145
 146         \ingroup console_commands
 147      */
 148 #   define SENF_CONSOLE_REGISTER_ENUM(Type, Values) \
 149         SENF_CONSOLE_REGISTER_ENUM_(BOOST_PP_EMPTY(), Type, Values)
 150
 151     /** \brief Register enum type for argument parsing
 152
 153         Enum types need to be registered explicitly to support parsing.
 154         \code
 155         class SomeClass
 156         {
 157             enum Foo { Foo1, Foo2 };
 158         };
 159
 160         SENF_CONSOLE_REGISTER_ENUM_MEMBER( SomeClass, Foo, (Foo1)(Foo2) );
 161         \endcode This macro will register an enum type and it's enumerators defined in a class. See
 162         \ref SENF_CONSOLE_REGISTER_ENUM to register an enum type declared at namespace scope.
 163
 164         \ingroup console_commands
 165      */
 166 #   define SENF_CONSOLE_REGISTER_ENUM_MEMBER(Class, Type, Values) \
 167         SENF_CONSOLE_REGISTER_ENUM_(Class::, Type, Values)
 168
 169 }}
 170
 171 ///////////////////////////////hh.e////////////////////////////////////////
 172 //#include "Traits.cci"
 173 #include "Traits.ct"
 174 #include "Traits.cti"
 175 #endif
 176
 177 \f
 178 // Local Variables:
 179 // mode: c++
 180 // fill-column: 100
 181 // comment-column: 40
 182 // c-file-style: "senf"
 183 // indent-tabs-mode: nil
 184 // ispell-local-dictionary: "american"
 185 // compile-command: "scons -u test"
 186 // End: