gdb/linespec.h

   1 /* Header for GDB line completion.
   2    Copyright (C) 2000, 2007, 2008, 2009, 2010, 2011
   3    Free Software Foundation, Inc.
   4
   5    This program is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  17
  18 #if !defined (LINESPEC_H)
  19 #define LINESPEC_H 1
  20
  21 struct symtab;
  22
  23 #include "vec.h"
  24
  25 /* Flags to pass to decode_line_1 and decode_line_full.  */
  26
  27 enum decode_line_flags
  28   {
  29     /* Set this flag if you want the resulting SALs to describe the
  30        first line of indicated functions.  */
  31     DECODE_LINE_FUNFIRSTLINE = 1,
  32
  33     /* Set this flag if you want "list mode".  In this mode, a
  34        FILE:LINE linespec will always return a result, and such
  35        linespecs will not be expanded to all matches.  */
  36     DECODE_LINE_LIST_MODE = 2
  37   };
  38
  39 /* decode_line_full returns a vector of these.  */
  40
  41 struct linespec_sals
  42 {
  43   /* This is the linespec corresponding to the sals contained in this
  44      object.  It can be passed as the FILTER argument to future calls
  45      to decode_line_full.  This is freed by
  46      destroy_linespec_result.  */
  47   char *canonical;
  48
  49   /* Sals.  The 'sals' field is destroyed by
  50      destroy_linespec_result.  */
  51   struct symtabs_and_lines sals;
  52 };
  53
  54 typedef struct linespec_sals linespec_sals;
  55 DEF_VEC_O (linespec_sals);
  56
  57 /* An instance of this may be filled in by decode_line_1.  The caller
  58    must call init_linespec_result to initialize it and
  59    destroy_linespec_result to destroy it.  The caller must make copies
  60    of any data that it needs to keep.  */
  61
  62 struct linespec_result
  63 {
  64   /* If non-zero, the linespec should be displayed to the user.  This
  65      is used by "unusual" linespecs where the ordinary `info break'
  66      display mechanism would do the wrong thing.  */
  67   int special_display;
  68
  69   /* If non-zero, the linespec result should be considered to be a
  70      "pre-expanded" multi-location linespec.  A pre-expanded linespec
  71      holds all matching locations in a single linespec_sals
  72      object.  */
  73   int pre_expanded;
  74
  75   /* If PRE_EXPANDED is non-zero, this is set to the linespec entered
  76      by the user.  This will be freed by destroy_linespec_result.  */
  77   char *addr_string;
  78
  79   /* The sals.  The vector will be freed by
  80      destroy_linespec_result.  */
  81   VEC (linespec_sals) *sals;
  82 };
  83
  84 /* Initialize a linespec_result.  */
  85
  86 extern void init_linespec_result (struct linespec_result *);
  87
  88 /* Destroy a linespec_result.  */
  89
  90 extern void destroy_linespec_result (struct linespec_result *);
  91
  92 /* Return a cleanup that destroys a linespec_result.  */
  93
  94 extern struct cleanup *
  95         make_cleanup_destroy_linespec_result (struct linespec_result *);
  96
  97 extern struct symtabs_and_lines
  98         decode_line_1 (char **argptr, int flags,
  99                        struct symtab *default_symtab, int default_line);
 100
 101 /* Parse *ARGPTR as a linespec and return results.  This is the "full"
 102    interface to this module, which handles multiple results
 103    properly.
 104
 105    For FLAGS, see decode_line_flags.  DECODE_LINE_LIST_MODE is not
 106    valid for this function.
 107
 108    DEFAULT_SYMTAB and DEFAULT_LINE describe the default location.
 109    DEFAULT_SYMTAB can be NULL, in which case the current symtab and
 110    line are used.
 111
 112    CANONICAL is where the results are stored.  It must not be NULL.
 113
 114    SELECT_MODE must be one of the multiple_symbols_* constants, or
 115    NULL.  It determines how multiple results will be handled.  If
 116    NULL, the appropriate CLI value will be used.
 117
 118    FILTER can either be NULL or a string holding a canonical name.
 119    This is only valid when SELECT_MODE is multiple_symbols_all.
 120
 121    Multiple results are handled differently depending on the
 122    arguments:
 123
 124    . With multiple_symbols_cancel, an exception is thrown.
 125
 126    . With multiple_symbols_ask, a menu is presented to the user.  The
 127    user may select none, in which case an exception is thrown; or all,
 128    which is handled like multiple_symbols_all, below.  Otherwise,
 129    CANONICAL->SALS will have one entry for each name the user chose.
 130
 131    . With multiple_symbols_all, CANONICAL->SALS will have a single
 132    entry describing all the matching locations.  If FILTER is
 133    non-NULL, then only locations whose canonical name is equal (in the
 134    strcmp sense) to FILTER will be returned; all others will be
 135    filtered out.  */
 136
 137 extern void decode_line_full (char **argptr, int flags,
 138                               struct symtab *default_symtab, int default_line,
 139                               struct linespec_result *canonical,
 140                               const char *select_mode,
 141                               const char *filter);
 142
 143 #endif /* defined (LINESPEC_H) */