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