gdb/macroexp.h

   1 /* Interface to C preprocessor macro expansion for GDB.
   2    Copyright (C) 2002-2024 Free Software Foundation, Inc.
   3    Contributed by Red Hat, 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
  21 #ifndef MACROEXP_H
  22 #define MACROEXP_H
  23
  24 struct macro_scope;
  25
  26 /* Expand any preprocessor macros in SOURCE (a null-terminated string), and
  27    return the expanded text.
  28
  29    Use SCOPE to find identifiers' preprocessor definitions.
  30
  31    The result is a null-terminated string.  */
  32 gdb::unique_xmalloc_ptr<char> macro_expand (const char *source,
  33                                             const macro_scope &scope);
  34
  35 /* Expand all preprocessor macro references that appear explicitly in SOURCE
  36    (a null-terminated string), but do not expand any new macro references
  37    introduced by that first level of expansion.
  38
  39    Use SCOPE to find identifiers' preprocessor definitions.
  40
  41    The result is a null-terminated string.  */
  42 gdb::unique_xmalloc_ptr<char> macro_expand_once (const char *source,
  43                                                  const macro_scope &scope);
  44
  45 /* If the null-terminated string pointed to by *LEXPTR begins with a
  46    macro invocation, return the result of expanding that invocation as
  47    a null-terminated string, and set *LEXPTR to the next character
  48    after the invocation.  The result is completely expanded; it
  49    contains no further macro invocations.
  50
  51    Otherwise, if *LEXPTR does not start with a macro invocation,
  52    return nullptr, and leave *LEXPTR unchanged.
  53
  54    Use SCOPE to find macro definitions.
  55
  56    If this function returns a string, the caller is responsible for
  57    freeing it, using xfree.
  58
  59    We need this expand-one-token-at-a-time interface in order to
  60    accommodate GDB's C expression parser, which may not consume the
  61    entire string.  When the user enters a command like
  62
  63       (gdb) break *func+20 if x == 5
  64
  65    the parser is expected to consume `func+20', and then stop when it
  66    sees the "if".  But of course, "if" appearing in a character string
  67    or as part of a larger identifier doesn't count.  So you pretty
  68    much have to do tokenization to find the end of the string that
  69    needs to be macro-expanded.  Our C/C++ tokenizer isn't really
  70    designed to be called by anything but the yacc parser engine.  */
  71 gdb::unique_xmalloc_ptr<char> macro_expand_next (const char **lexptr,
  72                                                  const macro_scope &scope);
  73
  74 /* Functions to classify characters according to cpp rules.  */
  75
  76 int macro_is_whitespace (int c);
  77 int macro_is_identifier_nondigit (int c);
  78 int macro_is_digit (int c);
  79
  80
  81 /* Stringify STR according to C rules and return a null-terminated string.  */
  82 gdb::unique_xmalloc_ptr<char> macro_stringify (const char *str);
  83
  84 #endif /* MACROEXP_H */