From 2a87b62c2eeda376b0c29a38a38174ca906aa597 Mon Sep 17 00:00:00 2001
From: g0dil <g0dil@wiback.org>
Date: Tue, 11 Aug 2009 10:14:39 +0000
Subject: [PATCH] Utils/Console: Add argument type conversion and
FlagCollection documentation
---
Utils/Console/Mainpage.dox | 23 ++++++++++++++++++++++
Utils/Console/Traits.hh | 40 ++++++++++++++++++++++++++++++++++++++
2 files changed, 63 insertions(+)
diff --git a/Utils/Console/Mainpage.dox b/Utils/Console/Mainpage.dox
index 4029ada36..e5f90e483 100644
--- a/Utils/Console/Mainpage.dox
+++ b/Utils/Console/Mainpage.dox
@@ -1271,6 +1271,29 @@
\endhtmlonly
+ \subsection console_args_convert Handling special 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
+
+ \code
+ unsigned char fun4(unsigned char value)
+ {
+ return value;
+ }
+
+ senf::console::root()
+ .add("test8", boost::function<unsigned (unsigned)>(&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.
+
+ The same idea can be used to support custom parsing rules. See senf::console::FlagCollection.
+
+
\subsection console_args_custom Extending the library to support additional types
To support or customize parsing/formatting of other types, they need to be registered. In it's
diff --git a/Utils/Console/Traits.hh b/Utils/Console/Traits.hh
index a5b0ccd77..da5eb602b 100644
--- a/Utils/Console/Traits.hh
+++ b/Utils/Console/Traits.hh
@@ -219,6 +219,46 @@ namespace console {
# define SENF_CONSOLE_REGISTER_ENUM_MEMBER(Class, Type, Values) \
SENF_CONSOLE_REGISTER_ENUM_(Class::, Type, Values)
+ /** \brief Bit-mask flag argument type
+
+ senf::console::FlagCollection supplies a special argument type for use in registering
+ console commands. This argument type is used to represent a bit-mask of single flags.
+
+ \code
+ // Function taking a flags argument
+ void func(unsigned flags);
+
+ // Enum containing all the possible flag values
+ enum MyFlags { Foo = 1,
+ Bar = 2,
+ Baz = 4,
+ Doo = 8 };
+ SENF_CONSOLE_REGISTER_ENUM(MyFlags, (Foo)(Bar)(Baz)(Boo));
+
+ // Register the function with a FlagCollection argument type
+ consoleDir.add("func", boost::function<void (FlagCollection<MyFlags>)>(&func));
+ \endcode
+
+ To use the FlagCollection class
+ \li you need a function which takes a bit-mask of flags as argument
+ \li you define and register an enum with all possible flag values
+ \li you register the function with a FlagCollection argument type using \c boost::function
+ for the conversion. This is also possible for return values.
+
+ The nice thing is, that \c boot::function supports compatible argument types and does
+ automatic type conversion. Since a FlagCollection is convertible to and from unsigned long,
+ this conversion will work.
+
+ After registering this function, you can call it with a collection of flags as argument
+
+ <pre>
+ console:/$ help func
+ Usage:
+ func arg11:MyFlags
+ console:/$ func Foo
+ console:/$ func (Foo Boo)
+ </pre>
+ */
template <class Enum>
struct FlagCollection
{
--
GitLab