contrib/llvm/tools/lldb/source/Commands/CommandObjectHelp.cpp

   1 //===-- CommandObjectHelp.cpp -----------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 // C Includes
  11 // C++ Includes
  12 // Other libraries and framework includes
  13 // Project includes
  14 #include "CommandObjectHelp.h"
  15 #include "lldb/Interpreter/CommandInterpreter.h"
  16 #include "lldb/Interpreter/CommandObjectMultiword.h"
  17 #include "lldb/Interpreter/CommandReturnObject.h"
  18 #include "lldb/Interpreter/Options.h"
  19
  20 using namespace lldb;
  21 using namespace lldb_private;
  22
  23 //-------------------------------------------------------------------------
  24 // CommandObjectHelp
  25 //-------------------------------------------------------------------------
  26
  27 void CommandObjectHelp::GenerateAdditionalHelpAvenuesMessage(
  28     Stream *s, llvm::StringRef command, llvm::StringRef prefix, llvm::StringRef subcommand,
  29     bool include_apropos, bool include_type_lookup) {
  30   if (!s || command.empty())
  31     return;
  32
  33   std::string command_str = command.str();
  34   std::string prefix_str = prefix.str();
  35   std::string subcommand_str = subcommand.str();
  36   const std::string &lookup_str = !subcommand_str.empty() ? subcommand_str : command_str;
  37   s->Printf("'%s' is not a known command.\n", command_str.c_str());
  38   s->Printf("Try '%shelp' to see a current list of commands.\n",
  39             prefix.str().c_str());
  40   if (include_apropos) {
  41     s->Printf("Try '%sapropos %s' for a list of related commands.\n",
  42       prefix_str.c_str(), lookup_str.c_str());
  43   }
  44   if (include_type_lookup) {
  45     s->Printf("Try '%stype lookup %s' for information on types, methods, "
  46               "functions, modules, etc.",
  47       prefix_str.c_str(), lookup_str.c_str());
  48   }
  49 }
  50
  51 CommandObjectHelp::CommandObjectHelp(CommandInterpreter &interpreter)
  52     : CommandObjectParsed(interpreter, "help", "Show a list of all debugger "
  53                                                "commands, or give details "
  54                                                "about a specific command.",
  55                           "help [<cmd-name>]"),
  56       m_options() {
  57   CommandArgumentEntry arg;
  58   CommandArgumentData command_arg;
  59
  60   // Define the first (and only) variant of this arg.
  61   command_arg.arg_type = eArgTypeCommandName;
  62   command_arg.arg_repetition = eArgRepeatStar;
  63
  64   // There is only one variant this argument could be; put it into the argument
  65   // entry.
  66   arg.push_back(command_arg);
  67
  68   // Push the data for the first argument into the m_arguments vector.
  69   m_arguments.push_back(arg);
  70 }
  71
  72 CommandObjectHelp::~CommandObjectHelp() = default;
  73
  74 static OptionDefinition g_help_options[] = {
  75     // clang-format off
  76   {LLDB_OPT_SET_ALL, false, "hide-aliases",         'a', OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone, "Hide aliases in the command list."},
  77   {LLDB_OPT_SET_ALL, false, "hide-user-commands",   'u', OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone, "Hide user-defined commands from the list."},
  78   {LLDB_OPT_SET_ALL, false, "show-hidden-commands", 'h', OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone, "Include commands prefixed with an underscore."},
  79     // clang-format on
  80 };
  81
  82 llvm::ArrayRef<OptionDefinition>
  83 CommandObjectHelp::CommandOptions::GetDefinitions() {
  84   return llvm::makeArrayRef(g_help_options);
  85 }
  86
  87 bool CommandObjectHelp::DoExecute(Args &command, CommandReturnObject &result) {
  88   CommandObject::CommandMap::iterator pos;
  89   CommandObject *cmd_obj;
  90   const size_t argc = command.GetArgumentCount();
  91
  92   // 'help' doesn't take any arguments, other than command names.  If argc is 0,
  93   // we show the user
  94   // all commands (aliases and user commands if asked for).  Otherwise every
  95   // argument must be the name of a command or a sub-command.
  96   if (argc == 0) {
  97     uint32_t cmd_types = CommandInterpreter::eCommandTypesBuiltin;
  98     if (m_options.m_show_aliases)
  99       cmd_types |= CommandInterpreter::eCommandTypesAliases;
 100     if (m_options.m_show_user_defined)
 101       cmd_types |= CommandInterpreter::eCommandTypesUserDef;
 102     if (m_options.m_show_hidden)
 103       cmd_types |= CommandInterpreter::eCommandTypesHidden;
 104
 105     result.SetStatus(eReturnStatusSuccessFinishNoResult);
 106     m_interpreter.GetHelp(result, cmd_types); // General help
 107   } else {
 108     // Get command object for the first command argument. Only search built-in
 109     // command dictionary.
 110     StringList matches;
 111     auto command_name = command[0].ref;
 112     cmd_obj = m_interpreter.GetCommandObject(command_name, &matches);
 113
 114     if (cmd_obj != nullptr) {
 115       StringList matches;
 116       bool all_okay = true;
 117       CommandObject *sub_cmd_obj = cmd_obj;
 118       // Loop down through sub_command dictionaries until we find the command
 119       // object that corresponds to the help command entered.
 120       std::string sub_command;
 121       for (auto &entry : command.entries().drop_front()) {
 122         sub_command = entry.ref;
 123         matches.Clear();
 124         if (sub_cmd_obj->IsAlias())
 125           sub_cmd_obj =
 126               ((CommandAlias *)sub_cmd_obj)->GetUnderlyingCommand().get();
 127         if (!sub_cmd_obj->IsMultiwordObject()) {
 128           all_okay = false;
 129           break;
 130         } else {
 131           CommandObject *found_cmd;
 132           found_cmd =
 133               sub_cmd_obj->GetSubcommandObject(sub_command.c_str(), &matches);
 134           if (found_cmd == nullptr || matches.GetSize() > 1) {
 135             all_okay = false;
 136             break;
 137           } else
 138             sub_cmd_obj = found_cmd;
 139         }
 140       }
 141
 142       if (!all_okay || (sub_cmd_obj == nullptr)) {
 143         std::string cmd_string;
 144         command.GetCommandString(cmd_string);
 145         if (matches.GetSize() >= 2) {
 146           StreamString s;
 147           s.Printf("ambiguous command %s", cmd_string.c_str());
 148           size_t num_matches = matches.GetSize();
 149           for (size_t match_idx = 0; match_idx < num_matches; match_idx++) {
 150             s.Printf("\n\t%s", matches.GetStringAtIndex(match_idx));
 151           }
 152           s.Printf("\n");
 153           result.AppendError(s.GetString());
 154           result.SetStatus(eReturnStatusFailed);
 155           return false;
 156         } else if (!sub_cmd_obj) {
 157           StreamString error_msg_stream;
 158           GenerateAdditionalHelpAvenuesMessage(
 159               &error_msg_stream, cmd_string.c_str(),
 160               m_interpreter.GetCommandPrefix(), sub_command.c_str());
 161           result.AppendError(error_msg_stream.GetString());
 162           result.SetStatus(eReturnStatusFailed);
 163           return false;
 164         } else {
 165           GenerateAdditionalHelpAvenuesMessage(
 166               &result.GetOutputStream(), cmd_string.c_str(),
 167               m_interpreter.GetCommandPrefix(), sub_command.c_str());
 168           result.GetOutputStream().Printf(
 169               "\nThe closest match is '%s'. Help on it follows.\n\n",
 170               sub_cmd_obj->GetCommandName().str().c_str());
 171         }
 172       }
 173
 174       sub_cmd_obj->GenerateHelpText(result);
 175
 176       if (m_interpreter.AliasExists(command_name)) {
 177         StreamString sstr;
 178         m_interpreter.GetAlias(command_name)->GetAliasExpansion(sstr);
 179         result.GetOutputStream().Printf("\n'%s' is an abbreviation for %s\n",
 180                                         command[0].c_str(), sstr.GetData());
 181       }
 182     } else if (matches.GetSize() > 0) {
 183       Stream &output_strm = result.GetOutputStream();
 184       output_strm.Printf("Help requested with ambiguous command name, possible "
 185                          "completions:\n");
 186       const size_t match_count = matches.GetSize();
 187       for (size_t i = 0; i < match_count; i++) {
 188         output_strm.Printf("\t%s\n", matches.GetStringAtIndex(i));
 189       }
 190     } else {
 191       // Maybe the user is asking for help about a command argument rather than
 192       // a command.
 193       const CommandArgumentType arg_type =
 194           CommandObject::LookupArgumentName(command_name);
 195       if (arg_type != eArgTypeLastArg) {
 196         Stream &output_strm = result.GetOutputStream();
 197         CommandObject::GetArgumentHelp(output_strm, arg_type, m_interpreter);
 198         result.SetStatus(eReturnStatusSuccessFinishNoResult);
 199       } else {
 200         StreamString error_msg_stream;
 201         GenerateAdditionalHelpAvenuesMessage(&error_msg_stream, command_name,
 202                                              m_interpreter.GetCommandPrefix(),
 203                                              "");
 204         result.AppendError(error_msg_stream.GetString());
 205         result.SetStatus(eReturnStatusFailed);
 206       }
 207     }
 208   }
 209
 210   return result.Succeeded();
 211 }
 212
 213 int CommandObjectHelp::HandleCompletion(Args &input, int &cursor_index,
 214                                         int &cursor_char_position,
 215                                         int match_start_point,
 216                                         int max_return_elements,
 217                                         bool &word_complete,
 218                                         StringList &matches) {
 219   // Return the completions of the commands in the help system:
 220   if (cursor_index == 0) {
 221     return m_interpreter.HandleCompletionMatches(
 222         input, cursor_index, cursor_char_position, match_start_point,
 223         max_return_elements, word_complete, matches);
 224   } else {
 225     CommandObject *cmd_obj = m_interpreter.GetCommandObject(input[0].ref);
 226
 227     // The command that they are getting help on might be ambiguous, in which
 228     // case we should complete that,
 229     // otherwise complete with the command the user is getting help on...
 230
 231     if (cmd_obj) {
 232       input.Shift();
 233       cursor_index--;
 234       return cmd_obj->HandleCompletion(
 235           input, cursor_index, cursor_char_position, match_start_point,
 236           max_return_elements, word_complete, matches);
 237     } else {
 238       return m_interpreter.HandleCompletionMatches(
 239           input, cursor_index, cursor_char_position, match_start_point,
 240           max_return_elements, word_complete, matches);
 241     }
 242   }
 243 }