gcc/substring-locations.h

   1 /* Source locations within string literals.
   2    Copyright (C) 2016-2018 Free Software Foundation, Inc.
   3
   4 This file is part of GCC.
   5
   6 GCC is free software; you can redistribute it and/or modify it under
   7 the terms of the GNU General Public License as published by the Free
   8 Software Foundation; either version 3, or (at your option) any later
   9 version.
  10
  11 GCC is distributed in the hope that it will be useful, but WITHOUT ANY
  12 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14 for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GCC; see the file COPYING3.  If not see
  18 <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef GCC_SUBSTRING_LOCATIONS_H
  21 #define GCC_SUBSTRING_LOCATIONS_H
  22
  23 /* The substring_loc class encapsulates information on the source location
  24    of a range of characters within a STRING_CST.
  25
  26    If needed by a diagnostic, the actual location_t of the substring_loc
  27    can be calculated by calling its get_location method.  This calls a
  28    langhook, since this is inherently frontend-specific.  For the C family
  29    of frontends, it calls back into libcpp to reparse the strings.  This
  30    gets the location information "on demand", rather than storing the
  31    location information in the initial lex for every string.  Thus the
  32    substring_loc can also be thought of as a deferred call into libcpp,
  33    to allow the non-trivial work of reparsing the string to be delayed
  34    until we actually need it (to emit a diagnostic for a particular range
  35    of characters).
  36
  37    substring_loc::get_location returns NULL if it succeeds, or an
  38    error message if it fails.  Error messages are intended for GCC
  39    developers (to help debugging) rather than for end-users.
  40
  41    The easiest way to use a substring_loc is via the format_warning_* APIs,
  42    which gracefully handle failure of substring_loc::get_location by using
  43    the location of the string as a whole if substring-information is
  44    unavailable.  */
  45
  46 class substring_loc
  47 {
  48  public:
  49   /* Constructor.  FMT_STRING_LOC is the location of the string as
  50      a whole.  STRING_TYPE is the type of the string.  It should be an
  51      ARRAY_TYPE of INTEGER_TYPE, or a POINTER_TYPE to such an ARRAY_TYPE.
  52      CARET_IDX, START_IDX, and END_IDX are offsets from the start
  53      of the string data.  */
  54   substring_loc (location_t fmt_string_loc, tree string_type,
  55                  int caret_idx, int start_idx, int end_idx)
  56   : m_fmt_string_loc (fmt_string_loc), m_string_type (string_type),
  57     m_caret_idx (caret_idx), m_start_idx (start_idx), m_end_idx (end_idx) {}
  58
  59   void set_caret_index (int caret_idx) { m_caret_idx = caret_idx; }
  60
  61   const char *get_location (location_t *out_loc) const;
  62
  63   location_t get_fmt_string_loc () const { return m_fmt_string_loc; }
  64   tree get_string_type () const { return m_string_type; }
  65   int get_caret_idx () const { return m_caret_idx; }
  66   int get_start_idx () const { return m_start_idx; }
  67   int get_end_idx () const { return m_end_idx; }
  68
  69  private:
  70   location_t m_fmt_string_loc;
  71   tree m_string_type;
  72   int m_caret_idx;
  73   int m_start_idx;
  74   int m_end_idx;
  75 };
  76
  77 /* Functions for emitting a warning about a format string.  */
  78
  79 extern bool format_warning_va (const substring_loc &fmt_loc,
  80                                const range_label *fmt_label,
  81                                location_t param_loc,
  82                                const range_label *param_label,
  83                                const char *corrected_substring,
  84                                int opt, const char *gmsgid, va_list *ap)
  85   ATTRIBUTE_GCC_DIAG (7, 0);
  86
  87 extern bool format_warning_n_va (const substring_loc &fmt_loc,
  88                                  const range_label *fmt_label,
  89                                  location_t param_loc,
  90                                  const range_label *param_label,
  91                                  const char *corrected_substring,
  92                                  int opt, unsigned HOST_WIDE_INT n,
  93                                  const char *singular_gmsgid,
  94                                  const char *plural_gmsgid, va_list *ap)
  95   ATTRIBUTE_GCC_DIAG (8, 0) ATTRIBUTE_GCC_DIAG (9, 0);
  96
  97 extern bool format_warning_at_substring (const substring_loc &fmt_loc,
  98                                          const range_label *fmt_label,
  99                                          location_t param_loc,
 100                                          const range_label *param_label,
 101                                          const char *corrected_substring,
 102                                          int opt, const char *gmsgid, ...)
 103   ATTRIBUTE_GCC_DIAG (7, 8);
 104
 105 extern bool format_warning_at_substring_n (const substring_loc &fmt_loc,
 106                                            const range_label *fmt_label,
 107                                            location_t param_loc,
 108                                            const range_label *param_label,
 109                                            const char *corrected_substring,
 110                                            int opt, unsigned HOST_WIDE_INT n,
 111                                            const char *singular_gmsgid,
 112                                            const char *plural_gmsgid, ...)
 113   ATTRIBUTE_GCC_DIAG (8, 10) ATTRIBUTE_GCC_DIAG (9, 10);
 114
 115 /* Implementation detail, for use when implementing
 116    LANG_HOOKS_GET_SUBSTRING_LOCATION.  */
 117
 118 extern const char *get_source_location_for_substring (cpp_reader *pfile,
 119                                                       string_concat_db *concats,
 120                                                       location_t strloc,
 121                                                       enum cpp_ttype type,
 122                                                       int caret_idx,
 123                                                       int start_idx, int end_idx,
 124                                                       location_t *out_loc);
 125
 126 #endif /* ! GCC_SUBSTRING_LOCATIONS_H */