X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=senf%2FUtils%2FConsole%2FMainpage.dox;h=8f81b1dba458e861d2d19a98187def1c3fb89305;hb=0003d55730b447329342161d12cf2ed23b63459e;hp=9b25f2ed4dba651bc777f1087d4b02fd85e3d15f;hpb=b8a2a9d30d2c0aa986c6c86f9cc9288ead67ebdb;p=senf.git diff --git a/senf/Utils/Console/Mainpage.dox b/senf/Utils/Console/Mainpage.dox index 9b25f2e..8f81b1d 100644 --- a/senf/Utils/Console/Mainpage.dox +++ b/senf/Utils/Console/Mainpage.dox @@ -2,23 +2,28 @@ // // Copyright (C) 2008 // Fraunhofer Institute for Open Communication Systems (FOKUS) -// Competence Center NETwork research (NET), St. Augustin, GERMANY -// Stefan Bund // -// This program is free software; you can redistribute it and/or modify -// it under the terms of the GNU General Public License as published by -// the Free Software Foundation; either version 2 of the License, or -// (at your option) any later version. +// The contents of this file are subject to the Fraunhofer FOKUS Public License +// Version 1.0 (the "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// http://senf.berlios.de/license.html // -// This program is distributed in the hope that it will be useful, -// but WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -// GNU General Public License for more details. +// The Fraunhofer FOKUS Public License Version 1.0 is based on, +// but modifies the Mozilla Public License Version 1.1. +// See the full license text for the amendments. // -// You should have received a copy of the GNU General Public License -// along with this program; if not, write to the -// Free Software Foundation, Inc., -// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +// Software distributed under the License is distributed on an "AS IS" basis, +// WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License +// for the specific language governing rights and limitations under the License. +// +// The Original Code is Fraunhofer FOKUS code. +// +// The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V. +// (registered association), Hansastraße 27 c, 80686 Munich, Germany. +// +// Contributor(s): +// Stefan Bund + /** \mainpage The Configuration and Runtime Control Library @@ -55,7 +60,7 @@ library. See above links for more: \code - #include + #include // Define callback function. void mycommand(std::ostream & os, int foo, int bar) @@ -137,7 +142,8 @@ \section intro_commands Implementing console/config commands - \seechapter \ref console_commands + \seechapter \ref console_commands \n + \seechapter \ref senf::console::factory 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 @@ -276,9 +282,19 @@ Options can be abbreviated at each directory boundary: A command /foo/bar/do can be called as --f-b-d as long as this name is unique. - Everything after the first '=' character is parsed into argument tokens using the normal - config/console parser. If the option has no '=' character, the list of argument tokens will be - empty. + Everything after the first '=' character is passed as arguments to the command. The exact + interpretation depends on the command: + \li If the command only takes a single token as argument (e.g. a single string or numeric + value), everything after the '=' sign is parsed into a single token (e.g. see rows 2 and 3 + of the following table). + \li In all other cases, the string after the '=' sign is parsed into argument tokens using the + config/console parser. In this case, quoted strings need to be quoted twice, once for the + shell and once for the config/console parser (e.g. see rows 4 and 5 of the following table). + \li If the option has no '=' character, the list of argument tokens will be empty (e.g. see row + 1 of the following table) + + Without these rules, multi-word string arguments would \e always have to be quoted twice (for + the shell and the config/console parser). @@ -297,8 +313,8 @@ - - + + @@ -306,10 +322,13 @@ -
CommandFile syntaxOption syntax
void doo(std::string const &)/path/to/doo "some test";--path-to-doo='"some text"'/path/to/doo "some text";--path-to-doo="some text"
/path/to/doo take 1; --path-to-doo="take 1"
- The last column is additionally quoted using standard \c sh quoting: quotes in arguments need to - be additionally quoted for the shell. + + void doo(std::string const &, int) + /path/to/doo "take two" 1; + --path-to-doo='"take two" 1' + + Short options are registered as aliases for long options. They can be registered with or without an implied parameter and can optionally take a parameter. so after @@ -333,7 +352,7 @@ $ program --mycommand="2 3" --mycommand="4 5" - (Beware, that the second argument to \c alias() is \e not shell quoted). + (Beware, that the second argument to \c alias() must \e not be shell quoted). \subsection console_access_root Changing the root node @@ -597,15 +616,16 @@ Depending on the object added, you can also bind to a more specific node type (e.g. senf::console::SimpleCommand) if you know the type of node returned. - Depending on the type of object added, there are additional attributes which can be set. These - attributes are always set by calling them on the factory return value. It is \e not guaranteed, - you can call these members on the node reference returned by the \c add() call. + Nodes are always added using a factory from the senf::console::factory namespace. The factory + has additional (type specific) attributes. These attributes are set by calling member functions + called 'attributors' on the temporary factory instance. It is \e not guaranteed, you can call + these members on the node reference returned by the \c add() call. \code namespace fty = senf::console::factory; - dir.add("name", fty::Command(callback) - .doc("The documentation") ); + dir.add("name", fty::Command(callback) .doc("The documentation") ); \endcode sets the \e doc attribute (if that is available, otherwise this will fail to compile). + \see senf::console::factory for a list of all node factories. \section console_manualparse Manually parsing command arguments @@ -668,7 +688,7 @@ \endhtmlonly As you can see above, the arguments and tokens are returned as + href="http://www.boost.org/doc/libs/release/libs/range/doc/html/range/reference/utilities/iterator_range.html"> boost::iterator_range instances. These behave much like containers: They have \c begin() and \c end() and some other useful members. @@ -1085,7 +1105,7 @@ senf::console::ScopedDirectory dir; Test2() : dir(this), var_(0) - { dir.add("var", fty::Variabl(var_) ); } + { dir.add("var", fty::Variable(var_) ); } private: int var_; @@ -1443,4 +1463,3 @@ // compile-command: "scons -u test" // mode: auto-fill // End: -