Console/Mainpage.dox

   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 /** \mainpage The Configuration and Runtime Control Framework
  24
  25     The Console library implements a runtime interactive (network) console which allows to
  26     configure, control and manipulate a running application in any way. Additionally this library
  27     provides support for configuration files and command line parsing which can be used with or
  28     without the network console.
  29
  30     \section console_intro Introduction
  31
  32     There are two components to the Config/console framework:
  33
  34     \li Building the node tree by registering objects and callbacks
  35     \li Utilizing the config/console framework by writing configuration files or using the
  36         interactive console.
  37
  38     Basic data structure of the console and config framework is the config/console node tree. This
  39     tree. This tree works like a file-system. Commands are added to this tree and can then be called
  40     from configuration files or from the interactive console.
  41
  42     To get started using the config/console library, see
  43     \li \ref node_tree
  44     \li \ref console_parser
  45
  46     \section console_example Example
  47
  48     The following example shows a \e very short summary on how to integrate the config/console
  49     library. See above links for more:
  50
  51     \code
  52     // Define callback function.
  53     void mycommand(std::ostream & os, senf::console::Arguments const & args)
  54     {
  55         // ...
  56         os << "!! Important message ...\n";
  57     }
  58
  59     int main(int, char**)
  60     {
  61         // Provide global documentation
  62         senf::console::root()
  63             .doc("This is someServer server");
  64
  65         // Add a command
  66         senf::console::root()
  67             .add("mycommand", &mycommand)
  68             .doc("mycommand <foo> [<bar>]\n\n"
  69                  "If <bar> is given, flurgle the <foo>, otherwise burgle it");
  70
  71         // Start the interactive console server
  72         senf::console::Server::start(senf::INet4SocketAddress(senf::INet4Address::None, 23232u))
  73             .name("someServer");
  74     }
  75     \endcode
  76
  77     after this registration, the console can be accessed easily via telnet:
  78
  79     <pre>
  80     $ telnet localhost 23232
  81     Trying 127.0.0.1...
  82     Connected to localhost.
  83     Escape character is '^]'
  84     xxxx-xx-xx xx:xx:xx.xxxxxx-0000 [NOTICE][senf::console::Server] Registered new client 0xxxxxxx
  85     someServer:/# ls
  86     mycommand
  87     someServer:/# mycommand
  88     !! Important message  ...
  89     someServer:/# exit
  90     xxxx-xx-xx xx:xx:xx.xxxxxx-0000 [NOTICE][senf::console::Server] Disposing client 0xxxxxxx
  91     Connection closed by foreign host.
  92     $
  93     </pre>
  94  */
  95
  96 \f
  97 // Local Variables:
  98 // mode: c++
  99 // fill-column: 100
 100 // comment-column: 40
 101 // c-file-style: "senf"
 102 // indent-tabs-mode: nil
 103 // ispell-local-dictionary: "american"
 104 // compile-command: "scons -u test"
 105 // mode: flyspell
 106 // mode: auto-fill
 107 // End: