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/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   CommandArgumentEntry arg;
51   CommandArgumentData command_arg;
52 
53   // A list of command names forming a path to the command we want help on.
54   // No names is allowed - in which case we dump the top-level help.
55   command_arg.arg_type = eArgTypeCommand;
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       cmd_types |= CommandInterpreter::eCommandTypesUserMW;
91     }
92     if (m_options.m_show_hidden)
93       cmd_types |= CommandInterpreter::eCommandTypesHidden;
94 
95     result.SetStatus(eReturnStatusSuccessFinishNoResult);
96     m_interpreter.GetHelp(result, cmd_types); // General help
97   } else {
98     // Get command object for the first command argument. Only search built-in
99     // command dictionary.
100     StringList matches;
101     auto command_name = command[0].ref();
102     cmd_obj = m_interpreter.GetCommandObject(command_name, &matches);
103 
104     if (cmd_obj != nullptr) {
105       StringList matches;
106       bool all_okay = true;
107       CommandObject *sub_cmd_obj = cmd_obj;
108       // Loop down through sub_command dictionaries until we find the command
109       // object that corresponds to the help command entered.
110       std::string sub_command;
111       for (auto &entry : command.entries().drop_front()) {
112         sub_command = std::string(entry.ref());
113         matches.Clear();
114         if (sub_cmd_obj->IsAlias())
115           sub_cmd_obj =
116               ((CommandAlias *)sub_cmd_obj)->GetUnderlyingCommand().get();
117         if (!sub_cmd_obj->IsMultiwordObject()) {
118           all_okay = false;
119           break;
120         } else {
121           CommandObject *found_cmd;
122           found_cmd =
123               sub_cmd_obj->GetSubcommandObject(sub_command.c_str(), &matches);
124           if (found_cmd == nullptr || matches.GetSize() > 1) {
125             all_okay = false;
126             break;
127           } else
128             sub_cmd_obj = found_cmd;
129         }
130       }
131 
132       if (!all_okay || (sub_cmd_obj == nullptr)) {
133         std::string cmd_string;
134         command.GetCommandString(cmd_string);
135         if (matches.GetSize() >= 2) {
136           StreamString s;
137           s.Printf("ambiguous command %s", cmd_string.c_str());
138           size_t num_matches = matches.GetSize();
139           for (size_t match_idx = 0; match_idx < num_matches; match_idx++) {
140             s.Printf("\n\t%s", matches.GetStringAtIndex(match_idx));
141           }
142           s.Printf("\n");
143           result.AppendError(s.GetString());
144           return false;
145         } else if (!sub_cmd_obj) {
146           StreamString error_msg_stream;
147           GenerateAdditionalHelpAvenuesMessage(
148               &error_msg_stream, cmd_string.c_str(),
149               m_interpreter.GetCommandPrefix(), sub_command.c_str());
150           result.AppendError(error_msg_stream.GetString());
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       }
197     }
198   }
199 
200   return result.Succeeded();
201 }
202 
203 void CommandObjectHelp::HandleCompletion(CompletionRequest &request) {
204   // Return the completions of the commands in the help system:
205   if (request.GetCursorIndex() == 0) {
206     m_interpreter.HandleCompletionMatches(request);
207     return;
208   }
209   CommandObject *cmd_obj =
210       m_interpreter.GetCommandObject(request.GetParsedLine()[0].ref());
211 
212   // The command that they are getting help on might be ambiguous, in which
213   // case we should complete that, otherwise complete with the command the
214   // user is getting help on...
215 
216   if (cmd_obj) {
217     request.ShiftArguments();
218     cmd_obj->HandleCompletion(request);
219     return;
220   }
221   m_interpreter.HandleCompletionMatches(request);
222 }
223