lldb/source/Commands/CommandObjectHelp.cpp

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