X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Console%2FMainpage.dox;h=c143bc35aea1912c69c3c47af5230744df771f58;hb=456ee576285b76aa46240f8001f426757810dcc1;hp=2466616cb3e84c1c5cf64b8aa0a60951dadb29cf;hpb=a99eba1e1f51afcd7867344f50206f4975cfd5dd;p=senf.git diff --git a/Console/Mainpage.dox b/Console/Mainpage.dox index 2466616..c143bc3 100644 --- a/Console/Mainpage.dox +++ b/Console/Mainpage.dox @@ -51,6 +51,8 @@ library. See above links for more: \code + #include + // Define callback function. void mycommand(std::ostream & os, int foo, int bar) { @@ -97,6 +99,46 @@ $ + \see \ref console_testserver for a complete example application + + \section intro_init Initialization + + To make the console accessible, it must be initialized when the program is started: + \code + #include + + int main(int argc, char * argv []) + { + // Configure console nodes, add commands ... + + // Start console server + senf::console::start(senf::INet4SocketAddress(12345u)) + .name("myserver"); + + // You need to enter the scheduler main-loop for the server to work + senf::Scheduler::instance().process(); + + // Alternatively enter the main-loop via the PPI + // senf::ppi::run(); + } + \endcode + + This will start the server on IPv4 port 12345. The servers name (as displayed in the interactive + console prompt) is set to 'myserver'. + + After launching the application, the server can be accessed at the given port: + \htmlonly + 
+    bash$ telnet localhost 12345
+    Trying 127.0.0.1...
+    Connected to localhost.
+    Escape character is '^]'.
+
+    myserver:/$ exit
+    Connection closed by foreign host.
+    bash$
+
+ \endhtmlonly \section intro_nodes The node tree @@ -108,7 +150,7 @@ \see \ref node_tree - \section intro_commands Console/config commands + \section intro_commands Registering console/config commands The console/config language does not define, how arguments are passed to the commands, it just tokenizes the input and passes the tokens to the commands which then handle the @@ -143,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(); + } + \endcode + + \see + senf::console::Server for the Server API \n + senf::console::Client / List of all + members 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 @@ -199,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::TokenRange & 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 @@ -303,7 +392,7 @@ Commands may have an optional first argument of type std::ostream &. This argument is not considered part of the real interface. When the command is executed, the callback will be - passed the current console's output stream object in this argument. With this, the callback can + passed the current consoles output stream object in this argument. With this, the callback can output arbitrary messages to the network console. \code void fun3(std::ostream & os, unsigned n, std::string text) @@ -595,8 +684,9 @@ \section console_memberfn Member functions - Member functions are supported like non-member functions. They must however be added through a - senf::console::ScopedDirectory instance to bind them to their instance. + Non-static member functions are supported like non-member functions (static member functions are + identical to non-members). They must however be added through a senf::console::ScopedDirectory + instance to bind them to their instance. \code class Test1 { @@ -700,7 +790,7 @@ \link senf::console::VariableAttributor::doc() .doc\endlink ( \e doc )Set variable documentation - \link senf::console::VariableAttributor::onChange() .onchange\endlink + \link senf::console::VariableAttributor::onChange() .onChange\endlink ( \e handler )Set change handler @@ -729,7 +819,146 @@ After this setup, \c varChanged will be called, whenever the value has changed. - \see senf::console::VariableAttributor for the complete attribute interface + \section console_args Registering special argument types + + By default, argument types which can be read and written using \c iostreams are automatically + supported. Other types need to be registered explicitly + + + \subsection console_args_enum Registering enum types + + Enum types are a special case, since it is not possible, to find a string representation for the + enumerator values automatically. Therefore, enum types need to be registered manually. + \code + enum MyEnum { Sit, Run, Jump }; + SENF_CONSOLE_REGISTER_ENUM( MyEnum, (Sit)(Run)(Jump) ); + + MyEnum fun4(MyEnum v) { return v } + + senf::console::root() + .add("test9", &fun4); + \endcode + + After an enum type is registered, it can be used like any other type for arguments or + return-values: + + \htmlonly + 
+    server:/$ test9 Sit
+    Sit
+    server:/$ test9 Crawl
+    argument syntax error: invalid enum value
+    server:/$ help test9
+    Usage:
+        test9 arg11:MyEnum
+    server:/$
+
+ \endhtmlonly + + \ref SENF_CONSOLE_REGISTER_ENUM() can only be used, to register enums at namespace scope. To + register enums defined within some class, use \ref SENF_CONSOLE_REGISTER_ENUM_MEMBER() + + \code + class Test3 + { + public: + enum Color { Red, Green, Blue }; + + senf::console::ScopedDirectory dir; + + Test3(); + + Color mem3(Color c) { return c } + }; + SENF_CONSOLE_REGISTER_ENUM_MEMBER( Test3, Color, (Red)(Green)(Blue) ); + + Test3::Test3() : dir(this) + { dir.add("test", &MyClass::mem3); } + + Test3 test3ob; + senf::console::root().add("test3ob", test3ob.dir); + \endcode + + Using this command/type is identical + \htmlonly + 
+    server:/$ test3ob/test Red
+    Red
+    server:/$ test3ob/test White
+    argument syntax error: invalid enum value
+    server:/$ help test3ob/test
+    Usage:
+        test arg11:Color
+
+ \endhtmlonly + + + \subsection console_args_custom Customizing argument and return value parsing/formatting + + To support or customize parsing/formatting of other types, they need to be registered. In it's + simplest case, this works, by just providing an appropriate overload for + senf_console_parse_argument() and senf_console_format_value(): + \code + struct Coordinate + { + Coordinate() : x(0), y(0) {} + Coordinate(int x_, int y_) : x(x_), y(y_) {} + + int x, y; + } + + void senf_console_parse_argument(senf::console::ParseCommandInfo::TokensRange const & tokens, + Coordinate & out) + { + 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 + + The parser will accept an argument with two tokens which are each forwarded to the integer + 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) } + + namespace kw = senf::console::kw; + + senf::console::root() + .add("test10", &fun5) + .arg("x","coordinate to double", + kw::default_value = Coordinate()) + \endcode + We can now call \c test10 with a coordinate argument: + \htmlonly + 
+    server:/$ test10 (2 7)
+    (4 14)
+    server:/$ help test10
+    Usage:
+        test10 [x:Coordinate]
+
+    With:
+        x         Coordinate to double
+            default: (0 0)
+    server:/$
+
+ \endhtmlonly + + If you want to customize the formatting of default values differently from the formating of + return-values or if you want to change the displayed name of a type, you will need to specialize + the senf::console::ArgumentTraits class instead of implementing + senf_console_parse_argument(). See senf::console::ArgumentTraits and + senf::console::ReturnValueTraits for more. */