Scheduler/Console/Variables.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 Variables public header */
  25
  26 #ifndef HH_Variables_
  27 #define HH_Variables_ 1
  28
  29 // Custom includes
  30 #include <boost/utility.hpp>
  31 #include <boost/type_traits/is_convertible.hpp>
  32 #include <boost/ref.hpp>
  33 #include "ParsedCommand.hh"
  34
  35 #include "Variables.ih"
  36 //#include "Variables.mpp"
  37 ///////////////////////////////hh.p////////////////////////////////////////
  38
  39 namespace senf {
  40 namespace console {
  41
  42     class ScopedDirectoryBase;
  43     template <class Variable> class VariableAttributor;
  44
  45 #ifndef DOXYGEN
  46
  47     template <class Variable>
  48     VariableAttributor<Variable> senf_console_add_node(
  49         DirectoryNode & node, std::string const & name, Variable & var, int,
  50         typename boost::disable_if< boost::is_convertible<Variable*, ScopedDirectoryBase*> >::type * = 0);
  51
  52     template <class Variable>
  53     typename detail::VariableNodeCreator<Variable>::result_type
  54     senf_console_add_node(DirectoryNode & node, std::string const & name,
  55                           boost::reference_wrapper<Variable> var, int);
  56
  57     template <class Variable, class Owner>
  58     VariableAttributor<Variable> senf_console_add_node(
  59         DirectoryNode & node, Owner & owner, std::string const & name, Variable & var, int,
  60         typename boost::disable_if< boost::is_convertible<Variable*, ScopedDirectoryBase*> >::type * = 0);
  61
  62 #endif
  63
  64     /** \brief Variable command attributes (const)
  65
  66         \see VariableAttributor
  67      */
  68     template <class Variable>
  69     class ConstVariableAttributor
  70     {
  71     public:
  72         typedef typename detail::QueryVariable<Variable>::Traits::Overload QueryOverload;
  73         typedef typename QueryOverload::Formatter Formatter;
  74         typedef OverloadedCommandNode node_type;
  75         typedef ConstVariableAttributor return_type;
  76
  77         ConstVariableAttributor doc(std::string const & doc);
  78         ConstVariableAttributor formatter(Formatter formatter);
  79
  80     protected:
  81         explicit ConstVariableAttributor(QueryOverload & queryOverload);
  82
  83     private:
  84         QueryOverload & queryOverload_;
  85
  86         friend class detail::VariableNodeCreator<Variable const>;
  87     };
  88
  89     /** \brief Variable command attributes
  90
  91         Variable commands allow to register any arbitrary variable as a command node. The variable
  92         will be registered as two command overloads: One which takes a single argument of the
  93         variables type to set the variable and another one taking no arguments and just querying the
  94         current variable value.
  95         \code
  96         int var;
  97         ScopedDirectory<> dir;
  98
  99         dir.add("var", var);
 100         \endcode
 101
 102         Variables should be registered only with a ScopedDirectory declared in the same scope
 103         (e.g. as a class member for member variables). This ensures, that the variable node is
 104         removed from the tree when the scope is destroyed.
 105
 106         Since a variable command is added as a combination of two ordinary overloads, it is possible
 107         to register additional overloads with the same name before or after registering the
 108         variable.
 109
 110         It is also possible, to register a variable read-only. To achieve this, just wrap it with \c
 111         boost::cref(). Such a variable cannot be changed only queried. Therefore, it does not have
 112         the parser() and typeName() attributes.
 113         \code
 114         dir.add("const_var", boost::cref(var))
 115         \endcode
 116
 117         \ingroup console_commands
 118      */
 119    template <class Variable>
 120     class VariableAttributor
 121         : public ConstVariableAttributor<Variable>
 122     {
 123     public:
 124         typedef typename detail::SetVariable<Variable>::Traits::Overload SetOverload;
 125         typedef typename detail::ArgumentInfo<typename SetOverload::arg1_type>::Parser Parser;
 126         typedef typename detail::SetVariable<Variable>::OnChangeHandler OnChangeHandler;
 127         typedef OverloadedCommandNode node_type;
 128         typedef VariableAttributor return_type;
 129
 130         typedef typename ConstVariableAttributor<Variable>::Formatter Formatter;
 131         typedef typename ConstVariableAttributor<Variable>::QueryOverload QueryOverload;
 132
 133         VariableAttributor doc(std::string const & doc); ///< Set documentation of the variable
 134         VariableAttributor formatter(Formatter formatter); ///< Set formatter
 135                                         /**< The \a formatter must be a callable with a signature
 136                                              compatible with
 137                                              \code
 138                                              void formatter(Variable const & value, std::ostream & os);
 139                                              \endcode
 140                                              The \a formatter takes the return value of the call \a
 141                                              value and writes it properly formated to \a os. */
 142
 143         VariableAttributor parser(Parser parser); ///< Set argument parser
 144                                         /**< The parser is an arbitrary callable object with
 145                                              the signature
 146                                              \code
 147                                                  void parser(senf::console::ParseCommandInfo::TokensRange const & tokens, value_type & out);
 148                                              \endcode
 149
 150                                              where \c value_type is the type of the overload
 151                                              parameter. The parser must read and parse the complete
 152                                              \a tokens range and return the parsed value in \a
 153                                              out. If the parser fails, it must raise a
 154                                              senf::console::SyntaxErrorException. */
 155         VariableAttributor typeName(std::string const & name); ///< Set name of the variable type
 156         VariableAttributor onChange(OnChangeHandler handler); ///< Set change callback
 157                                         /**< The \a handler callback is called, whenever the value
 158                                              of the variable is changed. The new value has already
 159                                              been set, when the callback is called, the old value is
 160                                              passed to the callback. The callback must have a
 161                                              signature compatible to
 162                                              \code
 163                                              void handler(Variable const & oldValue);
 164                                              \endcode */
 165
 166     protected:
 167
 168     private:
 169         VariableAttributor(QueryOverload & queryOverload, SetOverload & setOverload,
 170                            Variable & var);
 171
 172         SetOverload & setOverload_;
 173         Variable & var_;
 174
 175         friend class detail::VariableNodeCreator<Variable>;
 176     };
 177 }}
 178
 179 ///////////////////////////////hh.e////////////////////////////////////////
 180 //#include "Variables.cci"
 181 //#include "Variables.ct"
 182 #include "Variables.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: