Introduce class completion_tracker & rewrite completion<->readline interaction
[external/binutils.git] / 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) */