senf/Utils/Console/Utility.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2009
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 //
   6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
   7 // Version 1.0 (the "License"); you may not use this file except in compliance
   8 // with the License. You may obtain a copy of the License at
   9 // http://senf.berlios.de/license.html
  10 //
  11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
  12 // but modifies the Mozilla Public License Version 1.1.
  13 // See the full license text for the amendments.
  14 //
  15 // Software distributed under the License is distributed on an "AS IS" basis,
  16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  17 // for the specific language governing rights and limitations under the License.
  18 //
  19 // The Original Code is Fraunhofer FOKUS code.
  20 //
  21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
  22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
  23 // All Rights Reserved.
  24 //
  25 // Contributor(s):
  26 //   Stefan Bund <g0dil@berlios.de>
  27
  28 /** \file
  29     \brief Utility public header */
  30
  31 #ifndef HH_SENF_Utils_Console_Utility_
  32 #define HH_SENF_Utils_Console_Utility_ 1
  33
  34 // Custom includes
  35 #include "Parse.hh"
  36
  37 //#include "Utility.mpp"
  38 //-/////////////////////////////////////////////////////////////////////////////////////////////////
  39
  40 /** \defgroup senf_console_utilities Special console utility types
  41
  42     These types are provided by the %console library to support special argument or return value
  43     formatting rules.
  44  */
  45
  46 namespace senf {
  47 namespace console {
  48
  49     /** \brief Parse character value as single-char string
  50
  51         This helper types is a wrapper around \a CharT which must be a character type. A value of
  52         this type will be represented as a single character string, not as numeric value (the
  53         default interpretation of char arguments in the console library).
  54
  55         This wrapper is used via type conversion using \c boost::function to convert the
  56         argument/return type \a CharT  to CharAsString<CharT>:
  57         \code
  58         char foo(char v) { return v; }
  59
  60         senf::console::root().add(
  61             "foo", fty::Command< CharAsString<char> (CharAsString<char>) >(&foo));
  62         \endcode
  63
  64         \tparam CharT character type, one of \c char, \c signed \c char or \c unsigned \c char
  65
  66         \ingroup senf_console_utilities
  67      */
  68     template <class CharT>
  69     struct CharAsString
  70     {
  71         CharAsString();
  72         CharAsString(CharT value_);
  73         operator CharT () const;
  74         CharT value;
  75     };
  76
  77 #ifndef DOXYGEN
  78
  79     template <class CharT>
  80     struct ArgumentTraits< CharAsString<CharT> >
  81     {
  82         typedef CharAsString<CharT> type;
  83         static bool const singleToken = true;
  84
  85         static void parse(ParseCommandInfo::TokensRange const & tokens, CharAsString<CharT> & out);
  86         static std::string description();
  87         static std::string str(CharAsString<CharT> value);
  88     };
  89
  90     template <class CharT>
  91     struct ReturnValueTraits< CharAsString<CharT> >
  92     {
  93         typedef CharAsString<CharT> type;
  94
  95         static void format(CharAsString<CharT> value, std::ostream & os);
  96     };
  97
  98 #endif
  99
 100     /** \brief Value range
 101
 102         A value range may be represented in the console either by a single value (setting both \a
 103         low and \a high to the same value) or as a lower and upper bound separated by a colon.
 104
 105         \ingroup senf_console_utilities
 106      */
 107     template <class T>
 108     struct ValueRange
 109     {
 110         T low;
 111         T high;
 112     };
 113
 114 #ifndef DOXYGEN
 115
 116     template <class T>
 117     struct ArgumentTraits< ValueRange<T> >
 118     {
 119         typedef ValueRange<T> type;
 120         static bool const singleToken = true;
 121
 122         static void parse(ParseCommandInfo::TokensRange const & tokens, type & out);
 123         static std::string description();
 124         static std::string str(type const & value);
 125     };
 126
 127     template <class T>
 128     struct ReturnValueTraits< ValueRange<T> >
 129     {
 130         typedef ValueRange<T> type;
 131
 132         static void format(type const & value, std::ostream & os);
 133     };
 134
 135 #endif
 136
 137     /** \brief Bit-mask flag argument type
 138
 139         senf::console::FlagCollection supplies a special argument type for use in registering
 140         console commands. This argument type is used to represent a bit-mask of single flags.
 141
 142         \code
 143         // Function taking a flags argument
 144         void func(unsigned flags);
 145
 146         // Enum containing all the possible flag values
 147         enum MyFlags { Foo = 1,
 148                      Bar = 2,
 149                      Baz = 4,
 150                      Doo = 8 };
 151         SENF_CONSOLE_REGISTER_ENUM(MyFlags, (Foo)(Bar)(Baz)(Boo));
 152
 153         // Register the function with a FlagCollection argument type
 154         consoleDir.add("func", fty::Command<void (FlagCollection<MyFlags>)>(&func));
 155         \endcode
 156
 157         To use the FlagCollection class
 158         \li you need a function which takes a bit-mask of flags as argument
 159         \li you define and register an enum with all possible flag values
 160         \li you register the function with a FlagCollection argument type using \c boost::function
 161             for the conversion. This is also possible for return values.
 162
 163         The nice thing is, that \c boot::function supports compatible argument types and does
 164         automatic type conversion. Since a FlagCollection is convertible to and from unsigned long,
 165         this conversion will work.
 166
 167         After registering this function, you can call it with a collection of flags as argument
 168
 169         <pre>
 170         console:/$ help func
 171         Usage:
 172             func arg11:MyFlags
 173         console:/$ func Foo
 174         console:/$ func (Foo Boo)
 175         </pre>
 176
 177         \ingroup senf_console_utilities
 178      */
 179     template <class Enum>
 180     struct FlagCollection
 181     {
 182         operator unsigned long() const { return value; }
 183         FlagCollection() : value (0) {}
 184         FlagCollection(unsigned long value_) : value (value_) {}
 185         FlagCollection(Enum value_) : value (value_) {}
 186         unsigned long value;
 187     };
 188
 189 #ifndef DOXYGEN
 190
 191     template <class Enum>
 192     struct ArgumentTraits< FlagCollection<Enum> >
 193     {
 194         typedef FlagCollection<Enum> type;
 195         static bool const singleToken = false;
 196         static void parse(ParseCommandInfo::TokensRange const & tokens, type & out);
 197         static std::string description();
 198         static std::string str(type const & value);
 199     };
 200
 201     template <class Enum>
 202     struct ReturnValueTraits< FlagCollection<Enum> >
 203     {
 204         typedef FlagCollection<Enum> type;
 205         static void format(type const & value, std::ostream & os);
 206     };
 207
 208 #endif
 209
 210 }}
 211
 212 //-/////////////////////////////////////////////////////////////////////////////////////////////////
 213 //#include "Utility.cci"
 214 #include "Utility.ct"
 215 #include "Utility.cti"
 216 #endif
 217
 218 \f
 219 // Local Variables:
 220 // mode: c++
 221 // fill-column: 100
 222 // comment-column: 40
 223 // c-file-style: "senf"
 224 // indent-tabs-mode: nil
 225 // ispell-local-dictionary: "american"
 226 // compile-command: "scons -u test"
 227 // End: