//
// Copyright (C) 2008
// Fraunhofer Institute for Open Communication Systems (FOKUS)
-// Competence Center NETwork research (NET), St. Augustin, GERMANY
-// Stefan Bund <g0dil@berlios.de>
//
-// 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 <g0dil@berlios.de>
+
/** \mainpage The Configuration and Runtime Control Library
\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
Options can be abbreviated at each directory boundary: A command <tt>/foo/bar/do</tt> can be
called as <tt>--f-b-d</tt> 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).
<table style="font-size:80%" class="senf">
<tr><th>Command</th><th>File syntax</th><th>Option syntax</th></tr>
<tr>
<td><tt>void doo(std::string const &)</tt></td>
- <td><tt>/path/to/doo "some test";</tt></td>
- <td><tt>--path-to-doo='"some text"'</tt></td>
+ <td><tt>/path/to/doo "some text";</tt></td>
+ <td><tt>--path-to-doo="some text"</tt></td>
</tr>
<tr>
<td><tt>/path/to/doo take 1;</tt></td>
<td><tt>--path-to-doo="take 1"</tt></td>
</tr>
- </table>
- The last column is additionally quoted using standard \c sh quoting: quotes in arguments need to
- be additionally quoted for the shell.
+ <tr>
+ <td><tt>void doo(std::string const &, int)</tt></td>
+ <td><tt>/path/to/doo "take two" 1;</tt></td>
+ <td><tt>--path-to-doo='"take two" 1'</tt></td>
+ </tr>
+ </table>
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
$ program --mycommand="2 3" --mycommand="4 5"
</pre>
- (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
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
\endhtmlonly
As you can see above, the arguments and tokens are returned as <a
- href="http://www.boost.org/doc/libs/1_33_1/libs/range/doc/utility_class.html#iter_range">
+ href="http://www.boost.org/doc/libs/release/libs/range/doc/html/range/reference/utilities/iterator_range.html">
boost::iterator_range</a> instances. These behave much like containers: They have \c begin() and
\c end() and some other useful members.
// compile-command: "scons -u test"
// mode: auto-fill
// End:
-
projects / senf.git / blobdiff