// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-/** \mainpage The Configuration and Runtime Control Framework
+/** \mainpage The Configuration and Runtime Control Library
The Console library implements a runtime interactive (network) console which allows to
configure, control and manipulate a running application in any way. Additionally this library
provides support for configuration files and command line parsing which can be used with or
without the network console.
- \section console_intro Introduction
+ \autotoc
- There are two components to the Config/console framework:
+ \section console_intro Introduction
- \li Building the node tree by registering objects and callbacks
- \li Utilizing the config/console framework by writing configuration files or using the
- interactive console.
+ There are three parts to the Config/console library:
- Basic data structure of the console and config framework is the config/console node tree. This
- tree. This tree works like a file-system. Commands are added to this tree and can then be called
- from configuration files or from the interactive console.
+ \li The console/config library is based on a \link node_tree tree of console/config
+ nodes. \endlink
+ \li Besides directories, the node contains command nodes. Commands are based on \link
+ console_commands variables or callbacks.\endlink
+ \li The console/config library is utilized by writing configuration files or interactive
+ commands in \link console_parser the console/config language.\endlink
- To get started using the config/console library, see
- \li \ref node_tree
- \li \ref console_parser
- \li \ref console_commands
+ 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
+ more than just that.
\section console_example Example
\code
// Define callback function.
- void mycommand(std::ostream & os, senf::console::ParseCommandInfo const & command)
+ void mycommand(std::ostream & os, int foo, int bar)
{
// ...
os << "!! Important message ...\n";
}
+ namespace kw = senf::console::kw;
+
int main(int, char**)
{
// Provide global documentation
// Add a command
senf::console::root()
.add("mycommand", &mycommand)
- .doc("mycommand <foo> [<bar>]\n\n"
- "If <bar> is given, flurgle the <foo>, otherwise burgle it");
+ .doc("If <bar> is given, flurgle the <foo>, otherwise burgle it")
+ .arg("foo")
+ .arg(kw::name = "bar", kw::default_value = 0);
// Start the interactive console server
senf::console::Server::start(senf::INet4SocketAddress(senf::INet4Address::None, 23232u))
Connection closed by foreign host.
$
</pre>
+
+
+ \section intro_nodes The node tree
+
+ The basic idea is, that the console/config library manages a directory structure of parameters
+ 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).
+
+ \see \ref node_tree
+
+
+ \section intro_commands 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
+ conversion.
+
+ Since parsing the tokens into something usable is quite tedious and error prone, the library
+ implements automatic argument parsing where the argument tokens are automatically parsed
+ depending on argument types. This enables you to register a command taking an integer argument
+ which will be called with an already parsed integer value (or throw a
+ senf::console::SyntaxErrorException if the conversion fails). This will be the most often used
+ command.
+
+ \see \ref console_commands
+
+
+ \section intro_language The console/config language
+
+ To call the commands and set parameters, a very simple language is defined. The language is
+ almost declarative (e.g. it does not have any control-flow statements) but is processed
+ imperatively from top to bottom. This is very simple and flexible.
+
+ Commands are referenced by their path in the node tree. To simplify working with deeply nested
+ directory structures, the current directory may be changed persistently or temporarily for some
+ commands.
+ \code
+ /server/port 1234;
+
+ /logger/targets/console {
+ accept senf::log::Debug IMPORTANT;
+ accept server::ServerLog CRITICAL;
+ }
+ \endcode
+
+ \see \ref console_parser
*/
/** \defgroup console_commands Supported command types
\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.
+ \code
+ dir.add("name", 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.
+
+ The add call always returns (something which can be used as) a reference to the command node
+ added:
+ \code
+ senf::console::CommandNode & node ( dir.add( ... ) );
+ \endcode
+
+ 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.
+ \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") );
+ \endcode
+
+
\section console_manualparse Manually parsing command arguments
This is the most primitive type of command. It will be called with an output stream and with a
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.
+ This type of command has only a single attribute, \e doc to set the commands documentation.
+
\section console_autoparse Automatic argument parsing
- To greatly simplify parsing complex commands, we turn to automatic argument parsing. This
- feature allows to register (almost) arbitrary callbacks.
+ To greatly simplify parsing complex commands, we turn to automatic argument parsing.
+ \subsection console_autoadd Adding automatically parsed commands
+
+ Automatically parsed commands are registered by just adding a callback which has the correct
+ arguments and return-value defined:
\code
- std::string fun(std::string const & arg)
+ std::string fun2(std::string const & arg)
{
return arg;
}
\endcode
- This extremely simple callback may be registered by adding it to a
- senf::console::DirectoryNode.
+ This extremely simple callback may be registered by adding it to a senf::console::DirectoryNode.
\code
senf::console::root()
.add("test2", &fun2);
</pre>
\endhtmlonly
- As we can see, some documentation is automatically provided. To add more info, we need to add
- some additional attributes when registering the command:
+
+ \subsection command_ostream Accessing the console stream
+
+ Commands may have an optional first argument of type <tt>std::ostream &</tt>. 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
+ output arbitrary messages to the network console.
\code
- namespace kw = senf::console::kw;
+ void fun3(std::ostream & os, unsigned n, std::string text)
+ {
+ while (n-- > 0) os << text << std::endl;
+ }
senf::console::root()
- .add("test2", &test2)
- .doc("Echo 'arg' to the console")
- .arg( kw::name = "arg",
- kw::description = "Message to output" );
+ .add("test3", &fun3);
\endcode
- (Sadly, there is no way to automatically find out the \e name of an argument, just it's type.)
- Every callback argument corresponds with a call of the \c arg() attribute. Argument attributes
- are set using keywords from the \ref senf::console::kw namespace. You will probably wither use
- this namespace via a namespace alias (as above) or via a <tt>using namespace
- senf::console::kw</tt> declaration (as in all the following examples)
+ This simple command can now be used thus:
+ \htmlonly
+ <pre>
+ server:/$ test3
+ invalid number of arguments
+ server:/$ test3 stefan@j32.de
+ invalid number of arguments
+ server:/$ test3 2 ok
+ ok
+ ok
+ server:/$ help test3
+ Usage:
+ test3 arg11:int arg12:string
+ server:/$
+ </pre>
+ \endhtmlonly
+
+ \subsection command_overload Command overloading
+
+ 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);
+ \endcode
+ And now, we can call \c test4 with one or two args:
+ <pre>
+ server:/$ test4
+ invalid number of arguments
+ server:/$ test4 stefan@j32.de
+ stefan@j32.de
+ server:/$ test4 2 ok
+ ok
+ ok
+ server:/$ help test4
+ Usage:
+ 1- test4 arg11:int arg12:string
+ 2- test4 arg21:string
+ server:/$
+ </pre>
- You don't need
- to specify any information for an argument: To skip an argument, just call \c arg() without
- attributes for this argument.
+ \subsection console_attributes Attributes of automatically parsed commands
- After adding this information, the online help is much more intelligible
+ As have seen so far, some documentation is automatically provided. We can add more info, by
+ setting additional attributes.
+ \code
+ senf::console::root()
+ .add("test5", &fun3)
+ .doc("Echo text to the console")
+ .overloadDoc("Repeat {arg12} for {arg11} lines");
+ senf::console::root()
+ .add("test4", &fun2)
+ .overloadDoc("Echo the {arg21} argument")
+ \endcode
+
+ This additional info is used to provide more documentation:
\htmlonly
<pre>
- server:/$ help test2
+ server:/$ help test5
Usage:
- test2 arg:string
+ 1- test5 arg11:int arg12:string
+ 2- test5 arg21:string
- With:
- arg Message to output
+ Echo text to the console
- Echo 'arg' to the console
- server:/$
+ Variant 1:
+ Repeat {arg12} for {arg11} lines
+
+ Variant 2:
+ Echo the {arg21} argument
+ senf:/$
</pre>
\endhtmlonly
- \subsection command_ostream Accessing the console stream
-
- Commands may have an optional first argument of type <tt>std::ostream &</tt>. 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
- output arbitrary messages to the network console. See the next section for an example.
- \subsection command_overload Command overloading
+ \subsection console_argattributes Argument attributes
- Automatically parsed commands can be overloaded: You can register multiple commands under the
- same name. If this happens, each command is tried in turn until no SyntaxErrorException is
- raised.
+ Additional attributes can be set for each parameter. They are all passed to the
+ senf::console::ParsedArgumentAttributor::arg() attribute.
\code
- void fun3(std::ostream & os, unsigned n, std::string text)
- {
- // It's perfectly valid to check additional constraints here and throw a
- // SyntaxErrorException. In this case, the next overload will be tried. However, you must
- // ensure, That no action takes place before this check !
- if ( n==0 ) throw senf::console::SyntaxErrorException("invalid value for parameter 'n'");
- while (n-- > 0) os << text << std::endl;
- }
+ namespace kw = senf::console::kw;
- using namespace senf::console::kw;
-
senf::console::root()
- .add("test3", &fun3)
+ .add("test6", &fun3)
.doc("Echo text to the console")
- .overloadDoc("Repeat 'text' for 'n' lines")
- .arg( name = "n", description = "Number of repetitions" )
- .arg( name = "text", description = "Message to output" );
+ .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("test3", &fun2)
- .overloadDoc("Echo the 'text' argument")
- .arg( name = "text" );
+ .add("test6", &fun2)
+ .overloadDoc("Echo the {text} argument")
+ .arg( kw::name = "text" );
\endcode
- We can now call \c test3 with one or two arguments:
+ (Sadly, there is no way to automatically find out the \e name of an argument, just it's type.)
+ Every callback argument corresponds with a call of the \c arg() attribute. Argument attributes
+ are set using keywords from the \ref senf::console::kw namespace. You will probably either use
+ this namespace via a namespace alias (as above) or via a <tt>using namespace
+ senf::console::kw</tt> declaration (but beware of name collisions).
- \htmlonly
+ You don't need to specify any information for an argument: To skip an argument, just call \c
+ arg() without attributes for this argument.
+
+ After adding this information, the online help is much more readable
+ \htmlonly
<pre>
- server:/$ test3 "The sky is blue"
- The sky is blue
- server:/$ test3 4 ok
- ok
- ok
- ok
- ok
- server:/$ help test3
+ server:/$ help test6
Usage:
- 1- test3 n:unsigned text:string
- 2- test3 text:string
-
+ 1- test6 n:int text:string
+ 2- test6 text:string
+
With:
- n Numer of repetitions
- text Messsage to output
+ n Number of repetitions
+ text Text to output
Echo text to the console
Variant 1:
- Repeat 'text' for 'n' lines
+ Repeat {text} for {n} lines
Variant 2:
- Echo the 'text' argument
- senf:/$ And
-
+ Echo the {text} argument
+ senf:/$
</pre>
\endhtmlonly
+
+ \subsection console_argattribpos Passing argument attributes as positional arguments
+
+ Since most of the time, we only need to set the name and possibly a description for arguments,
+ there is a shortcut: name and description can be specified as positional arguments in this
+ order. So the following will give the exactly same result as the example in the previous section
+
+ \code
+ namespace kw = senf::console::kw;
+
+ senf::console::root()
+ .add("test6", &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");
+ \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 explicitly declared:
+ values. These have to be declared explicitly:
\code
- using namespace senf::console::kw;
+ namespace kw = senf::console::kw;
senf::console::root()
- .add("test4", &fun3)
- .arg( name = "n", description = "Number of repetitions", default_value = 1 )
- .arg( name = "text", description = "Message to output" );
+ .add("test7", &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");
\endcode
- (Default values must not necessarily be declared in the callback function too.) Of course,
- default values can be used together with overloading. Default (optional) value support is quite
+ 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.
+ 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:/$ test4 echo
+ server:/$ test7 echo
echo
- server:/$ test4 4 ok
+ server:/$ test7 4 ok
ok
ok
ok
ok
- server:/$ help test4
+ server:/$ help test7
Usage:
test4 [n:unsigned] text:string
With:
n Number of repetitions
- text Message to output
- default value: ok
+ default: 1
+ text Text to output
+
+ Echo {text} to the console, repeating {text} for {n} lines
server:/$
</pre>
\endhtmlonly
- \subsection console_auto_summary Attribute summary
+ \subsection console_attr_summary Attribute summary
+
+ Here a summary of the most common attributes
- Here a summary of all the attributes available for automatically parsed command nodes:
-
<table class="senf fixedwidth">
-
- <tr><td style="width:12em">\c doc ( \e text )</td><td>Documentation for all overloads</td></tr>
- <tr><td>\c overloadDoc ( \e text )</td><td>Documentation for a specific overliad</td></tr>
+ <tr><td>\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>
- <tr><td>\c arg ( \e attributes )</td><td>Set parameter attributes. All attributes are
- optional. The attribute keywords are defined in the \ref senf::console::kw namespace. Valid
- Attributes are:
- \li \e name: Parameter name
- \li \e description: One-line description of the argument
- \li \e default_value: Arguments default value</td></tr>
+ <tr><td>\link senf::console::ParsedArgumentAttributor::arg() .arg\endlink ( \e argument \e
+ attributes )</td><td>Set argument attributes (see below)</td></tr>
</table>
- See senf::console::ParsedArgumentAttributor 'List of all members'
+ The most important argument attributes (all defined in the senf::console::kw namespace) are:
+ <table class="senf fixed width">
+
+ <tr><td>\link senf::console::kw::name kw::name\endlink</td><td>Parameter name</td></tr>
+
+ <tr><td>\link senf::console::kw::description kw::description\endlink</td><td>One-line
+ description of the argument</td></tr>
+
+ <tr><td>\link senf::console::kw::default_value kw::default_value\endlink</td><td>Arguments
+ default value</td></tr>
+
+ </table>
+
+ \see <a
+ href="classsenf_1_1console_1_1ParsedArgumentAttributor-members.html">senf::console::ParsedArgumentAttributor
+ / 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 Registering member functions
Member functions are supported like non-member functions. They must however be added through a
public:
senf::console::ScopedDirectory<Test> dir;
- Test(std::string label) : dir(this), label_ (label) {
+ Test(std::string label) : dir(this), label_ (label)
+ {
dir.add("test4", &Test::test2);
dir.add("test4", &Test::test3);
}
- std::string test2(std::string const & text) { return label_ + ": " + text; }
- void test3(std::ostream & os, unsigned n, std::string const & text) {
- while (n-- > 0) os << label << ": " << text << std::endl; }
+ std::string test2(std::string const & text)
+ { return label_ + ": " + text; }
+
+ void test3(std::ostream & os, unsigned n, std::string const & text)
+ { while (n-- > 0) os << label << ": " << text << std::endl; }
private:
std::string label_;
if (! arg.defaultValue.empty())
os << ']';
- if (! arg.name.empty()) {
+ if (! arg.name.empty() || ! arg.defaultValue.empty()) {
ArgumentDocs::iterator k (argumentDocs.begin());
ArgumentDocs::iterator const k_end (argumentDocs.end());
for (; k != k_end; ++k)
ArgumentDocs::const_iterator i (argumentDocs.begin());
ArgumentDocs::const_iterator const i_end (argumentDocs.end());
for (; i != i_end; ++i) {
- if (! i->doc.empty()) {
+ if (! i->doc.empty() || ! i->defaultValue.empty()) {
os << " "
<< i->name
<< std::string(i->name.length()<8 ? 8-i->name.length() : 0, ' ')
? (boost::format("arg%d%d") % overloadIndex() % (index+1)).str()
: arg.name;
doc.type = arg.type;
- doc.defaultValue = arg.defaultValueStr();
+ if (arg.hasDefault) {
+ doc.defaultValue = arg.defaultDoc.empty()
+ ? arg.defaultValueStr()
+ : arg.defaultDoc;
+ if (doc.defaultValue.empty())
+ doc.defaultValue = "(empty)";
+ }
doc.doc = arg.doc;
}
overload().arg(index_).doc = doc;
}
+prefix_ void senf::console::ParsedCommandAttributorBase::typeName(std::string const & doc)
+ const
+{
+ overload().arg(index_).type = doc;
+}
+
+prefix_ void senf::console::ParsedCommandAttributorBase::defaultDoc(std::string const & doc)
+ const
+{
+ overload().arg(index_).defaultDoc = doc;
+}
+
prefix_ senf::console::ParsedCommandOverloadBase &
senf::console::ParsedCommandAttributorBase::overload()
const
// Custom includes
#include "../Utils/membind.hh"
#include <boost/format.hpp>
-#include <boost/parameter/binding.hpp>
+#include "../Utils/parameter.hh"
#define prefix_ inline
///////////////////////////////cti.p///////////////////////////////////////
overload().arg(index_).hasDefault = true;
}
+template <class Type, class Fn>
+prefix_ void senf::console::ParsedCommandAttributorBase::parser(Fn fn)
+ const
+{
+ overload().arg<Type>(index_).parser = fn;
+}
+
///////////////////////////////////////////////////////////////////////////
// senf::console::ParsedCommandAttributor<Overload>
argInfo(ArgumentPack const & args)
const
{
-# define HaveArg(tag) boost::is_same< \
- typename boost::parameter::binding<ArgumentPack, tag>::type, void >()
+# define ProcessArg(tag) \
+ argInfo( kw:: tag, args, senf::has_parameter< ArgumentPack, kw::type:: tag >() )
- argInfo( kw::name, args, HaveArg(kw::type::name) );
- argInfo( kw::description, args, HaveArg(kw::type::description) );
- argInfo( kw::default_value, args, HaveArg(kw::type::default_value) );
+ ProcessArg(name);
+ ProcessArg(description);
+ ProcessArg(default_value);
+ ProcessArg(type_name);
+ ProcessArg(default_doc);
+ ProcessArg(parser);
return next();
template <class Overload, unsigned index, bool flag>
template <class Kw, class ArgumentPack>
prefix_ void senf::console::ParsedArgumentAttributor<Overload,index,flag>::
-argInfo(Kw const &, ArgumentPack const &, boost::mpl::true_)
+argInfo(Kw const &, ArgumentPack const &, boost::mpl::false_)
const
{}
template <class ArgumentPack>
prefix_ void senf::console::ParsedArgumentAttributor<Overload,index,flag>::
argInfo(boost::parameter::keyword<kw::type::name> const &, ArgumentPack const & args,
- boost::mpl::false_)
+ boost::mpl::true_)
const
{
this->argName(args[kw::name]);
template <class ArgumentPack>
prefix_ void senf::console::ParsedArgumentAttributor<Overload,index,flag>::
argInfo(boost::parameter::keyword<kw::type::description> const &, ArgumentPack const & args,
- boost::mpl::false_)
+ boost::mpl::true_)
const
{
this->argDoc(args[kw::description]);
template <class ArgumentPack>
prefix_ void senf::console::ParsedArgumentAttributor<Overload,index,flag>::
argInfo(boost::parameter::keyword<kw::type::default_value> const &, ArgumentPack const & args,
- boost::mpl::false_)
+ boost::mpl::true_)
const
{
this->defaultValue(args[kw::default_value]);
}
template <class Overload, unsigned index, bool flag>
+template <class ArgumentPack>
+prefix_ void senf::console::ParsedArgumentAttributor<Overload,index,flag>::
+argInfo(boost::parameter::keyword<kw::type::type_name> const &, ArgumentPack const & args,
+ boost::mpl::true_)
+ const
+{
+ this->typeName(args[kw::type_name]);
+}
+
+template <class Overload, unsigned index, bool flag>
+template <class ArgumentPack>
+prefix_ void senf::console::ParsedArgumentAttributor<Overload,index,flag>::
+argInfo(boost::parameter::keyword<kw::type::default_doc> const &, ArgumentPack const & args,
+ boost::mpl::true_)
+ const
+{
+ BOOST_STATIC_ASSERT(( senf::has_parameter<ArgumentPack, kw::type::default_value>::value ));
+ this->defaultDoc(args[kw::default_doc]);
+}
+
+template <class Overload, unsigned index, bool flag>
+template <class ArgumentPack>
+prefix_ void senf::console::ParsedArgumentAttributor<Overload,index,flag>::
+argInfo(boost::parameter::keyword<kw::type::parser> const &, ArgumentPack const & args,
+ boost::mpl::true_)
+ const
+{
+ this->parser(args[kw::parser]);
+}
+
+template <class Overload, unsigned index, bool flag>
prefix_
senf::console::ParsedArgumentAttributor<Overload,index,flag>::
ParsedArgumentAttributor(Overload & overload)
defaultValue(value_type const & value)
const
{
- ParsedCommandAttributorBase::defaultValue<arg_type>(value);
+ ParsedCommandAttributorBase::defaultValue<value_type>(value);
+}
+
+template <class Overload, unsigned index, bool flag>
+template <class Fn>
+prefix_ void senf::console::ParsedArgumentAttributor<Overload,index,flag>::parser(Fn fn)
+ const
+{
+ ParsedCommandAttributorBase::parser<value_type>(fn);
}
///////////////////////////////////////////////////////////////////////////
#define HH_ParsedCommand_ 1
// Custom includes
+
+#define BOOST_PARAMETER_MAX_ARITY 6
+
#include <vector>
#include <boost/type_traits/function_traits.hpp>
#include <boost/type_traits/is_member_pointer.hpp>
-#include <boost/type_traits/is_same.hpp>
#include <boost/mpl/if.hpp>
#include <boost/utility.hpp>
#include <boost/parameter/keyword.hpp>
This class is the base class for those attributors. It provides members which do not depend
in any way on the exact type of command added.
+
+ \see \ref console_autoparse
*/
class ParsedCommandAttributorBase
{
void argName(std::string const & name) const;
void argDoc(std::string const & doc) const;
template <class Type> void defaultValue(Type const & value) const;
+ void typeName(std::string const & doc) const;
+ void defaultDoc(std::string const & doc) const;
+ template <class Type, class Fn> void parser(Fn fn) const;
ParsedCommandOverloadBase & overload() const;
void overloadDoc(std::string const & doc) const;
This class adds all those members, which do depend on the type of command added (and thereby
on that commands signature) but do not depend on the type of any single argument.
-
- \fixme Implement compile-time checking, that after a defaulted arg only defaulted args are
- allowed.
+
+ \see \ref console_autoparse
*/
template <class Overload>
class ParsedCommandAttributor
href="http://www.boost.org/doc/libs/1_33_1/libs/parameter/doc/html/index.html">Boost.Parameter</a>
library.
- For the keyword tags, the standard C++ scoping rules apply:
- \li Either qualify them with their complete namespace: <tt>arg( senf::console::kw::name =
- "name" )</tt>
- \li or use a namespace alias: <tt>namespace kw = senf::console::kw; arg( kw::name = "name"
- );</tt>
- \li import the keywords into your namespace: <tt>using namespace senf::console::kw; arg(
- name = "name");</tt>
+ For the keyword tags, the standard C++ scoping rules apply
+ \code
+ // Either qualify them with their complete namespace
+ dir.add(...)
+ .arg( senf::console::kw::name = "name" );
+
+ // Or use a namespace alias
+ namespace kw = senf::console::kw;
+ dir.add(...)
+ .arg( kw::name = "name" );
+
+ // Or import the keywords into the current namespace (beware of name collisions)
+ using namespace senf::console::kw;
+ dir.add(...)
+ .arg( name = "name" );
+ \endcode
The second alternative is preferred, the <tt>using namespace</tt> directive may be used as
long as the keyword names do not clash with another visible symbol.
+
+ \section kw_attributes Argument attribute values
+
+ The keywords are used to set argument attributes. The keywords \ref default_value and \ref
+ parser influence, how an argument is parsed/interpreted whereas \ref name, \ref description,
+ \ref type_name and \ref default_doc are used to change the arguments documentation:
+ \code
+ void command(int);
+
+ dir.add("command", &command)
+ .arg( kw::name = "name",
+ kw::description = "description",
+ kw::default_value = 1,
+ kw::type_name = "type_name",
+ kw::default_doc = "default_doc" );
+ \endcode
+ Will create the following documentation:
+ \htmlonly
+ <pre>
+ Usage:
+ command [name:type_name]
+
+ With:
+ name description
+ default: default_doc
+ </pre>
+ \endhtmlonly
+
+ \see \ref senf::console::ParsedArgumentAttributor::arg()
*/
namespace kw {
BOOST_PARAMETER_KEYWORD(type, name) ///< Argument name
- BOOST_PARAMETER_KEYWORD(type, description) ///< One-line Argument description
+ /**< Sets the displayed name of the argument. */
+ BOOST_PARAMETER_KEYWORD(type, description) ///< One-line argument description
+ /**< This description is shown in the argument
+ reference. If several overloads have same-named
+ arguments, only one of them should be documented. This
+ documentation then applies to all arguments of that
+ name. */
BOOST_PARAMETER_KEYWORD(type, default_value) ///< Argument default value
+ /**< If a default value is specified for an argument, that
+ argument is optional. If an overload is called with
+ fewer arguments than defined, optional values will be
+ used beginning at the last optional argument and going
+ forward until all arguments have values assigned. E.g.,
+ an overload with 5 parameters \a a - \a e with two
+ defaults attached:
+ <pre>
+ command a:int [b:int] c:int [d:int] e:int
+ </pre>
+ When calling the overload, the arguments will be
+ assigned in the following way:
+ <table class="senf fixedwidth">
+ <tr>
+ <td><tt>command 1 2</tt></td>
+ <td>SyntaxErrorException: invalid number of
+ arguments</td>
+ </tr>
+ <tr>
+ <td><tt>command 1 2 3</tt></td>
+ <td>\a a = 1, \n
+ \a b = \e default, \n
+ \a c = 2, \n
+ \a d = \e default, \n
+ \a e = 3</td>
+ </tr>
+ <tr>
+ <td><tt>command 1 2 3 4</tt></td>
+ <td>\a a = 1, \n
+ \a b = 2, \n
+ \a c = 3, \n
+ \a d = \e default, \n
+ \a e = 4</td>
+ </tr>
+ <tr>
+ <td><tt>command 1 2 3 4 5</tt></td>
+ <td>\a a = 1, \n
+ \a b = 2, \n
+ \a c = 3, \n
+ \a d = 4, \n
+ \a e = 5</td>
+ </tr>
+ <tr>
+ <td><tt>command 1 2 3 4 5 6</tt></td>
+ <td>SyntaxErrorException: invalid number of
+ arguments</td>
+ </tr>
+ </table>
+ So, if you assign default values as you are used to
+ they will work like in C++ and most other languages */
+ BOOST_PARAMETER_KEYWORD(type, type_name) ///< Type name of this arguments type
+ /**< By default, the type of an argument is extracted from
+ the C++ type name by taking the last component of the
+ fully scoped name. This value can be changed by setting
+ this attribute. */
+ BOOST_PARAMETER_KEYWORD(type, default_doc) ///< String rep of default value
+ /**< By default, the default value is documented by
+ converting the value to it's string representation
+ using \c boost::lexical_cast / \c iostreams. The
+ displayed value can be changed by setting this
+ attribute. */
+ BOOST_PARAMETER_KEYWORD(type, parser) ///< Argument parser
+ /**< The argument parser is used to convert the argument
+ token list returned by the console/config parser into
+ the appropriate value. If not set explicitly, this
+ conversion is supplied by the ArgumentTraits
+ class.
+
+ Setting the \a parser attribute allows to use a custom
+ parser. The parser is an arbitrary callable object with
+ the signature
+ \code
+ void parser(senf::console::ParseCommandInfo::TokensRange const & tokens, value_type & out);
+ \endcode
+ where \c value_type is the type of the overload
+ parameter. The parser must read and parse the complete
+ \a tokens range and return the parsed value in \a
+ out. If the parser fails, it must raise a
+ senf::console::SyntaxErrorException. */
}
/** \brief Derived class dependent ParsedCommandBase attributes
This class adds all those members, which do not depend on any specific argument but which
need to return the correct attributor type.
+
+ \see \ref console_autoparse
*/
template <class Overload, class Self>
class ParsedArgumentAttributorBase
This class adds all those members, which depend on a specific argument. Each call to \c arg
will advance to the next argument.
+
+ \see \ref console_autoparse
*/
template < class Overload,
unsigned index=0,
typedef boost::parameter::parameters<
kw::type::name,
kw::type::description,
- kw::type::default_value> arg_params;
+ kw::type::default_value,
+ kw::type::type_name,
+ kw::type::default_doc,
+ kw::type::parser> arg_params;
public:
typedef OverloadedCommandNode node_type;
argument. The attributes are passed to arg() as keyword
arguments using the <a
href="http://www.boost.org/doc/libs/1_33_1/libs/parameter/doc/html/index.html">Boost.Parameter</a>
- library. The valid keywords are defined in the
- senf::console::kw namespace.
-
- This member is only present, if there is an argument at
- the current index. */
+ library.
+ \code
+ ...
+ .arg( kw::name = "name",
+ kw::default_value = 1 )
+ ...
+ \endcode
+ The valid keywords are defined in the senf::console::kw
+ namespace.
+
+ Each call to arg() will increment the argument index
+ and advance to the next argument. This member is only
+ present, if there is an argument at the current. */
#ifndef DOXYVEN
-# define BOOST_PP_ITERATION_PARAMS_1 \
- (4, (1, 3, SENF_ABSOLUTE_INCLUDE_PATH(Console/ParsedCommand.mpp), 5))
+# define BOOST_PP_ITERATION_PARAMS_1 \
+ (4, (1, BOOST_PARAMETER_MAX_ARITY, \
+ SENF_ABSOLUTE_INCLUDE_PATH(Console/ParsedCommand.mpp), \
+ 5))
# include BOOST_PP_ITERATE()
#endif
template <class ArgumentPack>
next_type argInfo(ArgumentPack const & args) const;
template <class Kw, class ArgumentPack>
- void argInfo(Kw const &, ArgumentPack const &, boost::mpl::true_)
+ void argInfo(Kw const &, ArgumentPack const &, boost::mpl::false_)
const;
template <class ArgumentPack>
void argInfo(boost::parameter::keyword<kw::type::name> const &,
- ArgumentPack const & args, boost::mpl::false_)
+ ArgumentPack const & args, boost::mpl::true_)
const;
template <class ArgumentPack>
void argInfo(boost::parameter::keyword<kw::type::description> const &,
- ArgumentPack const & args, boost::mpl::false_)
+ ArgumentPack const & args, boost::mpl::true_)
const;
template <class ArgumentPack>
void argInfo(boost::parameter::keyword<kw::type::default_value> const &,
- ArgumentPack const & args, boost::mpl::false_)
+ ArgumentPack const & args, boost::mpl::true_)
+ const;
+ template <class ArgumentPack>
+ void argInfo(boost::parameter::keyword<kw::type::type_name> const &,
+ ArgumentPack const & args, boost::mpl::true_)
+ const;
+ template <class ArgumentPack>
+ void argInfo(boost::parameter::keyword<kw::type::default_doc> const &,
+ ArgumentPack const & args, boost::mpl::true_)
+ const;
+ template <class ArgumentPack>
+ void argInfo(boost::parameter::keyword<kw::type::parser> const &,
+ ArgumentPack const & args, boost::mpl::true_)
const;
next_type next() const;
void defaultValue(value_type const & value) const;
+ template <class Fn> void parser(Fn fn) const;
template <class O, unsigned i, bool f>
friend class ParsedArgumentAttributor;
#define IH_ParsedCommand_ 1
// Custom includes
+#include <boost/function.hpp>
+#include <boost/intrusive_ptr.hpp>
+#include "Parse.hh"
///////////////////////////////ih.p////////////////////////////////////////
std::string type;
std::string name;
+ std::string defaultDoc;
bool hasDefault;
std::string doc;
: public ArgumentInfoBase
{
typedef boost::intrusive_ptr<ArgumentInfo> ptr;
+ typedef boost::function<void (ParseCommandInfo::TokensRange const &,
+ ParameterType &)> Parser;
static ptr create();
ArgumentInfo();
ParameterType defaultValue;
+ Parser parser;
virtual std::string defaultValueStr() const;
};
- template <class Function, bool isFN=senf::is_any_function<Function>::value>
- struct ParsedCommandTraits
- {};
-
// FirstArgType returns void, if the function has no arguments, otherwise it returns arg1_type
template <class Traits, bool flag=(Traits::arity>0)>
typedef typename Traits::arg1_type type;
};
+ template <class Function, bool isFN=senf::is_any_function<Function>::value>
+ struct ParsedCommandTraits
+ {};
+
template <class Function>
struct ParsedCommandTraits<Function, true>
{
riterator const i_end (boost::rend(command.arguments()));
# define mpp_l(z,n,d) \
- if (i == i_end) \
- throw SyntaxErrorException("invalid number of arguments"); \
mpp_ArgTypeN(n) mpp_ArgN(n) (arg< mpp_ArgTypeN(n) >( n ).defaultValue); \
- if (! arg(n).hasDefault || nDefaults-- <= 0) \
- ArgumentTraits< mpp_ArgTypeN(n) >::parse( *(i++), mpp_ArgN(n) );
+ if (! arg(n).hasDefault || nDefaults-- <= 0) { \
+ if (i == i_end) \
+ throw SyntaxErrorException("invalid number of arguments"); \
+ if (arg< mpp_ArgTypeN(n) >(n).parser) \
+ arg< mpp_ArgTypeN(n) >(n).parser( *(i++), mpp_ArgN(n) ); \
+ else \
+ ArgumentTraits< mpp_ArgTypeN(n) >::parse( *(i++), mpp_ArgN(n) ); \
+ }
# define mpp_l_(z,n,d) mpp_l(z, BOOST_PP_SUB(BOOST_PP_DEC(BOOST_PP_ITERATION()), n), d)
BOOST_PP_REPEAT( BOOST_PP_ITERATION(), mpp_l_, _ )
# undef mpp_l
double cb2(){ return 1.2; }
void cb3(int i) { }
std::string cb4(std::ostream & os) { os << "text\n"; return "value"; }
- void cb5(std::ostream & os, std::string v) { os << "Value: " << v << "\n"; }
+ void cb5(std::ostream & os, std::string const & v) { os << "Value: " << v << "\n"; }
+
+ struct TestParser
+ {
+ typedef senf::console::ParseCommandInfo::TokensRange const & first_argument_type;
+ typedef std::string & second_argument_type;
+ typedef void result_type;
+
+ result_type operator()(first_argument_type, second_argument_type out) const
+ { out = "true"; }
+ };
+
}
BOOST_AUTO_UNIT_TEST(parsedCommand)
}
{
+ namespace kw = senf::console::kw;
+ std::stringstream ss;
+
+ // Just for the fun of it, use a functor and not a function pointer as parser ...
+ dir.add("cb6", &cb5)
+ .arg( kw::parser = TestParser() );
+ BOOST_CHECK_NO_THROW(
+ parser.parse("test/cb6 false",
+ boost::bind<void>( boost::ref(executor), boost::ref(ss), _1 )) );
+ BOOST_CHECK_EQUAL( ss.str(), "Value: true\n" );
+
+ }
+
+ {
std::stringstream ss;
using namespace senf::console::kw;
.arg( description = "Bar didelfrump di desgorb. Nu widsoflar brimeldrgf." )
.arg( name = "checkup",
+ type_name = "number",
description = "Florgel, dargel and durgel",
- default_value = 2.1 );
+ default_value = 2.1,
+ default_doc = "(double) 2.1" );
senf::console::OverloadedCommandNode & cbNode (
dir.add("cb", &cb5)
.overloadDoc(
"Uus Primordia fundo falsidicus corium, diurnitas humo pro leto. Sui Ueraciter\n"
"hio eruca lenis qua Agalmate ut fors penitentia. Iugum obdormio anxio nuncupo\n"
- "iam, in vos nam Custodi." ) );
+ "iam, in vos nam Custodi." )
+ .arg( "text", default_value = "" ) );
(void) cbNode;
- dir.add("cb", &cb2);
-
- parser.parse("test/cb 111 222.4; test/cb 222; test/cb foo; test/cb",
- boost::bind<void>( boost::ref(executor), boost::ref(ss), _1 ));
- BOOST_CHECK_EQUAL( ss.str(), "333\n" "224\n" "Value: foo\n" "1.2\n" );
+ BOOST_CHECK_NO_THROW(
+ parser.parse("test/cb 111 222.4",
+ boost::bind<void>( boost::ref(executor), boost::ref(ss), _1 )) );
+ BOOST_CHECK_NO_THROW(
+ parser.parse("test/cb 222",
+ boost::bind<void>( boost::ref(executor), boost::ref(ss), _1 )) );
+ BOOST_CHECK_NO_THROW(
+ parser.parse("test/cb foo",
+ boost::bind<void>( boost::ref(executor), boost::ref(ss), _1 )) );
+ BOOST_CHECK_NO_THROW(
+ parser.parse("test/cb",
+ boost::bind<void>( boost::ref(executor), boost::ref(ss), _1 )) );
+
+ BOOST_CHECK_EQUAL( ss.str(), "333\n" "224\n" "Value: foo\n" "Value: \n" );
}
{
BOOST_CHECK_EQUAL(
ss.str(),
"Usage:\n"
- " 1- cb arg11:int [checkup:double]\n"
- " 2- cb arg21:string\n"
- " 3- cb\n"
+ " 1- cb arg11:int [checkup:number]\n"
+ " 2- cb [text:string]\n"
"\n"
"With:\n"
" arg11 Bar didelfrump di desgorb. Nu widsoflar brimeldrgf.\n"
" checkup Florgel, dargel and durgel\n"
- " default: 2.1\n"
+ " default: (double) 2.1\n"
+ " text \n"
+ " default: (empty)\n"
"\n"
"Ops fortunate, ops me ut orgia vociferatio contumax per, rudo re loco emitto\n"
"intolerabiliter ita iugo. Subcribo gravo. Devenio luna fonticulus Castanea\n"
COMPILE_FAIL(argParser)
{
senf::console::ScopedDirectory<> dir;
+
+ // Fails, since there are only two arguments defined
dir.add("cb", &cb1)
.arg()
.arg()
.arg();
}
+COMPILE_FAIL(defaultDoc)
+{
+ senf::console::ScopedDirectory<> dir;
+ using namespace senf::console::kw;
+
+ // Fails, since default_value is missing but default_doc is given
+ dir.add("cb",&cb1)
+ .arg(default_doc = "doc");
+}
+
#endif
///////////////////////////////cc.e////////////////////////////////////////
<tr><td>\ref senfmpl</td><td>Some simple tools which help to solve common meta-programming
tasks</td></tr>
- <tr><td>\ref senfpp</td><td>Extensions to the Boost.Preprocessor library</td></tr>
+ <tr><td>\ref senfpp</td><td>Extensions to the <a
+ href="http://www.boost.org/doc/libs/1_33_1/libs/preprocessor/doc/index.html">Boost.Preprocessor</a>
+ library</td></tr>
- <tr><td>\ref typetraits</td><td>Extensions to the Boost.TypeTraits library</td></tr>
+ <tr><td>\ref typetraits</td><td>Extensions to the <a
+ href="http://www.boost.org/doc/libs/1_33_1/doc/html/boost_typetraits.html">Boost.TypeTraits</a>
+ library</td></tr>
+
+ <tr><td>\ref boost_parameter</td><td>Utilities concerning the <a
+ href="http://www.boost.org/doc/libs/1_33_1/libs/parameter/doc/html/index.html">Boost.Parameter</a>
+ library</td></tr>
</table>
--- /dev/null
+// $Id$
+//
+// 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.
+//
+// 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.
+//
+// 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.
+
+/** \file
+ \brief parameter public header */
+
+/** \defgroup boost_parameter Boost.Parameter utilities
+
+ Here we define some utilities for the <a
+ href="http://www.boost.org/doc/libs/1_33_1/libs/parameter/doc/html/index.html">Boost.Parameter</a>
+ library.
+ */
+
+#ifndef HH_parameter_
+#define HH_parameter_ 1
+
+// Custom includes
+#include <boost/parameter/binding.hpp>
+#include <boost/type_traits/is_same.hpp>
+#include <boost/mpl/not.hpp>
+
+//#include "parameter.mpp"
+///////////////////////////////hh.p////////////////////////////////////////
+
+namespace senf {
+
+ ///\addtogroup boost_parameter
+ ///\{
+
+ /** \brief Test \a ArgumentPack, whether the \a TagType argument was supplied
+
+ This check will test, whether the argument identified by the \a TagType keyword tag type was
+ specified in the \a ArgumentPack. This inherits from \c boost::mpl::true_ or \c
+ boost::mpl::false_ accordingly.
+
+ \tparam ArgumentPack argument pack to check
+ \tparam TagType keyword tag type identifying the argument to check
+ */
+ template <class ArgumentPack, class TagType>
+ struct has_parameter
+ : public boost::mpl::not_<
+ boost::is_same< typename boost::parameter::binding< ArgumentPack, TagType>::type,
+ void > >::type
+ {};
+
+ ///\}
+}
+
+///////////////////////////////hh.e////////////////////////////////////////
+//#include "parameter.cci"
+//#include "parameter.ct"
+//#include "parameter.cti"
+#endif
+
+\f
+// Local Variables:
+// mode: c++
+// fill-column: 100
+// comment-column: 40
+// c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
+// compile-command: "scons -u test"
+// End:
--- /dev/null
+// $Id$
+//
+// 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.
+//
+// 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.
+//
+// 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.
+
+/** \file
+ \brief parameter.test unit tests */
+
+//#include "parameter.test.hh"
+//#include "parameter.test.ih"
+
+// Custom includes
+#include "parameter.hh"
+
+#include <boost/test/auto_unit_test.hpp>
+#include <boost/test/test_tools.hpp>
+
+#define prefix_
+///////////////////////////////cc.p////////////////////////////////////////
+
+BOOST_AUTO_UNIT_TEST(parameter)
+{}
+
+///////////////////////////////cc.e////////////////////////////////////////
+#undef prefix_
+
+\f
+// Local Variables:
+// mode: c++
+// fill-column: 100
+// comment-column: 40
+// c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
+// compile-command: "scons -u test"
+// End:
<?xml version="1.0" encoding="utf-8"?>\r
<xsl:stylesheet version="1.0"\r
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"\r
- xmlns:str="http://exslt.org/strings">\r
+ xmlns:str="http://exslt.org/strings"\r
+ extension-element-prefixes="str">\r
\r
<xsl:output \r
method="html" \r
tests = scanTests(file(source[0].abspath))
errf = os.popen(env.subst('$CXXCOM -DCOMPILE_CHECK 2>&1', source=source, target=target))
passedTests = {}
+ delay_name = None
for error in errf:
elts = error.split(':',2)
if len(elts) != 3 : continue
if not os.path.exists(filename) : continue
try: line = int(line)
except ValueError : continue
+ message = message.strip()
+
+ if delay_name and not message.startswith('instantiated from '):
+ print "Passed test '%s': %s" % (delay_name, message)
+ delay_name = None
+ continue
+
filename = os.path.abspath(filename)
if filename != source[0].abspath : continue
for name,lines in tests.iteritems():
if line >= lines[0] and line <= lines[1]:
passedTests[name] = 1
- print "Passed test '%s': %s" % (name, message.strip())
+ if message.startswith('instantiated from '):
+ delay_name = name
+ else:
+ print "Passed test '%s': %s" % (name, message)
+ if delay_name:
+ print "Passed test '%s': <unknown message ??>" % delay_name
failedTests = set(tests.iterkeys()) - set(passedTests.iterkeys())
if failedTests:
for test in failedTests:
projects / senf.git / commitdiff