1 //===-- CommandObjectHelp.cpp -----------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
12 // Other libraries and framework 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"
21 using namespace lldb_private;
23 //-------------------------------------------------------------------------
25 //-------------------------------------------------------------------------
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())
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());
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());
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.",
57 CommandArgumentEntry arg;
58 CommandArgumentData command_arg;
60 // Define the first (and only) variant of this arg.
61 command_arg.arg_type = eArgTypeCommandName;
62 command_arg.arg_repetition = eArgRepeatStar;
64 // There is only one variant this argument could be; put it into the argument
66 arg.push_back(command_arg);
68 // Push the data for the first argument into the m_arguments vector.
69 m_arguments.push_back(arg);
72 CommandObjectHelp::~CommandObjectHelp() = default;
74 static OptionDefinition g_help_options[] = {
76 {LLDB_OPT_SET_ALL, false, "hide-aliases", 'a', OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone, "Hide aliases in the command list."},
77 {LLDB_OPT_SET_ALL, false, "hide-user-commands", 'u', OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone, "Hide user-defined commands from the list."},
78 {LLDB_OPT_SET_ALL, false, "show-hidden-commands", 'h', OptionParser::eNoArgument, nullptr, nullptr, 0, eArgTypeNone, "Include commands prefixed with an underscore."},
82 llvm::ArrayRef<OptionDefinition>
83 CommandObjectHelp::CommandOptions::GetDefinitions() {
84 return llvm::makeArrayRef(g_help_options);
87 bool CommandObjectHelp::DoExecute(Args &command, CommandReturnObject &result) {
88 CommandObject::CommandMap::iterator pos;
89 CommandObject *cmd_obj;
90 const size_t argc = command.GetArgumentCount();
92 // 'help' doesn't take any arguments, other than command names. If argc is 0,
94 // all commands (aliases and user commands if asked for). Otherwise every
95 // argument must be the name of a command or a sub-command.
97 uint32_t cmd_types = CommandInterpreter::eCommandTypesBuiltin;
98 if (m_options.m_show_aliases)
99 cmd_types |= CommandInterpreter::eCommandTypesAliases;
100 if (m_options.m_show_user_defined)
101 cmd_types |= CommandInterpreter::eCommandTypesUserDef;
102 if (m_options.m_show_hidden)
103 cmd_types |= CommandInterpreter::eCommandTypesHidden;
105 result.SetStatus(eReturnStatusSuccessFinishNoResult);
106 m_interpreter.GetHelp(result, cmd_types); // General help
108 // Get command object for the first command argument. Only search built-in
109 // command dictionary.
111 auto command_name = command[0].ref;
112 cmd_obj = m_interpreter.GetCommandObject(command_name, &matches);
114 if (cmd_obj != nullptr) {
116 bool all_okay = true;
117 CommandObject *sub_cmd_obj = cmd_obj;
118 // Loop down through sub_command dictionaries until we find the command
119 // object that corresponds to the help command entered.
120 std::string sub_command;
121 for (auto &entry : command.entries().drop_front()) {
122 sub_command = entry.ref;
124 if (sub_cmd_obj->IsAlias())
126 ((CommandAlias *)sub_cmd_obj)->GetUnderlyingCommand().get();
127 if (!sub_cmd_obj->IsMultiwordObject()) {
131 CommandObject *found_cmd;
133 sub_cmd_obj->GetSubcommandObject(sub_command.c_str(), &matches);
134 if (found_cmd == nullptr || matches.GetSize() > 1) {
138 sub_cmd_obj = found_cmd;
142 if (!all_okay || (sub_cmd_obj == nullptr)) {
143 std::string cmd_string;
144 command.GetCommandString(cmd_string);
145 if (matches.GetSize() >= 2) {
147 s.Printf("ambiguous command %s", cmd_string.c_str());
148 size_t num_matches = matches.GetSize();
149 for (size_t match_idx = 0; match_idx < num_matches; match_idx++) {
150 s.Printf("\n\t%s", matches.GetStringAtIndex(match_idx));
153 result.AppendError(s.GetString());
154 result.SetStatus(eReturnStatusFailed);
156 } else if (!sub_cmd_obj) {
157 StreamString error_msg_stream;
158 GenerateAdditionalHelpAvenuesMessage(
159 &error_msg_stream, cmd_string.c_str(),
160 m_interpreter.GetCommandPrefix(), sub_command.c_str());
161 result.AppendError(error_msg_stream.GetString());
162 result.SetStatus(eReturnStatusFailed);
165 GenerateAdditionalHelpAvenuesMessage(
166 &result.GetOutputStream(), cmd_string.c_str(),
167 m_interpreter.GetCommandPrefix(), sub_command.c_str());
168 result.GetOutputStream().Printf(
169 "\nThe closest match is '%s'. Help on it follows.\n\n",
170 sub_cmd_obj->GetCommandName().str().c_str());
174 sub_cmd_obj->GenerateHelpText(result);
176 if (m_interpreter.AliasExists(command_name)) {
178 m_interpreter.GetAlias(command_name)->GetAliasExpansion(sstr);
179 result.GetOutputStream().Printf("\n'%s' is an abbreviation for %s\n",
180 command[0].c_str(), sstr.GetData());
182 } else if (matches.GetSize() > 0) {
183 Stream &output_strm = result.GetOutputStream();
184 output_strm.Printf("Help requested with ambiguous command name, possible "
186 const size_t match_count = matches.GetSize();
187 for (size_t i = 0; i < match_count; i++) {
188 output_strm.Printf("\t%s\n", matches.GetStringAtIndex(i));
191 // Maybe the user is asking for help about a command argument rather than
193 const CommandArgumentType arg_type =
194 CommandObject::LookupArgumentName(command_name);
195 if (arg_type != eArgTypeLastArg) {
196 Stream &output_strm = result.GetOutputStream();
197 CommandObject::GetArgumentHelp(output_strm, arg_type, m_interpreter);
198 result.SetStatus(eReturnStatusSuccessFinishNoResult);
200 StreamString error_msg_stream;
201 GenerateAdditionalHelpAvenuesMessage(&error_msg_stream, command_name,
202 m_interpreter.GetCommandPrefix(),
204 result.AppendError(error_msg_stream.GetString());
205 result.SetStatus(eReturnStatusFailed);
210 return result.Succeeded();
213 int CommandObjectHelp::HandleCompletion(Args &input, int &cursor_index,
214 int &cursor_char_position,
215 int match_start_point,
216 int max_return_elements,
218 StringList &matches) {
219 // Return the completions of the commands in the help system:
220 if (cursor_index == 0) {
221 return m_interpreter.HandleCompletionMatches(
222 input, cursor_index, cursor_char_position, match_start_point,
223 max_return_elements, word_complete, matches);
225 CommandObject *cmd_obj = m_interpreter.GetCommandObject(input[0].ref);
227 // The command that they are getting help on might be ambiguous, in which
228 // case we should complete that,
229 // otherwise complete with the command the user is getting help on...
234 return cmd_obj->HandleCompletion(
235 input, cursor_index, cursor_char_position, match_start_point,
236 max_return_elements, word_complete, matches);
238 return m_interpreter.HandleCompletionMatches(
239 input, cursor_index, cursor_char_position, match_start_point,
240 max_return_elements, word_complete, matches);