From: g0dil <g0dil@270642c3-0616-0410-b53a-bc976706d245>
Date: Wed, 3 Jun 2009 13:52:05 +0000 (+0000)
Subject: Utils/Console: Add basic short-help info
X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=13d1ffe0c19d3085f1cf28f1a1c53d96572c0abe;p=senf.git

Utils/Console: Add basic short-help info

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

diff --git a/Utils/Console/Node.cc b/Utils/Console/Node.cc
index 41c1779..5a04317 100644
--- a/Utils/Console/Node.cc
+++ b/Utils/Console/Node.cc
@@ -95,10 +95,15 @@ prefix_ bool senf::console::GenericNode::isChildOf(DirectoryNode & parent)
 prefix_ void senf::console::LinkNode::v_help(std::ostream & os)
     const
 {
-    os << "link to ";
     follow().help(os);
 }
 
+prefix_ std::string senf::console::LinkNode::v_shorthelp()
+    const
+{
+    return follow().shorthelp();
+}
+
 ///////////////////////////////////////////////////////////////////////////
 //senf::console::DirectoryNode
 
@@ -161,6 +166,14 @@ prefix_ void senf::console::DirectoryNode::v_help(std::ostream & output)
     output << doc_ << "\n";
 }
 
+prefix_ std::string senf::console::DirectoryNode::v_shorthelp()
+    const
+{
+    if (! shortdoc_.empty())
+        return shortdoc_;
+    return doc_.substr(0,doc_.find('\n'));
+}
+
 ///////////////////////////////////////////////////////////////////////////
 // senf::console::detail::NodeTraverser
 
@@ -217,6 +230,14 @@ prefix_ void senf::console::SimpleCommandNode::v_help(std::ostream & output)
     output << doc_ << "\n";
 }
 
+prefix_ std::string senf::console::SimpleCommandNode::v_shorthelp()
+    const
+{
+    if (! shortdoc_.empty())
+        return shortdoc_;
+    return doc_.substr(0,doc_.find('\n'));
+}
+
 prefix_ void senf::console::SimpleCommandNode::v_execute(boost::any & rv, std::ostream & os,
                                                          ParseCommandInfo const & command)
     const
diff --git a/Utils/Console/Node.cci b/Utils/Console/Node.cci
index 59228c2..e0e3d77 100644
--- a/Utils/Console/Node.cci
+++ b/Utils/Console/Node.cci
@@ -84,6 +84,12 @@ prefix_ void senf::console::GenericNode::help(std::ostream & output)
     v_help(output);
 }
 
+prefix_ std::string senf::console::GenericNode::shorthelp()
+    const
+{
+    return v_shorthelp();
+}
+
 prefix_ bool senf::console::GenericNode::operator==(GenericNode & other)
     const
 {
@@ -247,6 +253,13 @@ senf::console::DirectoryNode::doc(std::string const & doc)
     return *this;
 }
 
+prefix_ senf::console::DirectoryNode &
+senf::console::DirectoryNode::shortdoc(std::string const & doc)
+{
+    shortdoc_ = doc;
+    return *this;
+}
+
 prefix_ senf::console::DirectoryNode::ptr senf::console::DirectoryNode::thisptr()
 {
     return boost::static_pointer_cast<DirectoryNode>(shared_from_this());
@@ -334,6 +347,13 @@ senf::console::SimpleCommandNode::doc(std::string const & doc)
     return *this;
 }
 
+prefix_ senf::console::SimpleCommandNode &
+senf::console::SimpleCommandNode::shortdoc(std::string const & doc)
+{
+    shortdoc_ = doc;
+    return *this;
+}
+
 prefix_ senf::console::SimpleCommandNode::ptr senf::console::SimpleCommandNode::thisptr()
 {
     return boost::static_pointer_cast<SimpleCommandNode>(shared_from_this());
diff --git a/Utils/Console/Node.hh b/Utils/Console/Node.hh
index 9a44c5a..4772b45 100644
--- a/Utils/Console/Node.hh
+++ b/Utils/Console/Node.hh
@@ -279,6 +279,7 @@ namespace console {
         bool active() const;            ///< \c true, if node is attached to the root() node
 
         void help(std::ostream & output) const; ///< Write help info to \a output
+        std::string shorthelp() const;  ///< Get short (one-line) documentation
 
         ptr thisptr();                  ///< Get smart pointer to node
         cptr thisptr() const;           ///< Get smart pointer to node (const)
@@ -312,8 +313,12 @@ namespace console {
 #endif
         virtual void v_help(std::ostream & output) const = 0;
                                         ///< Provide help information
-                                        /**< This member must be implemented in derived classes
-                                             to provide node specific help information. */
+                                        /**< This member must be implemented in derived classes to
+                                             provide node specific help information. */
+        virtual std::string v_shorthelp() const = 0;
+                                        ///< Provide short documentation
+                                        /**< This member must be implemented in derived classes to
+                                             provide node specific documentation. */
 
     private:
         std::string name_;
@@ -359,6 +364,7 @@ namespace console {
         explicit LinkNode(GenericNode & node);
 
         virtual void v_help(std::ostream &) const;
+        virtual std::string v_shorthelp() const;
 
         GenericNode::ptr node_;
     };
@@ -556,6 +562,7 @@ namespace console {
         ///////////////////////////////////////////////////////////////////////////
 
         DirectoryNode & doc(std::string const & doc); ///< Set node documentation
+        DirectoryNode & shortdoc(std::string const & doc); ///< Set node short documentation
 
         ptr thisptr();
         cptr thisptr() const;
@@ -566,9 +573,11 @@ namespace console {
     private:
         void add(GenericNode::ptr node);
         virtual void v_help(std::ostream & output) const;
+        virtual std::string v_shorthelp() const;
 
         ChildMap children_;
         std::string doc_;
+        std::string shortdoc_;
 
         friend DirectoryNode & root();
     };
@@ -694,18 +703,21 @@ namespace console {
         cptr thisptr() const;
 
         SimpleCommandNode & doc(std::string const & doc);
+        SimpleCommandNode & shortdoc(std::string const & doc);
 
     protected:
         SimpleCommandNode(Function const & fn);
 
     private:
         virtual void v_help(std::ostream & output) const;
+        virtual std::string v_shorthelp() const;
         virtual void v_execute(boost::any & rv, std::ostream & os, ParseCommandInfo const & command)
             const;
 
 
         Function fn_;
         std::string doc_;
+        std::string shortdoc_;
     };
 
 #ifndef DOXYGEN
diff --git a/Utils/Console/Node.test.cc b/Utils/Console/Node.test.cc
index 1b2a3c7..aeea861 100644
--- a/Utils/Console/Node.test.cc
+++ b/Utils/Console/Node.test.cc
@@ -107,10 +107,15 @@ BOOST_AUTO_UNIT_TEST(directoryNode)
         completions, 
         completions+sizeof(completions)/sizeof(completions[0]) );
 
-    p->doc("test doc");
+    p->doc("test doc\nline 2");
     std::stringstream ss;
     p->help(ss);
-    BOOST_CHECK_EQUAL( ss.str(), "test doc\n" );
+    BOOST_CHECK_EQUAL( ss.str(), "test doc\nline 2\n" );
+    BOOST_CHECK_EQUAL( p->shorthelp(), "test doc" );
+    p->doc("");
+    BOOST_CHECK_EQUAL( p->shorthelp(), "" );
+    p->shortdoc("short doc");
+    BOOST_CHECK_EQUAL( p->shorthelp(), "short doc" );
 
     BOOST_CHECK( senf::console::root().remove("dir1") == p );
     senf::console::root().remove("dir2");
diff --git a/Utils/Console/OverloadedCommand.cc b/Utils/Console/OverloadedCommand.cc
index abae95e..8a0c631 100644
--- a/Utils/Console/OverloadedCommand.cc
+++ b/Utils/Console/OverloadedCommand.cc
@@ -155,6 +155,14 @@ prefix_ void senf::console::OverloadedCommandNode::v_help(std::ostream & os)
     }
 }
 
+prefix_ std::string senf::console::OverloadedCommandNode::v_shorthelp()
+    const
+{
+    if (!shortdoc_.empty())
+        return shortdoc_;
+    return doc_.substr(0,doc_.find('\n'));
+}
+
 prefix_ void senf::console::OverloadedCommandNode::v_execute(boost::any & rv,
                                                              std::ostream & os,
                                                              ParseCommandInfo const & command)
diff --git a/Utils/Console/OverloadedCommand.cci b/Utils/Console/OverloadedCommand.cci
index c2fbdc6..dbbb7c0 100644
--- a/Utils/Console/OverloadedCommand.cci
+++ b/Utils/Console/OverloadedCommand.cci
@@ -56,6 +56,13 @@ senf::console::OverloadedCommandNode::doc(std::string const & doc)
     return *this;
 }
 
+prefix_ senf::console::OverloadedCommandNode &
+senf::console::OverloadedCommandNode::shortdoc(std::string const & doc)
+{
+    shortdoc_ = doc;
+    return *this;
+}
+
 prefix_ unsigned
 senf::console::OverloadedCommandNode::overloadIndex(CommandOverload const & overload)
 {
diff --git a/Utils/Console/OverloadedCommand.hh b/Utils/Console/OverloadedCommand.hh
index bb80f23..fb374ec 100644
--- a/Utils/Console/OverloadedCommand.hh
+++ b/Utils/Console/OverloadedCommand.hh
@@ -184,6 +184,8 @@ namespace console {
 
         OverloadedCommandNode & doc(std::string const & doc);
                                         ///< Assign global help for all overloads
+        OverloadedCommandNode & shortdoc(std::string const & doc);
+                                        ///< Assign short documentation for all overloads
 
         unsigned overloadIndex(CommandOverload const & overload);
                                         ///< Return the overload index for \a overload
@@ -197,6 +199,7 @@ namespace console {
         OverloadedCommandNode();
 
         virtual void v_help(std::ostream & output) const;
+        virtual std::string v_shorthelp() const;
         virtual void v_execute(boost::any & rv, std::ostream & os, ParseCommandInfo const & command)
             const;
 
@@ -204,6 +207,7 @@ namespace console {
 
         Overloads overloads_;
         std::string doc_;
+        std::string shortdoc_;
     };
 
     /** \brief Basic command overload
diff --git a/Utils/Console/ParsedCommand.cci b/Utils/Console/ParsedCommand.cci
index aeab60e..1ec6a29 100644
--- a/Utils/Console/ParsedCommand.cci
+++ b/Utils/Console/ParsedCommand.cci
@@ -120,6 +120,12 @@ prefix_ void senf::console::ParsedCommandAttributorBase::nodeDoc(std::string con
     node().doc(doc);
 }
 
+prefix_ void senf::console::ParsedCommandAttributorBase::shortDoc(std::string const & doc)
+    const
+{
+    node().shortdoc(doc);
+}
+
 ///////////////////////////////cci.e///////////////////////////////////////
 #undef prefix_
 
diff --git a/Utils/Console/ParsedCommand.cti b/Utils/Console/ParsedCommand.cti
index 065f14f..7e9710f 100644
--- a/Utils/Console/ParsedCommand.cti
+++ b/Utils/Console/ParsedCommand.cti
@@ -104,6 +104,15 @@ senf::console::ParsedArgumentAttributorBase<Overload,Self,ReturnType>::doc(std::
 
 template <class Overload, class Self, class ReturnType>
 prefix_ Self senf::console::ParsedArgumentAttributorBase<Overload,Self,ReturnType>::
+shortdoc(std::string const & doc)
+    const
+{
+    this->ParsedCommandAttributorBase::shortDoc(doc);
+    return static_cast<Self const &>(*this);
+}
+
+template <class Overload, class Self, class ReturnType>
+prefix_ Self senf::console::ParsedArgumentAttributorBase<Overload,Self,ReturnType>::
 overloadDoc(std::string const & doc)
     const
 {
@@ -137,6 +146,15 @@ senf::console::ParsedArgumentAttributorBase<Overload,Self,void>::doc(std::string
 }
 
 template <class Overload, class Self>
+prefix_ Self senf::console::ParsedArgumentAttributorBase<Overload, Self, void>::
+shortdoc(std::string const & doc)
+    const
+{
+    this->ParsedCommandAttributorBase::shortDoc(doc);
+    return static_cast<Self const &>(*this);
+}
+
+template <class Overload, class Self>
 prefix_ Self senf::console::ParsedArgumentAttributorBase<Overload,Self,void>::
 overloadDoc(std::string const & doc)
     const
diff --git a/Utils/Console/ParsedCommand.hh b/Utils/Console/ParsedCommand.hh
index ba0bbca..45276cb 100644
--- a/Utils/Console/ParsedCommand.hh
+++ b/Utils/Console/ParsedCommand.hh
@@ -216,6 +216,7 @@ namespace console {
         ParsedCommandOverloadBase & overload() const;
         void overloadDoc(std::string const & doc) const;
         void nodeDoc(std::string const & doc) const;
+        void shortDoc(std::string const & doc) const;
         
     private:
         ParsedCommandOverloadBase & overload_;
@@ -398,6 +399,7 @@ namespace console {
     {
     public:
         Self doc(std::string const & doc) const; ///< Set documentation for all overloads
+        Self shortdoc(std::string const & doc) const; ///< Set short documentation for all overloads
         Self overloadDoc(std::string const & doc) const; ///< Set overload specific documentation
         Self formatter(typename Overload::Formatter formatter) const; 
                                         ///< Set return value formatter
@@ -426,6 +428,7 @@ namespace console {
     {
     public:
         Self doc(std::string const & doc) const; ///< Set documentation for all overloads
+        Self shortdoc(std::string const & doc) const; ///< Set short documentation for all overloads
         Self overloadDoc(std::string const & doc) const; ///< Set overload specific documentation
 
     protected:
diff --git a/Utils/Console/ParsedCommand.test.cc b/Utils/Console/ParsedCommand.test.cc
index e2413e7..74f57d7 100644
--- a/Utils/Console/ParsedCommand.test.cc
+++ b/Utils/Console/ParsedCommand.test.cc
@@ -165,6 +165,9 @@ BOOST_AUTO_UNIT_TEST(parsedCommand)
                 "lux sto ioco. Per Re dono. Copiose reus scitus jus diligens sis scapulare\n"
                 "Servitium transi." )
 
+            .shortdoc(
+                "Ops fortunate." )
+
             .overloadDoc(
                 "Lo nam balnearius Opprimo Pennatus, no decentia sui, dicto esse se pulchritudo,\n"
                 "pupa Sive res indifferenter. Captivo pa." )
@@ -201,6 +204,8 @@ BOOST_AUTO_UNIT_TEST(parsedCommand)
                          boost::bind<void>( boost::ref(executor), boost::ref(ss), _1 )) );
 
         BOOST_CHECK_EQUAL( ss.str(), "333\n" "224\n" "Value: foo\n" "Value: \n" );
+
+        BOOST_CHECK_EQUAL( dir("cb").shorthelp(), "Ops fortunate." );
     }
 
     {
diff --git a/Utils/Console/Variables.cti b/Utils/Console/Variables.cti
index f428842..e5a311c 100644
--- a/Utils/Console/Variables.cti
+++ b/Utils/Console/Variables.cti
@@ -80,6 +80,14 @@ senf::console::ConstVariableAttributor<Variable>::doc(std::string const & doc)
 
 template <class Variable>
 prefix_ senf::console::ConstVariableAttributor<Variable>
+senf::console::ConstVariableAttributor<Variable>::shortdoc(std::string const & doc)
+{
+    queryOverload_.node().shortdoc(doc);
+    return *this;
+}
+
+template <class Variable>
+prefix_ senf::console::ConstVariableAttributor<Variable>
 senf::console::ConstVariableAttributor<Variable>::formatter(Formatter formatter)
 {
     queryOverload_.formatter(formatter);
@@ -146,6 +154,14 @@ senf::console::VariableAttributor<Variable>::doc(std::string const & doc)
 
 template <class Variable>
 prefix_ typename senf::console::VariableAttributor<Variable>
+senf::console::VariableAttributor<Variable>::shortdoc(std::string const & doc)
+{
+    ConstVariableAttributor<Variable>::shortdoc(doc);
+    return *this;
+}
+
+template <class Variable>
+prefix_ typename senf::console::VariableAttributor<Variable>
 senf::console::VariableAttributor<Variable>::formatter(Formatter formatter)
 {
     ConstVariableAttributor<Variable>::formatter(formatter);
diff --git a/Utils/Console/Variables.hh b/Utils/Console/Variables.hh
index 870f2ed..4f93a93 100644
--- a/Utils/Console/Variables.hh
+++ b/Utils/Console/Variables.hh
@@ -86,6 +86,7 @@ namespace console {
         typedef ConstVariableAttributor return_type;
 
         ConstVariableAttributor doc(std::string const & doc);
+        ConstVariableAttributor shortdoc(std::string const & doc);
         ConstVariableAttributor formatter(Formatter formatter);
 
         OverloadedCommandNode & node() const; ///< Return the node object
@@ -145,6 +146,7 @@ namespace console {
         typedef typename ConstVariableAttributor<Variable>::QueryOverload QueryOverload;
 
         VariableAttributor doc(std::string const & doc); ///< Set documentation of the variable
+        VariableAttributor shortdoc(std::string const & doc); ///< Set short documentation
         VariableAttributor formatter(Formatter formatter); ///< Set formatter
         /**< The \a formatter must be a callable with a signature
              compatible with