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  // Define the first (and only) variant of this arg.
55  command_arg.arg_type = eArgTypeCommandName;
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) {
92 
94  m_interpreter.GetHelp(result, cmd_types); // General help
95  } else {
96  // Get command object for the first command argument. Only search built-in
97  // command dictionary.
98  StringList matches;
99  auto command_name = command[0].ref();
100  cmd_obj = m_interpreter.GetCommandObject(command_name, &matches);
101 
102  if (cmd_obj != nullptr) {
103  StringList matches;
104  bool all_okay = true;
105  CommandObject *sub_cmd_obj = cmd_obj;
106  // Loop down through sub_command dictionaries until we find the command
107  // object that corresponds to the help command entered.
108  std::string sub_command;
109  for (auto &entry : command.entries().drop_front()) {
110  sub_command = std::string(entry.ref());
111  matches.Clear();
112  if (sub_cmd_obj->IsAlias())
113  sub_cmd_obj =
114  ((CommandAlias *)sub_cmd_obj)->GetUnderlyingCommand().get();
115  if (!sub_cmd_obj->IsMultiwordObject()) {
116  all_okay = false;
117  break;
118  } else {
119  CommandObject *found_cmd;
120  found_cmd =
121  sub_cmd_obj->GetSubcommandObject(sub_command.c_str(), &matches);
122  if (found_cmd == nullptr || matches.GetSize() > 1) {
123  all_okay = false;
124  break;
125  } else
126  sub_cmd_obj = found_cmd;
127  }
128  }
129 
130  if (!all_okay || (sub_cmd_obj == nullptr)) {
131  std::string cmd_string;
132  command.GetCommandString(cmd_string);
133  if (matches.GetSize() >= 2) {
134  StreamString s;
135  s.Printf("ambiguous command %s", cmd_string.c_str());
136  size_t num_matches = matches.GetSize();
137  for (size_t match_idx = 0; match_idx < num_matches; match_idx++) {
138  s.Printf("\n\t%s", matches.GetStringAtIndex(match_idx));
139  }
140  s.Printf("\n");
141  result.AppendError(s.GetString());
142  return false;
143  } else if (!sub_cmd_obj) {
144  StreamString error_msg_stream;
146  &error_msg_stream, cmd_string.c_str(),
147  m_interpreter.GetCommandPrefix(), sub_command.c_str());
148  result.AppendError(error_msg_stream.GetString());
149  return false;
150  } else {
152  &result.GetOutputStream(), cmd_string.c_str(),
153  m_interpreter.GetCommandPrefix(), sub_command.c_str());
154  result.GetOutputStream().Printf(
155  "\nThe closest match is '%s'. Help on it follows.\n\n",
156  sub_cmd_obj->GetCommandName().str().c_str());
157  }
158  }
159 
160  sub_cmd_obj->GenerateHelpText(result);
161  std::string alias_full_name;
162  // Don't use AliasExists here, that only checks exact name matches. If
163  // the user typed a shorter unique alias name, we should still tell them
164  // it was an alias.
165  if (m_interpreter.GetAliasFullName(command_name, alias_full_name)) {
166  StreamString sstr;
167  m_interpreter.GetAlias(alias_full_name)->GetAliasExpansion(sstr);
168  result.GetOutputStream().Printf("\n'%s' is an abbreviation for %s\n",
169  command[0].c_str(), sstr.GetData());
170  }
171  } else if (matches.GetSize() > 0) {
172  Stream &output_strm = result.GetOutputStream();
173  output_strm.Printf("Help requested with ambiguous command name, possible "
174  "completions:\n");
175  const size_t match_count = matches.GetSize();
176  for (size_t i = 0; i < match_count; i++) {
177  output_strm.Printf("\t%s\n", matches.GetStringAtIndex(i));
178  }
179  } else {
180  // Maybe the user is asking for help about a command argument rather than
181  // a command.
182  const CommandArgumentType arg_type =
183  CommandObject::LookupArgumentName(command_name);
184  if (arg_type != eArgTypeLastArg) {
185  Stream &output_strm = result.GetOutputStream();
186  CommandObject::GetArgumentHelp(output_strm, arg_type, m_interpreter);
188  } else {
189  StreamString error_msg_stream;
190  GenerateAdditionalHelpAvenuesMessage(&error_msg_stream, command_name,
192  "");
193  result.AppendError(error_msg_stream.GetString());
194  }
195  }
196  }
197 
198  return result.Succeeded();
199 }
200 
202  // Return the completions of the commands in the help system:
203  if (request.GetCursorIndex() == 0) {
205  return;
206  }
207  CommandObject *cmd_obj =
208  m_interpreter.GetCommandObject(request.GetParsedLine()[0].ref());
209 
210  // The command that they are getting help on might be ambiguous, in which
211  // case we should complete that, otherwise complete with the command the
212  // user is getting help on...
213 
214  if (cmd_obj) {
215  request.ShiftArguments();
216  cmd_obj->HandleCompletion(request);
217  return;
218  }
220 }
lldb_private::CommandInterpreter::eCommandTypesUserDef
@ eCommandTypesUserDef
Definition: CommandInterpreter.h:235
lldb_private::CommandObjectParsed
Definition: CommandObject.h:378
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::eArgTypeCommandName
@ eArgTypeCommandName
Definition: lldb-enumerations.h:527
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:236
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:162
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:366
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: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: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:358
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:39
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:150
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::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:237
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:201
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