contrib/llvm/tools/lldb/include/lldb/Interpreter/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 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
  43     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 entries to the stream \a s using label \a label_name.
  95     ///
  96     /// If label_name is nullptr, the dump operation is skipped.
  97     ///
  98     /// @param[in] s
  99     ///     The stream to which to dump all arguments in the argument
 100     ///     vector.
 101     /// @param[in] label_name
 102     ///     The label_name to use as the label printed for each
 103     ///     entry of the args like so:
 104     ///       {label_name}[{index}]={value}
 105     //------------------------------------------------------------------
 106     void
 107     Dump (Stream &s, const char *label_name = "argv") const;
 108
 109     //------------------------------------------------------------------
 110     /// Sets the command string contained by this object.
 111     ///
 112     /// The command string will be copied and split up into arguments
 113     /// that can be accessed via the accessor functions.
 114     ///
 115     /// @param[in] command
 116     ///     A command StringRef that will be copied and split up
 117     ///     into arguments.
 118     ///
 119     /// @see Args::GetArgumentCount() const
 120     /// @see Args::GetArgumentAtIndex (size_t) const
 121     /// @see Args::GetArgumentVector ()
 122     /// @see Args::Shift ()
 123     /// @see Args::Unshift (const char *)
 124     //------------------------------------------------------------------
 125     void
 126     SetCommandString (llvm::StringRef command);
 127
 128     bool
 129     GetCommandString (std::string &command) const;
 130
 131     bool
 132     GetQuotedCommandString (std::string &command) const;
 133
 134     //------------------------------------------------------------------
 135     /// Gets the number of arguments left in this command object.
 136     ///
 137     /// @return
 138     ///     The number or arguments in this object.
 139     //------------------------------------------------------------------
 140     size_t
 141     GetArgumentCount () const;
 142
 143     //------------------------------------------------------------------
 144     /// Gets the NULL terminated C string argument pointer for the
 145     /// argument at index \a idx.
 146     ///
 147     /// @return
 148     ///     The NULL terminated C string argument pointer if \a idx is a
 149     ///     valid argument index, NULL otherwise.
 150     //------------------------------------------------------------------
 151     const char *
 152     GetArgumentAtIndex (size_t idx) const;
 153
 154     char
 155     GetArgumentQuoteCharAtIndex (size_t idx) const;
 156
 157     //------------------------------------------------------------------
 158     /// Gets the argument vector.
 159     ///
 160     /// The value returned by this function can be used by any function
 161     /// that takes and vector. The return value is just like \a argv
 162     /// in the standard C entry point function:
 163     ///     \code
 164     ///         int main (int argc, const char **argv);
 165     ///     \endcode
 166     ///
 167     /// @return
 168     ///     An array of NULL terminated C string argument pointers that
 169     ///     also has a terminating NULL C string pointer
 170     //------------------------------------------------------------------
 171     char **
 172     GetArgumentVector ();
 173
 174     //------------------------------------------------------------------
 175     /// Gets the argument vector.
 176     ///
 177     /// The value returned by this function can be used by any function
 178     /// that takes and vector. The return value is just like \a argv
 179     /// in the standard C entry point function:
 180     ///     \code
 181     ///         int main (int argc, const char **argv);
 182     ///     \endcode
 183     ///
 184     /// @return
 185     ///     An array of NULL terminate C string argument pointers that
 186     ///     also has a terminating NULL C string pointer
 187     //------------------------------------------------------------------
 188     const char **
 189     GetConstArgumentVector () const;
 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     /// @return
 202     ///     The NULL terminated C string of the copy of \a arg_cstr.
 203     //------------------------------------------------------------------
 204     const char *
 205     AppendArgument (const char *arg_cstr, char quote_char = '\0');
 206
 207     void
 208     AppendArguments (const Args &rhs);
 209
 210     void
 211     AppendArguments (const char **argv);
 212
 213     //------------------------------------------------------------------
 214     /// Insert the argument value at index \a idx to \a arg_cstr.
 215     ///
 216     /// @param[in] idx
 217     ///     The index of where to insert the argument.
 218     ///
 219     /// @param[in] arg_cstr
 220     ///     The new argument as a NULL terminated C string.
 221     ///
 222     /// @param[in] quote_char
 223     ///     If the argument was originally quoted, put in the quote char here.
 224     ///
 225     /// @return
 226     ///     The NULL terminated C string of the copy of \a arg_cstr.
 227     //------------------------------------------------------------------
 228     const char *
 229     InsertArgumentAtIndex (size_t idx, const char *arg_cstr, char quote_char = '\0');
 230
 231     //------------------------------------------------------------------
 232     /// Replaces the argument value at index \a idx to \a arg_cstr
 233     /// if \a idx is a valid argument index.
 234     ///
 235     /// @param[in] idx
 236     ///     The index of the argument that will have its value replaced.
 237     ///
 238     /// @param[in] arg_cstr
 239     ///     The new argument as a NULL terminated C string.
 240     ///
 241     /// @param[in] quote_char
 242     ///     If the argument was originally quoted, put in the quote char here.
 243     ///
 244     /// @return
 245     ///     The NULL terminated C string of the copy of \a arg_cstr if
 246     ///     \a idx was a valid index, NULL otherwise.
 247     //------------------------------------------------------------------
 248     const char *
 249     ReplaceArgumentAtIndex (size_t idx, const char *arg_cstr, char quote_char = '\0');
 250
 251     //------------------------------------------------------------------
 252     /// Deletes the argument value at index
 253     /// if \a idx is a valid argument index.
 254     ///
 255     /// @param[in] idx
 256     ///     The index of the argument that will have its value replaced.
 257     ///
 258     //------------------------------------------------------------------
 259     void
 260     DeleteArgumentAtIndex (size_t idx);
 261
 262     //------------------------------------------------------------------
 263     /// Sets the argument vector value, optionally copying all
 264     /// arguments into an internal buffer.
 265     ///
 266     /// Sets the arguments to match those found in \a argv. All argument
 267     /// strings will be copied into an internal buffers.
 268     //
 269     //  FIXME: Handle the quote character somehow.
 270     //------------------------------------------------------------------
 271     void
 272     SetArguments (size_t argc, const char **argv);
 273
 274     void
 275     SetArguments (const char **argv);
 276
 277     //------------------------------------------------------------------
 278     /// Shifts the first argument C string value of the array off the
 279     /// argument array.
 280     ///
 281     /// The string value will be freed, so a copy of the string should
 282     /// be made by calling Args::GetArgumentAtIndex (size_t) const
 283     /// first and copying the returned value before calling
 284     /// Args::Shift().
 285     ///
 286     /// @see Args::GetArgumentAtIndex (size_t) const
 287     //------------------------------------------------------------------
 288     void
 289     Shift ();
 290
 291     //------------------------------------------------------------------
 292     /// Inserts a class owned copy of \a arg_cstr at the beginning of
 293     /// the argument vector.
 294     ///
 295     /// A copy \a arg_cstr will be made.
 296     ///
 297     /// @param[in] arg_cstr
 298     ///     The argument to push on the front of the argument stack.
 299     ///
 300     /// @param[in] quote_char
 301     ///     If the argument was originally quoted, put in the quote char here.
 302     ///
 303     /// @return
 304     ///     A pointer to the copy of \a arg_cstr that was made.
 305     //------------------------------------------------------------------
 306     const char *
 307     Unshift (const char *arg_cstr, char quote_char = '\0');
 308
 309     //------------------------------------------------------------------
 310     /// Parse the arguments in the contained arguments.
 311     ///
 312     /// The arguments that are consumed by the argument parsing process
 313     /// will be removed from the argument vector. The arguments that
 314     /// get processed start at the second argument. The first argument
 315     /// is assumed to be the command and will not be touched.
 316     ///
 317     /// @see class Options
 318     //------------------------------------------------------------------
 319     Error
 320     ParseOptions (Options &options);
 321
 322     size_t
 323     FindArgumentIndexForOption (Option *long_options, int long_options_index);
 324
 325     bool
 326     IsPositionalArgument (const char *arg);
 327
 328     // The following works almost identically to ParseOptions, except that no option is required to have arguments,
 329     // and it builds up the option_arg_vector as it parses the options.
 330
 331     void
 332     ParseAliasOptions (Options &options, CommandReturnObject &result, OptionArgVector *option_arg_vector,
 333                        std::string &raw_input_line);
 334
 335     void
 336     ParseArgsForCompletion (Options &options, OptionElementVector &option_element_vector, uint32_t cursor_index);
 337
 338     //------------------------------------------------------------------
 339     // Clear the arguments.
 340     //
 341     // For re-setting or blanking out the list of arguments.
 342     //------------------------------------------------------------------
 343     void
 344     Clear ();
 345
 346     static const char *
 347     StripSpaces (std::string &s,
 348                  bool leading = true,
 349                  bool trailing = true,
 350                  bool return_null_if_empty = true);
 351
 352     static bool
 353     UInt64ValueIsValidForByteSize (uint64_t uval64, size_t total_byte_size)
 354     {
 355         if (total_byte_size > 8)
 356             return false;
 357
 358         if (total_byte_size == 8)
 359             return true;
 360
 361         const uint64_t max = ((uint64_t)1 << (uint64_t)(total_byte_size * 8)) - 1;
 362         return uval64 <= max;
 363     }
 364
 365     static bool
 366     SInt64ValueIsValidForByteSize (int64_t sval64, size_t total_byte_size)
 367     {
 368         if (total_byte_size > 8)
 369             return false;
 370
 371         if (total_byte_size == 8)
 372             return true;
 373
 374         const int64_t max = ((int64_t)1 << (uint64_t)(total_byte_size * 8 - 1)) - 1;
 375         const int64_t min = ~(max);
 376         return min <= sval64 && sval64 <= max;
 377     }
 378
 379     static lldb::addr_t
 380     StringToAddress (const ExecutionContext *exe_ctx,
 381                      const char *s,
 382                      lldb::addr_t fail_value,
 383                      Error *error);
 384
 385     static bool
 386     StringToBoolean (const char *s, bool fail_value, bool *success_ptr);
 387
 388     static char StringToChar(const char *s, char fail_value, bool *success_ptr);
 389
 390     static int64_t
 391     StringToOptionEnum (const char *s, OptionEnumValueElement *enum_values, int32_t fail_value, Error &error);
 392
 393     static lldb::ScriptLanguage
 394     StringToScriptLanguage (const char *s, lldb::ScriptLanguage fail_value, bool *success_ptr);
 395
 396     static Error
 397     StringToFormat (const char *s,
 398                     lldb::Format &format,
 399                     size_t *byte_size_ptr); // If non-NULL, then a byte size can precede the format character
 400
 401     static lldb::Encoding
 402     StringToEncoding (const char *s,
 403                       lldb::Encoding fail_value = lldb::eEncodingInvalid);
 404
 405     static uint32_t
 406     StringToGenericRegister (const char *s);
 407
 408     static const char *
 409     StringToVersion (const char *s, uint32_t &major, uint32_t &minor, uint32_t &update);
 410
 411     static const char *
 412     GetShellSafeArgument (const FileSpec& shell, const char *unsafe_arg, std::string &safe_arg);
 413
 414     // EncodeEscapeSequences will change the textual representation of common
 415     // escape sequences like "\n" (two characters) into a single '\n'. It does
 416     // this for all of the supported escaped sequences and for the \0ooo (octal)
 417     // and \xXX (hex). The resulting "dst" string will contain the character
 418     // versions of all supported escape sequences. The common supported escape
 419     // sequences are: "\a", "\b", "\f", "\n", "\r", "\t", "\v", "\'", "\"", "\\".
 420
 421     static void
 422     EncodeEscapeSequences (const char *src, std::string &dst);
 423
 424     // ExpandEscapeSequences will change a string of possibly non-printable
 425     // characters and expand them into text. So '\n' will turn into two characters
 426     // like "\n" which is suitable for human reading. When a character is not
 427     // printable and isn't one of the common in escape sequences listed in the
 428     // help for EncodeEscapeSequences, then it will be encoded as octal. Printable
 429     // characters are left alone.
 430     static void
 431     ExpandEscapedCharacters (const char *src, std::string &dst);
 432
 433     static std::string
 434     EscapeLLDBCommandArgument (const std::string& arg, char quote_char);
 435
 436     // This one isn't really relevant to Arguments per se, but we're using the Args as a
 437     // general strings container, so...
 438     void
 439     LongestCommonPrefix (std::string &common_prefix);
 440
 441     //------------------------------------------------------------------
 442     /// Return whether a given environment variable exists.
 443     ///
 444     /// This command treats Args like a list of environment variables,
 445     /// as used in ProcessLaunchInfo.  It treats each argument as
 446     /// an {env_var_name}={value} or an {env_var_name} entry.
 447     ///
 448     /// @param[in] env_var_name
 449     ///     Specifies the name of the environment variable to check.
 450     ///
 451     /// @return
 452     ///     true if the specified env var name exists in the list in
 453     ///     either of the above-mentioned formats; otherwise, false.
 454     //------------------------------------------------------------------
 455     bool
 456     ContainsEnvironmentVariable(const char *env_var_name) const;
 457
 458 protected:
 459     //------------------------------------------------------------------
 460     // Classes that inherit from Args can see and modify these
 461     //------------------------------------------------------------------
 462     typedef std::list<std::string> arg_sstr_collection;
 463     typedef std::vector<const char *> arg_cstr_collection;
 464     typedef std::vector<char> arg_quote_char_collection;
 465     arg_sstr_collection m_args;
 466     arg_cstr_collection m_argv; ///< The current argument vector.
 467     arg_quote_char_collection m_args_quote_char;
 468
 469     void
 470     UpdateArgsAfterOptionParsing ();
 471
 472     void
 473     UpdateArgvFromArgs ();
 474
 475     llvm::StringRef
 476     ParseSingleArgument (llvm::StringRef command);
 477 };
 478
 479 } // namespace lldb_private
 480
 481 #endif  // liblldb_Command_h_