1 //===-- Args.h --------------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Command_h_
11 #define liblldb_Command_h_
20 // Other libraries and framework includes
21 #include "llvm/ADT/ArrayRef.h"
22 #include "llvm/ADT/StringRef.h"
24 #include "lldb/Utility/Status.h"
25 #include "lldb/lldb-private-types.h"
26 #include "lldb/lldb-types.h"
28 namespace lldb_private {
32 typedef std::vector<std::tuple<std::string, int, std::string>> OptionArgVector;
33 typedef std::shared_ptr<OptionArgVector> OptionArgVectorSP;
35 struct OptionArgElement {
36 enum { eUnrecognizedArg = -1, eBareDash = -2, eBareDoubleDash = -3 };
38 OptionArgElement(int defs_index, int pos, int arg_pos)
39 : opt_defs_index(defs_index), opt_pos(pos), opt_arg_pos(arg_pos) {}
46 typedef std::vector<OptionArgElement> OptionElementVector;
48 //----------------------------------------------------------------------
49 /// @class Args Args.h "lldb/Interpreter/Args.h"
50 /// @brief A command line argument class.
52 /// The Args class is designed to be fed a command line. The
53 /// command line is copied into an internal buffer and then split up
54 /// into arguments. Arguments are space delimited if there are no quotes
55 /// (single, double, or backtick quotes) surrounding the argument. Spaces
56 /// can be escaped using a \ character to avoid having to surround an
57 /// argument that contains a space with quotes.
58 //----------------------------------------------------------------------
64 std::unique_ptr<char[]> ptr;
66 char *data() { return ptr.get(); }
70 ArgEntry(llvm::StringRef str, char quote);
74 const char *c_str() const { return ptr.get(); }
77 //------------------------------------------------------------------
78 /// Construct with an option command string.
80 /// @param[in] command
81 /// A NULL terminated command that will be copied and split up
84 /// @see Args::SetCommandString(llvm::StringRef)
85 //------------------------------------------------------------------
86 Args(llvm::StringRef command = llvm::StringRef());
88 Args(const Args &rhs);
89 explicit Args(const StringList &list);
91 Args &operator=(const Args &rhs);
93 //------------------------------------------------------------------
95 //------------------------------------------------------------------
98 //------------------------------------------------------------------
99 /// Dump all entries to the stream \a s using label \a label_name.
101 /// If label_name is nullptr, the dump operation is skipped.
104 /// The stream to which to dump all arguments in the argument
106 /// @param[in] label_name
107 /// The label_name to use as the label printed for each
108 /// entry of the args like so:
109 /// {label_name}[{index}]={value}
110 //------------------------------------------------------------------
111 void Dump(Stream &s, const char *label_name = "argv") const;
113 //------------------------------------------------------------------
114 /// Sets the command string contained by this object.
116 /// The command string will be copied and split up into arguments
117 /// that can be accessed via the accessor functions.
119 /// @param[in] command
120 /// A command StringRef that will be copied and split up
123 /// @see Args::GetArgumentCount() const
124 /// @see Args::GetArgumentAtIndex (size_t) const
125 /// @see Args::GetArgumentVector ()
126 /// @see Args::Shift ()
127 /// @see Args::Unshift (const char *)
128 //------------------------------------------------------------------
129 void SetCommandString(llvm::StringRef command);
131 bool GetCommandString(std::string &command) const;
133 bool GetQuotedCommandString(std::string &command) const;
135 //------------------------------------------------------------------
136 /// Gets the number of arguments left in this command object.
139 /// The number or arguments in this object.
140 //------------------------------------------------------------------
141 size_t GetArgumentCount() const;
142 bool empty() const { return GetArgumentCount() == 0; }
144 //------------------------------------------------------------------
145 /// Gets the NULL terminated C string argument pointer for the
146 /// argument at index \a idx.
149 /// The NULL terminated C string argument pointer if \a idx is a
150 /// valid argument index, NULL otherwise.
151 //------------------------------------------------------------------
152 const char *GetArgumentAtIndex(size_t idx) const;
154 llvm::ArrayRef<ArgEntry> entries() const { return m_entries; }
155 char GetArgumentQuoteCharAtIndex(size_t idx) const;
157 std::vector<ArgEntry>::const_iterator begin() const {
158 return m_entries.begin();
160 std::vector<ArgEntry>::const_iterator end() const { return m_entries.end(); }
162 size_t size() const { return GetArgumentCount(); }
163 const ArgEntry &operator[](size_t n) const { return m_entries[n]; }
165 //------------------------------------------------------------------
166 /// Gets the argument vector.
168 /// The value returned by this function can be used by any function
169 /// that takes and vector. The return value is just like \a argv
170 /// in the standard C entry point function:
172 /// int main (int argc, const char **argv);
176 /// An array of NULL terminated C string argument pointers that
177 /// also has a terminating NULL C string pointer
178 //------------------------------------------------------------------
179 char **GetArgumentVector();
181 //------------------------------------------------------------------
182 /// Gets the argument vector.
184 /// The value returned by this function can be used by any function
185 /// that takes and vector. The return value is just like \a argv
186 /// in the standard C entry point function:
188 /// int main (int argc, const char **argv);
192 /// An array of NULL terminate C string argument pointers that
193 /// also has a terminating NULL C string pointer
194 //------------------------------------------------------------------
195 const char **GetConstArgumentVector() const;
197 //------------------------------------------------------------------
198 /// Gets the argument as an ArrayRef. Note that the return value does *not*
199 /// have a nullptr const char * at the end, as the size of the list is
200 /// embedded in the ArrayRef object.
201 //------------------------------------------------------------------
202 llvm::ArrayRef<const char *> GetArgumentArrayRef() const {
203 return llvm::makeArrayRef(m_argv).drop_back();
206 //------------------------------------------------------------------
207 /// Appends a new argument to the end of the list argument list.
209 /// @param[in] arg_cstr
210 /// The new argument as a NULL terminated C string.
212 /// @param[in] quote_char
213 /// If the argument was originally quoted, put in the quote char here.
214 //------------------------------------------------------------------
215 void AppendArgument(llvm::StringRef arg_str, char quote_char = '\0');
217 void AppendArguments(const Args &rhs);
219 void AppendArguments(const char **argv);
221 //------------------------------------------------------------------
222 /// Insert the argument value at index \a idx to \a arg_cstr.
225 /// The index of where to insert the argument.
227 /// @param[in] arg_cstr
228 /// The new argument as a NULL terminated C string.
230 /// @param[in] quote_char
231 /// If the argument was originally quoted, put in the quote char here.
234 /// The NULL terminated C string of the copy of \a arg_cstr.
235 //------------------------------------------------------------------
236 void InsertArgumentAtIndex(size_t idx, llvm::StringRef arg_str,
237 char quote_char = '\0');
239 //------------------------------------------------------------------
240 /// Replaces the argument value at index \a idx to \a arg_cstr
241 /// if \a idx is a valid argument index.
244 /// The index of the argument that will have its value replaced.
246 /// @param[in] arg_cstr
247 /// The new argument as a NULL terminated C string.
249 /// @param[in] quote_char
250 /// If the argument was originally quoted, put in the quote char here.
251 //------------------------------------------------------------------
252 void ReplaceArgumentAtIndex(size_t idx, llvm::StringRef arg_str,
253 char quote_char = '\0');
255 //------------------------------------------------------------------
256 /// Deletes the argument value at index
257 /// if \a idx is a valid argument index.
260 /// The index of the argument that will have its value replaced.
262 //------------------------------------------------------------------
263 void DeleteArgumentAtIndex(size_t idx);
265 //------------------------------------------------------------------
266 /// Sets the argument vector value, optionally copying all
267 /// arguments into an internal buffer.
269 /// Sets the arguments to match those found in \a argv. All argument
270 /// strings will be copied into an internal buffers.
272 // FIXME: Handle the quote character somehow.
273 //------------------------------------------------------------------
274 void SetArguments(size_t argc, const char **argv);
276 void SetArguments(const char **argv);
278 //------------------------------------------------------------------
279 /// Shifts the first argument C string value of the array off the
282 /// The string value will be freed, so a copy of the string should
283 /// be made by calling Args::GetArgumentAtIndex (size_t) const
284 /// first and copying the returned value before calling
287 /// @see Args::GetArgumentAtIndex (size_t) const
288 //------------------------------------------------------------------
291 //------------------------------------------------------------------
292 /// Inserts a class owned copy of \a arg_cstr at the beginning of
293 /// the argument vector.
295 /// A copy \a arg_cstr will be made.
297 /// @param[in] arg_cstr
298 /// The argument to push on the front of the argument stack.
300 /// @param[in] quote_char
301 /// If the argument was originally quoted, put in the quote char here.
302 //------------------------------------------------------------------
303 void Unshift(llvm::StringRef arg_str, char quote_char = '\0');
305 //------------------------------------------------------------------
306 /// Parse the arguments in the contained arguments.
308 /// The arguments that are consumed by the argument parsing process
309 /// will be removed from the argument vector. The arguments that
310 /// get processed start at the second argument. The first argument
311 /// is assumed to be the command and will not be touched.
313 /// param[in] platform_sp
314 /// The platform used for option validation. This is necessary
315 /// because an empty execution_context is not enough to get us
316 /// to a reasonable platform. If the platform isn't given,
317 /// we'll try to get it from the execution context. If we can't
318 /// get it from the execution context, we'll skip validation.
320 /// param[in] require_validation
321 /// When true, it will fail option parsing if validation could
322 /// not occur due to not having a platform.
324 /// @see class Options
325 //------------------------------------------------------------------
326 Status ParseOptions(Options &options, ExecutionContext *execution_context,
327 lldb::PlatformSP platform_sp, bool require_validation);
329 bool IsPositionalArgument(const char *arg);
331 // The following works almost identically to ParseOptions, except that no
332 // option is required to have arguments, and it builds up the
333 // option_arg_vector as it parses the options.
335 std::string ParseAliasOptions(Options &options, CommandReturnObject &result,
336 OptionArgVector *option_arg_vector,
337 llvm::StringRef raw_input_line);
339 void ParseArgsForCompletion(Options &options,
340 OptionElementVector &option_element_vector,
341 uint32_t cursor_index);
343 //------------------------------------------------------------------
344 // Clear the arguments.
346 // For re-setting or blanking out the list of arguments.
347 //------------------------------------------------------------------
350 static const char *StripSpaces(std::string &s, bool leading = true,
351 bool trailing = true,
352 bool return_null_if_empty = true);
354 static bool UInt64ValueIsValidForByteSize(uint64_t uval64,
355 size_t total_byte_size) {
356 if (total_byte_size > 8)
359 if (total_byte_size == 8)
362 const uint64_t max = ((uint64_t)1 << (uint64_t)(total_byte_size * 8)) - 1;
363 return uval64 <= max;
366 static bool SInt64ValueIsValidForByteSize(int64_t sval64,
367 size_t total_byte_size) {
368 if (total_byte_size > 8)
371 if (total_byte_size == 8)
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;
379 static lldb::addr_t StringToAddress(const ExecutionContext *exe_ctx,
381 lldb::addr_t fail_value, Status *error);
383 static bool StringToBoolean(llvm::StringRef s, bool fail_value,
386 static char StringToChar(llvm::StringRef s, char fail_value,
389 static int64_t StringToOptionEnum(llvm::StringRef s,
390 OptionEnumValueElement *enum_values,
391 int32_t fail_value, Status &error);
393 static lldb::ScriptLanguage
394 StringToScriptLanguage(llvm::StringRef s, lldb::ScriptLanguage fail_value,
397 // TODO: Use StringRef
398 static Status StringToFormat(const char *s, lldb::Format &format,
399 size_t *byte_size_ptr); // If non-NULL, then a
400 // byte size can precede
401 // the format character
403 static lldb::Encoding
404 StringToEncoding(llvm::StringRef s,
405 lldb::Encoding fail_value = lldb::eEncodingInvalid);
407 static uint32_t StringToGenericRegister(llvm::StringRef s);
409 static bool StringToVersion(llvm::StringRef string, uint32_t &major,
410 uint32_t &minor, uint32_t &update);
412 static const char *GetShellSafeArgument(const FileSpec &shell,
413 const char *unsafe_arg,
414 std::string &safe_arg);
416 // EncodeEscapeSequences will change the textual representation of common
417 // escape sequences like "\n" (two characters) into a single '\n'. It does
418 // this for all of the supported escaped sequences and for the \0ooo (octal)
419 // and \xXX (hex). The resulting "dst" string will contain the character
420 // versions of all supported escape sequences. The common supported escape
421 // sequences are: "\a", "\b", "\f", "\n", "\r", "\t", "\v", "\'", "\"", "\\".
423 static void EncodeEscapeSequences(const char *src, std::string &dst);
425 // ExpandEscapeSequences will change a string of possibly non-printable
426 // characters and expand them into text. So '\n' will turn into two characters
427 // like "\n" which is suitable for human reading. When a character is not
428 // printable and isn't one of the common in escape sequences listed in the
429 // help for EncodeEscapeSequences, then it will be encoded as octal. Printable
430 // characters are left alone.
431 static void ExpandEscapedCharacters(const char *src, std::string &dst);
433 static std::string EscapeLLDBCommandArgument(const std::string &arg,
436 //------------------------------------------------------------------
437 /// Add or replace an environment variable with the given value.
439 /// This command adds the environment variable if it is not already
440 /// present using the given value. If the environment variable is
441 /// already in the list, it replaces the first such occurrence
442 /// with the new value.
443 //------------------------------------------------------------------
444 void AddOrReplaceEnvironmentVariable(llvm::StringRef env_var_name,
445 llvm::StringRef new_value);
447 /// Return whether a given environment variable exists.
449 /// This command treats Args like a list of environment variables,
450 /// as used in ProcessLaunchInfo. It treats each argument as
451 /// an {env_var_name}={value} or an {env_var_name} entry.
453 /// @param[in] env_var_name
454 /// Specifies the name of the environment variable to check.
456 /// @param[out] argument_index
457 /// If non-null, then when the environment variable is found,
458 /// the index of the argument position will be returned in
459 /// the size_t pointed to by this argument.
462 /// true if the specified env var name exists in the list in
463 /// either of the above-mentioned formats; otherwise, false.
464 //------------------------------------------------------------------
465 bool ContainsEnvironmentVariable(llvm::StringRef env_var_name,
466 size_t *argument_index = nullptr) const;
469 size_t FindArgumentIndexForOption(Option *long_options,
470 int long_options_index) const;
472 std::vector<ArgEntry> m_entries;
473 std::vector<char *> m_argv;
475 void UpdateArgsAfterOptionParsing();
478 } // namespace lldb_private
480 #endif // liblldb_Command_h_