Utils/Console: Add argument type conversion and FlagCollection documentation

git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@1286 270642c3-0616-0410-b53a-bc976706d245

diff --git a/Utils/Console/Mainpage.dox b/Utils/Console/Mainpage.dox
index 4029ada..e5f90e4 100644 (file)
--- 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 a5b0ccd..da5eb60 100644 (file)
--- 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
     {