senf/Utils/Console/Utility.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2009
   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 Utility public header */
  25
  26 #ifndef HH_SENF_Utils_Console_Utility_
  27 #define HH_SENF_Utils_Console_Utility_ 1
  28
  29 // Custom includes
  30 #include "Parse.hh"
  31 #include "Traits.hh"
  32
  33 //#include "Utility.mpp"
  34 ///////////////////////////////hh.p////////////////////////////////////////
  35
  36 namespace senf {
  37 namespace console {
  38
  39     template <class CharT>
  40     struct CharAsString
  41     {
  42         CharAsString();
  43         CharAsString(CharT value_);
  44         operator CharT () const;
  45         CharT value;
  46     };
  47
  48 #ifndef DOXYGEN
  49
  50     template <class CharT>
  51     struct ArgumentTraits< CharAsString<CharT> >
  52     {
  53         typedef CharAsString<CharT> type;
  54         static bool const singleToken = true;
  55
  56         static void parse(ParseCommandInfo::TokensRange const & tokens, CharAsString<CharT> & out);
  57         static std::string description();
  58         static std::string str(CharAsString<CharT> value);
  59     };
  60
  61     template <class CharT>
  62     struct ReturnValueTraits< CharAsString<CharT> >
  63     {
  64         typedef CharAsString<CharT> type;
  65
  66         static void format(CharAsString<CharT> value, std::ostream & os);
  67     };
  68
  69 #endif
  70
  71     /** \brief Value range
  72
  73         A value range may be represented in the console either by a single value (setting both \a
  74         low and \a high to the same value) or as a lower and upper bound seperated by a colon
  75      */
  76     template <class T>
  77     struct ValueRange
  78     {
  79         T low;
  80         T high;
  81     };
  82
  83 #ifndef DOXYGEN
  84
  85     template <class T>
  86     struct ArgumentTraits< ValueRange<T> >
  87     {
  88         typedef ValueRange<T> type;
  89         static bool const singleToken = true;
  90
  91         static void parse(ParseCommandInfo::TokensRange const & tokens, type & out);
  92         static std::string description();
  93         static std::string str(type const & value);
  94     };
  95
  96     template <class T>
  97     struct ReturnValueTraits< ValueRange<T> >
  98     {
  99         typedef ValueRange<T> type;
 100
 101         static void format(type const & value, std::ostream & os);
 102     };
 103
 104 #endif
 105
 106     /** \brief Bit-mask flag argument type
 107
 108         senf::console::FlagCollection supplies a special argument type for use in registering
 109         console commands. This argument type is used to represent a bit-mask of single flags.
 110
 111         \code
 112         // Function taking a flags argument
 113         void func(unsigned flags);
 114
 115         // Enum containing all the possible flag values
 116         enum MyFlags { Foo = 1,
 117                      Bar = 2,
 118                      Baz = 4,
 119                      Doo = 8 };
 120         SENF_CONSOLE_REGISTER_ENUM(MyFlags, (Foo)(Bar)(Baz)(Boo));
 121
 122         // Register the function with a FlagCollection argument type
 123         consoleDir.add("func", boost::function<void (FlagCollection<MyFlags>)>(&func));
 124         \endcode
 125
 126         To use the FlagCollection class
 127         \li you need a function which takes a bit-mask of flags as argument
 128         \li you define and register an enum with all possible flag values
 129         \li you register the function with a FlagCollection argument type using \c boost::function
 130             for the conversion. This is also possible for return values.
 131
 132         The nice thing is, that \c boot::function supports compatible argument types and does
 133         automatic type conversion. Since a FlagCollection is convertible to and from unsigned long,
 134         this conversion will work.
 135
 136         After registering this function, you can call it with a collection of flags as argument
 137
 138         <pre>
 139         console:/$ help func
 140         Usage:
 141             func arg11:MyFlags
 142         console:/$ func Foo
 143         console:/$ func (Foo Boo)
 144         </pre>
 145      */
 146     template <class Enum>
 147     struct FlagCollection
 148     {
 149         operator unsigned long() const { return value; }
 150         FlagCollection() : value (0) {}
 151         FlagCollection(unsigned long value_) : value (value_) {}
 152         FlagCollection(Enum value_) : value (value_) {}
 153         unsigned long value;
 154     };
 155
 156 #ifndef DOXYGEN
 157
 158     template <class Enum>
 159     struct ArgumentTraits< FlagCollection<Enum> >
 160     {
 161         typedef FlagCollection<Enum> type;
 162         static bool const singleToken = false;
 163         static void parse(ParseCommandInfo::TokensRange const & tokens, type & out);
 164         static std::string description();
 165         static std::string str(type const & value);
 166     };
 167
 168     template <class Enum>
 169     struct ReturnValueTraits< FlagCollection<Enum> >
 170     {
 171         typedef FlagCollection<Enum> type;
 172         static void format(type const & value, std::ostream & os);
 173     };
 174
 175 #endif
 176
 177 }}
 178
 179 ///////////////////////////////hh.e////////////////////////////////////////
 180 //#include "Utility.cci"
 181 #include "Utility.ct"
 182 #include "Utility.cti"
 183 #endif
 184
 185 \f
 186 // Local Variables:
 187 // mode: c++
 188 // fill-column: 100
 189 // comment-column: 40
 190 // c-file-style: "senf"
 191 // indent-tabs-mode: nil
 192 // ispell-local-dictionary: "american"
 193 // compile-command: "scons -u test"
 194 // End: