Console: More documentation and cleanup

[senf.git] / Console / Node.hh

diff --git a/Console/Node.hh b/Console/Node.hh
index 86c3e17..71c66f7 100644 (file)
--- a/Console/Node.hh
+++ b/Console/Node.hh
@@ -23,7 +23,7 @@
 /** \file
     \brief Node public header */
 
-/** \defgroup node_tree The console/config file-system node tree
+/** \defgroup node_tree The node tree
     
     The console/config node tree is the central data-structure of the library. Into this tree, all
     commands and parameters are entered. The tree is then exposed using a file-system like
@@ -117,7 +117,8 @@
     \li An arbitrary node can be created and then (possibly later) added to the tree using the
         corresponding senf::console::DirectoryNode::add() overload.
     \li A senf::console::CommandNode is normally added to the tree by directly adding a callback
-        using one of the overloaded senf::console::DirectoryNode::add() members.
+        using one of the overloaded senf::console::DirectoryNode::add() members. See \ref
+        console_commands.
 
     When directly adding a node callback, the type of node added depends on the type of
     callback. The callback types which can be added are listed at \ref console_callbacks.
@@ -205,13 +206,12 @@
 #include "../Utils/Exception.hh"
 #include "../Utils/mpl.hh"
 #include "../Utils/Logger/SenfLog.hh"
+#include "../Utils/type_traits.hh"
 #include "Parse.hh"
 
 //#include "Node.mpp"
 ///////////////////////////////hh.p////////////////////////////////////////
 
-#include BOOST_TYPEOF_INCREMENT_REGISTRATION_GROUP()
-
 namespace senf {
 namespace console {
 
@@ -308,14 +308,16 @@ namespace console {
                                       * static_cast<DirectoryNode *>(0),
                                       * static_cast<std::string const *>(0),
                                       * static_cast<Object const *>(0),
-                                      0) ) result_type;
+                                      0) ) base_type;
+        typedef typename senf::remove_cvref<base_type>::type value_type;
 
-        typedef typename boost::remove_reference<result_type>::type NodeType;
+        typedef typename value_type::node_type NodeType;
+        typedef typename value_type::return_type result_type;
 
         /// Internal
         struct Creator {
-            static NodeType & create(DirectoryNode & node, std::string const & name, 
-                                     Object const & ob);
+            static result_type create(DirectoryNode & node, std::string const & name, 
+                                      Object const & ob);
         };
     };
 
@@ -355,6 +357,9 @@ namespace console {
         typedef boost::iterator_range<ChildMap::const_iterator> ChildrenRange;
         typedef ChildMap::const_iterator child_iterator;
 
+        typedef DirectoryNode node_type;
+        typedef DirectoryNode & return_type;
+
         ///////////////////////////////////////////////////////////////////////////
         ///\name Structors and default members
         ///\{
@@ -378,8 +383,8 @@ namespace console {
                                              \a name is empty, it is set to 'unnamed'. */
 
         template <class Object>
-        typename NodeCreateTraits<Object>::NodeType & add (std::string const & name, 
-                                                           Object const & ob);
+        typename NodeCreateTraits<Object>::result_type add (std::string const & name, 
+                                                            Object const & ob);
                                         ///< Generic child node factory
                                         /**< This member is used to create a new child node of the
                                              current directory. The type of node created depends on
@@ -411,6 +416,9 @@ namespace console {
                                              be saved and/or re-attached at some other place in the
                                              tree. */
 
+        bool hasChild(std::string const & name) const;
+                                        ///< \c true, if there is a child with name \a name
+
         GenericNode & get(std::string const & name) const;
                                         ///< Get child node
                                         /**< \throws UnknownNodeNameException if a child \a name
@@ -489,8 +497,6 @@ namespace console {
         friend DirectoryNode & root();
     };
 
-    BOOST_TYPEOF_REGISTER_TYPE(DirectoryNode);
-
     /// Exception: Unknown node name
     struct UnknownNodeNameException : public senf::Exception
     { UnknownNodeNameException() : senf::Exception("Unknown node name") {}};
@@ -501,6 +507,11 @@ namespace console {
     {};
 #endif
 
+    /**  \brief Syntax error parsing command arguments exception
+
+        All errors while parsing the arguments of a command must be signaled by throwing an instance
+        of SyntaxErrorException. This is important, so command overloading works.
+     */
     struct SyntaxErrorException : public senf::Exception
     {
         explicit SyntaxErrorException(std::string const & msg = "");
@@ -515,6 +526,9 @@ namespace console {
 
         To execute a command, CommandNode::operator()() or CommandNode::execute() is called.
 
+        Subclass instances of this node type are automatically created when adding commands to the
+        tree. See \ref console_commands.
+
         \ingroup node_tree
       */
     class CommandNode : public GenericNode
@@ -568,9 +582,14 @@ namespace console {
     /** \brief Most simple CommandNode implementation
 
         This CommandNode implementation simply forwards the \a output and \a arguments arguments to
-        an arbitrary callback.
+        an arbitrary callback. Thus, it allows to add callbacks with the signature
+        \code
+        void callback(std::ostream & os, senf::console::ParseCommandInfo const & command)
+        { ... }
+        \endcode
+        to the tree.
  
-        \ingroup node_tree
+        \ingroup console_commands
      */
     class SimpleCommandNode : public CommandNode
     {
@@ -585,6 +604,9 @@ namespace console {
 
         typedef boost::function<void (std::ostream &, ParseCommandInfo const &)> Function;
 
+        typedef SimpleCommandNode node_type;
+        typedef SimpleCommandNode & return_type;
+
         ///////////////////////////////////////////////////////////////////////////
         ///\name Structors and default members
         ///\{
@@ -617,12 +639,16 @@ namespace console {
                                               Function const & fn, ...);
 #endif
 
-    BOOST_TYPEOF_REGISTER_TYPE(SimpleCommandNode);
-
     DirectoryNode & root();
 
 }}
 
+#include BOOST_TYPEOF_INCREMENT_REGISTRATION_GROUP()
+
+BOOST_TYPEOF_REGISTER_TYPE(senf::console::DirectoryNode)
+BOOST_TYPEOF_REGISTER_TYPE(senf::console::SimpleCommandNode)
+
+
 ///////////////////////////////hh.e////////////////////////////////////////
 #include "Node.cci"
 #include "Node.ct"