LCOV - code coverage report
Current view: top level - src/tools/kdb - command.hpp (source / functions) Hit Total Coverage
Test: coverage-filtered.info Lines: 9 14 64.3 %
Date: 2019-09-12 12:28:41 Functions: 4 9 44.4 %

          Line data    Source code
       1             : /**
       2             :  * @file
       3             :  *
       4             :  * @brief
       5             :  *
       6             :  * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
       7             :  */
       8             : 
       9             : #ifndef COMMAND_HPP
      10             : #define COMMAND_HPP
      11             : 
      12             : #include <exception>
      13             : #include <memory>
      14             : #include <stdexcept>
      15             : #include <string>
      16             : 
      17             : class Cmdline;
      18             : 
      19             : /**
      20             :  * Base class for some of the exceptions thrown in a command, except
      21             :  * (see main.cpp for handling):
      22             :  * - KDBException for KDB errors
      23             :  * - invalid_argument is thrown for argument errors
      24             :  */
      25           6 : class CommandException : public std::exception
      26             : {
      27             : public:
      28           0 :         virtual const char * what () const throw () override
      29             :         {
      30           0 :                 return "A situation had a appeared where the command had to abort, but no message was given.";
      31             :         }
      32             : 
      33           0 :         virtual int errorCode () const throw ()
      34             :         {
      35           0 :                 return 3;
      36             :         }
      37             : };
      38             : 
      39           6 : class CommandAbortException : public CommandException
      40             : {
      41             :         int m_errorCode;
      42             :         std::string m_msg;
      43             : 
      44             : public:
      45           0 :         CommandAbortException () : m_errorCode (3), m_msg ()
      46             :         {
      47             :         }
      48             : 
      49           6 :         explicit CommandAbortException (std::string msg, int errorCode = 3) : m_errorCode (errorCode), m_msg (msg)
      50             :         {
      51           2 :         }
      52             : 
      53           2 :         virtual const char * what () const throw () override
      54             :         {
      55           6 :                 return !m_msg.empty () ? m_msg.c_str () :
      56           2 :                                          "A situation had occurred where the command had to abort, but no message is available.";
      57             :         }
      58             : 
      59           6 :         virtual int errorCode () const throw () override
      60             :         {
      61           6 :                 return m_errorCode;
      62             :         }
      63             : };
      64             : 
      65             : class Command
      66             : {
      67             : public:
      68             :         virtual ~Command ();
      69             : 
      70             :         /**
      71             :          * @return the text representing which short options are needed
      72             :          *         by this command.
      73             :          *
      74             :          * @note the :, which indicates that an optional argument is needed,
      75             :          *       is added automatically.
      76             :          *       HV (for help and version) are automatically added.
      77             :          *       All options are sorted and made unique before passed
      78             :          *       to getopt.
      79             :          *
      80             :          */
      81             :         virtual std::string getShortOptions () = 0;
      82             : 
      83             :         /**
      84             :          * @return a string describing describe what parameter the
      85             :          *       command needs or an empty line if none.
      86             :          *
      87             :          * The return value should be:
      88             :          *
      89             :          * @code
      90             :          * <name> [<value>]
      91             :          * @endcode
      92             :          *
      93             :          * if you want the help to be printed like:
      94             :          *
      95             :          * @code
      96             :          * Usage: kdb set <name> [<value>]
      97             :          * @endcode
      98             :          *
      99             :          * The string may be empty if no arguments are taken.
     100             :          */
     101             :         virtual std::string getSynopsis () = 0;
     102             : 
     103             :         /**
     104             :          * @return a one line help text
     105             :          *
     106             :          * The help text is shown in the overview of the command
     107             :          * and as first line of normal help text given by -H or --help
     108             :          *
     109             :          * The sentence should end with an dot.
     110             :          * No newline should occur in the sentence.
     111             :          *
     112             :          * @see getLongHelpText for the other help text lines
     113             :          */
     114             :         virtual std::string getShortHelpText () = 0;
     115             : 
     116             :         /**
     117             :          * @return a long description of what the command does.
     118             :          *
     119             :          * May contain multiple lines or paragraphs.
     120             :          * A line should not exceed 72 characters.
     121             :          * The text should not start or end with an newline feed.
     122             :          *
     123             :          * @code
     124             :          * Long description what the command does.
     125             :          * Even more explanation.
     126             :          * @endcode
     127             :          *
     128             :          * The long description should not repeat what the
     129             :          * short help text already said, because the
     130             :          * short help text will be the first line
     131             :          * when help is shown.
     132             :          *
     133             :          * @see getShortHelpText for the first line
     134             :          *
     135             :          * The long text should describe all elements
     136             :          * of the synopsis.
     137             :          *
     138             :          * @see getSynopsis for the synopsis
     139             :          *
     140             :          * It should not describe any of the commandline
     141             :          * options, but rather use the cmdline option
     142             :          * parsing system.
     143             :          *
     144             :          * @see getShortOptions to express available options
     145             :          */
     146             :         virtual std::string getLongHelpText () = 0;
     147             : 
     148             :         /**
     149             :          * Execute the command.
     150             :          *
     151             :          * @pre The options are parsed already.
     152             :          *
     153             :          * You need to take care if there is the correct number
     154             :          * of arguments with the correct contents.
     155             :          * This is needed because of optional parameters.
     156             :          *
     157             :          * @retval 0 if the command could be executed successfully.
     158             :          *
     159             :          * @return a positive number if any other error occurred.
     160             :          *         No help is shown in this situation.
     161             :          *
     162             :          * @throw invalid_argument if the cmdline arguments could
     163             :          *        not be processed successfully.
     164             :          */
     165             :         virtual int execute (Cmdline const & cmdline) = 0;
     166             : };
     167             : 
     168             : typedef std::unique_ptr<Command> CommandPtr;
     169             : 
     170             : #endif

Generated by: LCOV version 1.13