senf/Utils/Console/Example.dox

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