external/bsd/kyua-cli/dist/cli/cmd_help.cpp

   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
  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
  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
 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.
 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
 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 }