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>]") {
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 
67 
68 #define LLDB_OPTIONS_help
69 #include "CommandOptions.inc"
70 
71 llvm::ArrayRef<OptionDefinition>
73  return llvm::makeArrayRef(g_help_options);
74 }
75 
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) {
91  }
94 
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;
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 {
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);
190  } else {
191  StreamString error_msg_stream;
192  GenerateAdditionalHelpAvenuesMessage(&error_msg_stream, command_name,
194  "");
195  result.AppendError(error_msg_stream.GetString());
196  }
197  }
198  }
199 
200  return result.Succeeded();
201 }
202 
204  // Return the completions of the commands in the help system:
205  if (request.GetCursorIndex() == 0) {
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  }
222 }
lldb_private::CommandInterpreter::eCommandTypesUserDef
@ eCommandTypesUserDef
Definition: CommandInterpreter.h:235
lldb_private::CommandObjectParsed
Definition: CommandObject.h:393
lldb_private::StringList::Clear
void Clear()
Definition: StringList.cpp:105
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:76
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
lldb_private::CommandReturnObject::Succeeded
bool Succeeded() const
Definition: CommandReturnObject.cpp:131
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:74
lldb::eReturnStatusSuccessFinishNoResult
@ eReturnStatusSuccessFinishNoResult
Definition: lldb-enumerations.h:260
lldb_private::CommandObject::m_arguments
std::vector< CommandArgumentEntry > m_arguments
Definition: CommandObject.h:380
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:86
lldb::CommandArgumentType
CommandArgumentType
Definition: lldb-enumerations.h:515
lldb::eArgTypeLastArg
@ eArgTypeLastArg
Definition: lldb-enumerations.h:611
lldb_private::CommandReturnObject::SetStatus
void SetStatus(lldb::ReturnStatus status)
Definition: CommandReturnObject.cpp:127
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:72
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:46
lldb_private::StringList
Definition: StringList.h:26
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:372
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:542
lldb_private::CommandReturnObject
Definition: CommandReturnObject.h:26
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::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:203
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:849