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     /* Add to the completion tracker 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     void (*la_collect_symbol_completion_matches)
 332       (completion_tracker &tracker,
 333        const char *text,
 334        const char *word,
 335        enum type_code code);
 336
 337     /* The per-architecture (OS/ABI) language information.  */
 338     void (*la_language_arch_info) (struct gdbarch *,
 339                                    struct language_arch_info *);
 340
 341     /* Print the index of an element of an array.  */
 342     void (*la_print_array_index) (struct value *index_value,
 343                                   struct ui_file *stream,
 344                                   const struct value_print_options *options);
 345
 346     /* Return non-zero if TYPE should be passed (and returned) by
 347        reference at the language level.  */
 348     int (*la_pass_by_reference) (struct type *type);
 349
 350     /* Obtain a string from the inferior, storing it in a newly allocated
 351        buffer in BUFFER, which should be freed by the caller.  If the
 352        in- and out-parameter *LENGTH is specified at -1, the string is
 353        read until a null character of the appropriate width is found -
 354        otherwise the string is read to the length of characters specified.
 355        On completion, *LENGTH will hold the size of the string in characters.
 356        If a *LENGTH of -1 was specified it will count only actual
 357        characters, excluding any eventual terminating null character.
 358        Otherwise *LENGTH will include all characters - including any nulls.
 359        CHARSET will hold the encoding used in the string.  */
 360     void (*la_get_string) (struct value *value, gdb_byte **buffer, int *length,
 361                            struct type **chartype, const char **charset);
 362
 363     /* Return an expression that can be used for a location
 364        watchpoint.  TYPE is a pointer type that points to the memory
 365        to watch, and ADDR is the address of the watched memory.  */
 366     gdb::unique_xmalloc_ptr<char> (*la_watch_location_expression)
 367          (struct type *type, CORE_ADDR addr);
 368
 369     /* Return a pointer to the function that should be used to match
 370        a symbol name against LOOKUP_NAME. This is mostly for languages
 371        such as Ada where the matching algorithm depends on LOOKUP_NAME.
 372
 373        This field may be NULL, in which case strcmp_iw will be used
 374        to perform the matching.  */
 375     symbol_name_cmp_ftype (*la_get_symbol_name_cmp) (const char *lookup_name);
 376
 377     /* Find all symbols in the current program space matching NAME in
 378        DOMAIN, according to this language's rules.
 379
 380        The search is done in BLOCK only.
 381        The caller is responsible for iterating up through superblocks
 382        if desired.
 383
 384        For each one, call CALLBACK with the symbol.  If CALLBACK
 385        returns false, the iteration ends at that point.
 386
 387        This field may not be NULL.  If the language does not need any
 388        special processing here, 'iterate_over_symbols' should be
 389        used as the definition.  */
 390     void (*la_iterate_over_symbols)
 391       (const struct block *block, const char *name, domain_enum domain,
 392        gdb::function_view<symbol_found_callback_ftype> callback);
 393
 394     /* Various operations on varobj.  */
 395     const struct lang_varobj_ops *la_varobj_ops;
 396
 397     /* If this language allows compilation from the gdb command line,
 398        this method should be non-NULL.  When called it should return
 399        an instance of struct gcc_context appropriate to the language.
 400        When defined this method must never return NULL; instead it
 401        should throw an exception on failure.  The returned compiler
 402        instance is owned by its caller and must be deallocated by
 403        calling its 'destroy' method.  */
 404
 405     struct compile_instance *(*la_get_compile_instance) (void);
 406
 407     /* This method must be defined if 'la_get_gcc_context' is defined.
 408        If 'la_get_gcc_context' is not defined, then this method is
 409        ignored.
 410
 411        This takes the user-supplied text and returns a new bit of code
 412        to compile.
 413
 414        INST is the compiler instance being used.
 415        INPUT is the user's input text.
 416        GDBARCH is the architecture to use.
 417        EXPR_BLOCK is the block in which the expression is being
 418        parsed.
 419        EXPR_PC is the PC at which the expression is being parsed.  */
 420
 421     std::string (*la_compute_program) (struct compile_instance *inst,
 422                                        const char *input,
 423                                        struct gdbarch *gdbarch,
 424                                        const struct block *expr_block,
 425                                        CORE_ADDR expr_pc);
 426
 427     /* Add fields above this point, so the magic number is always last.  */
 428     /* Magic number for compat checking.  */
 429
 430     long la_magic;
 431
 432   };
 433
 434 #define LANG_MAGIC      910823L
 435
 436 /* Pointer to the language_defn for our current language.  This pointer
 437    always points to *some* valid struct; it can be used without checking
 438    it for validity.
 439
 440    The current language affects expression parsing and evaluation
 441    (FIXME: it might be cleaner to make the evaluation-related stuff
 442    separate exp_opcodes for each different set of semantics.  We
 443    should at least think this through more clearly with respect to
 444    what happens if the language is changed between parsing and
 445    evaluation) and printing of things like types and arrays.  It does
 446    *not* affect symbol-reading-- each source file in a symbol-file has
 447    its own language and we should keep track of that regardless of the
 448    language when symbols are read.  If we want some manual setting for
 449    the language of symbol files (e.g. detecting when ".c" files are
 450    C++), it should be a separate setting from the current_language.  */
 451
 452 extern const struct language_defn *current_language;
 453
 454 /* Pointer to the language_defn expected by the user, e.g. the language
 455    of main(), or the language we last mentioned in a message, or C.  */
 456
 457 extern const struct language_defn *expected_language;
 458
 459 /* language_mode ==
 460    language_mode_auto:   current_language automatically set upon selection
 461    of scope (e.g. stack frame)
 462    language_mode_manual: current_language set only by user.  */
 463
 464 extern enum language_mode
 465   {
 466     language_mode_auto, language_mode_manual
 467   }
 468 language_mode;
 469
 470 struct type *language_bool_type (const struct language_defn *l,
 471                                  struct gdbarch *gdbarch);
 472
 473 struct type *language_string_char_type (const struct language_defn *l,
 474                                         struct gdbarch *gdbarch);
 475
 476 /* Look up type NAME in language L, and return its definition for architecture
 477    GDBARCH.  Returns NULL if not found.  */
 478
 479 struct type *language_lookup_primitive_type (const struct language_defn *l,
 480                                              struct gdbarch *gdbarch,
 481                                              const char *name);
 482
 483 /* Wrapper around language_lookup_primitive_type to return the
 484    corresponding symbol.  */
 485
 486 struct symbol *
 487   language_lookup_primitive_type_as_symbol (const struct language_defn *l,
 488                                             struct gdbarch *gdbarch,
 489                                             const char *name);
 490
 491 \f
 492 /* These macros define the behaviour of the expression
 493    evaluator.  */
 494
 495 /* Should we range check values against the domain of their type?  */
 496 #define RANGE_CHECK (range_check != range_check_off)
 497
 498 /* "cast" really means conversion.  */
 499 /* FIXME -- should be a setting in language_defn.  */
 500 #define CAST_IS_CONVERSION(LANG) ((LANG)->la_language == language_c  || \
 501                                   (LANG)->la_language == language_cplus || \
 502                                   (LANG)->la_language == language_objc)
 503
 504 extern void language_info (int);
 505
 506 extern enum language set_language (enum language);
 507 \f
 508
 509 /* This page contains functions that return things that are
 510    specific to languages.  Each of these functions is based on
 511    the current setting of working_lang, which the user sets
 512    with the "set language" command.  */
 513
 514 #define LA_PRINT_TYPE(type,varstring,stream,show,level,flags)           \
 515   (current_language->la_print_type(type,varstring,stream,show,level,flags))
 516
 517 #define LA_PRINT_TYPEDEF(type,new_symbol,stream) \
 518   (current_language->la_print_typedef(type,new_symbol,stream))
 519
 520 #define LA_VALUE_PRINT(val,stream,options) \
 521   (current_language->la_value_print(val,stream,options))
 522
 523 #define LA_PRINT_CHAR(ch, type, stream) \
 524   (current_language->la_printchar(ch, type, stream))
 525 #define LA_PRINT_STRING(stream, elttype, string, length, encoding, force_ellipses, options) \
 526   (current_language->la_printstr(stream, elttype, string, length, \
 527                                  encoding, force_ellipses,options))
 528 #define LA_EMIT_CHAR(ch, type, stream, quoter) \
 529   (current_language->la_emitchar(ch, type, stream, quoter))
 530 #define LA_GET_STRING(value, buffer, length, chartype, encoding) \
 531   (current_language->la_get_string(value, buffer, length, chartype, encoding))
 532
 533 #define LA_PRINT_ARRAY_INDEX(index_value, stream, options) \
 534   (current_language->la_print_array_index(index_value, stream, options))
 535
 536 #define LA_ITERATE_OVER_SYMBOLS(BLOCK, NAME, DOMAIN, CALLBACK) \
 537   (current_language->la_iterate_over_symbols (BLOCK, NAME, DOMAIN, CALLBACK))
 538
 539 /* Test a character to decide whether it can be printed in literal form
 540    or needs to be printed in another representation.  For example,
 541    in C the literal form of the character with octal value 141 is 'a'
 542    and the "other representation" is '\141'.  The "other representation"
 543    is program language dependent.  */
 544
 545 #define PRINT_LITERAL_FORM(c)           \
 546   ((c) >= 0x20                          \
 547    && ((c) < 0x7F || (c) >= 0xA0)       \
 548    && (!sevenbit_strings || (c) < 0x80))
 549
 550 /* Type predicates */
 551
 552 extern int pointer_type (struct type *);
 553
 554 /* Error messages */
 555
 556 extern void range_error (const char *, ...) ATTRIBUTE_PRINTF (1, 2);
 557
 558 /* Data:  Does this value represent "truth" to the current language?  */
 559
 560 extern int value_true (struct value *);
 561
 562 /* Misc:  The string representing a particular enum language.  */
 563
 564 extern enum language language_enum (char *str);
 565
 566 extern const struct language_defn *language_def (enum language);
 567
 568 extern const char *language_str (enum language);
 569
 570 /* Add a language to the set known by GDB (at initialization time).  */
 571
 572 extern void add_language (const struct language_defn *);
 573
 574 /* Check for a language-specific trampoline.  */
 575
 576 extern CORE_ADDR skip_language_trampoline (struct frame_info *, CORE_ADDR pc);
 577
 578 /* Return demangled language symbol, or NULL.  */
 579 extern char *language_demangle (const struct language_defn *current_language,
 580                                 const char *mangled, int options);
 581
 582 /* A wrapper for la_sniff_from_mangled_name.  The arguments and result
 583    are as for the method.  */
 584
 585 extern int language_sniff_from_mangled_name (const struct language_defn *lang,
 586                                              const char *mangled,
 587                                              char **demangled);
 588
 589 /* Return class name from physname, or NULL.  */
 590 extern char *language_class_name_from_physname (const struct language_defn *,
 591                                                 const char *physname);
 592
 593 /* Splitting strings into words.  */
 594 extern const char *default_word_break_characters (void);
 595
 596 /* Print the index of an array element using the C99 syntax.  */
 597 extern void default_print_array_index (struct value *index_value,
 598                                        struct ui_file *stream,
 599                                        const struct value_print_options *options);
 600
 601 /* Return non-zero if TYPE should be passed (and returned) by
 602    reference at the language level.  */
 603 int language_pass_by_reference (struct type *type);
 604
 605 /* Return zero; by default, types are passed by value at the language
 606    level.  The target ABI may pass or return some structs by reference
 607    independent of this.  */
 608 int default_pass_by_reference (struct type *type);
 609
 610 /* The default implementation of la_print_typedef.  */
 611 void default_print_typedef (struct type *type, struct symbol *new_symbol,
 612                             struct ui_file *stream);
 613
 614 void default_get_string (struct value *value, gdb_byte **buffer, int *length,
 615                          struct type **char_type, const char **charset);
 616
 617 void c_get_string (struct value *value, gdb_byte **buffer, int *length,
 618                    struct type **char_type, const char **charset);
 619
 620 #endif /* defined (LANGUAGE_H) */