contrib/llvm/tools/lldb/include/lldb/Utility/Args.h

   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 LLDB_UTILITY_ARGS_H
  11 #define LLDB_UTILITY_ARGS_H
  12
  13 #include "lldb/Utility/Environment.h"
  14 #include "lldb/lldb-private-types.h"
  15 #include "lldb/lldb-types.h"
  16 #include "llvm/ADT/ArrayRef.h"
  17 #include "llvm/ADT/StringRef.h"
  18 #include <string>
  19 #include <utility>
  20 #include <vector>
  21
  22 namespace lldb_private {
  23
  24 //----------------------------------------------------------------------
  25 /// @class Args Args.h "lldb/Utility/Args.h"
  26 /// A command line argument class.
  27 ///
  28 /// The Args class is designed to be fed a command line. The command line is
  29 /// copied into an internal buffer and then split up into arguments. Arguments
  30 /// are space delimited if there are no quotes (single, double, or backtick
  31 /// quotes) surrounding the argument. Spaces can be escaped using a \
  32 /// character to avoid having to surround an argument that contains a space
  33 /// with quotes.
  34 //----------------------------------------------------------------------
  35 class Args {
  36 public:
  37   struct ArgEntry {
  38   private:
  39     friend class Args;
  40     std::unique_ptr<char[]> ptr;
  41
  42     char *data() { return ptr.get(); }
  43
  44   public:
  45     ArgEntry() = default;
  46     ArgEntry(llvm::StringRef str, char quote);
  47
  48     llvm::StringRef ref;
  49     char quote;
  50     const char *c_str() const { return ptr.get(); }
  51
  52     //------------------------------------------------------------------
  53     /// Returns true if this argument was quoted in any way.
  54     //------------------------------------------------------------------
  55     bool IsQuoted() const { return quote != '\0'; }
  56   };
  57
  58   //------------------------------------------------------------------
  59   /// Construct with an option command string.
  60   ///
  61   /// @param[in] command
  62   ///     A NULL terminated command that will be copied and split up
  63   ///     into arguments.
  64   ///
  65   /// @see Args::SetCommandString(llvm::StringRef)
  66   //------------------------------------------------------------------
  67   Args(llvm::StringRef command = llvm::StringRef());
  68
  69   Args(const Args &rhs);
  70   explicit Args(const StringList &list);
  71
  72   Args &operator=(const Args &rhs);
  73
  74   //------------------------------------------------------------------
  75   /// Destructor.
  76   //------------------------------------------------------------------
  77   ~Args();
  78
  79   explicit Args(const Environment &env) : Args() {
  80     SetArguments(const_cast<const char **>(env.getEnvp().get()));
  81   }
  82
  83   explicit operator Environment() const { return GetConstArgumentVector(); }
  84
  85   //------------------------------------------------------------------
  86   /// Dump all entries to the stream \a s using label \a label_name.
  87   ///
  88   /// If label_name is nullptr, the dump operation is skipped.
  89   ///
  90   /// @param[in] s
  91   ///     The stream to which to dump all arguments in the argument
  92   ///     vector.
  93   /// @param[in] label_name
  94   ///     The label_name to use as the label printed for each
  95   ///     entry of the args like so:
  96   ///       {label_name}[{index}]={value}
  97   //------------------------------------------------------------------
  98   void Dump(Stream &s, const char *label_name = "argv") const;
  99
 100   //------------------------------------------------------------------
 101   /// Sets the command string contained by this object.
 102   ///
 103   /// The command string will be copied and split up into arguments that can
 104   /// be accessed via the accessor functions.
 105   ///
 106   /// @param[in] command
 107   ///     A command StringRef that will be copied and split up
 108   ///     into arguments.
 109   ///
 110   /// @see Args::GetArgumentCount() const
 111   /// @see Args::GetArgumentAtIndex (size_t) const @see
 112   /// Args::GetArgumentVector () @see Args::Shift () @see Args::Unshift (const
 113   /// char *)
 114   //------------------------------------------------------------------
 115   void SetCommandString(llvm::StringRef command);
 116
 117   bool GetCommandString(std::string &command) const;
 118
 119   bool GetQuotedCommandString(std::string &command) const;
 120
 121   //------------------------------------------------------------------
 122   /// Gets the number of arguments left in this command object.
 123   ///
 124   /// @return
 125   ///     The number or arguments in this object.
 126   //------------------------------------------------------------------
 127   size_t GetArgumentCount() const;
 128   bool empty() const { return GetArgumentCount() == 0; }
 129
 130   //------------------------------------------------------------------
 131   /// Gets the NULL terminated C string argument pointer for the argument at
 132   /// index \a idx.
 133   ///
 134   /// @return
 135   ///     The NULL terminated C string argument pointer if \a idx is a
 136   ///     valid argument index, NULL otherwise.
 137   //------------------------------------------------------------------
 138   const char *GetArgumentAtIndex(size_t idx) const;
 139
 140   llvm::ArrayRef<ArgEntry> entries() const { return m_entries; }
 141   char GetArgumentQuoteCharAtIndex(size_t idx) const;
 142
 143   using const_iterator = std::vector<ArgEntry>::const_iterator;
 144
 145   const_iterator begin() const { return m_entries.begin(); }
 146   const_iterator end() const { return m_entries.end(); }
 147
 148   size_t size() const { return GetArgumentCount(); }
 149   const ArgEntry &operator[](size_t n) const { return m_entries[n]; }
 150
 151   //------------------------------------------------------------------
 152   /// Gets the argument vector.
 153   ///
 154   /// The value returned by this function can be used by any function that
 155   /// takes and vector. The return value is just like \a argv in the standard
 156   /// 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 **GetArgumentVector();
 166
 167   //------------------------------------------------------------------
 168   /// Gets the argument vector.
 169   ///
 170   /// The value returned by this function can be used by any function that
 171   /// takes and vector. The return value is just like \a argv in the standard
 172   /// C entry point function:
 173   ///     \code
 174   ///         int main (int argc, const char **argv);
 175   ///     \endcode
 176   ///
 177   /// @return
 178   ///     An array of NULL terminate C string argument pointers that
 179   ///     also has a terminating NULL C string pointer
 180   //------------------------------------------------------------------
 181   const char **GetConstArgumentVector() const;
 182
 183   //------------------------------------------------------------------
 184   /// Gets the argument as an ArrayRef. Note that the return value does *not*
 185   /// have a nullptr const char * at the end, as the size of the list is
 186   /// embedded in the ArrayRef object.
 187   //------------------------------------------------------------------
 188   llvm::ArrayRef<const char *> GetArgumentArrayRef() const {
 189     return llvm::makeArrayRef(m_argv).drop_back();
 190   }
 191
 192   //------------------------------------------------------------------
 193   /// Appends a new argument to the end of the list argument list.
 194   ///
 195   /// @param[in] arg_cstr
 196   ///     The new argument as a NULL terminated C string.
 197   ///
 198   /// @param[in] quote_char
 199   ///     If the argument was originally quoted, put in the quote char here.
 200   //------------------------------------------------------------------
 201   void AppendArgument(llvm::StringRef arg_str, char quote_char = '\0');
 202
 203   void AppendArguments(const Args &rhs);
 204
 205   void 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   void InsertArgumentAtIndex(size_t idx, llvm::StringRef arg_str,
 223                              char quote_char = '\0');
 224
 225   //------------------------------------------------------------------
 226   /// Replaces the argument value at index \a idx to \a arg_cstr if \a idx is
 227   /// 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   void ReplaceArgumentAtIndex(size_t idx, llvm::StringRef arg_str,
 239                               char quote_char = '\0');
 240
 241   //------------------------------------------------------------------
 242   /// Deletes the argument value at index
 243   /// if \a idx is a valid argument index.
 244   ///
 245   /// @param[in] idx
 246   ///     The index of the argument that will have its value replaced.
 247   ///
 248   //------------------------------------------------------------------
 249   void DeleteArgumentAtIndex(size_t idx);
 250
 251   //------------------------------------------------------------------
 252   /// Sets the argument vector value, optionally copying all arguments into an
 253   /// internal buffer.
 254   ///
 255   /// Sets the arguments to match those found in \a argv. All argument strings
 256   /// will be copied into an internal buffers.
 257   //
 258   //  FIXME: Handle the quote character somehow.
 259   //------------------------------------------------------------------
 260   void SetArguments(size_t argc, const char **argv);
 261
 262   void SetArguments(const char **argv);
 263
 264   //------------------------------------------------------------------
 265   /// Shifts the first argument C string value of the array off the argument
 266   /// array.
 267   ///
 268   /// The string value will be freed, so a copy of the string should be made
 269   /// by calling Args::GetArgumentAtIndex (size_t) const first and copying the
 270   /// returned value before calling Args::Shift().
 271   ///
 272   /// @see Args::GetArgumentAtIndex (size_t) const
 273   //------------------------------------------------------------------
 274   void Shift();
 275
 276   //------------------------------------------------------------------
 277   /// Inserts a class owned copy of \a arg_cstr at the beginning of the
 278   /// argument vector.
 279   ///
 280   /// A copy \a arg_cstr will be made.
 281   ///
 282   /// @param[in] arg_cstr
 283   ///     The argument to push on the front of the argument stack.
 284   ///
 285   /// @param[in] quote_char
 286   ///     If the argument was originally quoted, put in the quote char here.
 287   //------------------------------------------------------------------
 288   void Unshift(llvm::StringRef arg_str, char quote_char = '\0');
 289
 290   //------------------------------------------------------------------
 291   // Clear the arguments.
 292   //
 293   // For re-setting or blanking out the list of arguments.
 294   //------------------------------------------------------------------
 295   void Clear();
 296
 297   static const char *StripSpaces(std::string &s, bool leading = true,
 298                                  bool trailing = true,
 299                                  bool return_null_if_empty = true);
 300
 301   static bool UInt64ValueIsValidForByteSize(uint64_t uval64,
 302                                             size_t total_byte_size) {
 303     if (total_byte_size > 8)
 304       return false;
 305
 306     if (total_byte_size == 8)
 307       return true;
 308
 309     const uint64_t max = ((uint64_t)1 << (uint64_t)(total_byte_size * 8)) - 1;
 310     return uval64 <= max;
 311   }
 312
 313   static bool SInt64ValueIsValidForByteSize(int64_t sval64,
 314                                             size_t total_byte_size) {
 315     if (total_byte_size > 8)
 316       return false;
 317
 318     if (total_byte_size == 8)
 319       return true;
 320
 321     const int64_t max = ((int64_t)1 << (uint64_t)(total_byte_size * 8 - 1)) - 1;
 322     const int64_t min = ~(max);
 323     return min <= sval64 && sval64 <= max;
 324   }
 325
 326   static lldb::Encoding
 327   StringToEncoding(llvm::StringRef s,
 328                    lldb::Encoding fail_value = lldb::eEncodingInvalid);
 329
 330   static uint32_t StringToGenericRegister(llvm::StringRef s);
 331
 332   static const char *GetShellSafeArgument(const FileSpec &shell,
 333                                           const char *unsafe_arg,
 334                                           std::string &safe_arg);
 335
 336   // EncodeEscapeSequences will change the textual representation of common
 337   // escape sequences like "\n" (two characters) into a single '\n'. It does
 338   // this for all of the supported escaped sequences and for the \0ooo (octal)
 339   // and \xXX (hex). The resulting "dst" string will contain the character
 340   // versions of all supported escape sequences. The common supported escape
 341   // sequences are: "\a", "\b", "\f", "\n", "\r", "\t", "\v", "\'", "\"", "\\".
 342
 343   static void EncodeEscapeSequences(const char *src, std::string &dst);
 344
 345   // ExpandEscapeSequences will change a string of possibly non-printable
 346   // characters and expand them into text. So '\n' will turn into two
 347   // characters like "\n" which is suitable for human reading. When a character
 348   // is not printable and isn't one of the common in escape sequences listed in
 349   // the help for EncodeEscapeSequences, then it will be encoded as octal.
 350   // Printable characters are left alone.
 351   static void ExpandEscapedCharacters(const char *src, std::string &dst);
 352
 353   static std::string EscapeLLDBCommandArgument(const std::string &arg,
 354                                                char quote_char);
 355
 356 private:
 357   std::vector<ArgEntry> m_entries;
 358   std::vector<char *> m_argv;
 359 };
 360
 361 //----------------------------------------------------------------------
 362 /// @class OptionsWithRaw Args.h "lldb/Utility/Args.h"
 363 /// A pair of an option list with a 'raw' string as a suffix.
 364 ///
 365 /// This class works similar to Args, but handles the case where we have a
 366 /// trailing string that shouldn't be interpreted as a list of arguments but
 367 /// preserved as is. It is also only useful for handling command line options
 368 /// (e.g. '-foo bar -i0') that start with a dash.
 369 ///
 370 /// The leading option list is optional. If the first non-space character
 371 /// in the string starts with a dash, and the string contains an argument
 372 /// that is an unquoted double dash (' -- '), then everything up to the double
 373 /// dash is parsed as a list of arguments. Everything after the double dash
 374 /// is interpreted as the raw suffix string. Note that the space behind the
 375 /// double dash is not part of the raw suffix.
 376 ///
 377 /// All strings not matching the above format as considered to be just a raw
 378 /// string without any options.
 379 ///
 380 /// @see Args
 381 //----------------------------------------------------------------------
 382 class OptionsWithRaw {
 383 public:
 384   //------------------------------------------------------------------
 385   /// Parse the given string as a list of optional arguments with a raw suffix.
 386   ///
 387   /// See the class description for a description of the input format.
 388   ///
 389   /// @param[in] argument_string
 390   ///     The string that should be parsed.
 391   //------------------------------------------------------------------
 392   explicit OptionsWithRaw(llvm::StringRef argument_string);
 393
 394   //------------------------------------------------------------------
 395   /// Returns true if there are any arguments before the raw suffix.
 396   //------------------------------------------------------------------
 397   bool HasArgs() const { return m_has_args; }
 398
 399   //------------------------------------------------------------------
 400   /// Returns the list of arguments.
 401   ///
 402   /// You can only call this method if HasArgs returns true.
 403   //------------------------------------------------------------------
 404   Args &GetArgs() {
 405     assert(m_has_args);
 406     return m_args;
 407   }
 408
 409   //------------------------------------------------------------------
 410   /// Returns the list of arguments.
 411   ///
 412   /// You can only call this method if HasArgs returns true.
 413   //------------------------------------------------------------------
 414   const Args &GetArgs() const {
 415     assert(m_has_args);
 416     return m_args;
 417   }
 418
 419   //------------------------------------------------------------------
 420   /// Returns the part of the input string that was used for parsing the
 421   /// argument list. This string also includes the double dash that is used
 422   /// for separating the argument list from the suffix.
 423   ///
 424   /// You can only call this method if HasArgs returns true.
 425   //------------------------------------------------------------------
 426   llvm::StringRef GetArgStringWithDelimiter() const {
 427     assert(m_has_args);
 428     return m_arg_string_with_delimiter;
 429   }
 430
 431   //------------------------------------------------------------------
 432   /// Returns the part of the input string that was used for parsing the
 433   /// argument list.
 434   ///
 435   /// You can only call this method if HasArgs returns true.
 436   //------------------------------------------------------------------
 437   llvm::StringRef GetArgString() const {
 438     assert(m_has_args);
 439     return m_arg_string;
 440   }
 441
 442   //------------------------------------------------------------------
 443   /// Returns the raw suffix part of the parsed string.
 444   //------------------------------------------------------------------
 445   const std::string &GetRawPart() const { return m_suffix; }
 446
 447 private:
 448   void SetFromString(llvm::StringRef arg_string);
 449
 450   /// Keeps track if we have parsed and stored any arguments.
 451   bool m_has_args = false;
 452   Args m_args;
 453   llvm::StringRef m_arg_string;
 454   llvm::StringRef m_arg_string_with_delimiter;
 455
 456   // FIXME: This should be a StringRef, but some of the calling code expect a
 457   // C string here so only a real std::string is possible.
 458   std::string m_suffix;
 459 };
 460
 461 } // namespace lldb_private
 462
 463 #endif // LLDB_UTILITY_ARGS_H