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