1 // Copyright 2010 Google Inc.
2 // All rights reserved.
3 //
4 // Redistribution and use in source and binary forms, with or without
5 // modification, are permitted provided that the following conditions are
6 // met:
7 //
8 // * Redistributions of source code must retain the above copyright
9 // notice, this list of conditions and the following disclaimer.
10 // * Redistributions in binary form must reproduce the above copyright
11 // notice, this list of conditions and the following disclaimer in the
12 // documentation and/or other materials provided with the distribution.
13 // * Neither the name of Google Inc. nor the names of its contributors
14 // may be used to endorse or promote products derived from this software
15 // without specific prior written permission.
16 //
17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
20 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
22 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28
29 #include "cli/cmd_help.hpp"
30
31 #include <algorithm>
32 #include <cstdlib>
33
34 #include "cli/common.ipp"
35 #include "utils/cmdline/commands_map.ipp"
36 #include "utils/cmdline/exceptions.hpp"
37 #include "utils/cmdline/globals.hpp"
38 #include "utils/cmdline/options.hpp"
39 #include "utils/cmdline/parser.hpp"
40 #include "utils/cmdline/ui.hpp"
41 #include "utils/defs.hpp"
42 #include "utils/format/macros.hpp"
43 #include "utils/sanity.hpp"
44 #include "utils/text/table.hpp"
45
46 namespace cmdline = utils::cmdline;
47 namespace config = utils::config;
48 namespace text = utils::text;
49
50 using cli::cmd_help;
51
52
53 namespace {
54
55
56 /// Creates a table with the help of a set of options.
57 ///
58 /// \param options The set of options to describe. May be empty.
59 ///
60 /// \return A 2-column wide table with the description of the options.
61 static text::table
options_help(const cmdline::options_vector & options)62 options_help(const cmdline::options_vector& options)
63 {
64 text::table table(2);
65
66 for (cmdline::options_vector::const_iterator iter = options.begin();
67 iter != options.end(); iter++) {
68 const cmdline::base_option* option = *iter;
69
70 std::string description = option->description();
71 if (option->needs_arg() && option->has_default_value())
72 description += F(" (default: %s)") % option->default_value();
73
74 text::table_row row;
75
76 if (option->has_short_name())
77 row.push_back(F("%s, %s") % option->format_short_name() %
78 option->format_long_name());
79 else
80 row.push_back(F("%s") % option->format_long_name());
81 row.push_back(F("%s.") % description);
82
83 table.add_row(row);
84 }
85
86 return table;
87 }
88
89
90 /// Prints the summary of commands and generic options.
91 ///
92 /// \param ui Object to interact with the I/O of the program.
93 /// \param options The set of program-wide options for which to print help.
94 /// \param commands The set of commands for which to print help.
95 static void
general_help(cmdline::ui * ui,const cmdline::options_vector * options,const cmdline::commands_map<cli::cli_command> * commands)96 general_help(cmdline::ui* ui, const cmdline::options_vector* options,
97 const cmdline::commands_map< cli::cli_command >* commands)
98 {
99 PRE(!commands->empty());
100
101 ui->out_tag_wrap(
102 "Usage: ",
103 F("%s [general_options] command [command_options] [args]") %
104 cmdline::progname(), false);
105
106 const text::table options_table = options_help(*options);
107 text::widths_vector::value_type first_width =
108 options_table.column_width(0);
109
110 std::map< std::string, text::table > command_tables;
111
112 for (cmdline::commands_map< cli::cli_command >::const_iterator
113 iter = commands->begin(); iter != commands->end(); iter++) {
114 const std::string& category = (*iter).first;
115 const std::set< std::string >& command_names = (*iter).second;
116
117 command_tables.insert(std::map< std::string, text::table >::value_type(
118 category, text::table(2)));
119 text::table& table = command_tables.find(category)->second;
120
121 for (std::set< std::string >::const_iterator i2 = command_names.begin();
122 i2 != command_names.end(); i2++) {
123 const cli::cli_command* command = commands->find(*i2);
124 text::table_row row;
125 row.push_back(command->name());
126 row.push_back(F("%s.") % command->short_description());
127 table.add_row(row);
128 }
129
130 if (table.column_width(0) > first_width)
131 first_width = table.column_width(0);
132 }
133
134 text::table_formatter formatter;
135 formatter.set_column_width(0, first_width);
136 formatter.set_column_width(1, text::table_formatter::width_refill);
137 formatter.set_separator(" ");
138
139 if (!options_table.empty()) {
140 ui->out_wrap("");
141 ui->out_wrap("Available general options:");
142 ui->out_table(options_table, formatter, " ");
143 }
144
145 // Iterate using the same loop as above to preserve ordering.
146 for (cmdline::commands_map< cli::cli_command >::const_iterator
147 iter = commands->begin(); iter != commands->end(); iter++) {
148 const std::string& category = (*iter).first;
149 ui->out_wrap("");
150 ui->out_wrap(F("%s commands:") %
151 (category.empty() ? "Generic" : category));
152 ui->out_table(command_tables.find(category)->second, formatter, " ");
153 }
154
155 ui->out_wrap("");
156 ui->out_wrap("See kyua(1) for more details.");
157 }
158
159
160 /// Prints help for a particular subcommand.
161 ///
162 /// \param ui Object to interact with the I/O of the program.
163 /// \param general_options The options that apply to all commands.
164 /// \param command Pointer to the command to describe.
165 static void
subcommand_help(cmdline::ui * ui,const utils::cmdline::options_vector * general_options,const cli::cli_command * command)166 subcommand_help(cmdline::ui* ui,
167 const utils::cmdline::options_vector* general_options,
168 const cli::cli_command* command)
169 {
170 ui->out_tag_wrap(
171 "Usage: ", F("%s [general_options] %s%s%s") %
172 cmdline::progname() % command->name() %
173 (command->options().empty() ? "" : " [command_options]") %
174 (command->arg_list().empty() ? "" : (" " + command->arg_list())),
175 false);
176 ui->out_wrap("");
177 ui->out_wrap(F("%s.") % command->short_description());
178
179 const text::table general_table = options_help(*general_options);
180 const text::table command_table = options_help(command->options());
181
182 const text::widths_vector::value_type first_width =
183 std::max(general_table.column_width(0), command_table.column_width(0));
184 text::table_formatter formatter;
185 formatter.set_column_width(0, first_width);
186 formatter.set_column_width(1, text::table_formatter::width_refill);
187 formatter.set_separator(" ");
188
189 if (!general_table.empty()) {
190 ui->out_wrap("");
191 ui->out_wrap("Available general options:");
192 ui->out_table(general_table, formatter, " ");
193 }
194
195 if (!command_table.empty()) {
196 ui->out_wrap("");
197 ui->out_wrap("Available command options:");
198 ui->out_table(command_table, formatter, " ");
199 }
200
201 ui->out_wrap("");
202 ui->out_wrap(F("See kyua-%s(1) for more details.") % command->name());
203 }
204
205
206 } // anonymous namespace
207
208
209 /// Default constructor for cmd_help.
210 ///
211 /// \param options_ The set of program-wide options for which to provide help.
212 /// \param commands_ The set of commands for which to provide help.
cmd_help(const cmdline::options_vector * options_,const cmdline::commands_map<cli_command> * commands_)213 cmd_help::cmd_help(const cmdline::options_vector* options_,
214 const cmdline::commands_map< cli_command >* commands_) :
215 cli_command("help", "[subcommand]", 0, 1, "Shows usage information"),
216 _options(options_),
217 _commands(commands_)
218 {
219 }
220
221
222 /// Entry point for the "help" subcommand.
223 ///
224 /// \param ui Object to interact with the I/O of the program.
225 /// \param cmdline Representation of the command line to the subcommand.
226 /// \param unused_user_config The runtime configuration of the program.
227 ///
228 /// \return 0 to indicate success.
229 int
run(utils::cmdline::ui * ui,const cmdline::parsed_cmdline & cmdline,const config::tree & UTILS_UNUSED_PARAM (user_config))230 cmd_help::run(utils::cmdline::ui* ui, const cmdline::parsed_cmdline& cmdline,
231 const config::tree& UTILS_UNUSED_PARAM(user_config))
232 {
233 if (cmdline.arguments().empty()) {
234 general_help(ui, _options, _commands);
235 } else {
236 INV(cmdline.arguments().size() == 1);
237 const std::string& cmdname = cmdline.arguments()[0];
238 const cli::cli_command* command = _commands->find(cmdname);
239 if (command == NULL)
240 throw cmdline::usage_error(F("The command %s does not exist") %
241 cmdname);
242 else
243 subcommand_help(ui, _options, command);
244 }
245
246 return EXIT_SUCCESS;
247 }
248