gdb/language.h

   1 /* Source-language-related definitions for GDB.
   2
   3    Copyright (C) 1991-2017 Free Software Foundation, Inc.
   4
   5    Contributed by the Department of Computer Science at the State University
   6    of New York at Buffalo.
   7
   8    This file is part of GDB.
   9
  10    This program is free software; you can redistribute it and/or modify
  11    it under the terms of the GNU General Public License as published by
  12    the Free Software Foundation; either version 3 of the License, or
  13    (at your option) any later version.
  14
  15    This program is distributed in the hope that it will be useful,
  16    but WITHOUT ANY WARRANTY; without even the implied warranty of
  17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18    GNU General Public License for more details.
  19
  20    You should have received a copy of the GNU General Public License
  21    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  22
  23 #if !defined (LANGUAGE_H)
  24 #define LANGUAGE_H 1
  25
  26 #include "symtab.h"
  27 #include "common/function-view.h"
  28
  29 /* Forward decls for prototypes.  */
  30 struct value;
  31 struct objfile;
  32 struct frame_info;
  33 struct expression;
  34 struct ui_file;
  35 struct value_print_options;
  36 struct type_print_options;
  37 struct lang_varobj_ops;
  38 struct parser_state;
  39 struct compile_instance;
  40
  41 #define MAX_FORTRAN_DIMS  7     /* Maximum number of F77 array dims.  */
  42
  43 /* range_mode ==
  44    range_mode_auto:   range_check set automatically to default of language.
  45    range_mode_manual: range_check set manually by user.  */
  46
  47 extern enum range_mode
  48   {
  49     range_mode_auto, range_mode_manual
  50   }
  51 range_mode;
  52
  53 /* range_check ==
  54    range_check_on:    Ranges are checked in GDB expressions, producing errors.
  55    range_check_warn:  Ranges are checked, producing warnings.
  56    range_check_off:   Ranges are not checked in GDB expressions.  */
  57
  58 extern enum range_check
  59   {
  60     range_check_off, range_check_warn, range_check_on
  61   }
  62 range_check;
  63
  64 /* case_mode ==
  65    case_mode_auto:   case_sensitivity set upon selection of scope.
  66    case_mode_manual: case_sensitivity set only by user.  */
  67
  68 extern enum case_mode
  69   {
  70     case_mode_auto, case_mode_manual
  71   }
  72 case_mode;
  73
  74 /* array_ordering ==
  75    array_row_major:     Arrays are in row major order.
  76    array_column_major:  Arrays are in column major order.  */
  77
  78 extern enum array_ordering
  79   {
  80     array_row_major, array_column_major
  81   }
  82 array_ordering;
  83
  84
  85 /* case_sensitivity ==
  86    case_sensitive_on:   Case sensitivity in name matching is used.
  87    case_sensitive_off:  Case sensitivity in name matching is not used.  */
  88
  89 extern enum case_sensitivity
  90   {
  91     case_sensitive_on, case_sensitive_off
  92   }
  93 case_sensitivity;
  94
  95
  96 /* macro_expansion ==
  97    macro_expansion_no:  No macro expansion is available.
  98    macro_expansion_c:   C-like macro expansion is available.  */
  99
 100 enum macro_expansion
 101   {
 102     macro_expansion_no, macro_expansion_c
 103   };
 104
 105 \f
 106 /* Per architecture (OS/ABI) language information.  */
 107
 108 struct language_arch_info
 109 {
 110   /* Its primitive types.  This is a vector ended by a NULL pointer.
 111      These types can be specified by name in parsing types in
 112      expressions, regardless of whether the program being debugged
 113      actually defines such a type.  */
 114   struct type **primitive_type_vector;
 115
 116   /* Symbol wrappers around primitive_type_vector, so that the symbol lookup
 117      machinery can return them.  */
 118   struct symbol **primitive_type_symbols;
 119
 120   /* Type of elements of strings.  */
 121   struct type *string_char_type;
 122
 123   /* Symbol name of type to use as boolean type, if defined.  */
 124   const char *bool_type_symbol;
 125   /* Otherwise, this is the default boolean builtin type.  */
 126   struct type *bool_type_default;
 127 };
 128
 129 /* A pointer to a function expected to return nonzero if
 130    SYMBOL_SEARCH_NAME matches the given LOOKUP_NAME.
 131
 132    SYMBOL_SEARCH_NAME should be a symbol's "search" name.
 133    LOOKUP_NAME should be the name of an entity after it has been
 134    transformed for lookup.  */
 135
 136 typedef int (*symbol_name_cmp_ftype) (const char *symbol_search_name,
 137                                           const char *lookup_name);
 138
 139 /* Structure tying together assorted information about a language.  */
 140
 141 struct language_defn
 142   {
 143     /* Name of the language.  */
 144
 145     const char *la_name;
 146
 147     /* Natural or official name of the language.  */
 148
 149     const char *la_natural_name;
 150
 151     /* its symtab language-enum (defs.h).  */
 152
 153     enum language la_language;
 154
 155     /* Default range checking.  */
 156
 157     enum range_check la_range_check;
 158
 159     /* Default case sensitivity.  */
 160     enum case_sensitivity la_case_sensitivity;
 161
 162     /* Multi-dimensional array ordering.  */
 163     enum array_ordering la_array_ordering;
 164
 165     /* Style of macro expansion, if any, supported by this language.  */
 166     enum macro_expansion la_macro_expansion;
 167
 168     /* A NULL-terminated array of file extensions for this language.
 169        The extension must include the ".", like ".c".  If this
 170        language doesn't need to provide any filename extensions, this
 171        may be NULL.  */
 172
 173     const char *const *la_filename_extensions;
 174
 175     /* Definitions related to expression printing, prefixifying, and
 176        dumping.  */
 177
 178     const struct exp_descriptor *la_exp_desc;
 179
 180     /* Parser function.  */
 181
 182     int (*la_parser) (struct parser_state *);
 183
 184     /* Parser error function.  */
 185
 186     void (*la_error) (const char *);
 187
 188     /* Given an expression *EXPP created by prefixifying the result of
 189        la_parser, perform any remaining processing necessary to complete
 190        its translation.  *EXPP may change; la_post_parser is responsible
 191        for releasing its previous contents, if necessary.  If
 192        VOID_CONTEXT_P, then no value is expected from the expression.  */
 193
 194     void (*la_post_parser) (struct expression ** expp, int void_context_p);
 195
 196     void (*la_printchar) (int ch, struct type *chtype,
 197                           struct ui_file * stream);
 198
 199     void (*la_printstr) (struct ui_file * stream, struct type *elttype,
 200                          const gdb_byte *string, unsigned int length,
 201                          const char *encoding, int force_ellipses,
 202                          const struct value_print_options *);
 203
 204     void (*la_emitchar) (int ch, struct type *chtype,
 205                          struct ui_file * stream, int quoter);
 206
 207     /* Print a type using syntax appropriate for this language.  */
 208
 209     void (*la_print_type) (struct type *, const char *, struct ui_file *, int,
 210                            int, const struct type_print_options *);
 211
 212     /* Print a typedef using syntax appropriate for this language.
 213        TYPE is the underlying type.  NEW_SYMBOL is the symbol naming
 214        the type.  STREAM is the output stream on which to print.  */
 215
 216     void (*la_print_typedef) (struct type *type, struct symbol *new_symbol,
 217                               struct ui_file *stream);
 218
 219     /* Print a value using syntax appropriate for this language.
 220
 221        TYPE is the type of the sub-object to be printed.
 222
 223        EMBEDDED_OFFSET is the offset into the outermost object of the
 224        sub-object represented by TYPE.  This is the object which this
 225        call should print.  Note that the enclosing type is not
 226        available.
 227
 228        ADDRESS is the address in the inferior of the enclosing object.
 229
 230        STREAM is the stream on which the value is to be printed.
 231
 232        RECURSE is the recursion depth.  It is zero-based.
 233
 234        OPTIONS are the formatting options to be used when
 235        printing.  */
 236
 237     void (*la_val_print) (struct type *type,
 238                           int embedded_offset, CORE_ADDR address,
 239                           struct ui_file *stream, int recurse,
 240                           struct value *val,
 241                           const struct value_print_options *options);
 242
 243     /* Print a top-level value using syntax appropriate for this language.  */
 244
 245     void (*la_value_print) (struct value *, struct ui_file *,
 246                             const struct value_print_options *);
 247
 248     /* Given a symbol VAR, the corresponding block VAR_BLOCK (if any) and a
 249        stack frame id FRAME, read the value of the variable and return (pointer
 250        to a) struct value containing the value.
 251
 252        VAR_BLOCK is needed if there's a possibility for VAR to be outside
 253        FRAME.  This is what happens if FRAME correspond to a nested function
 254        and VAR is defined in the outer function.  If callers know that VAR is
 255        located in FRAME or is global/static, NULL can be passed as VAR_BLOCK.
 256
 257        Throw an error if the variable cannot be found.  */
 258
 259     struct value *(*la_read_var_value) (struct symbol *var,
 260                                         const struct block *var_block,
 261                                         struct frame_info *frame);
 262
 263     /* PC is possibly an unknown languages trampoline.
 264        If that PC falls in a trampoline belonging to this language,
 265        return the address of the first pc in the real function, or 0
 266        if it isn't a language tramp for this language.  */
 267     CORE_ADDR (*skip_trampoline) (struct frame_info *, CORE_ADDR);
 268
 269     /* Now come some hooks for lookup_symbol.  */
 270
 271     /* If this is non-NULL, specifies the name that of the implicit
 272        local variable that refers to the current object instance.  */
 273
 274     const char *la_name_of_this;
 275
 276     /* This is a function that lookup_symbol will call when it gets to
 277        the part of symbol lookup where C looks up static and global
 278        variables.  */
 279
 280     struct block_symbol (*la_lookup_symbol_nonlocal)
 281       (const struct language_defn *,
 282        const char *,
 283        const struct block *,
 284        const domain_enum);
 285
 286     /* Find the definition of the type with the given name.  */
 287     struct type *(*la_lookup_transparent_type) (const char *);
 288
 289     /* Return demangled language symbol, or NULL.  */
 290     char *(*la_demangle) (const char *mangled, int options);
 291
 292     /* Demangle a symbol according to this language's rules.  Unlike
 293        la_demangle, this does not take any options.
 294
 295        *DEMANGLED will be set by this function.
 296
 297        If this function returns 0, then *DEMANGLED must always be set
 298        to NULL.
 299
 300        If this function returns 1, the implementation may set this to
 301        a xmalloc'd string holding the demangled form.  However, it is
 302        not required to.  The string, if any, is owned by the caller.
 303
 304        The resulting string should be of the form that will be
 305        installed into a symbol.  */
 306     int (*la_sniff_from_mangled_name) (const char *mangled, char **demangled);
 307
 308     /* Return class name of a mangled method name or NULL.  */
 309     char *(*la_class_name_from_physname) (const char *physname);
 310
 311     /* Table for printing expressions.  */
 312
 313     const struct op_print *la_op_print_tab;
 314
 315     /* Zero if the language has first-class arrays.  True if there are no
 316        array values, and array objects decay to pointers, as in C.  */
 317
 318     char c_style_arrays;
 319
 320     /* Index to use for extracting the first element of a string.  */
 321     char string_lower_bound;
 322
 323     /* The list of characters forming word boundaries.  */
 324     const char *(*la_word_break_characters) (void);
 325
 326     /* Should return a vector of all symbols which are possible
 327        completions for TEXT.  WORD is the entire command on which the
 328        completion is being made.  If CODE is TYPE_CODE_UNDEF, then all
 329        symbols should be examined; otherwise, only STRUCT_DOMAIN
 330        symbols whose type has a code of CODE should be matched.  */
 331     VEC (char_ptr) *(*la_make_symbol_completion_list) (const char *text,
 332                                                        const char *word,
 333                                                        enum type_code code);
 334
 335     /* The per-architecture (OS/ABI) language information.  */
 336     void (*la_language_arch_info) (struct gdbarch *,
 337                                    struct language_arch_info *);
 338
 339     /* Print the index of an element of an array.  */
 340     void (*la_print_array_index) (struct value *index_value,
 341                                   struct ui_file *stream,
 342                                   const struct value_print_options *options);
 343
 344     /* Return non-zero if TYPE should be passed (and returned) by
 345        reference at the language level.  */
 346     int (*la_pass_by_reference) (struct type *type);
 347
 348     /* Obtain a string from the inferior, storing it in a newly allocated
 349        buffer in BUFFER, which should be freed by the caller.  If the
 350        in- and out-parameter *LENGTH is specified at -1, the string is
 351        read until a null character of the appropriate width is found -
 352        otherwise the string is read to the length of characters specified.
 353        On completion, *LENGTH will hold the size of the string in characters.
 354        If a *LENGTH of -1 was specified it will count only actual
 355        characters, excluding any eventual terminating null character.
 356        Otherwise *LENGTH will include all characters - including any nulls.
 357        CHARSET will hold the encoding used in the string.  */
 358     void (*la_get_string) (struct value *value, gdb_byte **buffer, int *length,
 359                            struct type **chartype, const char **charset);
 360
 361     /* Return a pointer to the function that should be used to match
 362        a symbol name against LOOKUP_NAME. This is mostly for languages
 363        such as Ada where the matching algorithm depends on LOOKUP_NAME.
 364
 365        This field may be NULL, in which case strcmp_iw will be used
 366        to perform the matching.  */
 367     symbol_name_cmp_ftype (*la_get_symbol_name_cmp) (const char *lookup_name);
 368
 369     /* Find all symbols in the current program space matching NAME in
 370        DOMAIN, according to this language's rules.
 371
 372        The search is done in BLOCK only.
 373        The caller is responsible for iterating up through superblocks
 374        if desired.
 375
 376        For each one, call CALLBACK with the symbol.  If CALLBACK
 377        returns false, the iteration ends at that point.
 378
 379        This field may not be NULL.  If the language does not need any
 380        special processing here, 'iterate_over_symbols' should be
 381        used as the definition.  */
 382     void (*la_iterate_over_symbols)
 383       (const struct block *block, const char *name, domain_enum domain,
 384        gdb::function_view<symbol_found_callback_ftype> callback);
 385
 386     /* Various operations on varobj.  */
 387     const struct lang_varobj_ops *la_varobj_ops;
 388
 389     /* If this language allows compilation from the gdb command line,
 390        this method should be non-NULL.  When called it should return
 391        an instance of struct gcc_context appropriate to the language.
 392        When defined this method must never return NULL; instead it
 393        should throw an exception on failure.  The returned compiler
 394        instance is owned by its caller and must be deallocated by
 395        calling its 'destroy' method.  */
 396
 397     struct compile_instance *(*la_get_compile_instance) (void);
 398
 399     /* This method must be defined if 'la_get_gcc_context' is defined.
 400        If 'la_get_gcc_context' is not defined, then this method is
 401        ignored.
 402
 403        This takes the user-supplied text and returns a new bit of code
 404        to compile.
 405
 406        INST is the compiler instance being used.
 407        INPUT is the user's input text.
 408        GDBARCH is the architecture to use.
 409        EXPR_BLOCK is the block in which the expression is being
 410        parsed.
 411        EXPR_PC is the PC at which the expression is being parsed.  */
 412
 413     std::string (*la_compute_program) (struct compile_instance *inst,
 414                                        const char *input,
 415                                        struct gdbarch *gdbarch,
 416                                        const struct block *expr_block,
 417                                        CORE_ADDR expr_pc);
 418
 419     /* Add fields above this point, so the magic number is always last.  */
 420     /* Magic number for compat checking.  */
 421
 422     long la_magic;
 423
 424   };
 425
 426 #define LANG_MAGIC      910823L
 427
 428 /* Pointer to the language_defn for our current language.  This pointer
 429    always points to *some* valid struct; it can be used without checking
 430    it for validity.
 431
 432    The current language affects expression parsing and evaluation
 433    (FIXME: it might be cleaner to make the evaluation-related stuff
 434    separate exp_opcodes for each different set of semantics.  We
 435    should at least think this through more clearly with respect to
 436    what happens if the language is changed between parsing and
 437    evaluation) and printing of things like types and arrays.  It does
 438    *not* affect symbol-reading-- each source file in a symbol-file has
 439    its own language and we should keep track of that regardless of the
 440    language when symbols are read.  If we want some manual setting for
 441    the language of symbol files (e.g. detecting when ".c" files are
 442    C++), it should be a separate setting from the current_language.  */
 443
 444 extern const struct language_defn *current_language;
 445
 446 /* Pointer to the language_defn expected by the user, e.g. the language
 447    of main(), or the language we last mentioned in a message, or C.  */
 448
 449 extern const struct language_defn *expected_language;
 450
 451 /* language_mode ==
 452    language_mode_auto:   current_language automatically set upon selection
 453    of scope (e.g. stack frame)
 454    language_mode_manual: current_language set only by user.  */
 455
 456 extern enum language_mode
 457   {
 458     language_mode_auto, language_mode_manual
 459   }
 460 language_mode;
 461
 462 struct type *language_bool_type (const struct language_defn *l,
 463                                  struct gdbarch *gdbarch);
 464
 465 struct type *language_string_char_type (const struct language_defn *l,
 466                                         struct gdbarch *gdbarch);
 467
 468 /* Look up type NAME in language L, and return its definition for architecture
 469    GDBARCH.  Returns NULL if not found.  */
 470
 471 struct type *language_lookup_primitive_type (const struct language_defn *l,
 472                                              struct gdbarch *gdbarch,
 473                                              const char *name);
 474
 475 /* Wrapper around language_lookup_primitive_type to return the
 476    corresponding symbol.  */
 477
 478 struct symbol *
 479   language_lookup_primitive_type_as_symbol (const struct language_defn *l,
 480                                             struct gdbarch *gdbarch,
 481                                             const char *name);
 482
 483 \f
 484 /* These macros define the behaviour of the expression
 485    evaluator.  */
 486
 487 /* Should we range check values against the domain of their type?  */
 488 #define RANGE_CHECK (range_check != range_check_off)
 489
 490 /* "cast" really means conversion.  */
 491 /* FIXME -- should be a setting in language_defn.  */
 492 #define CAST_IS_CONVERSION(LANG) ((LANG)->la_language == language_c  || \
 493                                   (LANG)->la_language == language_cplus || \
 494                                   (LANG)->la_language == language_objc)
 495
 496 extern void language_info (int);
 497
 498 extern enum language set_language (enum language);
 499 \f
 500
 501 /* This page contains functions that return things that are
 502    specific to languages.  Each of these functions is based on
 503    the current setting of working_lang, which the user sets
 504    with the "set language" command.  */
 505
 506 #define LA_PRINT_TYPE(type,varstring,stream,show,level,flags)           \
 507   (current_language->la_print_type(type,varstring,stream,show,level,flags))
 508
 509 #define LA_PRINT_TYPEDEF(type,new_symbol,stream) \
 510   (current_language->la_print_typedef(type,new_symbol,stream))
 511
 512 #define LA_VALUE_PRINT(val,stream,options) \
 513   (current_language->la_value_print(val,stream,options))
 514
 515 #define LA_PRINT_CHAR(ch, type, stream) \
 516   (current_language->la_printchar(ch, type, stream))
 517 #define LA_PRINT_STRING(stream, elttype, string, length, encoding, force_ellipses, options) \
 518   (current_language->la_printstr(stream, elttype, string, length, \
 519                                  encoding, force_ellipses,options))
 520 #define LA_EMIT_CHAR(ch, type, stream, quoter) \
 521   (current_language->la_emitchar(ch, type, stream, quoter))
 522 #define LA_GET_STRING(value, buffer, length, chartype, encoding) \
 523   (current_language->la_get_string(value, buffer, length, chartype, encoding))
 524
 525 #define LA_PRINT_ARRAY_INDEX(index_value, stream, options) \
 526   (current_language->la_print_array_index(index_value, stream, options))
 527
 528 #define LA_ITERATE_OVER_SYMBOLS(BLOCK, NAME, DOMAIN, CALLBACK) \
 529   (current_language->la_iterate_over_symbols (BLOCK, NAME, DOMAIN, CALLBACK))
 530
 531 /* Test a character to decide whether it can be printed in literal form
 532    or needs to be printed in another representation.  For example,
 533    in C the literal form of the character with octal value 141 is 'a'
 534    and the "other representation" is '\141'.  The "other representation"
 535    is program language dependent.  */
 536
 537 #define PRINT_LITERAL_FORM(c)           \
 538   ((c) >= 0x20                          \
 539    && ((c) < 0x7F || (c) >= 0xA0)       \
 540    && (!sevenbit_strings || (c) < 0x80))
 541
 542 /* Type predicates */
 543
 544 extern int pointer_type (struct type *);
 545
 546 /* Error messages */
 547
 548 extern void range_error (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 549
 550 /* Data:  Does this value represent "truth" to the current language?  */
 551
 552 extern int value_true (struct value *);
 553
 554 /* Misc:  The string representing a particular enum language.  */
 555
 556 extern enum language language_enum (char *str);
 557
 558 extern const struct language_defn *language_def (enum language);
 559
 560 extern const char *language_str (enum language);
 561
 562 /* Add a language to the set known by GDB (at initialization time).  */
 563
 564 extern void add_language (const struct language_defn *);
 565
 566 /* Check for a language-specific trampoline.  */
 567
 568 extern CORE_ADDR skip_language_trampoline (struct frame_info *, CORE_ADDR pc);
 569
 570 /* Return demangled language symbol, or NULL.  */
 571 extern char *language_demangle (const struct language_defn *current_language,
 572                                 const char *mangled, int options);
 573
 574 /* A wrapper for la_sniff_from_mangled_name.  The arguments and result
 575    are as for the method.  */
 576
 577 extern int language_sniff_from_mangled_name (const struct language_defn *lang,
 578                                              const char *mangled,
 579                                              char **demangled);
 580
 581 /* Return class name from physname, or NULL.  */
 582 extern char *language_class_name_from_physname (const struct language_defn *,
 583                                                 const char *physname);
 584
 585 /* Splitting strings into words.  */
 586 extern const char *default_word_break_characters (void);
 587
 588 /* Print the index of an array element using the C99 syntax.  */
 589 extern void default_print_array_index (struct value *index_value,
 590                                        struct ui_file *stream,
 591                                        const struct value_print_options *options);
 592
 593 /* Return non-zero if TYPE should be passed (and returned) by
 594    reference at the language level.  */
 595 int language_pass_by_reference (struct type *type);
 596
 597 /* Return zero; by default, types are passed by value at the language
 598    level.  The target ABI may pass or return some structs by reference
 599    independent of this.  */
 600 int default_pass_by_reference (struct type *type);
 601
 602 /* The default implementation of la_print_typedef.  */
 603 void default_print_typedef (struct type *type, struct symbol *new_symbol,
 604                             struct ui_file *stream);
 605
 606 void default_get_string (struct value *value, gdb_byte **buffer, int *length,
 607                          struct type **char_type, const char **charset);
 608
 609 void c_get_string (struct value *value, gdb_byte **buffer, int *length,
 610                    struct type **char_type, const char **charset);
 611
 612 #endif /* defined (LANGUAGE_H) */