X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Console%2FMainpage.dox;h=2466616cb3e84c1c5cf64b8aa0a60951dadb29cf;hb=0eaf5340de8c2fbb02b1e0e13a797931e221dff3;hp=6929f2537fba9c84879ff36f57e4af24a1bae86f;hpb=8e708e9784c76461252c3bdf646d291c593a49be;p=senf.git

diff --git a/Console/Mainpage.dox b/Console/Mainpage.dox
index 6929f25..2466616 100644
--- a/Console/Mainpage.dox
+++ b/Console/Mainpage.dox
@@ -266,7 +266,7 @@
     
     To greatly simplify parsing complex commands, we turn to automatic argument parsing. 
 
-    \subsection console_autoadd Adding automatically parsed commands
+    \subsection console_autoadd Adding
 
     Automatically parsed commands are registered by just adding a callback which has the correct
     arguments and return-value defined:
@@ -332,7 +332,7 @@
     </pre>
     \endhtmlonly
 
-    \subsection command_overload Command overloading
+    \subsection command_overload 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.
@@ -358,7 +358,22 @@
     server:/$
     </pre>
 
-    \subsection console_attributes Attributes of automatically parsed commands
+    One note: When taking the address of an overloaded function (member or non-member), the C++
+    language forces you to cast that address to one of the possible types so the compiler knows,
+    which overload is requested. So to add a function which is overloaded in C++, each overload
+    needs to be added explicitly, casting to the correct type:
+    \code
+    void over(int);
+    void over(int,int);
+
+    senf::console::root()
+        .add("over", static_cast<void (*)(int)>(&over));
+    senf::console::root()
+        .add("over", static_cast<void (*)(int,int)>(&over));
+    \endcode
+
+
+    \subsection console_attributes Attributes
 
     As have seen so far, some documentation is automatically provided. We can add more info, by
     setting additional attributes. 
@@ -444,13 +459,9 @@
     </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
-
+    order. So the following will give the exactly same result as above:
     \code
     namespace kw = senf::console::kw;
 
@@ -512,14 +523,46 @@
     </pre>
     \endhtmlonly
 
+
+    \subsection console_boostfn Non-function-pointer commands
+
+    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:
+
+    \code
+    senf::console::root()
+        .add("test8", 
+             boost::function<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
+    ok
+    ok
+    ok
+    ok
+    server:/$ help test8
+    Usage:
+        test8 arg11:string
+    server:/$
+    </pre>
+    \endhtmlonly
+
+
     \subsection console_attr_summary Attribute summary
 
     Here a summary of the most common attributes
 
     <table class="senf fixedwidth">
 
-    <tr><td>\link senf::console::ParsedArgumentAttributorBase::doc() .doc\endlink ( \e doc )</td><td>Set
-    documentation for all overloads</td></tr>
+    <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>
@@ -533,7 +576,8 @@
     
     <table class="senf fixed width">
 
-    <tr><td>\link senf::console::kw::name kw::name\endlink</td><td>Parameter name</td></tr>
+    <tr><td style="width:14em">\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>
@@ -549,26 +593,24 @@
         \ref senf::console::kw for a list of all argument attribute keywords
 
         
-    \section console_memberfn Registering member functions
+    \section console_memberfn Member functions
     
     Member functions are supported like non-member functions. They must however be added through a
     senf::console::ScopedDirectory instance to bind them to their instance.
     \code
-    class Test 
+    class Test1
     {
     public:
-        senf::console::ScopedDirectory<Test> dir;
-
-        Test(std::string label) : dir(this), label_ (label) 
-        {
-            dir.add("test4", &Test::test2);
-            dir.add("test4", &Test::test3);
-        }
+        senf::console::ScopedDirectory<Test1> dir;
 
-        std::string test2(std::string const & text)
+        Test1(std::string label) : dir(this), label_ (label) 
+            { dir.add("test", &Test::test1);
+              dir.add("test", &Test::test2); }
+    
+        std::string test1(std::string const & text)
             { return label_ + ": " + text; }
 
-        void test3(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:
@@ -577,12 +619,117 @@
 
     // ...
 
-    Test testOb ("test");
-    senf::console::root().add("testobj", testOb.dir);
+    Test1 test1ob ("test");
+    senf::console::root().add("test1ob", test1ob.dir);
     \endcode
 
     Binding via senf::console::ScopedDirectory ensures, that the commands are automatically removed
     from the tree when the object is destroyed.
+
+
+    \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. 
+    \code
+    class Test2
+    {
+    public:
+        senf::console::ScopedDirectory<Test2> dir;
+
+        Test2() : dir(this), var_(0)
+            { dir.add("var", var_); }
+
+    private:
+        int var_;
+    };
+
+    Test2 test2ob;
+    senf::console::root().add("test2ob", test2ob.dir);
+    \endcode
+    This shows the most common scenario: A member variable is added to a ScopedDirectory of the same
+    class. This ensures, that the variable command node is removed from the tree when the instance
+    (and thereby the variable) are destroyed. The variable can now be used like any other command:
+    \htmlonly
+    <pre>
+    server:/$ test2ob/var
+    0
+    server:/$ test2ob/var 10
+    server:/$ test2ob/var
+    10
+    server:/$ help test2ob
+    Usage:
+        1- var new_value:int
+        2- var
+    server:/$
+    </pre>
+    \endhtmlonly
+
+
+    \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
+    int var (0);
+
+    senf::console::root().add("var1", boost::cref(var));
+    \endcode
+    A read-only variable only has a single overload:
+    \htmlonly
+    <pre>
+    server:/$ var1
+    0
+    server:/$ help var1
+    Usage:
+        var1
+    server:/$ 
+    </pre>
+    \endhtmlonly
+
+
+    \subsection console_varattr Attributes
+
+    The most important Variable command attributes are
+
+    <table class="senf fixedwidth">
+
+    <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
+
+    \subsection console_varchange Change notification
+
+    A \e handler can be set to be called, whenever the variable is changed. It will be called with a
+    reference to the old value. The handler is called, after the value has been changed
+
+    \code
+    int var (0);
+
+    // Since this is int, it would make sense to declare the argument pass-by-value (int old)
+    // but for more complex args, use a const & here
+    void varChanged(int const & old)
+    {
+        // ...
+    }
+
+    senf::console::root().add("var2",var)
+        .onChange(&varChanged);
+    \endcode
+    
+    After this setup, \c varChanged will be called, whenever the value has changed.
+
+
+    \see senf::console::VariableAttributor for the complete attribute interface
  */