1dda28197Spatrick //===-- CommandObjectHelp.cpp ---------------------------------------------===//
2061da546Spatrick //
3061da546Spatrick // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4061da546Spatrick // See https://llvm.org/LICENSE.txt for license information.
5061da546Spatrick // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6061da546Spatrick //
7061da546Spatrick //===----------------------------------------------------------------------===//
8061da546Spatrick
9061da546Spatrick #include "CommandObjectHelp.h"
10061da546Spatrick #include "lldb/Interpreter/CommandInterpreter.h"
11*f6aab3d8Srobert #include "lldb/Interpreter/CommandOptionArgumentTable.h"
12061da546Spatrick #include "lldb/Interpreter/CommandReturnObject.h"
13061da546Spatrick
14061da546Spatrick using namespace lldb;
15061da546Spatrick using namespace lldb_private;
16061da546Spatrick
17061da546Spatrick // CommandObjectHelp
18061da546Spatrick
GenerateAdditionalHelpAvenuesMessage(Stream * s,llvm::StringRef command,llvm::StringRef prefix,llvm::StringRef subcommand,bool include_upropos,bool include_type_lookup)19061da546Spatrick void CommandObjectHelp::GenerateAdditionalHelpAvenuesMessage(
20061da546Spatrick Stream *s, llvm::StringRef command, llvm::StringRef prefix,
21061da546Spatrick llvm::StringRef subcommand, bool include_upropos,
22061da546Spatrick bool include_type_lookup) {
23061da546Spatrick if (!s || command.empty())
24061da546Spatrick return;
25061da546Spatrick
26061da546Spatrick std::string command_str = command.str();
27061da546Spatrick std::string prefix_str = prefix.str();
28061da546Spatrick std::string subcommand_str = subcommand.str();
29061da546Spatrick const std::string &lookup_str =
30061da546Spatrick !subcommand_str.empty() ? subcommand_str : command_str;
31061da546Spatrick s->Printf("'%s' is not a known command.\n", command_str.c_str());
32061da546Spatrick s->Printf("Try '%shelp' to see a current list of commands.\n",
33061da546Spatrick prefix.str().c_str());
34061da546Spatrick if (include_upropos) {
35061da546Spatrick s->Printf("Try '%sapropos %s' for a list of related commands.\n",
36061da546Spatrick prefix_str.c_str(), lookup_str.c_str());
37061da546Spatrick }
38061da546Spatrick if (include_type_lookup) {
39061da546Spatrick s->Printf("Try '%stype lookup %s' for information on types, methods, "
40061da546Spatrick "functions, modules, etc.",
41061da546Spatrick prefix_str.c_str(), lookup_str.c_str());
42061da546Spatrick }
43061da546Spatrick }
44061da546Spatrick
CommandObjectHelp(CommandInterpreter & interpreter)45061da546Spatrick CommandObjectHelp::CommandObjectHelp(CommandInterpreter &interpreter)
46061da546Spatrick : CommandObjectParsed(interpreter, "help",
47061da546Spatrick "Show a list of all debugger "
48061da546Spatrick "commands, or give details "
49061da546Spatrick "about a specific command.",
50*f6aab3d8Srobert "help [<cmd-name>]") {
51061da546Spatrick CommandArgumentEntry arg;
52061da546Spatrick CommandArgumentData command_arg;
53061da546Spatrick
54*f6aab3d8Srobert // A list of command names forming a path to the command we want help on.
55*f6aab3d8Srobert // No names is allowed - in which case we dump the top-level help.
56*f6aab3d8Srobert command_arg.arg_type = eArgTypeCommand;
57061da546Spatrick command_arg.arg_repetition = eArgRepeatStar;
58061da546Spatrick
59061da546Spatrick // There is only one variant this argument could be; put it into the argument
60061da546Spatrick // entry.
61061da546Spatrick arg.push_back(command_arg);
62061da546Spatrick
63061da546Spatrick // Push the data for the first argument into the m_arguments vector.
64061da546Spatrick m_arguments.push_back(arg);
65061da546Spatrick }
66061da546Spatrick
67061da546Spatrick CommandObjectHelp::~CommandObjectHelp() = default;
68061da546Spatrick
69061da546Spatrick #define LLDB_OPTIONS_help
70061da546Spatrick #include "CommandOptions.inc"
71061da546Spatrick
72061da546Spatrick llvm::ArrayRef<OptionDefinition>
GetDefinitions()73061da546Spatrick CommandObjectHelp::CommandOptions::GetDefinitions() {
74*f6aab3d8Srobert return llvm::ArrayRef(g_help_options);
75061da546Spatrick }
76061da546Spatrick
DoExecute(Args & command,CommandReturnObject & result)77061da546Spatrick bool CommandObjectHelp::DoExecute(Args &command, CommandReturnObject &result) {
78061da546Spatrick CommandObject::CommandMap::iterator pos;
79061da546Spatrick CommandObject *cmd_obj;
80061da546Spatrick const size_t argc = command.GetArgumentCount();
81061da546Spatrick
82061da546Spatrick // 'help' doesn't take any arguments, other than command names. If argc is
83061da546Spatrick // 0, we show the user all commands (aliases and user commands if asked for).
84061da546Spatrick // Otherwise every argument must be the name of a command or a sub-command.
85061da546Spatrick if (argc == 0) {
86061da546Spatrick uint32_t cmd_types = CommandInterpreter::eCommandTypesBuiltin;
87061da546Spatrick if (m_options.m_show_aliases)
88061da546Spatrick cmd_types |= CommandInterpreter::eCommandTypesAliases;
89*f6aab3d8Srobert if (m_options.m_show_user_defined) {
90061da546Spatrick cmd_types |= CommandInterpreter::eCommandTypesUserDef;
91*f6aab3d8Srobert cmd_types |= CommandInterpreter::eCommandTypesUserMW;
92*f6aab3d8Srobert }
93061da546Spatrick if (m_options.m_show_hidden)
94061da546Spatrick cmd_types |= CommandInterpreter::eCommandTypesHidden;
95061da546Spatrick
96061da546Spatrick result.SetStatus(eReturnStatusSuccessFinishNoResult);
97061da546Spatrick m_interpreter.GetHelp(result, cmd_types); // General help
98061da546Spatrick } else {
99061da546Spatrick // Get command object for the first command argument. Only search built-in
100061da546Spatrick // command dictionary.
101061da546Spatrick StringList matches;
102061da546Spatrick auto command_name = command[0].ref();
103061da546Spatrick cmd_obj = m_interpreter.GetCommandObject(command_name, &matches);
104061da546Spatrick
105061da546Spatrick if (cmd_obj != nullptr) {
106061da546Spatrick StringList matches;
107061da546Spatrick bool all_okay = true;
108061da546Spatrick CommandObject *sub_cmd_obj = cmd_obj;
109061da546Spatrick // Loop down through sub_command dictionaries until we find the command
110061da546Spatrick // object that corresponds to the help command entered.
111061da546Spatrick std::string sub_command;
112061da546Spatrick for (auto &entry : command.entries().drop_front()) {
113dda28197Spatrick sub_command = std::string(entry.ref());
114061da546Spatrick matches.Clear();
115061da546Spatrick if (sub_cmd_obj->IsAlias())
116061da546Spatrick sub_cmd_obj =
117061da546Spatrick ((CommandAlias *)sub_cmd_obj)->GetUnderlyingCommand().get();
118061da546Spatrick if (!sub_cmd_obj->IsMultiwordObject()) {
119061da546Spatrick all_okay = false;
120061da546Spatrick break;
121061da546Spatrick } else {
122061da546Spatrick CommandObject *found_cmd;
123061da546Spatrick found_cmd =
124061da546Spatrick sub_cmd_obj->GetSubcommandObject(sub_command.c_str(), &matches);
125061da546Spatrick if (found_cmd == nullptr || matches.GetSize() > 1) {
126061da546Spatrick all_okay = false;
127061da546Spatrick break;
128061da546Spatrick } else
129061da546Spatrick sub_cmd_obj = found_cmd;
130061da546Spatrick }
131061da546Spatrick }
132061da546Spatrick
133061da546Spatrick if (!all_okay || (sub_cmd_obj == nullptr)) {
134061da546Spatrick std::string cmd_string;
135061da546Spatrick command.GetCommandString(cmd_string);
136061da546Spatrick if (matches.GetSize() >= 2) {
137061da546Spatrick StreamString s;
138061da546Spatrick s.Printf("ambiguous command %s", cmd_string.c_str());
139061da546Spatrick size_t num_matches = matches.GetSize();
140061da546Spatrick for (size_t match_idx = 0; match_idx < num_matches; match_idx++) {
141061da546Spatrick s.Printf("\n\t%s", matches.GetStringAtIndex(match_idx));
142061da546Spatrick }
143061da546Spatrick s.Printf("\n");
144061da546Spatrick result.AppendError(s.GetString());
145061da546Spatrick return false;
146061da546Spatrick } else if (!sub_cmd_obj) {
147061da546Spatrick StreamString error_msg_stream;
148061da546Spatrick GenerateAdditionalHelpAvenuesMessage(
149061da546Spatrick &error_msg_stream, cmd_string.c_str(),
150061da546Spatrick m_interpreter.GetCommandPrefix(), sub_command.c_str());
151061da546Spatrick result.AppendError(error_msg_stream.GetString());
152061da546Spatrick return false;
153061da546Spatrick } else {
154061da546Spatrick GenerateAdditionalHelpAvenuesMessage(
155061da546Spatrick &result.GetOutputStream(), cmd_string.c_str(),
156061da546Spatrick m_interpreter.GetCommandPrefix(), sub_command.c_str());
157061da546Spatrick result.GetOutputStream().Printf(
158061da546Spatrick "\nThe closest match is '%s'. Help on it follows.\n\n",
159061da546Spatrick sub_cmd_obj->GetCommandName().str().c_str());
160061da546Spatrick }
161061da546Spatrick }
162061da546Spatrick
163061da546Spatrick sub_cmd_obj->GenerateHelpText(result);
164061da546Spatrick std::string alias_full_name;
165061da546Spatrick // Don't use AliasExists here, that only checks exact name matches. If
166061da546Spatrick // the user typed a shorter unique alias name, we should still tell them
167061da546Spatrick // it was an alias.
168061da546Spatrick if (m_interpreter.GetAliasFullName(command_name, alias_full_name)) {
169061da546Spatrick StreamString sstr;
170061da546Spatrick m_interpreter.GetAlias(alias_full_name)->GetAliasExpansion(sstr);
171061da546Spatrick result.GetOutputStream().Printf("\n'%s' is an abbreviation for %s\n",
172061da546Spatrick command[0].c_str(), sstr.GetData());
173061da546Spatrick }
174061da546Spatrick } else if (matches.GetSize() > 0) {
175061da546Spatrick Stream &output_strm = result.GetOutputStream();
176061da546Spatrick output_strm.Printf("Help requested with ambiguous command name, possible "
177061da546Spatrick "completions:\n");
178061da546Spatrick const size_t match_count = matches.GetSize();
179061da546Spatrick for (size_t i = 0; i < match_count; i++) {
180061da546Spatrick output_strm.Printf("\t%s\n", matches.GetStringAtIndex(i));
181061da546Spatrick }
182061da546Spatrick } else {
183061da546Spatrick // Maybe the user is asking for help about a command argument rather than
184061da546Spatrick // a command.
185061da546Spatrick const CommandArgumentType arg_type =
186061da546Spatrick CommandObject::LookupArgumentName(command_name);
187061da546Spatrick if (arg_type != eArgTypeLastArg) {
188061da546Spatrick Stream &output_strm = result.GetOutputStream();
189061da546Spatrick CommandObject::GetArgumentHelp(output_strm, arg_type, m_interpreter);
190061da546Spatrick result.SetStatus(eReturnStatusSuccessFinishNoResult);
191061da546Spatrick } else {
192061da546Spatrick StreamString error_msg_stream;
193061da546Spatrick GenerateAdditionalHelpAvenuesMessage(&error_msg_stream, command_name,
194061da546Spatrick m_interpreter.GetCommandPrefix(),
195061da546Spatrick "");
196061da546Spatrick result.AppendError(error_msg_stream.GetString());
197061da546Spatrick }
198061da546Spatrick }
199061da546Spatrick }
200061da546Spatrick
201061da546Spatrick return result.Succeeded();
202061da546Spatrick }
203061da546Spatrick
HandleCompletion(CompletionRequest & request)204061da546Spatrick void CommandObjectHelp::HandleCompletion(CompletionRequest &request) {
205061da546Spatrick // Return the completions of the commands in the help system:
206061da546Spatrick if (request.GetCursorIndex() == 0) {
207061da546Spatrick m_interpreter.HandleCompletionMatches(request);
208061da546Spatrick return;
209061da546Spatrick }
210061da546Spatrick CommandObject *cmd_obj =
211061da546Spatrick m_interpreter.GetCommandObject(request.GetParsedLine()[0].ref());
212061da546Spatrick
213061da546Spatrick // The command that they are getting help on might be ambiguous, in which
214061da546Spatrick // case we should complete that, otherwise complete with the command the
215061da546Spatrick // user is getting help on...
216061da546Spatrick
217061da546Spatrick if (cmd_obj) {
218061da546Spatrick request.ShiftArguments();
219061da546Spatrick cmd_obj->HandleCompletion(request);
220061da546Spatrick return;
221061da546Spatrick }
222061da546Spatrick m_interpreter.HandleCompletionMatches(request);
223061da546Spatrick }
224