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 constexpr OptionDefinition g_help_options[] = {
75     // clang-format off
76   {LLDB_OPT_SET_ALL, false, "hide-aliases",         'a', OptionParser::eNoArgument, nullptr, {}, 0, eArgTypeNone, "Hide aliases in the command list."},
77   {LLDB_OPT_SET_ALL, false, "hide-user-commands",   'u', OptionParser::eNoArgument, nullptr, {}, 0, eArgTypeNone, "Hide user-defined commands from the list."},
78   {LLDB_OPT_SET_ALL, false, "show-hidden-commands", 'h', OptionParser::eNoArgument, 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
93   // 0, we show the user all commands (aliases and user commands if asked for).
94   // Otherwise every argument must be the name of a command or a sub-command.
95   if (argc == 0) {
96     uint32_t cmd_types = CommandInterpreter::eCommandTypesBuiltin;
97     if (m_options.m_show_aliases)
98       cmd_types |= CommandInterpreter::eCommandTypesAliases;
99     if (m_options.m_show_user_defined)
100       cmd_types |= CommandInterpreter::eCommandTypesUserDef;
101     if (m_options.m_show_hidden)
102       cmd_types |= CommandInterpreter::eCommandTypesHidden;
103 
104     result.SetStatus(eReturnStatusSuccessFinishNoResult);
105     m_interpreter.GetHelp(result, cmd_types); // General help
106   } else {
107     // Get command object for the first command argument. Only search built-in
108     // command dictionary.
109     StringList matches;
110     auto command_name = command[0].ref;
111     cmd_obj = m_interpreter.GetCommandObject(command_name, &matches);
112 
113     if (cmd_obj != nullptr) {
114       StringList matches;
115       bool all_okay = true;
116       CommandObject *sub_cmd_obj = cmd_obj;
117       // Loop down through sub_command dictionaries until we find the command
118       // object that corresponds to the help command entered.
119       std::string sub_command;
120       for (auto &entry : command.entries().drop_front()) {
121         sub_command = entry.ref;
122         matches.Clear();
123         if (sub_cmd_obj->IsAlias())
124           sub_cmd_obj =
125               ((CommandAlias *)sub_cmd_obj)->GetUnderlyingCommand().get();
126         if (!sub_cmd_obj->IsMultiwordObject()) {
127           all_okay = false;
128           break;
129         } else {
130           CommandObject *found_cmd;
131           found_cmd =
132               sub_cmd_obj->GetSubcommandObject(sub_command.c_str(), &matches);
133           if (found_cmd == nullptr || matches.GetSize() > 1) {
134             all_okay = false;
135             break;
136           } else
137             sub_cmd_obj = found_cmd;
138         }
139       }
140 
141       if (!all_okay || (sub_cmd_obj == nullptr)) {
142         std::string cmd_string;
143         command.GetCommandString(cmd_string);
144         if (matches.GetSize() >= 2) {
145           StreamString s;
146           s.Printf("ambiguous command %s", cmd_string.c_str());
147           size_t num_matches = matches.GetSize();
148           for (size_t match_idx = 0; match_idx < num_matches; match_idx++) {
149             s.Printf("\n\t%s", matches.GetStringAtIndex(match_idx));
150           }
151           s.Printf("\n");
152           result.AppendError(s.GetString());
153           result.SetStatus(eReturnStatusFailed);
154           return false;
155         } else if (!sub_cmd_obj) {
156           StreamString error_msg_stream;
157           GenerateAdditionalHelpAvenuesMessage(
158               &error_msg_stream, cmd_string.c_str(),
159               m_interpreter.GetCommandPrefix(), sub_command.c_str());
160           result.AppendError(error_msg_stream.GetString());
161           result.SetStatus(eReturnStatusFailed);
162           return false;
163         } else {
164           GenerateAdditionalHelpAvenuesMessage(
165               &result.GetOutputStream(), cmd_string.c_str(),
166               m_interpreter.GetCommandPrefix(), sub_command.c_str());
167           result.GetOutputStream().Printf(
168               "\nThe closest match is '%s'. Help on it follows.\n\n",
169               sub_cmd_obj->GetCommandName().str().c_str());
170         }
171       }
172 
173       sub_cmd_obj->GenerateHelpText(result);
174 
175       if (m_interpreter.AliasExists(command_name)) {
176         StreamString sstr;
177         m_interpreter.GetAlias(command_name)->GetAliasExpansion(sstr);
178         result.GetOutputStream().Printf("\n'%s' is an abbreviation for %s\n",
179                                         command[0].c_str(), sstr.GetData());
180       }
181     } else if (matches.GetSize() > 0) {
182       Stream &output_strm = result.GetOutputStream();
183       output_strm.Printf("Help requested with ambiguous command name, possible "
184                          "completions:\n");
185       const size_t match_count = matches.GetSize();
186       for (size_t i = 0; i < match_count; i++) {
187         output_strm.Printf("\t%s\n", matches.GetStringAtIndex(i));
188       }
189     } else {
190       // Maybe the user is asking for help about a command argument rather than
191       // a command.
192       const CommandArgumentType arg_type =
193           CommandObject::LookupArgumentName(command_name);
194       if (arg_type != eArgTypeLastArg) {
195         Stream &output_strm = result.GetOutputStream();
196         CommandObject::GetArgumentHelp(output_strm, arg_type, m_interpreter);
197         result.SetStatus(eReturnStatusSuccessFinishNoResult);
198       } else {
199         StreamString error_msg_stream;
200         GenerateAdditionalHelpAvenuesMessage(&error_msg_stream, command_name,
201                                              m_interpreter.GetCommandPrefix(),
202                                              "");
203         result.AppendError(error_msg_stream.GetString());
204         result.SetStatus(eReturnStatusFailed);
205       }
206     }
207   }
208 
209   return result.Succeeded();
210 }
211 
212 int CommandObjectHelp::HandleCompletion(CompletionRequest &request) {
213   // Return the completions of the commands in the help system:
214   if (request.GetCursorIndex() == 0) {
215     return m_interpreter.HandleCompletionMatches(request);
216   } else {
217     CommandObject *cmd_obj =
218         m_interpreter.GetCommandObject(request.GetParsedLine()[0].ref);
219 
220     // The command that they are getting help on might be ambiguous, in which
221     // case we should complete that, otherwise complete with the command the
222     // user is getting help on...
223 
224     if (cmd_obj) {
225       request.GetParsedLine().Shift();
226       request.SetCursorIndex(request.GetCursorIndex() - 1);
227       return cmd_obj->HandleCompletion(request);
228     } else {
229       return m_interpreter.HandleCompletionMatches(request);
230     }
231   }
232 }
233