4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
24 \brief Node public header */
31 #include <boost/shared_ptr.hpp>
32 #include <boost/weak_ptr.hpp>
33 #include <boost/enable_shared_from_this.hpp>
34 #include <boost/utility.hpp>
35 #include <boost/range/iterator_range.hpp>
36 #include <boost/typeof/typeof.hpp>
37 #include <boost/type_traits/remove_reference.hpp>
38 #include "../Utils/Exception.hh"
39 #include "../Utils/mpl.hh"
40 #include "../Utils/Logger/SenfLog.hh"
44 ///////////////////////////////hh.p////////////////////////////////////////
46 #include BOOST_TYPEOF_INCREMENT_REGISTRATION_GROUP()
54 /** \brief Config/console node tree base-class
56 GenericNode is the base class of all node objects. There are two basic node types derived
57 from GenericNode: DirectoryNode and CommandNode.
59 All nodes are dynamically allocated and automatically managed using reference counting.
61 All nodes are normally linked into a single tree which root node is
62 senf::console::root(). Nodes may however be orphaned (not linked to the tree) either
63 directly (the node has no parent) or indirectly (the node has a parent but is part of an
64 orphaned subtree which is not linked to the root node).
66 Every active (non-orphaned) node (except the root() node) has a non-empty node name. This
67 name is assigned to the node when adding the node to the tree.
70 : public boost::enable_shared_from_this<GenericNode>
72 SENF_LOG_CLASS_AREA();
74 ///////////////////////////////////////////////////////////////////////////
77 typedef boost::shared_ptr<GenericNode> ptr;
78 typedef boost::shared_ptr<GenericNode const> cptr;
79 typedef boost::weak_ptr<GenericNode> weak_ptr;
81 ///////////////////////////////////////////////////////////////////////////
83 virtual ~GenericNode();
85 std::string const & name() const; ///< Node name
86 boost::shared_ptr<DirectoryNode> parent() const; ///< Parent node
87 /**< May be null, if the node is the root node or if it is
88 not linked to the tree */
90 std::string path() const; ///< Node path
91 /**< The node path is built by joining the names of all
92 parent nodes with '/' chars. */
94 ptr unlink(); ///< Remove node from it's parent directory
95 /**< You may either discard the return value and thereby
96 dispose the node or may re-attach the node at some
97 other place using DirectoryNode::add(). */
99 bool active() const; ///< \c true, if node is attached to the root() node
101 void help(std::ostream & output) const; /// Write help info to \a output
103 ptr thisptr(); ///< Get smart pointer to node
104 cptr thisptr() const; ///< Get smart pointer to node (const)
109 void name(std::string const & name);
116 virtual void v_help(std::ostream & output) const = 0;
117 ///< Provide help information
118 /**< This member must be implemented in derived classes
119 to provide node specific help information. */
123 DirectoryNode * parent_;
125 friend class DirectoryNode;
128 class SimpleCommandNode;
130 /** \brief Internal: Node creation helper traits
132 This class is used internally to find out the type of node to create for a specific argument
135 template <class Object>
136 struct NodeCreateTraits
138 typedef BOOST_TYPEOF_TPL( senf_console_add_node(
139 * static_cast<DirectoryNode *>(0),
140 * static_cast<std::string const *>(0),
141 * static_cast<Object const *>(0),
144 typedef typename boost::remove_reference<result_type>::type NodeType;
147 static NodeType & create(DirectoryNode & node, std::string const & name,
152 /** \brief Config/console tree directory node
154 This node type provides the internal and root nodes of the tree. It allows to add arbitrary
155 children and supports directory traversal.
157 Nodes are normally not instantiated manually but are created by the DirectoryNode via
158 mkdir() or add(). Special add() members however allow externally allocated node objects.
160 Nodes may be added to the tree only once, otherwise chaos will ensue. Since nodes are always
161 managed dynamically, there is a special ObjectDirectory proxy template which provides a
162 DirectoryNode facade. ObjectDirectory is used if a class wants to manage it's own directory
165 Every node is assigned a (new) name when it is added to a directory. If the directory
166 already has an entry of that name, the name is made unique by appending a suffix of the form
167 '-n' where n is a number starting at 1. If the name is empty, int is set to 'unnamed' and
168 then uniquified as above. Automatically providing unique names simplifies adding
169 configuration/console support to generic components.
171 class DirectoryNode : public GenericNode
173 SENF_LOG_CLASS_AREA();
174 typedef std::map<std::string, GenericNode::ptr> ChildMap;
176 ///////////////////////////////////////////////////////////////////////////
179 typedef boost::shared_ptr<DirectoryNode> ptr;
180 typedef boost::shared_ptr<DirectoryNode const> cptr;
181 typedef boost::weak_ptr<DirectoryNode> weak_ptr;
183 typedef boost::iterator_range<ChildMap::const_iterator> ChildrenRange;
184 typedef ChildMap::const_iterator child_iterator;
186 ///////////////////////////////////////////////////////////////////////////
187 ///\name Structors and default members
190 static ptr create(); ///< Create node object.
191 /**< You should normally use either mkdir() or
192 ObjectDirectory instead of create() */
195 ///////////////////////////////////////////////////////////////////////////
199 template <class NodeType>
200 NodeType & add(std::string const & name, boost::shared_ptr<NodeType> node);
201 ///< Add node to tree
202 /**< Adds the \a node to the tree as a child of \a this
203 node. The node is given the name \a name. If a node of
204 that name already exists, a numeric suffix of the form
205 '-n' is added to the name until the name is unique. If
206 \a name is empty, it is set to 'unnamed'. */
208 template <class Object>
209 typename NodeCreateTraits<Object>::NodeType & add (std::string const & name,
211 ///< Generic child node factory
212 /**< This member is used to create a new child node of the
213 current directory. The type of node created depends on
214 the type of argument passed.
216 The node type is selected by the NodeCreateTraits
217 class. To allow adding a specific node type, you need
218 to provide an overload for
219 <tt>senf_console_add_node</tt> which must be visible at
220 when you register the new node.
222 MyNodeType & senf_console_add_node(
224 std::string const & name,
225 MySpecialObject const & ob,
228 return dir.add(name, MyNodeType::create(ob));
231 (Do not forget the last unnamed 'int' parameter which
232 is not used but serves to disambiguate the
235 GenericNode::ptr remove(std::string const & name);
236 ///< Remove node \a name from the tree
237 /**< The returned pointer may either be discarded, which
238 will automatically dispose the removed node, or it may
239 be saved and/or re-attached at some other place in the
242 DirectoryNode & operator[](std::string const & name) const;
243 ///< Get directory child node
244 /**< \throws UnknownNodeNameException if a child \a name
246 \throws std::bad_cast if the child \a name is not a
249 CommandNode & operator()(std::string const & name) const;
250 ///< Get command child node
251 /**< \throws UnknownNodeNameException if a child \a name
253 \throws std::bad_cast if the child \a name is not a
256 GenericNode & get(std::string const & name) const;
258 /**< \throws UnknownNodeNameException if a child \a name
261 DirectoryNode & mkdir(std::string const & name);
262 ///< Create sub-directory node
264 ChildrenRange children() const;
265 ///< Return iterator range over all children.
266 /**< The returned range is sorted by child name. */
269 ///////////////////////////////////////////////////////////////////////////
271 template <class ForwardRange>
272 GenericNode & traverse(ForwardRange const & range);
273 ///< Traverse node path starting at this node
274 /**< The <tt>FordwareRange::value_type</tt> must be
275 (convertible to) std::string. Each range element
276 constitutes a step along the node traversal.
278 If the range starts with an empty element, the
279 traversal is started at the root() node, otherwise it
280 is started at \a this node. The traversal supports '.',
281 '..' and ignores further empty elements. */
283 DirectoryNode & doc(std::string const & doc);
284 ///< Set node documentation
287 cptr thisptr() const;
293 void add(GenericNode::ptr node);
294 virtual void v_help(std::ostream & output) const;
299 friend DirectoryNode & root();
302 BOOST_TYPEOF_REGISTER_TYPE(DirectoryNode);
304 /// Exception: Unknown node name
305 struct UnknownNodeNameException : public senf::Exception
306 { UnknownNodeNameException() : senf::Exception("Unknown node name") {}};
309 template <class Type>
310 struct NodeCreateTraits< boost::shared_ptr<Type> >
314 /** \brief Config/console tree command node
316 The CommandNode is the base-class for the tree leaf nodes. Concrete command node
317 implementations are derived from this class.
319 To execute a command, CommandNode::operator()() is called. This abstract virtual function
320 must be implemented in a derived class.
322 class CommandNode : public GenericNode
324 SENF_LOG_CLASS_AREA();
326 ///////////////////////////////////////////////////////////////////////////
329 typedef boost::shared_ptr<CommandNode> ptr;
330 typedef boost::shared_ptr<CommandNode const> cptr;
331 typedef boost::weak_ptr<CommandNode> weak_ptr;
333 typedef ParseCommandInfo::ArgumentsRange Arguments;
335 ///////////////////////////////////////////////////////////////////////////
337 virtual void operator()(std::ostream & output, Arguments const & arguments) = 0;
338 ///< Called to execute the command
339 /**< \param[in] output stream where result messages may be
341 \param[in] arguments command arguments. This is a
342 range of ranges of ArgumentToken instances. */
345 cptr thisptr() const;
353 /** \brief Most simple CommandNode implementation
355 This CommandNode implementation simply forwards the \a output and \a arguments arguments to
356 an arbitrary callback.
358 class SimpleCommandNode : public CommandNode
360 SENF_LOG_CLASS_AREA();
362 ///////////////////////////////////////////////////////////////////////////
365 typedef boost::shared_ptr<SimpleCommandNode> ptr;
366 typedef boost::shared_ptr<SimpleCommandNode const> cptr;
367 typedef boost::weak_ptr<SimpleCommandNode> weak_ptr;
369 typedef boost::function<void (std::ostream &, Arguments const &)> Function;
371 ///////////////////////////////////////////////////////////////////////////
373 virtual void operator()(std::ostream & output, Arguments const & arguments);
376 cptr thisptr() const;
378 static ptr create(Function const & fn);
380 SimpleCommandNode & doc(std::string const & doc);
383 SimpleCommandNode(Function const & fn);
386 virtual void v_help(std::ostream & output) const;
393 template <class Function>
394 SimpleCommandNode & senf_console_add_node(DirectoryNode & node, std::string const & name,
395 Function const & fn, ...);
398 BOOST_TYPEOF_REGISTER_TYPE(SimpleCommandNode);
400 DirectoryNode & root();
404 ///////////////////////////////hh.e////////////////////////////////////////
414 // comment-column: 40
415 // c-file-style: "senf"
416 // indent-tabs-mode: nil
417 // ispell-local-dictionary: "american"
418 // compile-command: "scons -u test"