cmd_help.cpp revision 1.1.1.1.4.2 
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
46namespace cmdline = utils::cmdline;
47namespace config = utils::config;
48namespace text = utils::text;
49
50using cli::cmd_help;
51
52
53namespace {
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.
61static text::table
62options_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.
95static void
96general_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.
165static void
166subcommand_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.
213cmd_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.
229int
230cmd_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