1 //===-- Args.h --------------------------------------------------*- 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 #ifndef liblldb_Command_h_ 11 #define liblldb_Command_h_ 12 13 // C Includes 14 // C++ Includes 15 #include <list> 16 #include <string> 17 #include <vector> 18 #include <utility> 19 20 // Other libraries and framework includes 21 // Project includes 22 #include "lldb/lldb-private-types.h" 23 #include "lldb/lldb-types.h" 24 #include "lldb/Core/Error.h" 25 #include "lldb/Host/OptionParser.h" 26 27 namespace lldb_private { 28 29 typedef std::pair<int, std::string> OptionArgValue; 30 typedef std::pair<std::string, OptionArgValue> OptionArgPair; 31 typedef std::vector<OptionArgPair> OptionArgVector; 32 typedef std::shared_ptr<OptionArgVector> OptionArgVectorSP; 33 34 struct OptionArgElement 35 { 36 enum { 37 eUnrecognizedArg = -1, 38 eBareDash = -2, 39 eBareDoubleDash = -3 40 }; 41 OptionArgElementOptionArgElement42 OptionArgElement (int defs_index, int pos, int arg_pos) : 43 opt_defs_index(defs_index), 44 opt_pos (pos), 45 opt_arg_pos (arg_pos) 46 { 47 } 48 49 int opt_defs_index; 50 int opt_pos; 51 int opt_arg_pos; 52 }; 53 54 typedef std::vector<OptionArgElement> OptionElementVector; 55 56 //---------------------------------------------------------------------- 57 /// @class Args Args.h "lldb/Interpreter/Args.h" 58 /// @brief A command line argument class. 59 /// 60 /// The Args class is designed to be fed a command line. The 61 /// command line is copied into an internal buffer and then split up 62 /// into arguments. Arguments are space delimited if there are no quotes 63 /// (single, double, or backtick quotes) surrounding the argument. Spaces 64 /// can be escaped using a \ character to avoid having to surround an 65 /// argument that contains a space with quotes. 66 //---------------------------------------------------------------------- 67 class Args 68 { 69 public: 70 71 //------------------------------------------------------------------ 72 /// Construct with an option command string. 73 /// 74 /// @param[in] command 75 /// A NULL terminated command that will be copied and split up 76 /// into arguments. 77 /// 78 /// @see Args::SetCommandString(const char *) 79 //------------------------------------------------------------------ 80 Args (const char *command = NULL); 81 82 Args (const char *command, size_t len); 83 84 Args (const Args &rhs); 85 86 const Args & 87 operator= (const Args &rhs); 88 89 //------------------------------------------------------------------ 90 /// Destructor. 91 //------------------------------------------------------------------ 92 ~Args(); 93 94 //------------------------------------------------------------------ 95 /// Dump all arguments to the stream \a s. 96 /// 97 /// @param[in] s 98 /// The stream to which to dump all arguments in the argument 99 /// vector. 100 //------------------------------------------------------------------ 101 void 102 Dump (Stream *s); 103 104 //------------------------------------------------------------------ 105 /// Sets the command string contained by this object. 106 /// 107 /// The command string will be copied and split up into arguments 108 /// that can be accessed via the accessor functions. 109 /// 110 /// @param[in] command 111 /// A NULL terminated command that will be copied and split up 112 /// into arguments. 113 /// 114 /// @see Args::GetArgumentCount() const 115 /// @see Args::GetArgumentAtIndex (size_t) const 116 /// @see Args::GetArgumentVector () 117 /// @see Args::Shift () 118 /// @see Args::Unshift (const char *) 119 //------------------------------------------------------------------ 120 void 121 SetCommandString (const char *command); 122 123 void 124 SetCommandString (const char *command, size_t len); 125 126 bool 127 GetCommandString (std::string &command) const; 128 129 bool 130 GetQuotedCommandString (std::string &command) const; 131 132 //------------------------------------------------------------------ 133 /// Gets the number of arguments left in this command object. 134 /// 135 /// @return 136 /// The number or arguments in this object. 137 //------------------------------------------------------------------ 138 size_t 139 GetArgumentCount () const; 140 141 //------------------------------------------------------------------ 142 /// Gets the NULL terminated C string argument pointer for the 143 /// argument at index \a idx. 144 /// 145 /// @return 146 /// The NULL terminated C string argument pointer if \a idx is a 147 /// valid argument index, NULL otherwise. 148 //------------------------------------------------------------------ 149 const char * 150 GetArgumentAtIndex (size_t idx) const; 151 152 char 153 GetArgumentQuoteCharAtIndex (size_t idx) const; 154 155 //------------------------------------------------------------------ 156 /// Gets the argument vector. 157 /// 158 /// The value returned by this function can be used by any function 159 /// that takes and vector. The return value is just like \a argv 160 /// in the standard C entry point function: 161 /// \code 162 /// int main (int argc, const char **argv); 163 /// \endcode 164 /// 165 /// @return 166 /// An array of NULL terminated C string argument pointers that 167 /// also has a terminating NULL C string pointer 168 //------------------------------------------------------------------ 169 char ** 170 GetArgumentVector (); 171 172 //------------------------------------------------------------------ 173 /// Gets the argument vector. 174 /// 175 /// The value returned by this function can be used by any function 176 /// that takes and vector. The return value is just like \a argv 177 /// in the standard C entry point function: 178 /// \code 179 /// int main (int argc, const char **argv); 180 /// \endcode 181 /// 182 /// @return 183 /// An array of NULL terminate C string argument pointers that 184 /// also has a terminating NULL C string pointer 185 //------------------------------------------------------------------ 186 const char ** 187 GetConstArgumentVector () const; 188 189 190 //------------------------------------------------------------------ 191 /// Appends a new argument to the end of the list argument list. 192 /// 193 /// @param[in] arg_cstr 194 /// The new argument as a NULL terminated C string. 195 /// 196 /// @param[in] quote_char 197 /// If the argument was originally quoted, put in the quote char here. 198 /// 199 /// @return 200 /// The NULL terminated C string of the copy of \a arg_cstr. 201 //------------------------------------------------------------------ 202 const char * 203 AppendArgument (const char *arg_cstr, char quote_char = '\0'); 204 205 void 206 AppendArguments (const Args &rhs); 207 208 void 209 AppendArguments (const char **argv); 210 211 //------------------------------------------------------------------ 212 /// Insert the argument value at index \a idx to \a arg_cstr. 213 /// 214 /// @param[in] idx 215 /// The index of where to insert the argument. 216 /// 217 /// @param[in] arg_cstr 218 /// The new argument as a NULL terminated C string. 219 /// 220 /// @param[in] quote_char 221 /// If the argument was originally quoted, put in the quote char here. 222 /// 223 /// @return 224 /// The NULL terminated C string of the copy of \a arg_cstr. 225 //------------------------------------------------------------------ 226 const char * 227 InsertArgumentAtIndex (size_t idx, const char *arg_cstr, char quote_char = '\0'); 228 229 //------------------------------------------------------------------ 230 /// Replaces the argument value at index \a idx to \a arg_cstr 231 /// if \a idx is a valid argument index. 232 /// 233 /// @param[in] idx 234 /// The index of the argument that will have its value replaced. 235 /// 236 /// @param[in] arg_cstr 237 /// The new argument as a NULL terminated C string. 238 /// 239 /// @param[in] quote_char 240 /// If the argument was originally quoted, put in the quote char here. 241 /// 242 /// @return 243 /// The NULL terminated C string of the copy of \a arg_cstr if 244 /// \a idx was a valid index, NULL otherwise. 245 //------------------------------------------------------------------ 246 const char * 247 ReplaceArgumentAtIndex (size_t idx, const char *arg_cstr, char quote_char = '\0'); 248 249 //------------------------------------------------------------------ 250 /// Deletes the argument value at index 251 /// if \a idx is a valid argument index. 252 /// 253 /// @param[in] idx 254 /// The index of the argument that will have its value replaced. 255 /// 256 //------------------------------------------------------------------ 257 void 258 DeleteArgumentAtIndex (size_t idx); 259 260 //------------------------------------------------------------------ 261 /// Sets the argument vector value, optionally copying all 262 /// arguments into an internal buffer. 263 /// 264 /// Sets the arguments to match those found in \a argv. All argument 265 /// strings will be copied into an internal buffers. 266 // 267 // FIXME: Handle the quote character somehow. 268 //------------------------------------------------------------------ 269 void 270 SetArguments (size_t argc, const char **argv); 271 272 void 273 SetArguments (const char **argv); 274 275 //------------------------------------------------------------------ 276 /// Shifts the first argument C string value of the array off the 277 /// argument array. 278 /// 279 /// The string value will be freed, so a copy of the string should 280 /// be made by calling Args::GetArgumentAtIndex (size_t) const 281 /// first and copying the returned value before calling 282 /// Args::Shift(). 283 /// 284 /// @see Args::GetArgumentAtIndex (size_t) const 285 //------------------------------------------------------------------ 286 void 287 Shift (); 288 289 //------------------------------------------------------------------ 290 /// Inserts a class owned copy of \a arg_cstr at the beginning of 291 /// the argument vector. 292 /// 293 /// A copy \a arg_cstr will be made. 294 /// 295 /// @param[in] arg_cstr 296 /// The argument to push on the front the the argument stack. 297 /// 298 /// @param[in] quote_char 299 /// If the argument was originally quoted, put in the quote char here. 300 /// 301 /// @return 302 /// A pointer to the copy of \a arg_cstr that was made. 303 //------------------------------------------------------------------ 304 const char * 305 Unshift (const char *arg_cstr, char quote_char = '\0'); 306 307 //------------------------------------------------------------------ 308 /// Parse the arguments in the contained arguments. 309 /// 310 /// The arguments that are consumed by the argument parsing process 311 /// will be removed from the argument vector. The arguements that 312 /// get processed start at the second argument. The first argument 313 /// is assumed to be the command and will not be touched. 314 /// 315 /// @see class Options 316 //------------------------------------------------------------------ 317 Error 318 ParseOptions (Options &options); 319 320 size_t 321 FindArgumentIndexForOption (Option *long_options, int long_options_index); 322 323 bool 324 IsPositionalArgument (const char *arg); 325 326 // The following works almost identically to ParseOptions, except that no option is required to have arguments, 327 // and it builds up the option_arg_vector as it parses the options. 328 329 void 330 ParseAliasOptions (Options &options, CommandReturnObject &result, OptionArgVector *option_arg_vector, 331 std::string &raw_input_line); 332 333 void 334 ParseArgsForCompletion (Options &options, OptionElementVector &option_element_vector, uint32_t cursor_index); 335 336 //------------------------------------------------------------------ 337 // Clear the arguments. 338 // 339 // For re-setting or blanking out the list of arguments. 340 //------------------------------------------------------------------ 341 void 342 Clear (); 343 344 static const char * 345 StripSpaces (std::string &s, 346 bool leading = true, 347 bool trailing = true, 348 bool return_null_if_empty = true); 349 350 static int32_t 351 StringToSInt32 (const char *s, int32_t fail_value = 0, int base = 0, bool *success_ptr = NULL); 352 353 static uint32_t 354 StringToUInt32 (const char *s, uint32_t fail_value = 0, int base = 0, bool *success_ptr = NULL); 355 356 static int64_t 357 StringToSInt64 (const char *s, int64_t fail_value = 0, int base = 0, bool *success_ptr = NULL); 358 359 static uint64_t 360 StringToUInt64 (const char *s, uint64_t fail_value = 0, int base = 0, bool *success_ptr = NULL); 361 362 static bool UInt64ValueIsValidForByteSize(uint64_t uval64,size_t total_byte_size)363 UInt64ValueIsValidForByteSize (uint64_t uval64, size_t total_byte_size) 364 { 365 if (total_byte_size > 8) 366 return false; 367 368 if (total_byte_size == 8) 369 return true; 370 371 const uint64_t max = ((uint64_t)1 << (uint64_t)(total_byte_size * 8)) - 1; 372 return uval64 <= max; 373 } 374 375 static bool SInt64ValueIsValidForByteSize(int64_t sval64,size_t total_byte_size)376 SInt64ValueIsValidForByteSize (int64_t sval64, size_t total_byte_size) 377 { 378 if (total_byte_size > 8) 379 return false; 380 381 if (total_byte_size == 8) 382 return true; 383 384 const int64_t max = ((int64_t)1 << (uint64_t)(total_byte_size * 8 - 1)) - 1; 385 const int64_t min = ~(max); 386 return min <= sval64 && sval64 <= max; 387 } 388 389 static lldb::addr_t 390 StringToAddress (const ExecutionContext *exe_ctx, 391 const char *s, 392 lldb::addr_t fail_value, 393 Error *error); 394 395 static bool 396 StringToBoolean (const char *s, bool fail_value, bool *success_ptr); 397 398 static int64_t 399 StringToOptionEnum (const char *s, OptionEnumValueElement *enum_values, int32_t fail_value, Error &error); 400 401 static lldb::ScriptLanguage 402 StringToScriptLanguage (const char *s, lldb::ScriptLanguage fail_value, bool *success_ptr); 403 404 static Error 405 StringToFormat (const char *s, 406 lldb::Format &format, 407 size_t *byte_size_ptr); // If non-NULL, then a byte size can precede the format character 408 409 static lldb::Encoding 410 StringToEncoding (const char *s, 411 lldb::Encoding fail_value = lldb::eEncodingInvalid); 412 413 static uint32_t 414 StringToGenericRegister (const char *s); 415 416 static const char * 417 StringToVersion (const char *s, uint32_t &major, uint32_t &minor, uint32_t &update); 418 419 static const char * 420 GetShellSafeArgument (const char *unsafe_arg, std::string &safe_arg); 421 422 // EncodeEscapeSequences will change the textual representation of common 423 // escape sequences like "\n" (two characters) into a single '\n'. It does 424 // this for all of the supported escaped sequences and for the \0ooo (octal) 425 // and \xXX (hex). The resulting "dst" string will contain the character 426 // versions of all supported escape sequences. The common supported escape 427 // sequences are: "\a", "\b", "\f", "\n", "\r", "\t", "\v", "\'", "\"", "\\". 428 429 static void 430 EncodeEscapeSequences (const char *src, std::string &dst); 431 432 // ExpandEscapeSequences will change a string of possibly non-printable 433 // characters and expand them into text. So '\n' will turn into two chracters 434 // like "\n" which is suitable for human reading. When a character is not 435 // printable and isn't one of the common in escape sequences listed in the 436 // help for EncodeEscapeSequences, then it will be encoded as octal. Printable 437 // characters are left alone. 438 static void 439 ExpandEscapedCharacters (const char *src, std::string &dst); 440 441 // This one isn't really relevant to Arguments per se, but we're using the Args as a 442 // general strings container, so... 443 void 444 LongestCommonPrefix (std::string &common_prefix); 445 446 protected: 447 //------------------------------------------------------------------ 448 // Classes that inherit from Args can see and modify these 449 //------------------------------------------------------------------ 450 typedef std::list<std::string> arg_sstr_collection; 451 typedef std::vector<const char *> arg_cstr_collection; 452 typedef std::vector<char> arg_quote_char_collection; 453 arg_sstr_collection m_args; 454 arg_cstr_collection m_argv; ///< The current argument vector. 455 arg_quote_char_collection m_args_quote_char; 456 457 void 458 UpdateArgsAfterOptionParsing (); 459 460 void 461 UpdateArgvFromArgs (); 462 }; 463 464 } // namespace lldb_private 465 466 #endif // liblldb_Command_h_ 467