// $Id$
//
-// Copyright (C) 2008
+// 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
nodes.
\li There exist several interfaces to \link console_access access\endlink entries in the node
tree: interactive console, reading configuration files etc.
-
+
The node tree works like a directory structure. Commands are entered into this directory
structure and can be called passing arbitrary arguments. Configuration parameters are just
commands which set their respective parameter, however the library allows commands to do much
}
namespace kw = senf::console::kw;
+ namespace fty = senf::console::factory;
int main(int argc, char** argv)
{
.doc("This is someServer server");
// Add a command
- senf::console::root()
- .add("mycommand", &mycommand)
+ senf::console::root().add("mycommand", fty::Command(&mycommand)
.doc("If <bar> is given, flurgle the <foo>, otherwise burgle it")
.arg("foo")
- .arg(kw::name = "bar", kw::default_value = 0);
+ .arg(kw::name = "bar", kw::default_value = 0) );
// Parse command line parameters
senf::console::parseOptions(argc,argv);
</pre>
the console can be accessed easily via telnet:
-
+
<pre>
$ telnet localhost 23232
Trying 127.0.0.1...
and auxiliary commands. Parameters are just commands which set a parameter value so everything
is either a directory entry (senf::console::DirectoryNode) or a command
(senf::console::CommandNode).
-
+
\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
To get more flexible, instantiate a senf::console::ConfigFile instance at use that to parse the
file
-
+
\code
senf::console::ConfigFile cf ("some.conf");
// The following line is optional: Call to ignore mussing files
commands.
\code
/server/port 1234;
-
+
/logger/targets/console {
accept senf::log::Debug IMPORTANT;
accept server::ServerLog CRITICAL;
\endcode
This registeres two short options and accumulates all non-option arguments in \c args.
-
+
If the application supports other configuration sources besides the command line options (like
configuration files) see \ref console_access_multiple and add a senf::console::OptionsConfig()
source to a senf::console::ConfigBundle.
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>
<td><tt>/path/to/doo john.doe@everywhere.org;</tt></td>
<td><tt>--path-to-doo="john.doe@everywhere.org"</tt></td>
</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
</pre>
which is the same as
-
+
<pre>
$ 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
When used in it's default state, parsing will always interpret all commands relative to the
senf::console::root() node and will parse a file completely.
- The first possibility to control this is to change the root node. This is done by
+ The first possibility to control this is to change the root node. This is done by
\li passing that root node to the helper class or to the parse helper as an additional argument
(see the respective documentation).
\li passing it to the senf::console::ConfigBundle constructor when parsing multiple sources.
-
+
for example:
\code
parsing.
\code
- // Create a console/config aware object and place it into the node tree
+ // Create a console/config aware object and place it (that is it's directory node) into the node
+ // tree
FooObject foo;
senf::console::root().add("foo", foo.dir);
// Open configuration file
senf::console::ConfigFile cf ("/etc/myserver.conf");
-
+
// Parse only commands in the configuration file which are in the foo.dir directory
cf.parse(foo.dir);
senf::console::ConfigBundle conf (senf::console::root()["config"]);
conf.add( senf::console::FileConfig("/etc/myserver.conf") );
conf.add( senf::console::FileConfig(".myserver.conf")->ignoreMissing() );
- conf.add( senf::console::OptionsConfig(senf::Daemon::instance().argc(),
+ conf.add( senf::console::OptionsConfig(senf::Daemon::instance().argc(),
senf::Daemon::instance().argv()) )
.nonOptions(args)
.alias('c', "--mycommand",true)
// Parse the logger subsystem commands in '/logger'
conf.parse(senf::console::root()['logger']);
-
+
...
// Parse all other configuration commands. All necessary commands and links in '/config' must by
- // now have been created.
+ // now have been created.
conf.parse();
\endcode
// You need to enter the scheduler main-loop for the server to work
senf::scheduler::process();
-
+
// Alternatively enter the main-loop via the PPI
// senf::ppi::run();
}
int main(int, char**)
{
senf::console::Server & server ( senf::console::start( ... ) );
-
+
// Do something ...
server.stop()
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
+ \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
non-interactive mode. In this mode, no prompt is displayed. In this mode, commands are \e not
terminated automatically by end-of-line (CR). This allows, to easily cat an arbitrary
configuration file into the network console using netcat:
-
+
<pre>
$ nc -q1 localhost 23232 < some.conf
</pre>
</pre>
Commands are executed as soon as the terminating character (';', '{' or '}') is received or when
- the sending end of the connection is closed.
+ the sending end of the connection is closed.
\section console_udp Non-interactive UDP console
The UDP console allows to script the console tree via UDP packets. Every UDP packet must be a
complete command (or sequence of commands). The combined reply of all these commands will be
- returned in a single UDP packet. This reply can be disabled or directed to a different address.
+ returned in a single UDP packet. This reply can be disabled or directed to a different address.
To start a UDP server, just create an instance of the senf::console::UDPServer class
\code
/** \defgroup console_commands Supported command types
The Console/config library supports quite a number of different command types. All these types
- of command are registered, by passing them to DirectoryNode::add()
+ of command are registered by passing an appropriate factory instance to DirectoryNode::add()
\autotoc
\section console_cmdadd Adding commands and setting attributes
- Basically, all commands are added using senf::console::DirectoryNode::add(). What exactly
- happens depends on the type of object added.
+ Basically, all commands are added using senf::console::DirectoryNode::add().
\code
- dir.add("name", callback)
+ namespace fty = senf::console::factory;
+ dir.add("name", fty::Command(callback));
\endcode
- will add a command 'name' which will execute 'callback' when called, where 'callback' can be a
- lot of things as documented in the following chapters.
+ will add the command 'name' which will execute 'callback' when called.
The add call always returns (something which can be used as) a reference to the command node
added:
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 return value <b>before saving that value as a
- node reference</b>. It is \e not guaranteed, you can call these members on the node
- reference.
+ 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
- dir.add("name", callback)
- .doc("The documentation");
- \endcode
- sets the \e doc attribute (if that is available, otherwise this will fail to compile). The
- attribute members return value is again (something which can be used as) a reference to the
- command node
- \code
- senf::console::CommandNode & node (
- dir.add("name", callback)
- .doc("The documentation") );
+ namespace fty = senf::console::factory;
+ 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
os << value << std::endl;
}
\endcode
-
+
Registering this callback is done by simply adding it. To provide online help, pass it to
'doc()':
\code
- senf::console::root()
- .add("test1", &fun1)
+ namespace fty = senf::console::factory;
+ senf::console::root().add("test1", fty::Command(&fun1)
.doc("Usage:\n"
" test1 arg\n"
"\n"
- "Echo 'arg' to the console");
+ "Echo 'arg' to the console") );
\endcode
The callback may now be called interactively on the console by it's registered name:
\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.
-
+
The parser will have divided the argument tokens into arguments already. This simplifies further
parsing. If however you want to access the list of argument tokens as a single list, you can do
so using senf::console::ParseCommandInfo::tokens().
-
+
Parsing arguments is quite simple but can get very tedious. To simplify this task, the parsing
can be delegated to the Console/config library. See the next section.
\section console_autoparse Automatic argument parsing
-
- To greatly simplify parsing complex commands, we turn to automatic argument parsing.
+
+ To greatly simplify parsing complex commands, we turn to automatic argument parsing.
\subsection console_autoadd Adding
This extremely simple callback may be registered by adding it to a senf::console::DirectoryNode.
\code
- senf::console::root()
- .add("test2", &fun2);
+ namespace fty = senf::console::factory;
+ senf::console::root().add("test2", fty::Command(&fun2));
\endcode
The functionality is now identical to \c test1:
\htmlonly
passed the current consoles output stream object in this argument. With this, the callback can
output arbitrary messages to the network console.
\code
+ namespace fty = senf::console::factory;
+
void fun3(std::ostream & os, unsigned n, std::string text)
{
while (n-- > 0) os << text << std::endl;
}
- senf::console::root()
- .add("test3", &fun3);
+ senf::console::root().add("test3", fty::Command(&fun3));
\endcode
This simple command can now be used thus:
Automatically parsed commands can be overloaded: You can register multiple commands under the
same name. Each overload is tried in turn until no SyntaxErrorException is raised.
\code
- senf::console::root()
- .add("test4", &fun3);
- senf::console::root()
- .add("test4", &fun2);
+ namespace fty = senf::console::factory;
+
+ senf::console::root().add("test4", fty::Command(&fun3));
+ senf::console::root().add("test4", fty::Command(&fun2));
\endcode
And now, we can call \c test4 with one or two args:
<pre>
Utils/membind.hh to simplify this:
\code
+ namespace fty = senf::console::factory;
+
void over(int);
void over(int,int);
- senf::console::root()
- .add("over", SENF_FNP(void, over, (int)));
- senf::console::root()
- .add("over", SENF_FNP(void, over, (int,int));
-
+ senf::console::root().add("over", fty::Command(SENF_FNP(void, over, (int))));
+ senf::console::root().add("over", fty::Command(SENF_FNP(void, over, (int,int)));
+
class SomeModule {
senf::console::ScopedDirectory<SomeModule> dir;
-
+
unsigned int overlodedMethod() const {....};
void overlodedMethod(unsigned int) {....};
-
+
void addConsoleCommands() {
- dir.node().add("overlodedMethod",
- SENF_MEMBINDFNP(unsigned int, SomeModule, overlodedMethod, () const));
- dir.node().add("overlodedMethod",
- SENF_MEMBINDFNP(unsigned int, SomeModule, overlodedMethod, (unsigned int));
+ dir.node()
+ .add("overlodedMethod", fty::Command(
+ SENF_MEMBINDFNP(unsigned int, SomeModule, overlodedMethod, () const)));
+ dir.node()
+ .add("overlodedMethod", fty::Command(
+ SENF_MEMBINDFNP(unsigned int, SomeModule, overlodedMethod, (unsigned int))));
}
}
\endcode
\subsection console_attributes Attributes
As have seen so far, some documentation is automatically provided. We can add more info, by
- setting additional attributes.
+ setting additional attributes.
\code
- senf::console::root()
- .add("test5", &fun3)
+ namespace fty = senf::console::factory;
+
+ senf::console::root().add("test5", fty::Command(&fun3)
.doc("Echo text to the console")
- .overloadDoc("Repeat {arg12} for {arg11} lines");
- senf::console::root()
- .add("test4", &fun2)
- .overloadDoc("Echo the {arg21} argument")
+ .overloadDoc("Repeat {arg12} for {arg11} lines") );
+ senf::console::root().add("test4", fty::Command(&fun2)
+ .overloadDoc("Echo the {arg21} argument") );
\endcode
This additional info is used to provide more documentation:
Variant 1:
Repeat {arg12} for {arg11} lines
-
+
Variant 2:
Echo the {arg21} argument
senf:/$
\code
namespace kw = senf::console::kw;
+ namespace fty = senf::console::factory;
- senf::console::root()
- .add("test6", &fun3)
+ senf::console::root().add("test6", fty::Command(&fun3)
.doc("Echo text to the console")
.overloadDoc("Repeat {text} for {n} lines");
.arg( kw::name = "n", kw::description="Number of repetitions" )
- .arg( kw::name = "text", kw::description="Text to output" );
- senf::console::root()
- .add("test6", &fun2)
+ .arg( kw::name = "text", kw::description="Text to output" ) );
+ senf::console::root().add("test6", fty::Command(&fun2)
.overloadDoc("Echo the {text} argument")
- .arg( kw::name = "text" );
+ .arg( kw::name = "text" ) );
\endcode
(Sadly, there is no way to automatically find out the \e name of an argument, just it's type.)
Variant 1:
Repeat {text} for {n} lines
-
+
Variant 2:
Echo the {text} argument
senf:/$
order. So the following will give the exactly same result as above:
\code
namespace kw = senf::console::kw;
+ namespace fty = senf::console::factory;
- senf::console::root()
- .add("test6", &fun3)
+ senf::console::root().add("test6", fty::Command(&fun3)
.doc("Echo text to the console")
.overloadDoc("Repeat <text> for <n> lines");
.arg("n", "Number of repetitions")
- .arg("text", "Text to output");
- senf::console::root()
- .add("test6", &fun2)
- .overloadDoc("Echo the <text> argument")
+ .arg("text", "Text to output") );
+ senf::console::root().add("test6", fty::Command(&fun2)
+ .overloadDoc("Echo the <text> argument") );
.arg("text");
\endcode
-
+
Keyword arguments should always be used if additional attributes are set. You can however mix
positional and keyword arguments.
-
+
\subsection console_defaults Default values
-
+
Another information which can not be automatically gathered from the type system is default
values. These have to be declared explicitly:
\code
namespace kw = senf::console::kw;
+ namespace fty = senf::console::factory;
- senf::console::root()
- .add("test7", &fun3)
+ senf::console::root().add("test7", fty::Command(&fun3)
.doc("Echo {text} to the console, repeating {text} for {n} lines")
.arg("n", "Number of repetitions", kw::default_value=1)
- .arg("text", "Text to output");
+ .arg("text", "Text to output") );
\endcode
Default values can be used together with overloading. Default (optional) value support is quite
flexible, it is not mandatory, for default values to be specified only for the trailing
arguments. For the exact definition, how parsed argument values are assigned to overload
arguments in the presence of default values, see \ref senf::console::kw::default_value.
-
+
\htmlonly
<pre>
server:/$ test7 echo
server:/$ help test7
Usage:
test4 [n:unsigned] text:string
-
+
With:
n Number of repetitions
default: 1
It is possible to add other callable objects besides function (and member-function)
pointers. However, since it is not possible to automatically deduce the argument and return
- types in this case, the callables have to be wrapped in a \c boost::function object:
-
+ types in this case, the signature has to be specified explicitly:
\code
+ namespace fty = senf::console::factory;
+
senf::console::root()
- .add("test8",
- boost::function<void (std::ostream &, std::string const &)>(
- boost::bind(&fun3, _1, 4u, _2)));
+ .add("test8",fty::Command<void (std::ostream &, std::string const &)>(
+ boost::bind(&fun3, _1, 4u, _2)));
\endcode
This works with any callable object where argument types cannot be deduced automatically:
Boost.Bind expressions, Boost.Lambda expressions, functors and so on.
-
+
\htmlonly
<pre>
server:/$ test8 ok
<tr><td style="width:14em">\link senf::console::ParsedArgumentAttributorBase::doc() .doc\endlink
( \e doc )</td><td>Set documentation for all overloads</td></tr>
-
+
<tr><td>\link senf::console::ParsedArgumentAttributorBase::overloadDoc()
.overloadDoc\endlink ( \e doc )</td><td>Set documentation for a specific overload</td></tr>
</table>
The most important argument attributes (all defined in the senf::console::kw namespace) are:
-
+
<table class="senf fixed width">
<tr><td style="width:14em">\link senf::console::kw::name kw::name\endlink</td><td>Parameter
/ List of all members</a> for the complete attribute interface \n
\ref senf::console::kw for a list of all argument attribute keywords
-
+
\section console_memberfn Member functions
-
+
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
+ namespace fty = senf::console::factory;
+
class Test1
{
public:
senf::console::ScopedDirectory<Test1> dir;
- Test1(std::string label) : dir(this), label_ (label)
- { dir.add("test", &Test::test1);
- dir.add("test", &Test::test2); }
-
+ Test1(std::string label) : dir(this), label_ (label)
+ { dir.add("test", fty::Command(&Test::test1, this));
+ dir.add("test", fty::Command(&Test::test2, this)); }
+
std::string test1(std::string const & text)
{ return label_ + ": " + text; }
- void test2(std::ostream & os, unsigned n, std::string const & text)
+ void test2(std::ostream & os, unsigned n, std::string const & text)
{ while (n-- > 0) os << label << ": " << text << std::endl; }
private:
\section console_variables Variables
-
+
\subsection console_varadd Adding
The console/config library supports the direct registration of variables as commands. A
variable command consists of two overloads, one to query the current value and one to change the
- value.
+ value.
\code
+ namespace fty = senf::console::factory;
+
class Test2
{
public:
senf::console::ScopedDirectory<Test2> dir;
Test2() : dir(this), var_(0)
- { dir.add("var", var_); }
+ { dir.add("var", fty::Variable(var_) ); }
private:
int var_;
\subsection console_varro Read-only variables
-
+
The library also supports read-only variables. To make a variable read-only, just wrap it in \c
boost::cref() (where \c cref stands for \c const reference)
\code
+ namespace fty = senf::console::factory;
+
int var (0);
- senf::console::root().add("var1", boost::cref(var));
+ senf::console::root().add("var1", fty::Variable(boost::cref(var)));
\endcode
A read-only variable only has a single overload:
\htmlonly
server:/$ help var1
Usage:
var1
- server:/$
+ server:/$
</pre>
\endhtmlonly
<tr><td style="width:14em">\link senf::console::VariableAttributor::doc() .doc\endlink
( \e doc )</td><td>Set variable documentation</td></tr>
-
+
<tr><td>\link senf::console::VariableAttributor::onChange() .onChange\endlink
( \e handler )</td><td>Set change handler</td></tr>
-
+
</table>
\see senf::console::VariableAttributor for the complete attribute interface
reference to the old value. The handler is called, after the value has been changed
\code
+ namespace fty = senf::console::factory;
+
int var (0);
// Since this is int, it would make sense to declare the argument pass-by-value (int old)
// ...
}
- senf::console::root().add("var2",var)
- .onChange(&varChanged);
+ senf::console::root().add("var2", fty::Variable(var)
+ .onChange(&varChanged) );
\endcode
-
+
After this setup, \c varChanged will be called, whenever the value has changed.
- \section console_args Special types
+ \section console_args Console library supported types
+
+ By default, types which can be read and written using \c iostreams are automatically supported.
+ This includes all the C++ built-in types as well as user defined streamable types.
+
+ An exception is made for all \c char types: These types are by default parsed as \e numeric
+ values not single-character data. To interpret \c char values as single-char strings, use \ref
+ senf::console::CharAsString.
+
+ \subsection console_args_stl STL container support
+
+ The %console library contains support for the STL container types: \c std::vector, \c
+ std::list, \c std::set, \c std::multiset, \c std::map and \c std::multimap.
+
+ All container types are parsed as parenthesized list of elements. Each element is parsed as
+ defined for the element type:
+
+ \c vector, \c list or \c set of integers:
+ <pre>
+ (1 2 3)
+ </pre>
+
+ \c vector, \c list or \c set of strings:
+ <pre>
+ ("String 1" "String 2" "String 3")
+ </pre>
+
+ \c vector, \c list or \c set of <tt>pair<int,string></tt>:
+ <pre>
+ ((1 "String 1") (2 "String 2") (3 "String 3"))
+ </pre>
+
+ Empty collection:
+ <pre>
+ ()
+ </pre>
- By default, types which can be read and written using \c iostreams are automatically
- supported. Other types need to be registered explicitly
+ Collection's with only one element may skip the parenthesis <em>if and only if</em> the element
+ type does not need additional parenthesis
+
+ A \c vector, \c list or \c set of integer with one element may be written with or without
+ parenthesis:
+ <pre>
+ (1)
+ 1
+ </pre>
+
+ \e but a single element \c vector, \c list or \c set of <tt>pair<int,string></tt> may \e only be
+ written:
+ <pre>
+ ((1 "String 1"))
+ </pre>
+
+ In mapping containers, the key and value are separated by \c =:
+ <pre>
+ (foo=1 bar=2 "foo bar"=3)
+ </pre>
\subsection console_args_bool Boolean arguments and return values
The console library by default formats boolean values using the strings \c true and \c false for
their representation. When parsing a boolean value, most sensible representations will be
accepted:
-
+
<table class="senf">
<tr><td>\c true</td> <td>\c false</td> <td>\ref senf::console::formatTrueFalse</td></tr>
<tr><td>\c on</td> <td>\c off</td> <td>\ref senf::console::formatOnOff</td></tr>
The last column lists explicit formatters which can be set to customize the return value
formatting of a registered overload accordingly.
-
+
\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
+ namespace fty = senf::console::factory;
+
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);
+ senf::console::root().add("test9", fty::Command(&fun4));
\endcode
After an enum type is registered, it can be used like any other type for arguments or
register enums defined within some class, use \ref SENF_CONSOLE_REGISTER_ENUM_MEMBER()
\code
+ namespace fty = senf::console::factory;
+
class Test3
{
public:
enum Color { Red, Green, Blue };
-
+
senf::console::ScopedDirectory<Test3> dir;
Test3();
SENF_CONSOLE_REGISTER_ENUM_MEMBER( Test3, Color, (Red)(Green)(Blue) );
Test3::Test3() : dir(this)
- { dir.add("test", &Test3::mem3); }
-
+ { dir.add("test", fty::Command(&Test3::mem3, this)); }
+
Test3 test3ob;
senf::console::root().add("test3ob", test3ob.dir);
\endcode
\subsection console_args_convert Handling argument types by conversion
Sometimes an argument type is best handled by just pretending it to be of some other type. The
- basic idea is, to us \c boost::function to convert the real argument type to some different type
+ basic idea is, to provide an explicit signature with different (but compatible) types to the
+ factory:
\code
- unsigned char fun4(unsigned char value)
+ namespace fty = senf::console::factory;
+
+ int fun4(int value)
{
return value;
}
-
+
senf::console::root()
- .add("test8", boost::function<unsigned (unsigned)>(&fun4));
+ .add("test8", fty::Command<bool (bool)>(&fun4));
\endcode
-
- Here, the type signature specified via \c boost::function is different from the real type
- signature but is compatible. \c boost::function automatically handles the conversion
- process. Since the console library now sees the argument and return value of type \c unsigned,
- the values will be parsed correctly as numeric values.
-
+ Here, the type signature passed to fty::Command is different from the real type signature but it
+ is compatible, the conversion is handled automatically. Since the console library now sees the
+ argument and return value of type \c bool, the values will be parsed and formatted as boolean
+ values.
+
+
\subsection console_args_special Special Console types
The %console library defines some special types to be used as arguments and/or return values.
{
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 senf::console::CheckedArgumentIteratorWrapper ensures two things: That all input
The formatter writes out the value as a parenthesized pair.
\code
+ namespace fty = senf::console::factory;
+
Coordinate fun5(Coordinate const & p) { return Coordinate(2*p.x, 2*p.y) }
-
+
namespace kw = senf::console::kw;
senf::console::root()
- .add("test10", &fun5)
+ .add("test10", fty::Command(&fun5))
.arg("x","coordinate to double",
kw::default_value = Coordinate())
\endcode
server:/$
</pre>
\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
// compile-command: "scons -u test"
// mode: auto-fill
// End:
-
projects / senf.git / blobdiff