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
22 #include "lldb/lldb-private-types.h"
23 #include "lldb/lldb-types.h"
24 #include "lldb/Core/Error.h"
25 #include "lldb/Host/OptionParser.h"
27 namespace lldb_private {
29 typedef std::pair<int, std::string> OptionArgValue;
30 typedef std::pair<std::string, OptionArgValue> OptionArgPair;
31 typedef std::vector<OptionArgPair> OptionArgVector;
32 typedef std::shared_ptr<OptionArgVector> OptionArgVectorSP;
34 struct OptionArgElement
37 eUnrecognizedArg = -1,
42 OptionArgElement (int defs_index, int pos, int arg_pos) :
43 opt_defs_index(defs_index),
54 typedef std::vector<OptionArgElement> OptionElementVector;
56 //----------------------------------------------------------------------
57 /// @class Args Args.h "lldb/Interpreter/Args.h"
58 /// @brief A command line argument class.
60 /// The Args class is designed to be fed a command line. The
61 /// command line is copied into an internal buffer and then split up
62 /// into arguments. Arguments are space delimited if there are no quotes
63 /// (single, double, or backtick quotes) surrounding the argument. Spaces
64 /// can be escaped using a \ character to avoid having to surround an
65 /// argument that contains a space with quotes.
66 //----------------------------------------------------------------------
71 //------------------------------------------------------------------
72 /// Construct with an option command string.
74 /// @param[in] command
75 /// A NULL terminated command that will be copied and split up
78 /// @see Args::SetCommandString(const char *)
79 //------------------------------------------------------------------
80 Args (const char *command = NULL);
82 Args (const char *command, size_t len);
84 Args (const Args &rhs);
87 operator= (const Args &rhs);
89 //------------------------------------------------------------------
91 //------------------------------------------------------------------
94 //------------------------------------------------------------------
95 /// Dump all arguments to the stream \a s.
98 /// The stream to which to dump all arguments in the argument
100 //------------------------------------------------------------------
104 //------------------------------------------------------------------
105 /// Sets the command string contained by this object.
107 /// The command string will be copied and split up into arguments
108 /// that can be accessed via the accessor functions.
110 /// @param[in] command
111 /// A NULL terminated command that will be copied and split up
114 /// @see Args::GetArgumentCount() const
115 /// @see Args::GetArgumentAtIndex (size_t) const
116 /// @see Args::GetArgumentVector ()
117 /// @see Args::Shift ()
118 /// @see Args::Unshift (const char *)
119 //------------------------------------------------------------------
121 SetCommandString (const char *command);
124 SetCommandString (const char *command, size_t len);
127 GetCommandString (std::string &command) const;
130 GetQuotedCommandString (std::string &command) const;
132 //------------------------------------------------------------------
133 /// Gets the number of arguments left in this command object.
136 /// The number or arguments in this object.
137 //------------------------------------------------------------------
139 GetArgumentCount () const;
141 //------------------------------------------------------------------
142 /// Gets the NULL terminated C string argument pointer for the
143 /// argument at index \a idx.
146 /// The NULL terminated C string argument pointer if \a idx is a
147 /// valid argument index, NULL otherwise.
148 //------------------------------------------------------------------
150 GetArgumentAtIndex (size_t idx) const;
153 GetArgumentQuoteCharAtIndex (size_t idx) const;
155 //------------------------------------------------------------------
156 /// Gets the argument vector.
158 /// The value returned by this function can be used by any function
159 /// that takes and vector. The return value is just like \a argv
160 /// in the standard C entry point function:
162 /// int main (int argc, const char **argv);
166 /// An array of NULL terminated C string argument pointers that
167 /// also has a terminating NULL C string pointer
168 //------------------------------------------------------------------
170 GetArgumentVector ();
172 //------------------------------------------------------------------
173 /// Gets the argument vector.
175 /// The value returned by this function can be used by any function
176 /// that takes and vector. The return value is just like \a argv
177 /// in the standard C entry point function:
179 /// int main (int argc, const char **argv);
183 /// An array of NULL terminate C string argument pointers that
184 /// also has a terminating NULL C string pointer
185 //------------------------------------------------------------------
187 GetConstArgumentVector () const;
190 //------------------------------------------------------------------
191 /// Appends a new argument to the end of the list argument list.
193 /// @param[in] arg_cstr
194 /// The new argument as a NULL terminated C string.
196 /// @param[in] quote_char
197 /// If the argument was originally quoted, put in the quote char here.
200 /// The NULL terminated C string of the copy of \a arg_cstr.
201 //------------------------------------------------------------------
203 AppendArgument (const char *arg_cstr, char quote_char = '\0');
206 AppendArguments (const Args &rhs);
209 AppendArguments (const char **argv);
211 //------------------------------------------------------------------
212 /// Insert the argument value at index \a idx to \a arg_cstr.
215 /// The index of where to insert the argument.
217 /// @param[in] arg_cstr
218 /// The new argument as a NULL terminated C string.
220 /// @param[in] quote_char
221 /// If the argument was originally quoted, put in the quote char here.
224 /// The NULL terminated C string of the copy of \a arg_cstr.
225 //------------------------------------------------------------------
227 InsertArgumentAtIndex (size_t idx, const char *arg_cstr, char quote_char = '\0');
229 //------------------------------------------------------------------
230 /// Replaces the argument value at index \a idx to \a arg_cstr
231 /// if \a idx is a valid argument index.
234 /// The index of the argument that will have its value replaced.
236 /// @param[in] arg_cstr
237 /// The new argument as a NULL terminated C string.
239 /// @param[in] quote_char
240 /// If the argument was originally quoted, put in the quote char here.
243 /// The NULL terminated C string of the copy of \a arg_cstr if
244 /// \a idx was a valid index, NULL otherwise.
245 //------------------------------------------------------------------
247 ReplaceArgumentAtIndex (size_t idx, const char *arg_cstr, char quote_char = '\0');
249 //------------------------------------------------------------------
250 /// Deletes the argument value at index
251 /// if \a idx is a valid argument index.
254 /// The index of the argument that will have its value replaced.
256 //------------------------------------------------------------------
258 DeleteArgumentAtIndex (size_t idx);
260 //------------------------------------------------------------------
261 /// Sets the argument vector value, optionally copying all
262 /// arguments into an internal buffer.
264 /// Sets the arguments to match those found in \a argv. All argument
265 /// strings will be copied into an internal buffers.
267 // FIXME: Handle the quote character somehow.
268 //------------------------------------------------------------------
270 SetArguments (size_t argc, const char **argv);
273 SetArguments (const char **argv);
275 //------------------------------------------------------------------
276 /// Shifts the first argument C string value of the array off the
279 /// The string value will be freed, so a copy of the string should
280 /// be made by calling Args::GetArgumentAtIndex (size_t) const
281 /// first and copying the returned value before calling
284 /// @see Args::GetArgumentAtIndex (size_t) const
285 //------------------------------------------------------------------
289 //------------------------------------------------------------------
290 /// Inserts a class owned copy of \a arg_cstr at the beginning of
291 /// the argument vector.
293 /// A copy \a arg_cstr will be made.
295 /// @param[in] arg_cstr
296 /// The argument to push on the front of the argument stack.
298 /// @param[in] quote_char
299 /// If the argument was originally quoted, put in the quote char here.
302 /// A pointer to the copy of \a arg_cstr that was made.
303 //------------------------------------------------------------------
305 Unshift (const char *arg_cstr, char quote_char = '\0');
307 //------------------------------------------------------------------
308 /// Parse the arguments in the contained arguments.
310 /// The arguments that are consumed by the argument parsing process
311 /// will be removed from the argument vector. The arguments that
312 /// get processed start at the second argument. The first argument
313 /// is assumed to be the command and will not be touched.
315 /// @see class Options
316 //------------------------------------------------------------------
318 ParseOptions (Options &options);
321 FindArgumentIndexForOption (Option *long_options, int long_options_index);
324 IsPositionalArgument (const char *arg);
326 // The following works almost identically to ParseOptions, except that no option is required to have arguments,
327 // and it builds up the option_arg_vector as it parses the options.
330 ParseAliasOptions (Options &options, CommandReturnObject &result, OptionArgVector *option_arg_vector,
331 std::string &raw_input_line);
334 ParseArgsForCompletion (Options &options, OptionElementVector &option_element_vector, uint32_t cursor_index);
336 //------------------------------------------------------------------
337 // Clear the arguments.
339 // For re-setting or blanking out the list of arguments.
340 //------------------------------------------------------------------
345 StripSpaces (std::string &s,
347 bool trailing = true,
348 bool return_null_if_empty = true);
351 StringToSInt32 (const char *s, int32_t fail_value = 0, int base = 0, bool *success_ptr = NULL);
354 StringToUInt32 (const char *s, uint32_t fail_value = 0, int base = 0, bool *success_ptr = NULL);
357 StringToSInt64 (const char *s, int64_t fail_value = 0, int base = 0, bool *success_ptr = NULL);
360 StringToUInt64 (const char *s, uint64_t fail_value = 0, int base = 0, bool *success_ptr = NULL);
363 UInt64ValueIsValidForByteSize (uint64_t uval64, size_t total_byte_size)
365 if (total_byte_size > 8)
368 if (total_byte_size == 8)
371 const uint64_t max = ((uint64_t)1 << (uint64_t)(total_byte_size * 8)) - 1;
372 return uval64 <= max;
376 SInt64ValueIsValidForByteSize (int64_t sval64, size_t total_byte_size)
378 if (total_byte_size > 8)
381 if (total_byte_size == 8)
384 const int64_t max = ((int64_t)1 << (uint64_t)(total_byte_size * 8 - 1)) - 1;
385 const int64_t min = ~(max);
386 return min <= sval64 && sval64 <= max;
390 StringToAddress (const ExecutionContext *exe_ctx,
392 lldb::addr_t fail_value,
396 StringToBoolean (const char *s, bool fail_value, bool *success_ptr);
399 StringToOptionEnum (const char *s, OptionEnumValueElement *enum_values, int32_t fail_value, Error &error);
401 static lldb::ScriptLanguage
402 StringToScriptLanguage (const char *s, lldb::ScriptLanguage fail_value, bool *success_ptr);
405 StringToFormat (const char *s,
406 lldb::Format &format,
407 size_t *byte_size_ptr); // If non-NULL, then a byte size can precede the format character
409 static lldb::Encoding
410 StringToEncoding (const char *s,
411 lldb::Encoding fail_value = lldb::eEncodingInvalid);
414 StringToGenericRegister (const char *s);
417 StringToVersion (const char *s, uint32_t &major, uint32_t &minor, uint32_t &update);
420 GetShellSafeArgument (const char *unsafe_arg, std::string &safe_arg);
422 // EncodeEscapeSequences will change the textual representation of common
423 // escape sequences like "\n" (two characters) into a single '\n'. It does
424 // this for all of the supported escaped sequences and for the \0ooo (octal)
425 // and \xXX (hex). The resulting "dst" string will contain the character
426 // versions of all supported escape sequences. The common supported escape
427 // sequences are: "\a", "\b", "\f", "\n", "\r", "\t", "\v", "\'", "\"", "\\".
430 EncodeEscapeSequences (const char *src, std::string &dst);
432 // ExpandEscapeSequences will change a string of possibly non-printable
433 // characters and expand them into text. So '\n' will turn into two characters
434 // like "\n" which is suitable for human reading. When a character is not
435 // printable and isn't one of the common in escape sequences listed in the
436 // help for EncodeEscapeSequences, then it will be encoded as octal. Printable
437 // characters are left alone.
439 ExpandEscapedCharacters (const char *src, std::string &dst);
441 // This one isn't really relevant to Arguments per se, but we're using the Args as a
442 // general strings container, so...
444 LongestCommonPrefix (std::string &common_prefix);
447 //------------------------------------------------------------------
448 // Classes that inherit from Args can see and modify these
449 //------------------------------------------------------------------
450 typedef std::list<std::string> arg_sstr_collection;
451 typedef std::vector<const char *> arg_cstr_collection;
452 typedef std::vector<char> arg_quote_char_collection;
453 arg_sstr_collection m_args;
454 arg_cstr_collection m_argv; ///< The current argument vector.
455 arg_quote_char_collection m_args_quote_char;
458 UpdateArgsAfterOptionParsing ();
461 UpdateArgvFromArgs ();
464 } // namespace lldb_private
466 #endif // liblldb_Command_h_