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