gdb/cli/cli-utils.h

   1 /* CLI utilities.
   2
   3    Copyright (C) 2011-2019 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef CLI_CLI_UTILS_H
  21 #define CLI_CLI_UTILS_H
  22
  23 #include "completer.h"
  24
  25 struct cmd_list_element;
  26
  27 /* *PP is a string denoting a number.  Get the number.  Advance *PP
  28    after the string and any trailing whitespace.
  29
  30    The string can either be a number, or "$" followed by the name of a
  31    convenience variable, or ("$" or "$$") followed by digits.
  32
  33    TRAILER is a character which can be found after the number; most
  34    commonly this is `-'.  If you don't want a trailer, use \0.  */
  35
  36 extern int get_number_trailer (const char **pp, int trailer);
  37
  38 /* Convenience.  Like get_number_trailer, but with no TRAILER.  */
  39
  40 extern int get_number (const char **);
  41
  42 /* Like the above, but takes a non-const "char **".  */
  43
  44 extern int get_number (char **);
  45
  46 /* Like get_number_trailer, but works with ULONGEST, and throws on
  47    error instead of returning 0.  */
  48 extern ULONGEST get_ulongest (const char **pp, int trailer = '\0');
  49
  50 /* Structure to hold the values of the options used by the 'info
  51    variables' command and other similar commands.  These correspond to the
  52    -q and -t options.  */
  53
  54 struct info_print_options
  55 {
  56   int quiet = false;
  57   char *type_regexp = nullptr;
  58
  59   ~info_print_options ()
  60   {
  61     xfree (type_regexp);
  62   }
  63 };
  64
  65 /* Extract options from ARGS for commands like 'info variables', placing
  66    the options into OPTS.  ARGS is updated to point to the first character
  67    after the options, or, if there is nothing after the options, then ARGS
  68    is set to nullptr.  */
  69
  70 extern void extract_info_print_options (info_print_options *opts,
  71                                         const char **args);
  72
  73 /* Function that can be used as a command completer for 'info variable'
  74    and friends.  This offers command option completion as well as symbol
  75    completion.  At the moment all symbols are offered for all commands.  */
  76
  77 extern void info_print_command_completer (struct cmd_list_element *ignore,
  78                                           completion_tracker &tracker,
  79                                           const char *text,
  80                                           const char * /* word */);
  81
  82 /* Throws an error telling the user that ARGS starts with an option
  83    unrecognized by COMMAND.  */
  84
  85 extern void report_unrecognized_option_error (const char *command,
  86                                               const char *args);
  87
  88
  89 /* Builds the help string for a command documented by PREFIX,
  90    followed by the extract_info_print_args help for ENTITY_KIND.  */
  91
  92 const char *info_print_args_help (const char *prefix,
  93                                   const char *entity_kind);
  94
  95 /* Parse a number or a range.
  96    A number will be of the form handled by get_number.
  97    A range will be of the form <number1> - <number2>, and
  98    will represent all the integers between number1 and number2,
  99    inclusive.  */
 100
 101 class number_or_range_parser
 102 {
 103 public:
 104   /* Default construction.  Must call init before calling
 105      get_next.  */
 106   number_or_range_parser () {}
 107
 108   /* Calls init automatically.  */
 109   number_or_range_parser (const char *string);
 110
 111   /* STRING is the string to be parsed.  */
 112   void init (const char *string);
 113
 114   /* While processing a range, this fuction is called iteratively; At
 115      each call it will return the next value in the range.
 116
 117      At the beginning of parsing a range, the char pointer
 118      STATE->m_cur_tok will be advanced past <number1> and left
 119      pointing at the '-' token.  Subsequent calls will not advance the
 120      pointer until the range is completed.  The call that completes
 121      the range will advance the pointer past <number2>.  */
 122   int get_number ();
 123
 124   /* Setup internal state such that get_next() returns numbers in the
 125      START_VALUE to END_VALUE range.  END_PTR is where the string is
 126      advanced to when get_next() returns END_VALUE.  */
 127   void setup_range (int start_value, int end_value,
 128                     const char *end_ptr);
 129
 130   /* Returns true if parsing has completed.  */
 131   bool finished () const;
 132
 133   /* Return the string being parsed.  When parsing has finished, this
 134      points past the last parsed token.  */
 135   const char *cur_tok () const
 136   { return m_cur_tok; }
 137
 138   /* True when parsing a range.  */
 139   bool in_range () const
 140   { return m_in_range; }
 141
 142   /* When parsing a range, the final value in the range.  */
 143   int end_value () const
 144   { return m_end_value; }
 145
 146   /* When parsing a range, skip past the final token in the range.  */
 147   void skip_range ()
 148   {
 149     gdb_assert (m_in_range);
 150     m_cur_tok = m_end_ptr;
 151     m_in_range = false;
 152   }
 153
 154 private:
 155   /* No need for these.  They are intentionally not defined anywhere.  */
 156   number_or_range_parser (const number_or_range_parser &);
 157   number_or_range_parser &operator= (const number_or_range_parser &);
 158
 159   /* The string being parsed.  When parsing has finished, this points
 160      past the last parsed token.  */
 161   const char *m_cur_tok;
 162
 163   /* Last value returned.  */
 164   int m_last_retval;
 165
 166   /* When parsing a range, the final value in the range.  */
 167   int m_end_value;
 168
 169   /* When parsing a range, a pointer past the final token in the
 170      range.  */
 171   const char *m_end_ptr;
 172
 173   /* True when parsing a range.  */
 174   bool m_in_range;
 175 };
 176
 177 /* Accept a number and a string-form list of numbers such as is
 178    accepted by get_number_or_range.  Return TRUE if the number is
 179    in the list.
 180
 181    By definition, an empty list includes all numbers.  This is to
 182    be interpreted as typing a command such as "delete break" with
 183    no arguments.  */
 184
 185 extern int number_is_in_list (const char *list, int number);
 186
 187 /* Reverse S to the last non-whitespace character without skipping past
 188    START.  */
 189
 190 extern const char *remove_trailing_whitespace (const char *start,
 191                                                const char *s);
 192
 193 /* Same, for non-const S.  */
 194
 195 static inline char *
 196 remove_trailing_whitespace (const char *start, char *s)
 197 {
 198   return (char *) remove_trailing_whitespace (start, (const char *) s);
 199 }
 200
 201 /* A helper function to extract an argument from *ARG.  An argument is
 202    delimited by whitespace.  The return value is empty if no argument
 203    was found.  */
 204
 205 extern std::string extract_arg (char **arg);
 206
 207 /* A const-correct version of the above.  */
 208
 209 extern std::string extract_arg (const char **arg);
 210
 211 /* A helper function that looks for an argument at the start of a
 212    string.  The argument must also either be at the end of the string,
 213    or be followed by whitespace.  Returns 1 if it finds the argument,
 214    0 otherwise.  If the argument is found, it updates *STR to point
 215    past the argument and past any whitespace following the
 216    argument.  */
 217 extern int check_for_argument (const char **str, const char *arg, int arg_len);
 218
 219 /* Same as above, but ARG's length is computed.  */
 220
 221 static inline int
 222 check_for_argument (const char **str, const char *arg)
 223 {
 224   return check_for_argument (str, arg, strlen (arg));
 225 }
 226
 227 /* Same, for non-const STR.  */
 228
 229 static inline int
 230 check_for_argument (char **str, const char *arg, int arg_len)
 231 {
 232   return check_for_argument (const_cast<const char **> (str),
 233                              arg, arg_len);
 234 }
 235
 236 static inline int
 237 check_for_argument (char **str, const char *arg)
 238 {
 239   return check_for_argument (str, arg, strlen (arg));
 240 }
 241
 242 /* qcs_flags struct groups the -q, -c, and -s flags parsed by "thread
 243    apply" and "frame apply" commands */
 244
 245 struct qcs_flags
 246 {
 247   int quiet = false;
 248   int cont = false;
 249   int silent = false;
 250 };
 251
 252 /* Validate FLAGS.  Throws an error if both FLAGS->CONT and
 253    FLAGS->SILENT are true.  WHICH_COMMAND is included in the error
 254    message.  */
 255 extern void validate_flags_qcs (const char *which_command, qcs_flags *flags);
 256
 257 #endif /* CLI_CLI_UTILS_H */