Utils/Logger: Remove dependency on libboost_datetime

[senf.git] / Console / Mainpage.dox

diff --git a/Console/Mainpage.dox b/Console/Mainpage.dox
index 1b7da14..c143bc3 100644 (file)
--- a/Console/Mainpage.dox
+++ b/Console/Mainpage.dox
@@ -185,6 +185,53 @@
     \endcode
 
     \see \ref console_parser
+
+
+    \section console_misc Further features
+
+    \subsection console_serverclient Server and Client objects
+
+    The senf::console::Server and senf::console::Client objects offer further API calls. To access
+    the server instance you need to store away the senf::console::Server reference returned when
+    starting the server so you can later refer to it:
+    \code
+    int main(int, char**)
+    {
+        senf::console::Server & server ( senf::console::start( ... ) );
+    
+        // Do something ...
+
+        server.stop()
+    }
+    \endcode
+
+    The client instance can be accessed via the \c std::ostream arg of any command callback
+    \code
+    void someCallback(std::ostream & os, ... )
+    {
+        senf::console::Client & client (senf::console::Client::get(os));
+    
+        // Use the client's log target
+        client.route<senf::log::Debug, senf::Log::IMPORTANT>();
+    }
+    \endcode
+
+    \see 
+        senf::console::Server for the Server API \n
+        <a href="classsenf_1_1console_1_1Client-members.html">senf::console::Client / List of all
+        members</a> for the Client API
+
+
+    \subsection console_shell Features of the interactive console shell
+
+    The interactive shell will use the GNU readline library for the first connected
+    instance. Further users will not have access to this functionality since GNU readline is
+    completely non-reentrant.
+
+    The shell supports auto-cd and auto-completion: If you enter the name of a directory at the
+    prompt, the console will change to that directory. With auto-completion, any unique beginning of
+    a path component will be completed automatically and transparently to th corresponding full
+    name.
  */
 
 /** \defgroup console_commands Supported command types
@@ -241,22 +288,22 @@
     \code
     void fun1(std::ostream & os, senf::console::ParseCommandInfo const & command)
     {
-        // We take exactly one argument
-        if (command.arguments().size() != 1) 
-            raise senf::console::SyntaxErrorException("invalid number of arguments");
-
-        senf::console::ParseCommandInfo::TokensRange & argTokens (
-            command.arguments()[0]);
-
-        // The argument must have exactly one token
-        if (argTokens.size() != 1)
-            raise senf::console::SyntaxErrorException("argument syntax error");
-
-        // Retrieve the token value
-        std::string arg (argTokens[0].value());
-
-        // In this example, we just write the argument to the output stream
-        os << arg << std::endl;
+        // Here we declare variables for the arguments
+        std::string value;
+
+        {
+            // We parse the arguments using the CheckedArgumentIteratorWrapper. This wrapper
+            // will throw a SyntaxErrorException if we access a nonexistent argument or if we
+            // do not parse all arguments.
+            senf::console::CheckedArgumentIteratorWrapper args (command.arguments());
+
+            senf::console::ParseCommandInfo::TokensRange argTokens ( *(args++) );
+            if (arg1Tokens.size() != 1)
+                raise senf::console::SyntaxErrorException("argument syntax error");
+            value = arg1Tokens[0];
+        }
+
+        os << value << std::endl;
     }
     \endcode
     
@@ -863,23 +910,23 @@
     void senf_console_parse_argument(senf::console::ParseCommandInfo::TokensRange const & tokens,
                                      Coordinate & out)
     {
-        if (tokens.size() != 2)
-            throw SyntaxErrorException("parameter syntax error");
-        senf::console::ArgumentTraits<int>::parse(
-            senf::console::ParseCommandInfo::TokensRange( tokens.begin(), tokens.begin()+1 ),
-            out.x )
-        senf::console::ArgumentTraits<int>::parse(
-            senf::console::ParseCommandInfo::TokensRange( tokens.begin()+1, tokens.end() ),
-            out.y )
+        senf::console::CheckedArgumentIteratorWrapper arg (tokens);
+        senf::console::parse( *(arg++), out.x );
+        senf::console::parse( *(arg++), out.y );
     }
 
     void senf_console_format_value(Coordinate const & value, std::ostream & os)
     {
         os << '(' << value.x << ' ' << value.y << ')';
     }
-    \endcode
+    \endcode 
+
     The parser will accept an argument with two tokens which are each forwarded to the integer
-    parser. The formatter writes out the value as a parenthesized pair.
+    parser. The senf::console::CheckedArgumentIteratorWrapper ensures two things: That all input
+    tokens are parsed and no extra trailing tokens are left unparsed and it checks, that all
+    referenced tokens really exist.
+
+    The formatter writes out the value as a parenthesized pair.
 
     \code
     Coordinate fun5(Coordinate const & p) { return Coordinate(2*p.x, 2*p.y) }