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