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