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 // 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
  42     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
 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
 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_