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
|