Console/Example.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 /** \page console_testserver Test Server
  24
  25     \dontinclude testServer.cc
  26
  27     You can find this code in the \c testServer.cc source file.
  28
  29     \skip Custom
  30     \skip #include
  31     \until namespace
  32
  33     Here we see the necessary include files. For console support only <tt>senf/Console.hh</tt> needs
  34     to be included. This will pull in all necessary definitions.
  35
  36     We declare an alias for the senf::console::kw namespace which we will use further down for the
  37     keyword arguments.
  38
  39     \until echo
  40     \until }
  41     \until }
  42
  43     The first callback \c echo utilizes \link console_manualparse manual argument
  44     parsing\endlink. You should always refer to the iterator types as shown here since this will be
  45     safe from future changes.
  46
  47     The following \c struct \c TestObject is used to show how member functions and objects are used
  48     in the console.
  49
  50     \until dir
  51
  52     Important is the definition of the <b>public</b> senf::console::ScopedDirectory member called \c
  53     dir. This member can be used later to add the class to the node tree. Here we just register a
  54     single function \c vat (with \link console_autoparse automatic argument parsing\endlink) and
  55     set some command attributes.
  56
  57     \until };
  58
  59     The \c shutdownServer callback terminates the server.
  60
  61     \until }
  62
  63     This happens in two steps: First the \c terminate() call tells the scheduler to leave it's
  64     main-loop after shutdownServer returns (which is ultimately called via the console server from
  65     the scheduler). Throwing a senf::console::Executor::ExitException is like entering the \c exit
  66     built-in command at the console.
  67
  68     The next callback accesses the client instance directly to manipulate the logging:
  69
  70     \until }
  71
  72     The senf::console::Client instance can be accessed using the senf::console::Client::get() helper
  73     via the output stream. Since every Client is a senf::log::Target, we can route arbitrary log
  74     messages to the console instance.
  75
  76     We now define \c main() which initializes the node tree and starts the console server
  77
  78     \until route
  79
  80     Here we just setup more verbose logging and set \c SIGPIPE signals to be ignored. \c SIGPIPE's
  81     are a pain and really should be disabled.
  82
  83     \until settings
  84
  85     This shows, how to set the top-level documentation and create a new subdirectory directly
  86
  87     \until mkdir
  88
  89     Here we create another new directory but save a reference so we can later access the node
  90     directly. All the add commands return such a node reference of the correct type (this is a lie,
  91     but it works like this anyways and it's an implementation detail that must not concern you
  92     here).
  93
  94     This way of stroing a refernce is not bad, but even better is to use a \c
  95     senf::console::ScopedDirectory<> for this
  96
  97     \until functions
  98
  99     This will automatically remove the node from the tree when the senf::console::ScopedDiretory
 100     instance is destroyed and keeps the node alive even when unlinked from the tree (a plain
 101     reference becomes invalid when anyone later unlinks the node from the tree). This is much safer
 102     and is the preferred way to keep a hold on a directory.
 103
 104     The next statements add commands to the various directories declared so far
 105
 106     \until Example
 107
 108     We now continue by creating an instance of our test class \c TestObject
 109
 110     \until Example
 111
 112     We add that objects directory to the \c test dir. We now have created a directory structure like
 113     tis:
 114     <pre>
 115     /
 116       console/
 117         showlog
 118       server/
 119         shutdown
 120       test/
 121         echo
 122         testob/
 123           vat
 124     </pre>
 125
 126     We now start the server (giving it a nice descriptive name) and run the scheduler.
 127
 128     \until }
 129  */
 130
 131 \f
 132 // Local Variables:
 133 // mode: c++
 134 // fill-column: 100
 135 // comment-column: 40
 136 // c-file-style: "senf"
 137 // indent-tabs-mode: nil
 138 // ispell-local-dictionary: "american"
 139 // compile-command: "scons -U doc"
 140 // mode: flyspell
 141 // mode: auto-fill
 142 // End: