Console/Node.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2008
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief Node public header */
  25
  26 /** \defgroup node_tree The node tree
  27
  28     The console/config node tree is the central data-structure of the library. Into this tree, all
  29     commands and parameters are entered. The tree is then exposed using a file-system like
  30     interface.
  31
  32     \autotoc
  33
  34     \section console_tree The tree
  35
  36     We will start by giving a more complete example. This example contains most of the stuff needed
  37     for using the console/config library.
  38
  39     \code
  40     // Define callback function.
  41     void mycommand(std::ostream & os, senf::console::ParseCommandInfo const & command)
  42     {
  43         // ...
  44         os << "!! Important message ...\n";
  45     }
  46
  47     class SomeClass
  48     {
  49     public:
  50         // Declare a directory node (proxy) for use by this class. This must be public so we can add
  51         // it to the node tree later.
  52         senf::console::ScopedDirectory<SomeClass> dir;
  53
  54         SomeClass() : dir(this)
  55         {
  56             // You may document the directory here or later when adding it to the tree
  57             dir.doc("Manager for something");
  58
  59             // Add a member function (the pointer-to-member is automatically bound to this instance)
  60             dir.add("member", &SomeClass::member)
  61                 .doc("Do the member operation");
  62         }
  63
  64         void member(std::ostream & os, senf::console::ParseCommandInfo const & command)
  65         {
  66             // ...
  67         }
  68     };
  69
  70     int main(int, char**)
  71     {
  72         // Provide global documentation
  73         senf::console::root()
  74             .doc("This is someServer server");
  75
  76         // Add a new directory to the root and document it. All the mutators return the node object
  77         // itself so operations can be chained.
  78         senf::console::DirectoryNode & mydir (
  79                 .mkdir("myserver")
  80                 .doc("My server specific directory"));
  81
  82         // Add a command to that directory
  83         mydir.add("mycommand", &mycommand)
  84             .doc("mycommand <foo> [<bar>]\n\n"
  85                  "If <bar> is given, flurgle the <foo>, otherwise burgle it");
  86
  87         // Create a SomeClass instance and add it's directory.
  88         SomeClass someClass;
  89         mydir.add("someClass", someClass.dir);
  90
  91         // Start the interactive console server
  92         senf::console::Server::start(senf::INet4SocketAddress(senf::INet4Address::None, 23232u))
  93             .name("someServer");
  94     }
  95     \endcode
  96
  97     \subsection console_nodes Node types
  98
  99     The console/config library tree consists of two basic node types:
 100
 101     \li senf::console::DirectoryNode provides internal nodes with an arbitrary number of children
 102     \li senf::console::CommandNode describes a command entry in the tree
 103
 104     senf::console::CommandNode is the base-class of all command nodes of which there are several,
 105     depending on the type of command.
 106
 107     There is a single root node, the senf::console::DirectoryNode called senf::console::root(). From
 108     this node, the tree is traversed.
 109
 110     All nodes are allocated on the heap and are managed using a smart pointer.
 111
 112     \subsection console_manipulate Manipulating the node tree
 113
 114     There are several ways to add nodes to the tree:
 115
 116     \li A senf::console::DirectoryNode can be added using senf::console::DirectoryNode::mkdir().
 117     \li An arbitrary node can be created and then (possibly later) added to the tree using the
 118         corresponding senf::console::DirectoryNode::add() overload.
 119     \li A senf::console::CommandNode is normally added to the tree by directly adding a callback
 120         using one of the overloaded senf::console::DirectoryNode::add() members. See \ref
 121         console_commands.
 122
 123     When directly adding a node callback, the type of node added depends on the type of
 124     callback. The callback types which can be added are listed at \ref console_callbacks.
 125
 126     \code
 127     void callback(std::ostream & os, senf::console::ParseCommandInfo const & command) { ... }
 128     // ...
 129     myDirectory.add("foo",&callback);
 130     \endcode
 131
 132     Every node is identified among it's siblings by it's name. The name of the node is set when
 133     adding the node to the tree. If the name is empty or non-unique, a unique name will be
 134     automatically provided.
 135
 136     To remove a node from the tree, just use the nodes senf::console::GenericNode::unlink() or the
 137     parents senf::console::DirectoryNode::remove() member. This call removes the node from it's
 138     parent and returns a (smart) node pointer.
 139
 140     \li If you ignore the return value, the node (and it's children) will be deleted.
 141     \li Alternatively, you may store away the node and re-attach it later.
 142     \li An node (or subtree) can be moved to a different place by unlinking the node at it's old
 143         place and re-adding it at it's new location.
 144     \li To rename a node, unlink and re-add it with a different name.
 145
 146     \code
 147     myDirectory.add("bar", myDirectory.remove("foo"));
 148     \endcode
 149
 150     \subsection console_node_param Assigning additional node parameters
 151
 152     Depending on the node type added, additional node parameters may be set. For example, every node
 153     has a documentation parameter which is used by the online-help system. To assign these
 154     parameters, the node exposes corresponding member functions. Since
 155     senf::console::DirectoryNode::add() returns the newly added node by reference, additional
 156     parameters may just be added to the end of the add command:
 157     \code
 158     myDirectory.add("foo",&fooCallback).doc("The foo method");
 159     \endcode
 160     Since the parameter setters all return the node reference, additional parameters may just be
 161     added to the end of the command.
 162
 163     \subsection console_tree_traverse Traversing the tree
 164
 165     The simplest way to access tree elements is to save the return value of the
 166     senf::console::DirectoryNode::add() members. However, saving the reference will not ensure, that
 167     the node is not removed. If the node might be removed from the tree, you should use a smart
 168     pointer (either <tt>ptr</tt> or <tt>weak_ptr</tt>) to hold the node.
 169
 170     Another possibility is to traverse the tree explicitly. For this purpose, the operators '[]' and
 171     '()' have been overloaded in senf::console::DirectoryNode.
 172     \code
 173     senf::console::root().getDirectory("myDirectory").getCommand("foo")
 174     \\ or more concise but otherwise completely identical
 175     senf::console::root()["myDirectory"]("foo")
 176     \endcode
 177
 178     getDirectory and the '[]' operator will return a senf::console::DirectoryNode whereas getCommand
 179     and the '()' operator will return a senf::console::CommandNode. If the node is not found or is
 180     not of the correct type, an exception will be raised.
 181
 182     \section console_object_dir Assigning a directory to an object instance
 183
 184     Most objects will register several commands. So it makes sense for these objects to manage their
 185     own directory. Since directories are however allocated on the heap, they cannot be directly
 186     added to a class. To facilitate this usage, the senf::console::ScopedDirectory is used. This
 187     class provides a senf::console::DirectoryNode facade. Internally, it automatically creates a
 188     senf::console::DirectoryNode to which all calls are forwarded.
 189
 190     The senf::console::ScopedDirectory member should be declared public. This allows the user of the
 191     class to add the node to the tree.
 192  */
 193
 194 #ifndef HH_Node_
 195 #define HH_Node_ 1
 196
 197 // Custom includes
 198 #include <map>
 199 #include <boost/shared_ptr.hpp>
 200 #include <boost/weak_ptr.hpp>
 201 #include <boost/enable_shared_from_this.hpp>
 202 #include <boost/utility.hpp>
 203 #include <boost/range/iterator_range.hpp>
 204 #include <boost/typeof/typeof.hpp>
 205 #include <boost/type_traits/remove_reference.hpp>
 206 #include "../Utils/Exception.hh"
 207 #include "../Utils/mpl.hh"
 208 #include "../Utils/Logger/SenfLog.hh"
 209 #include "../Utils/type_traits.hh"
 210 #include "Parse.hh"
 211
 212 //#include "Node.mpp"
 213 ///////////////////////////////hh.p////////////////////////////////////////
 214
 215 namespace senf {
 216 namespace console {
 217
 218     class DirectoryNode;
 219     class CommandNode;
 220
 221     /** \brief Config/console node tree base-class
 222
 223         GenericNode is the base class of all node objects. There are two basic node types derived
 224         from GenericNode:  DirectoryNode and CommandNode.
 225
 226         All nodes are dynamically allocated and automatically managed using reference counting.
 227
 228         All nodes are normally linked into a single tree which root node is
 229         senf::console::root(). Nodes may however be orphaned (not linked to the tree) either
 230         directly (the node has no parent) or indirectly (the node has a parent but is part of an
 231         orphaned subtree which is not linked to the root node).
 232
 233         Every active (non-orphaned) node (except the root() node) has a non-empty node name. This
 234         name is assigned to the node when adding the node to the tree.
 235
 236         \ingroup node_tree
 237       */
 238     class GenericNode
 239         : public boost::enable_shared_from_this<GenericNode>
 240     {
 241         SENF_LOG_CLASS_AREA();
 242     public:
 243         ///////////////////////////////////////////////////////////////////////////
 244         // Types
 245
 246         typedef boost::shared_ptr<GenericNode> ptr;
 247         typedef boost::shared_ptr<GenericNode const> cptr;
 248         typedef boost::weak_ptr<GenericNode> weak_ptr;
 249
 250         ///////////////////////////////////////////////////////////////////////////
 251
 252         virtual ~GenericNode();
 253
 254         std::string const & name() const; ///< Node name
 255         boost::shared_ptr<DirectoryNode> parent() const; ///< Parent node
 256                                         /**< May be null, if the node is the root node or if it is
 257                                              not linked to the tree */
 258
 259         std::string path() const;       ///< Node path
 260                                         /**< The node path is built by joining the names of all
 261                                              parent nodes with '/' chars. */
 262
 263         ptr unlink();                   ///< Remove node from it's parent directory
 264                                         /**< You may either discard the return value and thereby
 265                                              dispose the node or may re-attach the node at some
 266                                              other place using DirectoryNode::add(). */
 267
 268         bool active() const;            ///< \c true, if node is attached to the root() node
 269
 270         void help(std::ostream & output) const; /// Write help info to \a output
 271
 272         ptr thisptr();                  ///< Get smart pointer to node
 273         cptr thisptr() const;           ///< Get smart pointer to node (const)
 274
 275     protected:
 276         GenericNode();
 277
 278         void name(std::string const & name);
 279
 280 #ifndef DOXYGEN
 281     private:
 282 #else
 283     public:
 284 #endif
 285         virtual void v_help(std::ostream & output) const = 0;
 286                                         ///< Provide help information
 287                                         /**< This member must be implemented in derived classes
 288                                              to provide node specific help information. */
 289
 290     private:
 291         std::string name_;
 292         DirectoryNode * parent_;
 293
 294         friend class DirectoryNode;
 295     };
 296
 297     class SimpleCommandNode;
 298
 299     /** \brief Internal: Node creation helper traits
 300
 301         This class is used internally to find out the type of node to create for a specific argument
 302         type.
 303      */
 304     template <class Object>
 305     struct NodeCreateTraits
 306     {
 307         typedef BOOST_TYPEOF_TPL( senf_console_add_node(
 308                                       * static_cast<DirectoryNode *>(0),
 309                                       * static_cast<std::string const *>(0),
 310                                       * static_cast<Object const *>(0),
 311                                       0) ) base_type;
 312         typedef typename senf::remove_cvref<base_type>::type value_type;
 313
 314         typedef typename value_type::node_type NodeType;
 315         typedef typename value_type::return_type result_type;
 316
 317         /// Internal
 318         struct Creator {
 319             static result_type create(DirectoryNode & node, std::string const & name,
 320                                       Object const & ob);
 321         };
 322     };
 323
 324     /** \brief Config/console tree directory node
 325
 326         This node type provides the internal and root nodes of the tree. It allows to add arbitrary
 327         children and supports directory traversal.
 328
 329         Nodes are normally not instantiated manually but are created by the DirectoryNode via
 330         mkdir() or add(). Special add() members however allow externally allocated node objects.
 331
 332         Nodes may be added to the tree only once, otherwise chaos will ensue. Since nodes are always
 333         managed dynamically, there is a special ScopedDirectory proxy template which provides a
 334         DirectoryNode facade. ScopedDirectory is used if a class wants to manage it's own directory
 335         as a data member.
 336
 337         Every node is assigned a (new) name when it is added to a directory. If the directory
 338         already has an entry of that name, the name is made unique by appending a suffix of the form
 339         '-n' where n is a number starting at 1. If the name is empty, int is set to 'unnamed' and
 340         then uniquified as above. Automatically providing unique names simplifies adding
 341         configuration/console support to generic components.
 342
 343         \ingroup node_tree
 344       */
 345     class DirectoryNode : public GenericNode
 346     {
 347         SENF_LOG_CLASS_AREA();
 348         typedef std::map<std::string, GenericNode::ptr> ChildMap;
 349     public:
 350         ///////////////////////////////////////////////////////////////////////////
 351         // Types
 352
 353         typedef boost::shared_ptr<DirectoryNode> ptr;
 354         typedef boost::shared_ptr<DirectoryNode const> cptr;
 355         typedef boost::weak_ptr<DirectoryNode> weak_ptr;
 356
 357         typedef boost::iterator_range<ChildMap::const_iterator> ChildrenRange;
 358         typedef ChildMap::const_iterator child_iterator;
 359
 360         typedef DirectoryNode node_type;
 361         typedef DirectoryNode & return_type;
 362
 363         ///////////////////////////////////////////////////////////////////////////
 364         ///\name Structors and default members
 365         ///\{
 366
 367         static ptr create();            ///< Create node object.
 368                                         /**< You should normally use either mkdir() or
 369                                              ScopedDirectory instead of create() */
 370
 371         ///\}
 372         ///////////////////////////////////////////////////////////////////////////
 373         ///\name Children
 374         ///\{
 375
 376         template <class NodeType>
 377         NodeType & add(std::string const & name, boost::shared_ptr<NodeType> node);
 378                                         ///< Add node to tree
 379                                         /**< Adds the \a node to the tree as a child of \a this
 380                                              node. The node is given the name \a name. If a node of
 381                                              that name already exists, a numeric suffix of the form
 382                                              '-n' is added to the name until the name is unique. If
 383                                              \a name is empty, it is set to 'unnamed'. */
 384
 385         template <class Object>
 386         typename NodeCreateTraits<Object>::result_type add (std::string const & name,
 387                                                             Object const & ob);
 388                                         ///< Generic child node factory
 389                                         /**< This member is used to create a new child node of the
 390                                              current directory. The type of node created depends on
 391                                              the type of argument passed.
 392
 393                                              The node type is selected by the NodeCreateTraits
 394                                              class. To allow adding a specific node type, you need
 395                                              to provide an overload for
 396                                              <tt>senf_console_add_node</tt> which must be visible at
 397                                              when you register the new node.
 398                                              \code
 399                                              MyNodeType & senf_console_add_node(
 400                                                  DirectoryNode & dir,
 401                                                  std::string const & name,
 402                                                  MySpecialObject const & ob,
 403                                                  int)
 404                                              {
 405                                                  return dir.add(name, MyNodeType::create(ob));
 406                                              }
 407                                              \endcode
 408                                              (Do not forget the last unnamed 'int' parameter which
 409                                              is not used but serves to disambiguate the
 410                                              overloads). */
 411
 412         GenericNode::ptr remove(std::string const & name);
 413                                         ///< Remove node \a name from the tree
 414                                         /**< The returned pointer may either be discarded, which
 415                                              will automatically dispose the removed node, or it may
 416                                              be saved and/or re-attached at some other place in the
 417                                              tree. */
 418
 419         bool hasChild(std::string const & name) const;
 420                                         ///< \c true, if there is a child with name \a name
 421
 422         GenericNode & get(std::string const & name) const;
 423                                         ///< Get child node
 424                                         /**< \throws UnknownNodeNameException if a child \a name
 425                                                  does not exist */
 426
 427         DirectoryNode & getDirectory(std::string const & name) const;
 428                                         ///< Get directory child node
 429                                         /**< Same as operator[]
 430                                              \throws UnknownNodeNameException if a child \a name
 431                                                  does not exist.
 432                                              \throws std::bad_cast if the child \a name is not a
 433                                                  directory node. */
 434
 435         DirectoryNode & operator[](std::string const & name) const;
 436                                         ///< Get directory child node
 437                                         /**< Same as getDirectory
 438                                              \throws UnknownNodeNameException if a child \a name
 439                                                  does not exist.
 440                                              \throws std::bad_cast if the child \a name is not a
 441                                                  directory node. */
 442
 443         CommandNode & getCommand(std::string const & name) const;
 444                                         ///< Get command child node
 445                                         /**< Same as operator()
 446                                              \throws UnknownNodeNameException if a child \a name
 447                                                  does not exist
 448                                              \throws std::bad_cast if the child \a name is not a
 449                                                  command node. */
 450
 451         CommandNode & operator()(std::string const & name) const;
 452                                         ///< Get command child node
 453                                         /**< Same as getCommand()
 454                                              \throws UnknownNodeNameException if a child \a name
 455                                                  does not exist
 456                                              \throws std::bad_cast if the child \a name is not a
 457                                                  command node. */
 458
 459         DirectoryNode & mkdir(std::string const & name);
 460                                         ///< Create sub-directory node
 461
 462         ChildrenRange children() const;
 463                                         ///< Return iterator range over all children.
 464                                         /**< The returned range is sorted by child name. */
 465
 466         ///\}
 467         ///////////////////////////////////////////////////////////////////////////
 468
 469         template <class ForwardRange>
 470         GenericNode & traverse(ForwardRange const & range);
 471                                         ///< Traverse node path starting at this node
 472                                         /**< The <tt>ForwardRange::value_type</tt> must be
 473                                              (convertible to) std::string. Each range element
 474                                              constitutes a step along the node traversal.
 475
 476                                              If the range starts with an empty element, the
 477                                              traversal is started at the root() node, otherwise it
 478                                              is started at \a this node. The traversal supports '.',
 479                                              '..' and ignores further empty elements. */
 480
 481         DirectoryNode & doc(std::string const & doc);
 482                                         ///< Set node documentation
 483
 484         ptr thisptr();
 485         cptr thisptr() const;
 486
 487     protected:
 488         DirectoryNode();
 489
 490     private:
 491         void add(GenericNode::ptr node);
 492         virtual void v_help(std::ostream & output) const;
 493
 494         ChildMap children_;
 495         std::string doc_;
 496
 497         friend DirectoryNode & root();
 498     };
 499
 500     /// Exception: Unknown node name
 501     struct UnknownNodeNameException : public senf::Exception
 502     { UnknownNodeNameException() : senf::Exception("Unknown node name") {}};
 503
 504 #ifndef DOXYGEN
 505     template <class Type>
 506     struct NodeCreateTraits< boost::shared_ptr<Type> >
 507     {};
 508 #endif
 509
 510     struct SyntaxErrorException : public senf::Exception
 511     {
 512         explicit SyntaxErrorException(std::string const & msg = "");
 513
 514         virtual char const * what() const throw();
 515     };
 516
 517     /** \brief Config/console tree command node
 518
 519         The CommandNode is the base-class for the tree leaf nodes. Concrete command node
 520         implementations are derived from this class.
 521
 522         To execute a command, CommandNode::operator()() or CommandNode::execute() is called.
 523
 524         Subclass instances of this node type are automatically created when adding commands to the
 525         tree. See \ref console_commands.
 526
 527         \ingroup node_tree
 528       */
 529     class CommandNode : public GenericNode
 530     {
 531         SENF_LOG_CLASS_AREA();
 532     public:
 533         ///////////////////////////////////////////////////////////////////////////
 534         // Types
 535
 536         typedef boost::shared_ptr<CommandNode> ptr;
 537         typedef boost::shared_ptr<CommandNode const> cptr;
 538         typedef boost::weak_ptr<CommandNode> weak_ptr;
 539
 540         ///////////////////////////////////////////////////////////////////////////
 541
 542         void execute(std::ostream & output, ParseCommandInfo const & command) const;
 543                                         ///< Execute the command
 544                                         /**< Same as operator()()
 545                                              \param[in] output stream where result messages may be
 546                                                  written to
 547                                              \param[in] arguments command arguments. This is a
 548                                                  range of ranges of ArgumentToken instances. */
 549
 550         void operator()(std::ostream & output, ParseCommandInfo const & command) const;
 551                                         ///< Execute the command
 552                                         /**< Same as execute()
 553                                              \param[in] output stream where result messages may be
 554                                                  written to
 555                                              \param[in] arguments command arguments. This is a
 556                                                  range of ranges of ArgumentToken instances. */
 557
 558         ptr thisptr();
 559         cptr thisptr() const;
 560
 561     protected:
 562         CommandNode();
 563
 564 #ifndef DOXYGEN
 565     private:
 566 #endif
 567         virtual void v_execute(std::ostream & output, ParseCommandInfo const & command) const = 0;
 568                                         ///< Called to execute the command
 569                                         /**< \param[in] output stream where result messages may be
 570                                                  written to
 571                                              \param[in] arguments command arguments. This is a
 572                                                  range of ranges of ArgumentToken instances. */
 573
 574     private:
 575     };
 576
 577     /** \brief Most simple CommandNode implementation
 578
 579         This CommandNode implementation simply forwards the \a output and \a arguments arguments to
 580         an arbitrary callback. Thus, it allows to add callbacks with the signature
 581         \code
 582         void callback(std::ostream & os, senf::console::ParseCommandInfo const & command)
 583         { ... }
 584         \endcode
 585         to the tree.
 586
 587         \ingroup console_commands
 588      */
 589     class SimpleCommandNode : public CommandNode
 590     {
 591         SENF_LOG_CLASS_AREA();
 592     public:
 593         ///////////////////////////////////////////////////////////////////////////
 594         // Types
 595
 596         typedef boost::shared_ptr<SimpleCommandNode> ptr;
 597         typedef boost::shared_ptr<SimpleCommandNode const> cptr;
 598         typedef boost::weak_ptr<SimpleCommandNode> weak_ptr;
 599
 600         typedef boost::function<void (std::ostream &, ParseCommandInfo const &)> Function;
 601
 602         typedef SimpleCommandNode node_type;
 603         typedef SimpleCommandNode & return_type;
 604
 605         ///////////////////////////////////////////////////////////////////////////
 606         ///\name Structors and default members
 607         ///\{
 608
 609         static ptr create(Function const & fn);
 610
 611         ///\}
 612         ///////////////////////////////////////////////////////////////////////////
 613
 614         ptr thisptr();
 615         cptr thisptr() const;
 616
 617         SimpleCommandNode & doc(std::string const & doc);
 618
 619     protected:
 620         SimpleCommandNode(Function const & fn);
 621
 622     private:
 623         virtual void v_help(std::ostream & output) const;
 624         virtual void v_execute(std::ostream & output, ParseCommandInfo const & command) const;
 625
 626
 627         Function fn_;
 628         std::string doc_;
 629     };
 630
 631 #ifndef DOXYGEN
 632     template <class Function>
 633     SimpleCommandNode & senf_console_add_node(DirectoryNode & node, std::string const & name,
 634                                               Function const & fn, ...);
 635 #endif
 636
 637     DirectoryNode & root();
 638
 639 }}
 640
 641 #include BOOST_TYPEOF_INCREMENT_REGISTRATION_GROUP()
 642
 643 BOOST_TYPEOF_REGISTER_TYPE(senf::console::DirectoryNode)
 644 BOOST_TYPEOF_REGISTER_TYPE(senf::console::SimpleCommandNode)
 645
 646
 647 ///////////////////////////////hh.e////////////////////////////////////////
 648 #include "Node.cci"
 649 #include "Node.ct"
 650 #include "Node.cti"
 651 #endif
 652
 653 \f
 654 // Local Variables:
 655 // mode: c++
 656 // fill-column: 100
 657 // comment-column: 40
 658 // c-file-style: "senf"
 659 // indent-tabs-mode: nil
 660 // ispell-local-dictionary: "american"
 661 // compile-command: "scons -u test"
 662 // End: