gdb/cli/cli-utils.h

   1 /* CLI utilities.
   2
   3    Copyright (C) 2011-2018 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_UTILS_H
  21 #define CLI_UTILS_H
  22
  23 /* *PP is a string denoting a number.  Get the number.  Advance *PP
  24    after the string and any trailing whitespace.
  25
  26    The string can either be a number, or "$" followed by the name of a
  27    convenience variable, or ("$" or "$$") followed by digits.
  28
  29    TRAILER is a character which can be found after the number; most
  30    commonly this is `-'.  If you don't want a trailer, use \0.  */
  31
  32 extern int get_number_trailer (const char **pp, int trailer);
  33
  34 /* Convenience.  Like get_number_trailer, but with no TRAILER.  */
  35
  36 extern int get_number (const char **);
  37
  38 /* Like the above, but takes a non-const "char **".  */
  39
  40 extern int get_number (char **);
  41
  42 /* Parse a number or a range.
  43    A number will be of the form handled by get_number.
  44    A range will be of the form <number1> - <number2>, and
  45    will represent all the integers between number1 and number2,
  46    inclusive.  */
  47
  48 class number_or_range_parser
  49 {
  50 public:
  51   /* Default construction.  Must call init before calling
  52      get_next.  */
  53   number_or_range_parser () {}
  54
  55   /* Calls init automatically.  */
  56   number_or_range_parser (const char *string);
  57
  58   /* STRING is the string to be parsed.  */
  59   void init (const char *string);
  60
  61   /* While processing a range, this fuction is called iteratively; At
  62      each call it will return the next value in the range.
  63
  64      At the beginning of parsing a range, the char pointer
  65      STATE->m_cur_tok will be advanced past <number1> and left
  66      pointing at the '-' token.  Subsequent calls will not advance the
  67      pointer until the range is completed.  The call that completes
  68      the range will advance the pointer past <number2>.  */
  69   int get_number ();
  70
  71   /* Setup internal state such that get_next() returns numbers in the
  72      START_VALUE to END_VALUE range.  END_PTR is where the string is
  73      advanced to when get_next() returns END_VALUE.  */
  74   void setup_range (int start_value, int end_value,
  75                     const char *end_ptr);
  76
  77   /* Returns true if parsing has completed.  */
  78   bool finished () const;
  79
  80   /* Return the string being parsed.  When parsing has finished, this
  81      points past the last parsed token.  */
  82   const char *cur_tok () const
  83   { return m_cur_tok; }
  84
  85   /* True when parsing a range.  */
  86   bool in_range () const
  87   { return m_in_range; }
  88
  89   /* When parsing a range, the final value in the range.  */
  90   int end_value () const
  91   { return m_end_value; }
  92
  93   /* When parsing a range, skip past the final token in the range.  */
  94   void skip_range ()
  95   {
  96     gdb_assert (m_in_range);
  97     m_cur_tok = m_end_ptr;
  98     m_in_range = false;
  99   }
 100
 101 private:
 102   /* No need for these.  They are intentionally not defined anywhere.  */
 103   number_or_range_parser (const number_or_range_parser &);
 104   number_or_range_parser &operator= (const number_or_range_parser &);
 105
 106   /* The string being parsed.  When parsing has finished, this points
 107      past the last parsed token.  */
 108   const char *m_cur_tok;
 109
 110   /* Last value returned.  */
 111   int m_last_retval;
 112
 113   /* When parsing a range, the final value in the range.  */
 114   int m_end_value;
 115
 116   /* When parsing a range, a pointer past the final token in the
 117      range.  */
 118   const char *m_end_ptr;
 119
 120   /* True when parsing a range.  */
 121   bool m_in_range;
 122 };
 123
 124 /* Accept a number and a string-form list of numbers such as is
 125    accepted by get_number_or_range.  Return TRUE if the number is
 126    in the list.
 127
 128    By definition, an empty list includes all numbers.  This is to
 129    be interpreted as typing a command such as "delete break" with
 130    no arguments.  */
 131
 132 extern int number_is_in_list (const char *list, int number);
 133
 134 /* Reverse S to the last non-whitespace character without skipping past
 135    START.  */
 136
 137 extern const char *remove_trailing_whitespace (const char *start,
 138                                                const char *s);
 139
 140 /* Same, for non-const S.  */
 141
 142 static inline char *
 143 remove_trailing_whitespace (const char *start, char *s)
 144 {
 145   return (char *) remove_trailing_whitespace (start, (const char *) s);
 146 }
 147
 148 /* A helper function to extract an argument from *ARG.  An argument is
 149    delimited by whitespace.  The return value is empty if no argument
 150    was found.  */
 151
 152 extern std::string extract_arg (char **arg);
 153
 154 /* A const-correct version of the above.  */
 155
 156 extern std::string extract_arg (const char **arg);
 157
 158 /* A helper function that looks for an argument at the start of a
 159    string.  The argument must also either be at the end of the string,
 160    or be followed by whitespace.  Returns 1 if it finds the argument,
 161    0 otherwise.  If the argument is found, it updates *STR.  */
 162 extern int check_for_argument (const char **str, const char *arg, int arg_len);
 163
 164 /* Same, for non-const STR.  */
 165
 166 static inline int
 167 check_for_argument (char **str, const char *arg, int arg_len)
 168 {
 169   return check_for_argument (const_cast<const char **> (str),
 170                              arg, arg_len);
 171 }
 172
 173 /* A helper function that looks for a set of flags at the start of a
 174    string.  The possible flags are given as a null terminated string.
 175    A flag in STR must either be at the end of the string,
 176    or be followed by whitespace.
 177    Returns 0 if no valid flag is found at the start of STR.
 178    Otherwise updates *STR, and returns N (which is > 0),
 179    such that FLAGS [N - 1] is the valid found flag.  */
 180 extern int parse_flags (const char **str, const char *flags);
 181
 182 /* qcs_flags struct regroups the flags parsed by parse_flags_qcs.  */
 183
 184 struct qcs_flags
 185 {
 186   bool quiet = false;
 187   bool cont = false;
 188   bool silent = false;
 189 };
 190
 191 /* A helper function that uses parse_flags to handle the flags qcs :
 192      A flag -q sets FLAGS->QUIET to true.
 193      A flag -c sets FLAGS->CONT to true.
 194      A flag -s sets FLAGS->SILENT to true.
 195
 196    The caller is responsible to initialize *FLAGS to false before the (first)
 197    call to parse_flags_qcs.
 198    parse_flags_qcs can then be called iteratively to search for more
 199    valid flags, as part of a 'main parsing loop' searching for -q/-c/-s
 200    flags together with other flags and options.
 201
 202    Returns true and updates *STR and one of FLAGS->QUIET, FLAGS->CONT,
 203    FLAGS->SILENT if it finds a valid flag.
 204    Returns false if no valid flag is found at the beginning of STR.
 205
 206    Throws an error if a flag is found such that both FLAGS->CONT and
 207    FLAGS->SILENT are true.  */
 208
 209 extern bool parse_flags_qcs (const char *which_command, const char **str,
 210                              qcs_flags *flags);
 211 #endif /* CLI_UTILS_H */