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/Error.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);
90 Args &operator=(const Args &rhs);
92 //------------------------------------------------------------------
94 //------------------------------------------------------------------
97 //------------------------------------------------------------------
98 /// Dump all entries to the stream \a s using label \a label_name.
100 /// If label_name is nullptr, the dump operation is skipped.
103 /// The stream to which to dump all arguments in the argument
105 /// @param[in] label_name
106 /// The label_name to use as the label printed for each
107 /// entry of the args like so:
108 /// {label_name}[{index}]={value}
109 //------------------------------------------------------------------
110 void Dump(Stream &s, const char *label_name = "argv") const;
112 //------------------------------------------------------------------
113 /// Sets the command string contained by this object.
115 /// The command string will be copied and split up into arguments
116 /// that can be accessed via the accessor functions.
118 /// @param[in] command
119 /// A command StringRef that will be copied and split up
122 /// @see Args::GetArgumentCount() const
123 /// @see Args::GetArgumentAtIndex (size_t) const
124 /// @see Args::GetArgumentVector ()
125 /// @see Args::Shift ()
126 /// @see Args::Unshift (const char *)
127 //------------------------------------------------------------------
128 void SetCommandString(llvm::StringRef command);
130 bool GetCommandString(std::string &command) const;
132 bool GetQuotedCommandString(std::string &command) const;
134 //------------------------------------------------------------------
135 /// Gets the number of arguments left in this command object.
138 /// The number or arguments in this object.
139 //------------------------------------------------------------------
140 size_t GetArgumentCount() const;
141 bool empty() const { return GetArgumentCount() == 0; }
143 //------------------------------------------------------------------
144 /// Gets the NULL terminated C string argument pointer for the
145 /// argument at index \a idx.
148 /// The NULL terminated C string argument pointer if \a idx is a
149 /// valid argument index, NULL otherwise.
150 //------------------------------------------------------------------
151 const char *GetArgumentAtIndex(size_t idx) const;
153 llvm::ArrayRef<ArgEntry> entries() const { return m_entries; }
154 char GetArgumentQuoteCharAtIndex(size_t idx) const;
156 std::vector<ArgEntry>::const_iterator begin() const {
157 return m_entries.begin();
159 std::vector<ArgEntry>::const_iterator end() const { return m_entries.end(); }
161 size_t size() const { return GetArgumentCount(); }
162 const ArgEntry &operator[](size_t n) const { return m_entries[n]; }
164 //------------------------------------------------------------------
165 /// Gets the argument vector.
167 /// The value returned by this function can be used by any function
168 /// that takes and vector. The return value is just like \a argv
169 /// in the standard C entry point function:
171 /// int main (int argc, const char **argv);
175 /// An array of NULL terminated C string argument pointers that
176 /// also has a terminating NULL C string pointer
177 //------------------------------------------------------------------
178 char **GetArgumentVector();
180 //------------------------------------------------------------------
181 /// Gets the argument vector.
183 /// The value returned by this function can be used by any function
184 /// that takes and vector. The return value is just like \a argv
185 /// in the standard C entry point function:
187 /// int main (int argc, const char **argv);
191 /// An array of NULL terminate C string argument pointers that
192 /// also has a terminating NULL C string pointer
193 //------------------------------------------------------------------
194 const char **GetConstArgumentVector() const;
196 //------------------------------------------------------------------
197 /// Gets the argument as an ArrayRef. Note that the return value does *not*
198 /// have a nullptr const char * at the end, as the size of the list is
199 /// embedded in the ArrayRef object.
200 //------------------------------------------------------------------
201 llvm::ArrayRef<const char *> GetArgumentArrayRef() const {
202 return llvm::makeArrayRef(m_argv).drop_back();
205 //------------------------------------------------------------------
206 /// Appends a new argument to the end of the list argument list.
208 /// @param[in] arg_cstr
209 /// The new argument as a NULL terminated C string.
211 /// @param[in] quote_char
212 /// If the argument was originally quoted, put in the quote char here.
213 //------------------------------------------------------------------
214 void AppendArgument(llvm::StringRef arg_str, char quote_char = '\0');
216 void AppendArguments(const Args &rhs);
218 void AppendArguments(const char **argv);
220 //------------------------------------------------------------------
221 /// Insert the argument value at index \a idx to \a arg_cstr.
224 /// The index of where to insert the argument.
226 /// @param[in] arg_cstr
227 /// The new argument as a NULL terminated C string.
229 /// @param[in] quote_char
230 /// If the argument was originally quoted, put in the quote char here.
233 /// The NULL terminated C string of the copy of \a arg_cstr.
234 //------------------------------------------------------------------
235 void InsertArgumentAtIndex(size_t idx, llvm::StringRef arg_str,
236 char quote_char = '\0');
238 //------------------------------------------------------------------
239 /// Replaces the argument value at index \a idx to \a arg_cstr
240 /// if \a idx is a valid argument index.
243 /// The index of the argument that will have its value replaced.
245 /// @param[in] arg_cstr
246 /// The new argument as a NULL terminated C string.
248 /// @param[in] quote_char
249 /// If the argument was originally quoted, put in the quote char here.
250 //------------------------------------------------------------------
251 void ReplaceArgumentAtIndex(size_t idx, llvm::StringRef arg_str,
252 char quote_char = '\0');
254 //------------------------------------------------------------------
255 /// Deletes the argument value at index
256 /// if \a idx is a valid argument index.
259 /// The index of the argument that will have its value replaced.
261 //------------------------------------------------------------------
262 void DeleteArgumentAtIndex(size_t idx);
264 //------------------------------------------------------------------
265 /// Sets the argument vector value, optionally copying all
266 /// arguments into an internal buffer.
268 /// Sets the arguments to match those found in \a argv. All argument
269 /// strings will be copied into an internal buffers.
271 // FIXME: Handle the quote character somehow.
272 //------------------------------------------------------------------
273 void SetArguments(size_t argc, const char **argv);
275 void SetArguments(const char **argv);
277 //------------------------------------------------------------------
278 /// Shifts the first argument C string value of the array off the
281 /// The string value will be freed, so a copy of the string should
282 /// be made by calling Args::GetArgumentAtIndex (size_t) const
283 /// first and copying the returned value before calling
286 /// @see Args::GetArgumentAtIndex (size_t) const
287 //------------------------------------------------------------------
290 //------------------------------------------------------------------
291 /// Inserts a class owned copy of \a arg_cstr at the beginning of
292 /// the argument vector.
294 /// A copy \a arg_cstr will be made.
296 /// @param[in] arg_cstr
297 /// The argument to push on the front of the argument stack.
299 /// @param[in] quote_char
300 /// If the argument was originally quoted, put in the quote char here.
301 //------------------------------------------------------------------
302 void Unshift(llvm::StringRef arg_str, char quote_char = '\0');
304 //------------------------------------------------------------------
305 /// Parse the arguments in the contained arguments.
307 /// The arguments that are consumed by the argument parsing process
308 /// will be removed from the argument vector. The arguments that
309 /// get processed start at the second argument. The first argument
310 /// is assumed to be the command and will not be touched.
312 /// param[in] platform_sp
313 /// The platform used for option validation. This is necessary
314 /// because an empty execution_context is not enough to get us
315 /// to a reasonable platform. If the platform isn't given,
316 /// we'll try to get it from the execution context. If we can't
317 /// get it from the execution context, we'll skip validation.
319 /// param[in] require_validation
320 /// When true, it will fail option parsing if validation could
321 /// not occur due to not having a platform.
323 /// @see class Options
324 //------------------------------------------------------------------
325 Error ParseOptions(Options &options, ExecutionContext *execution_context,
326 lldb::PlatformSP platform_sp, bool require_validation);
328 bool IsPositionalArgument(const char *arg);
330 // The following works almost identically to ParseOptions, except that no
331 // option is required to have arguments, and it builds up the
332 // option_arg_vector as it parses the options.
334 std::string ParseAliasOptions(Options &options, CommandReturnObject &result,
335 OptionArgVector *option_arg_vector,
336 llvm::StringRef raw_input_line);
338 void ParseArgsForCompletion(Options &options,
339 OptionElementVector &option_element_vector,
340 uint32_t cursor_index);
342 //------------------------------------------------------------------
343 // Clear the arguments.
345 // For re-setting or blanking out the list of arguments.
346 //------------------------------------------------------------------
349 static const char *StripSpaces(std::string &s, bool leading = true,
350 bool trailing = true,
351 bool return_null_if_empty = true);
353 static bool UInt64ValueIsValidForByteSize(uint64_t uval64,
354 size_t total_byte_size) {
355 if (total_byte_size > 8)
358 if (total_byte_size == 8)
361 const uint64_t max = ((uint64_t)1 << (uint64_t)(total_byte_size * 8)) - 1;
362 return uval64 <= max;
365 static bool SInt64ValueIsValidForByteSize(int64_t sval64,
366 size_t total_byte_size) {
367 if (total_byte_size > 8)
370 if (total_byte_size == 8)
373 const int64_t max = ((int64_t)1 << (uint64_t)(total_byte_size * 8 - 1)) - 1;
374 const int64_t min = ~(max);
375 return min <= sval64 && sval64 <= max;
378 static lldb::addr_t StringToAddress(const ExecutionContext *exe_ctx,
380 lldb::addr_t fail_value, Error *error);
382 static bool StringToBoolean(llvm::StringRef s, bool fail_value,
385 static char StringToChar(llvm::StringRef s, char fail_value,
388 static int64_t StringToOptionEnum(llvm::StringRef s,
389 OptionEnumValueElement *enum_values,
390 int32_t fail_value, Error &error);
392 static lldb::ScriptLanguage
393 StringToScriptLanguage(llvm::StringRef s, lldb::ScriptLanguage fail_value,
396 // TODO: Use StringRef
397 static Error StringToFormat(const char *s, lldb::Format &format,
398 size_t *byte_size_ptr); // If non-NULL, then a
399 // byte size can precede
400 // the format character
402 static lldb::Encoding
403 StringToEncoding(llvm::StringRef s,
404 lldb::Encoding fail_value = lldb::eEncodingInvalid);
406 static uint32_t StringToGenericRegister(llvm::StringRef s);
408 static bool StringToVersion(llvm::StringRef string, uint32_t &major,
409 uint32_t &minor, uint32_t &update);
411 static const char *GetShellSafeArgument(const FileSpec &shell,
412 const char *unsafe_arg,
413 std::string &safe_arg);
415 // EncodeEscapeSequences will change the textual representation of common
416 // escape sequences like "\n" (two characters) into a single '\n'. It does
417 // this for all of the supported escaped sequences and for the \0ooo (octal)
418 // and \xXX (hex). The resulting "dst" string will contain the character
419 // versions of all supported escape sequences. The common supported escape
420 // sequences are: "\a", "\b", "\f", "\n", "\r", "\t", "\v", "\'", "\"", "\\".
422 static void EncodeEscapeSequences(const char *src, std::string &dst);
424 // ExpandEscapeSequences will change a string of possibly non-printable
425 // characters and expand them into text. So '\n' will turn into two characters
426 // like "\n" which is suitable for human reading. When a character is not
427 // printable and isn't one of the common in escape sequences listed in the
428 // help for EncodeEscapeSequences, then it will be encoded as octal. Printable
429 // characters are left alone.
430 static void ExpandEscapedCharacters(const char *src, std::string &dst);
432 static std::string EscapeLLDBCommandArgument(const std::string &arg,
435 //------------------------------------------------------------------
436 /// Add or replace an environment variable with the given value.
438 /// This command adds the environment variable if it is not already
439 /// present using the given value. If the environment variable is
440 /// already in the list, it replaces the first such occurrence
441 /// with the new value.
442 //------------------------------------------------------------------
443 void AddOrReplaceEnvironmentVariable(llvm::StringRef env_var_name,
444 llvm::StringRef new_value);
446 /// Return whether a given environment variable exists.
448 /// This command treats Args like a list of environment variables,
449 /// as used in ProcessLaunchInfo. It treats each argument as
450 /// an {env_var_name}={value} or an {env_var_name} entry.
452 /// @param[in] env_var_name
453 /// Specifies the name of the environment variable to check.
455 /// @param[out] argument_index
456 /// If non-null, then when the environment variable is found,
457 /// the index of the argument position will be returned in
458 /// the size_t pointed to by this argument.
461 /// true if the specified env var name exists in the list in
462 /// either of the above-mentioned formats; otherwise, false.
463 //------------------------------------------------------------------
464 bool ContainsEnvironmentVariable(llvm::StringRef env_var_name,
465 size_t *argument_index = nullptr) const;
468 size_t FindArgumentIndexForOption(Option *long_options,
469 int long_options_index) const;
471 std::vector<ArgEntry> m_entries;
472 std::vector<char *> m_argv;
474 void UpdateArgsAfterOptionParsing();
477 } // namespace lldb_private
479 #endif // liblldb_Command_h_