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