1 //===-- CommandObjectHelp.cpp -----------------------------------*- C++ -*-===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===----------------------------------------------------------------------===// 9 10 #include "lldb/lldb-python.h" 11 12 #include "CommandObjectHelp.h" 13 14 // C Includes 15 // C++ Includes 16 // Other libraries and framework includes 17 // Project includes 18 #include "lldb/Interpreter/CommandObjectMultiword.h" 19 #include "lldb/Interpreter/CommandInterpreter.h" 20 #include "lldb/Interpreter/Options.h" 21 #include "lldb/Interpreter/CommandReturnObject.h" 22 23 using namespace lldb; 24 using namespace lldb_private; 25 26 //------------------------------------------------------------------------- 27 // CommandObjectHelp 28 //------------------------------------------------------------------------- 29 30 CommandObjectHelp::CommandObjectHelp (CommandInterpreter &interpreter) : 31 CommandObjectParsed (interpreter, 32 "help", 33 "Show a list of all debugger commands, or give details about specific commands.", 34 "help [<cmd-name>]"), m_options (interpreter) 35 { 36 CommandArgumentEntry arg; 37 CommandArgumentData command_arg; 38 39 // Define the first (and only) variant of this arg. 40 command_arg.arg_type = eArgTypeCommandName; 41 command_arg.arg_repetition = eArgRepeatStar; 42 43 // There is only one variant this argument could be; put it into the argument entry. 44 arg.push_back (command_arg); 45 46 // Push the data for the first argument into the m_arguments vector. 47 m_arguments.push_back (arg); 48 } 49 50 CommandObjectHelp::~CommandObjectHelp() 51 { 52 } 53 54 OptionDefinition 55 CommandObjectHelp::CommandOptions::g_option_table[] = 56 { 57 { LLDB_OPT_SET_ALL, false, "show-aliases", 'a', no_argument, NULL, 0, eArgTypeNone, "Show aliases in the command list."}, 58 { LLDB_OPT_SET_ALL, false, "hide-user-commands", 'u', no_argument, NULL, 0, eArgTypeNone, "Hide user-defined commands from the list."}, 59 { 0, false, NULL, 0, 0, NULL, 0, eArgTypeNone, NULL } 60 }; 61 62 bool 63 CommandObjectHelp::DoExecute (Args& command, CommandReturnObject &result) 64 { 65 CommandObject::CommandMap::iterator pos; 66 CommandObject *cmd_obj; 67 const size_t argc = command.GetArgumentCount (); 68 69 // 'help' doesn't take any arguments, other than command names. If argc is 0, we show the user 70 // all commands (aliases and user commands if asked for). Otherwise every argument must be the name of a command or a sub-command. 71 if (argc == 0) 72 { 73 uint32_t cmd_types = CommandInterpreter::eCommandTypesBuiltin; 74 if (m_options.m_show_aliases) 75 cmd_types |= CommandInterpreter::eCommandTypesAliases; 76 if (m_options.m_show_user_defined) 77 cmd_types |= CommandInterpreter::eCommandTypesUserDef; 78 79 result.SetStatus (eReturnStatusSuccessFinishNoResult); 80 m_interpreter.GetHelp (result, cmd_types); // General help 81 } 82 else 83 { 84 // Get command object for the first command argument. Only search built-in command dictionary. 85 StringList matches; 86 cmd_obj = m_interpreter.GetCommandObject (command.GetArgumentAtIndex (0), &matches); 87 bool is_alias_command = m_interpreter.AliasExists (command.GetArgumentAtIndex (0)); 88 std::string alias_name = command.GetArgumentAtIndex(0); 89 90 if (cmd_obj != NULL) 91 { 92 StringList matches; 93 bool all_okay = true; 94 CommandObject *sub_cmd_obj = cmd_obj; 95 // Loop down through sub_command dictionaries until we find the command object that corresponds 96 // to the help command entered. 97 for (int i = 1; i < argc && all_okay; ++i) 98 { 99 std::string sub_command = command.GetArgumentAtIndex(i); 100 matches.Clear(); 101 if (! sub_cmd_obj->IsMultiwordObject ()) 102 { 103 all_okay = false; 104 } 105 else 106 { 107 CommandObject *found_cmd; 108 found_cmd = sub_cmd_obj->GetSubcommandObject(sub_command.c_str(), &matches); 109 if (found_cmd == NULL) 110 all_okay = false; 111 else if (matches.GetSize() > 1) 112 all_okay = false; 113 else 114 sub_cmd_obj = found_cmd; 115 } 116 } 117 118 if (!all_okay || (sub_cmd_obj == NULL)) 119 { 120 std::string cmd_string; 121 command.GetCommandString (cmd_string); 122 if (matches.GetSize() < 2) 123 { 124 result.AppendErrorWithFormat("'%s' is not a known command.\n" 125 "Try 'help' to see a current list of commands.\n", 126 cmd_string.c_str()); 127 } 128 else 129 { 130 StreamString s; 131 s.Printf ("ambiguous command %s", cmd_string.c_str()); 132 size_t num_matches = matches.GetSize(); 133 for (size_t match_idx = 0; match_idx < num_matches; match_idx++) 134 { 135 s.Printf ("\n\t%s", matches.GetStringAtIndex(match_idx)); 136 } 137 s.Printf ("\n"); 138 result.AppendError(s.GetData()); 139 } 140 141 result.SetStatus (eReturnStatusFailed); 142 } 143 else 144 { 145 Stream &output_strm = result.GetOutputStream(); 146 if (sub_cmd_obj->GetOptions() != NULL) 147 { 148 if (sub_cmd_obj->WantsRawCommandString()) 149 { 150 std::string help_text (sub_cmd_obj->GetHelp()); 151 help_text.append (" This command takes 'raw' input (no need to quote stuff)."); 152 m_interpreter.OutputFormattedHelpText (output_strm, "", "", help_text.c_str(), 1); 153 } 154 else 155 m_interpreter.OutputFormattedHelpText (output_strm, "", "", sub_cmd_obj->GetHelp(), 1); 156 output_strm.Printf ("\nSyntax: %s\n", sub_cmd_obj->GetSyntax()); 157 sub_cmd_obj->GetOptions()->GenerateOptionUsage (output_strm, sub_cmd_obj); 158 const char *long_help = sub_cmd_obj->GetHelpLong(); 159 if ((long_help != NULL) 160 && (strlen (long_help) > 0)) 161 output_strm.Printf ("\n%s", long_help); 162 if (sub_cmd_obj->WantsRawCommandString() && !sub_cmd_obj->WantsCompletion()) 163 { 164 // Emit the message about using ' -- ' between the end of the command options and the raw input 165 // conditionally, i.e., only if the command object does not want completion. 166 m_interpreter.OutputFormattedHelpText (output_strm, "", "", 167 "\nIMPORTANT NOTE: Because this command takes 'raw' input, if you use any command options" 168 " you must use ' -- ' between the end of the command options and the beginning of the raw input.", 1); 169 } 170 else if (sub_cmd_obj->GetNumArgumentEntries() > 0 171 && sub_cmd_obj->GetOptions() 172 && sub_cmd_obj->GetOptions()->NumCommandOptions() > 0) 173 { 174 // Also emit a warning about using "--" in case you are using a command that takes options and arguments. 175 m_interpreter.OutputFormattedHelpText (output_strm, "", "", 176 "\nThis command takes options and free-form arguments. If your arguments resemble" 177 " option specifiers (i.e., they start with a - or --), you must use ' -- ' between" 178 " the end of the command options and the beginning of the arguments.", 1); 179 } 180 181 // Mark this help command with a success status. 182 result.SetStatus (eReturnStatusSuccessFinishNoResult); 183 } 184 else if (sub_cmd_obj->IsMultiwordObject()) 185 { 186 if (sub_cmd_obj->WantsRawCommandString()) 187 { 188 std::string help_text (sub_cmd_obj->GetHelp()); 189 help_text.append (" This command takes 'raw' input (no need to quote stuff)."); 190 m_interpreter.OutputFormattedHelpText (output_strm, "", "", help_text.c_str(), 1); 191 } 192 else 193 m_interpreter.OutputFormattedHelpText (output_strm, "", "", sub_cmd_obj->GetHelp(), 1); 194 sub_cmd_obj->GenerateHelpText (result); 195 } 196 else 197 { 198 const char *long_help = sub_cmd_obj->GetHelpLong(); 199 if ((long_help != NULL) 200 && (strlen (long_help) > 0)) 201 output_strm.Printf ("%s", long_help); 202 else if (sub_cmd_obj->WantsRawCommandString()) 203 { 204 std::string help_text (sub_cmd_obj->GetHelp()); 205 help_text.append (" This command takes 'raw' input (no need to quote stuff)."); 206 m_interpreter.OutputFormattedHelpText (output_strm, "", "", help_text.c_str(), 1); 207 } 208 else 209 m_interpreter.OutputFormattedHelpText (output_strm, "", "", sub_cmd_obj->GetHelp(), 1); 210 output_strm.Printf ("\nSyntax: %s\n", sub_cmd_obj->GetSyntax()); 211 // Mark this help command with a success status. 212 result.SetStatus (eReturnStatusSuccessFinishNoResult); 213 } 214 } 215 216 if (is_alias_command) 217 { 218 StreamString sstr; 219 m_interpreter.GetAliasHelp (alias_name.c_str(), cmd_obj->GetCommandName(), sstr); 220 result.GetOutputStream().Printf ("\n'%s' is an abbreviation for %s\n", alias_name.c_str(), sstr.GetData()); 221 } 222 } 223 else if (matches.GetSize() > 0) 224 { 225 Stream &output_strm = result.GetOutputStream(); 226 output_strm.Printf("Help requested with ambiguous command name, possible completions:\n"); 227 const size_t match_count = matches.GetSize(); 228 for (size_t i = 0; i < match_count; i++) 229 { 230 output_strm.Printf("\t%s\n", matches.GetStringAtIndex(i)); 231 } 232 } 233 else 234 { 235 // Maybe the user is asking for help about a command argument rather than a command. 236 const CommandArgumentType arg_type = CommandObject::LookupArgumentName (command.GetArgumentAtIndex (0)); 237 if (arg_type != eArgTypeLastArg) 238 { 239 Stream &output_strm = result.GetOutputStream (); 240 CommandObject::GetArgumentHelp (output_strm, arg_type, m_interpreter); 241 result.SetStatus (eReturnStatusSuccessFinishNoResult); 242 } 243 else 244 { 245 result.AppendErrorWithFormat 246 ("'%s' is not a known command.\nTry 'help' to see a current list of commands.\n", 247 command.GetArgumentAtIndex(0)); 248 result.SetStatus (eReturnStatusFailed); 249 } 250 } 251 } 252 253 return result.Succeeded(); 254 } 255 256 int 257 CommandObjectHelp::HandleCompletion 258 ( 259 Args &input, 260 int &cursor_index, 261 int &cursor_char_position, 262 int match_start_point, 263 int max_return_elements, 264 bool &word_complete, 265 StringList &matches 266 ) 267 { 268 // Return the completions of the commands in the help system: 269 if (cursor_index == 0) 270 { 271 return m_interpreter.HandleCompletionMatches (input, 272 cursor_index, 273 cursor_char_position, 274 match_start_point, 275 max_return_elements, 276 word_complete, 277 matches); 278 } 279 else 280 { 281 CommandObject *cmd_obj = m_interpreter.GetCommandObject (input.GetArgumentAtIndex(0)); 282 283 // The command that they are getting help on might be ambiguous, in which case we should complete that, 284 // otherwise complete with the command the user is getting help on... 285 286 if (cmd_obj) 287 { 288 input.Shift(); 289 cursor_index--; 290 return cmd_obj->HandleCompletion (input, 291 cursor_index, 292 cursor_char_position, 293 match_start_point, 294 max_return_elements, 295 word_complete, 296 matches); 297 } 298 else 299 { 300 return m_interpreter.HandleCompletionMatches (input, 301 cursor_index, 302 cursor_char_position, 303 match_start_point, 304 max_return_elements, 305 word_complete, 306 matches); 307 } 308 } 309 } 310