LLDB  mainline
CommandObjectHelp.cpp
Go to the documentation of this file.
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"
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  m_options() {
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 
68 
69 #define LLDB_OPTIONS_help
70 #include "CommandOptions.inc"
71 
72 llvm::ArrayRef<OptionDefinition>
74  return llvm::makeArrayRef(g_help_options);
75 }
76 
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) {
92  }
95 
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;
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 {
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);
191  } else {
192  StreamString error_msg_stream;
193  GenerateAdditionalHelpAvenuesMessage(&error_msg_stream, command_name,
195  "");
196  result.AppendError(error_msg_stream.GetString());
197  }
198  }
199  }
200 
201  return result.Succeeded();
202 }
203 
205  // Return the completions of the commands in the help system:
206  if (request.GetCursorIndex() == 0) {
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  }
223 }
lldb_private::CommandInterpreter::eCommandTypesUserDef
@ eCommandTypesUserDef
Definition: CommandInterpreter.h:235
lldb_private::CommandObjectParsed
Definition: CommandObject.h:394
lldb_private::StringList::Clear
void Clear()
Definition: StringList.cpp:99
lldb_private::CommandInterpreter::GetCommandPrefix
const char * GetCommandPrefix()
lldb_private::CompletionRequest::GetParsedLine
const Args & GetParsedLine() const
Definition: CompletionRequest.h:134
lldb_private::CommandInterpreter::GetHelp
void GetHelp(CommandReturnObject &result, uint32_t types=eCommandTypesAllThem)
lldb_private::CommandInterpreter::GetAliasFullName
bool GetAliasFullName(llvm::StringRef cmd, std::string &full_name) const
lldb_private::CommandObject::CommandArgumentData
Definition: CommandObject.h:89
lldb::eArgTypeCommand
@ eArgTypeCommand
Definition: lldb-enumerations.h:601
lldb_private::CommandInterpreter::GetCommandObject
CommandObject * GetCommandObject(llvm::StringRef cmd, StringList *matches=nullptr, StringList *descriptions=nullptr) const
lldb_private::CommandObjectHelp::DoExecute
bool DoExecute(Args &command, CommandReturnObject &result) override
Definition: CommandObjectHelp.cpp:77
lldb_private::CommandInterpreter::eCommandTypesAliases
@ eCommandTypesAliases
Definition: CommandInterpreter.h:237
lldb_private::CommandObject::CommandArgumentData::arg_repetition
ArgumentRepetitionType arg_repetition
Definition: CommandObject.h:92
lldb_private::CommandObject::GetSubcommandObject
virtual CommandObject * GetSubcommandObject(llvm::StringRef sub_cmd, StringList *matches=nullptr)
Definition: CommandObject.h:170
lldb_private::Stream
Definition: Stream.h:28
lldb_private::Args
Definition: Args.h:33
CommandReturnObject.h
lldb_private::StreamString::GetString
llvm::StringRef GetString() const
Definition: StreamString.cpp:51
lldb_private::StringList::GetSize
size_t GetSize() const
Definition: StringList.cpp:68
lldb::eReturnStatusSuccessFinishNoResult
@ eReturnStatusSuccessFinishNoResult
Definition: lldb-enumerations.h:260
lldb_private::CommandObject::m_arguments
std::vector< CommandArgumentEntry > m_arguments
Definition: CommandObject.h:381
lldb_private::CommandObjectHelp::~CommandObjectHelp
~CommandObjectHelp() override
lldb_private::CommandObject::GetArgumentHelp
static void GetArgumentHelp(Stream &str, lldb::CommandArgumentType arg_type, CommandInterpreter &interpreter)
Definition: CommandObject.cpp:377
lldb_private::StringList::GetStringAtIndex
const char * GetStringAtIndex(size_t idx) const
Definition: StringList.cpp:80
lldb::CommandArgumentType
CommandArgumentType
Definition: lldb-enumerations.h:515
lldb::eArgTypeLastArg
@ eArgTypeLastArg
Definition: lldb-enumerations.h:605
lldb_private::CommandReturnObject::SetStatus
void SetStatus(lldb::ReturnStatus status)
Definition: CommandReturnObject.cpp:121
lldb_private::StreamString::GetData
const char * GetData() const
Definition: StreamString.h:43
lldb_private::CommandObjectHelp::CommandOptions::GetDefinitions
llvm::ArrayRef< OptionDefinition > GetDefinitions() override
Definition: CommandObjectHelp.cpp:73
lldb_private::CommandObjectHelp::CommandOptions::m_show_user_defined
bool m_show_user_defined
Definition: CommandObjectHelp.h:72
lldb_private::CommandReturnObject::GetOutputStream
Stream & GetOutputStream()
Definition: CommandReturnObject.h:45
lldb_private::StringList
Definition: StringList.h:25
lldb_private::StreamString
Definition: StreamString.h:23
lldb_private::Args::entries
llvm::ArrayRef< ArgEntry > entries() const
Definition: Args.h:130
lldb_private::CommandObject::GetCommandName
llvm::StringRef GetCommandName() const
Definition: CommandObject.cpp:80
lldb_private::CommandInterpreter
Definition: CommandInterpreter.h:214
lldb_private::eArgRepeatStar
@ eArgRepeatStar
Definition: lldb-private-enumerations.h:98
lldb_private::CommandObject::m_interpreter
CommandInterpreter & m_interpreter
Definition: CommandObject.h:373
lldb_private::CommandObject::CommandArgumentData::arg_type
lldb::CommandArgumentType arg_type
Definition: CommandObject.h:91
string
string(SUBSTRING ${p} 10 -1 pStripped) if($
Definition: Plugins/CMakeLists.txt:40
lldb_private::CommandInterpreter::HandleCompletionMatches
void HandleCompletionMatches(CompletionRequest &request)
lldb_private::CommandObject
Definition: CommandObject.h:67
lldb_private::CommandAlias
Definition: CommandAlias.h:20
lldb_private::CommandObject::IsAlias
virtual bool IsAlias()
Definition: CommandObject.h:154
lldb_private::CommandObject::LookupArgumentName
static lldb::CommandArgumentType LookupArgumentName(llvm::StringRef arg_name)
Definition: CommandObject.cpp:539
lldb_private::CommandReturnObject
Definition: CommandReturnObject.h:25
uint32_t
lldb_private::CommandObject::IsMultiwordObject
virtual bool IsMultiwordObject()
Definition: CommandObject.h:146
lldb_private::CommandInterpreter::eCommandTypesUserMW
@ eCommandTypesUserMW
Definition: CommandInterpreter.h:236
lldb_private::CommandObjectHelp::CommandOptions::m_show_hidden
bool m_show_hidden
Definition: CommandObjectHelp.h:73
lldb_private::CommandObject::HandleCompletion
virtual void HandleCompletion(CompletionRequest &request)
This default version handles calling option argument completions and then calls HandleArgumentComplet...
Definition: CommandObject.cpp:273
lldb_private::CompletionRequest::ShiftArguments
void ShiftArguments()
Drops the first argument from the argument list.
Definition: CompletionRequest.h:143
lldb_private::CommandAlias::GetAliasExpansion
void GetAliasExpansion(StreamString &help_string) const
Definition: CommandAlias.cpp:141
lldb_private::CommandInterpreter::eCommandTypesHidden
@ eCommandTypesHidden
Definition: CommandInterpreter.h:238
lldb_private::CommandReturnObject::Succeeded
bool Succeeded()
Definition: CommandReturnObject.cpp:125
lldb_private::Args::GetCommandString
bool GetCommandString(std::string &command) const
Definition: Args.cpp:212
lldb_private::Stream::Printf
size_t Printf(const char *format,...) __attribute__((format(printf
Output printf formatted output to the stream.
Definition: Stream.cpp:107
lldb_private::CompletionRequest::GetCursorIndex
size_t GetCursorIndex() const
Definition: CompletionRequest.h:156
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::CommandInterpreter::GetAlias
const CommandAlias * GetAlias(llvm::StringRef alias_name) const
lldb_private::CommandObjectHelp::GenerateAdditionalHelpAvenuesMessage
static void GenerateAdditionalHelpAvenuesMessage(Stream *s, llvm::StringRef command, llvm::StringRef prefix, llvm::StringRef subcommand, bool include_upropos=true, bool include_type_lookup=true)
Definition: CommandObjectHelp.cpp:18
CommandInterpreter.h
lldb_private::CommandObjectHelp::HandleCompletion
void HandleCompletion(CompletionRequest &request) override
This default version handles calling option argument completions and then calls HandleArgumentComplet...
Definition: CommandObjectHelp.cpp:204
lldb_private::CommandObjectHelp::m_options
CommandOptions m_options
Definition: CommandObjectHelp.h:82
lldb_private::CommandObject::CommandArgumentEntry
std::vector< CommandArgumentData > CommandArgumentEntry
Definition: CommandObject.h:105
lldb_private::CommandInterpreter::eCommandTypesBuiltin
@ eCommandTypesBuiltin
Definition: CommandInterpreter.h:234
lldb_private::CommandReturnObject::AppendError
void void AppendError(llvm::StringRef in_string)
Definition: CommandReturnObject.cpp:100
lldb_private::Args::GetArgumentCount
size_t GetArgumentCount() const
Gets the number of arguments left in this command object.
Definition: Args.h:118
lldb
Definition: SBAddress.h:15
lldb_private::CommandObjectHelp::CommandOptions::m_show_aliases
bool m_show_aliases
Definition: CommandObjectHelp.h:71
lldb_private::CompletionRequest
Definition: CompletionRequest.h:100
CommandObjectHelp.h
lldb_private::CommandObject::GenerateHelpText
void GenerateHelpText(CommandReturnObject &result)
Definition: CommandObject.cpp:846