[deliverable/binutils-gdb.git] / gdb / completer.h

/* Header for GDB line completion.
   Copyright (C) 2000-2017 Free Software Foundation, Inc.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */

#if !defined (COMPLETER_H)
#define COMPLETER_H 1

#include "gdb_vecs.h"
#include "command.h"

/* Types of functions in struct match_list_displayer.  */

struct match_list_displayer;

typedef void mld_crlf_ftype (const struct match_list_displayer *);
typedef void mld_putch_ftype (const struct match_list_displayer *, int);
typedef void mld_puts_ftype (const struct match_list_displayer *,
			     const char *);
typedef void mld_flush_ftype (const struct match_list_displayer *);
typedef void mld_erase_entire_line_ftype (const struct match_list_displayer *);
typedef void mld_beep_ftype (const struct match_list_displayer *);
typedef int mld_read_key_ftype (const struct match_list_displayer *);

/* Interface between CLI/TUI and gdb_match_list_displayer.  */

struct match_list_displayer
{
  /* The screen dimensions to work with when displaying matches.  */
  int height, width;

  /* Print cr,lf.  */
  mld_crlf_ftype *crlf;

  /* Not "putc" to avoid issues where it is a stdio macro.  Sigh.  */
  mld_putch_ftype *putch;

  /* Print a string.  */
  mld_puts_ftype *puts;

  /* Flush all accumulated output.  */
  mld_flush_ftype *flush;

  /* Erase the currently line on the terminal (but don't discard any text the
     user has entered, readline may shortly re-print it).  */
  mld_erase_entire_line_ftype *erase_entire_line;

  /* Ring the bell.  */
  mld_beep_ftype *beep;

  /* Read one key.  */
  mld_read_key_ftype *read_key;
};

/* A list of completion candidates.  Each element is a malloc string,
   because ownership of the strings is transferred to readline, which
   calls free on each element.  */
typedef std::vector<gdb::unique_xmalloc_ptr<char>> completion_list;

/* The final result of a completion that is handed over to either
   readline or the "completion" command (which pretends to be
   readline).  Mainly a wrapper for a readline-style match list array,
   though other bits of info are included too.  */

struct completion_result
{
  /* Create an empty result.  */
  completion_result ();

  /* Create a result.  */
  completion_result (char **match_list, size_t number_matches,
		     bool completion_suppress_append);

  /* Destroy a result.  */
  ~completion_result ();

  /* Disable copying, since we don't need it.  */
  completion_result (const completion_result &rhs) = delete;
  void operator= (const completion_result &rhs) = delete;

  /* Move a result.  */
  completion_result (completion_result &&rhs);

  /* Release ownership of the match list array.  */
  char **release_match_list ();

  /* Sort the match list.  */
  void sort_match_list ();

private:
  /* Destroy the match list array and its contents.  */
  void reset_match_list ();

public:
  /* (There's no point in making these fields private, since the whole
     point of this wrapper is to build data in the layout expected by
     readline.  Making them private would require adding getters for
     the "complete" command, which would expose the same
     implementation details anyway.)  */

  /* The match list array, in the format that readline expects.
     match_list[0] contains the common prefix.  The real match list
     starts at index 1.  The list is NULL terminated.  If there's only
     one match, then match_list[1] is NULL.  If there are no matches,
     then this is NULL.  */
  char **match_list;
  /* The number of matched completions in MATCH_LIST.  Does not
     include the NULL terminator or the common prefix.  */
  size_t number_matches;

  /* Whether readline should suppress appending a whitespace, when
     there's only one possible completion.  */
  bool completion_suppress_append;
};

/* Object used by completers to build a completion match list to hand
   over to readline.  It tracks:

   - How many unique completions have been generated, to terminate
     completion list generation early if the list has grown to a size
     so large as to be useless.  This helps avoid GDB seeming to lock
     up in the event the user requests to complete on something vague
     that necessitates the time consuming expansion of many symbol
     tables.
*/
class completion_tracker
{
public:
  completion_tracker ();
  ~completion_tracker ();

  /* Disable copy.  */
  completion_tracker (const completion_tracker &rhs) = delete;
  void operator= (const completion_tracker &rhs) = delete;

  /* Add the completion NAME to the list of generated completions if
     it is not there already.  If too many completions were already
     found, this throws an error.  */
  void add_completion (gdb::unique_xmalloc_ptr<char> name);

  /* Add all completions matches in LIST.  Elements are moved out of
     LIST.  */
  void add_completions (completion_list &&list);

  /* True if we have any completion match recorded.  */
  bool have_completions () const
  { return !m_entries_vec.empty (); }

  /* Build a completion_result containing the list of completion
     matches to hand over to readline.  The parameters are as in
     rl_attempted_completion_function.  */
  completion_result build_completion_result (const char *text,
					     int start, int end);

private:

  /* Add the completion NAME to the list of generated completions if
     it is not there already.  If false is returned, too many
     completions were found.  */
  bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name);

  /* Given a new match, recompute the lowest common denominator (LCD)
     to hand over to readline.  */
  void recompute_lowest_common_denominator (const char *new_match);

  /* The completion matches found so far, in a vector.  */
  completion_list m_entries_vec;

  /* The completion matches found so far, in a hash table, for
     duplicate elimination as entries are added.  Otherwise the user
     is left scratching his/her head: readline and complete_command
     will remove duplicates, and if removal of duplicates there brings
     the total under max_completions the user may think gdb quit
     searching too early.  */
  htab_t m_entries_hash;

  /* Our idea of lowest common denominator to hand over to readline.  */
  char *m_lowest_common_denominator = NULL;

  /* If true, the LCD is unique.  I.e., all completion candidates had
     the same string.  */
  bool m_lowest_common_denominator_unique = false;
};

extern void gdb_display_match_list (char **matches, int len, int max,
				    const struct match_list_displayer *);

extern const char *get_max_completions_reached_message (void);

extern void complete_line (completion_tracker &tracker,
			   const char *text,
			   const char *line_buffer,
			   int point);

/* Find the bounds of the word in TEXT for completion purposes, and
   return a pointer to the end of the word.  Calls the completion
   machinery for a handle_brkchars phase (using TRACKER) to figure out
   the right work break characters for the command in TEXT.
   QUOTE_CHAR, if non-null, is set to the opening quote character if
   we found an unclosed quoted substring, '\0' otherwise.  */
extern const char *completion_find_completion_word (completion_tracker &tracker,
						    const char *text,
						    int *quote_char);

extern char **gdb_rl_attempted_completion_function (const char *text,
						    int start, int end);

extern void noop_completer (struct cmd_list_element *,
			    completion_tracker &tracker,
			    const char *, const char *);

extern void filename_completer (struct cmd_list_element *,
				completion_tracker &tracker,
				const char *, const char *);

extern void expression_completer (struct cmd_list_element *,
				  completion_tracker &tracker,
				  const char *, const char *);

extern void location_completer (struct cmd_list_element *,
				completion_tracker &tracker,
				const char *, const char *);

extern void symbol_completer (struct cmd_list_element *,
			      completion_tracker &tracker,
			      const char *, const char *);

extern void command_completer (struct cmd_list_element *,
			       completion_tracker &tracker,
			       const char *, const char *);

extern void signal_completer (struct cmd_list_element *,
			      completion_tracker &tracker,
			      const char *, const char *);

extern void reg_or_group_completer (struct cmd_list_element *,
				    completion_tracker &tracker,
				    const char *, const char *);

extern void reggroup_completer (struct cmd_list_element *,
				completion_tracker &tracker,
				const char *, const char *);

extern const char *get_gdb_completer_quote_characters (void);

extern char *gdb_completion_word_break_characters (void);

/* Set the word break characters array to BREAK_CHARS.  This function
   is useful as const-correct alternative to direct assignment to
   rl_completer_word_break_characters, which is "char *",
   not "const char *".  */
extern void set_rl_completer_word_break_characters (const char *break_chars);

/* Get the matching completer_handle_brkchars_ftype function for FN.
   FN is one of the core completer functions above (filename,
   location, symbol, etc.).  This function is useful for cases when
   the completer doesn't know the type of the completion until some
   calculation is done (e.g., for Python functions).  */

extern completer_handle_brkchars_ftype *
  completer_handle_brkchars_func_for_completer (completer_ftype *fn);

/* Exported to linespec.c */

extern const char *skip_quoted_chars (const char *, const char *,
				      const char *);

extern const char *skip_quoted (const char *);

/* Maximum number of candidates to consider before the completer
   bails by throwing MAX_COMPLETIONS_REACHED_ERROR.  Negative values
   disable limiting.  */

extern int max_completions;

#endif /* defined (COMPLETER_H) */
Commit	Line	Data
c5f0f3d0	1	/* Header for GDB line completion.
61baf725	2	Copyright (C) 2000-2017 Free Software Foundation, Inc.
c5f0f3d0 FN	3
	4	This program is free software; you can redistribute it and/or modify
	5	it under the terms of the GNU General Public License as published by
a9762ec7	6	the Free Software Foundation; either version 3 of the License, or
c5f0f3d0 FN	7	(at your option) any later version.
	8
	9	This program is distributed in the hope that it will be useful,
	10	but WITHOUT ANY WARRANTY; without even the implied warranty of
	11	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	12	GNU General Public License for more details.
	13
	14	You should have received a copy of the GNU General Public License
a9762ec7	15	along with this program. If not, see <http://www.gnu.org/licenses/>. */
c5f0f3d0 FN	16
	17	#if !defined (COMPLETER_H)
	18	#define COMPLETER_H 1
	19
49c4e619	20	#include "gdb_vecs.h"
7d793aa9	21	#include "command.h"
49c4e619	22
82083d6d DE	23	/* Types of functions in struct match_list_displayer. */
	24
	25	struct match_list_displayer;
	26
	27	typedef void mld_crlf_ftype (const struct match_list_displayer *);
	28	typedef void mld_putch_ftype (const struct match_list_displayer *, int);
	29	typedef void mld_puts_ftype (const struct match_list_displayer *,
	30	const char *);
	31	typedef void mld_flush_ftype (const struct match_list_displayer *);
	32	typedef void mld_erase_entire_line_ftype (const struct match_list_displayer *);
	33	typedef void mld_beep_ftype (const struct match_list_displayer *);
	34	typedef int mld_read_key_ftype (const struct match_list_displayer *);
	35
	36	/* Interface between CLI/TUI and gdb_match_list_displayer. */
	37
	38	struct match_list_displayer
	39	{
	40	/* The screen dimensions to work with when displaying matches. */
	41	int height, width;
	42
	43	/* Print cr,lf. */
	44	mld_crlf_ftype *crlf;
	45
	46	/* Not "putc" to avoid issues where it is a stdio macro. Sigh. */
	47	mld_putch_ftype *putch;
	48
	49	/* Print a string. */
	50	mld_puts_ftype *puts;
	51
	52	/* Flush all accumulated output. */
	53	mld_flush_ftype *flush;
	54
	55	/* Erase the currently line on the terminal (but don't discard any text the
	56	user has entered, readline may shortly re-print it). */
	57	mld_erase_entire_line_ftype *erase_entire_line;
	58
	59	/* Ring the bell. */
	60	mld_beep_ftype *beep;
	61
	62	/* Read one key. */
	63	mld_read_key_ftype *read_key;
	64	};
	65
eb3ff9a5 PA	66	/* A list of completion candidates. Each element is a malloc string,
	67	because ownership of the strings is transferred to readline, which
	68	calls free on each element. */
	69	typedef std::vector<gdb::unique_xmalloc_ptr<char>> completion_list;
	70
	71	/* The final result of a completion that is handed over to either
	72	readline or the "completion" command (which pretends to be
	73	readline). Mainly a wrapper for a readline-style match list array,
	74	though other bits of info are included too. */
	75
	76	struct completion_result
	77	{
	78	/* Create an empty result. */
	79	completion_result ();
	80
	81	/* Create a result. */
	82	completion_result (char **match_list, size_t number_matches,
	83	bool completion_suppress_append);
	84
	85	/* Destroy a result. */
	86	~completion_result ();
	87
	88	/* Disable copying, since we don't need it. */
	89	completion_result (const completion_result &rhs) = delete;
	90	void operator= (const completion_result &rhs) = delete;
	91
	92	/* Move a result. */
	93	completion_result (completion_result &&rhs);
	94
	95	/* Release ownership of the match list array. */
	96	char **release_match_list ();
	97
	98	/* Sort the match list. */
	99	void sort_match_list ();
	100
	101	private:
	102	/* Destroy the match list array and its contents. */
	103	void reset_match_list ();
	104
	105	public:
	106	/* (There's no point in making these fields private, since the whole
	107	point of this wrapper is to build data in the layout expected by
	108	readline. Making them private would require adding getters for
	109	the "complete" command, which would expose the same
	110	implementation details anyway.) */
	111
	112	/* The match list array, in the format that readline expects.
	113	match_list[0] contains the common prefix. The real match list
	114	starts at index 1. The list is NULL terminated. If there's only
	115	one match, then match_list[1] is NULL. If there are no matches,
	116	then this is NULL. */
	117	char **match_list;
	118	/* The number of matched completions in MATCH_LIST. Does not
	119	include the NULL terminator or the common prefix. */
	120	size_t number_matches;
	121
	122	/* Whether readline should suppress appending a whitespace, when
	123	there's only one possible completion. */
	124	bool completion_suppress_append;
	125	};
	126
	127	/* Object used by completers to build a completion match list to hand
	128	over to readline. It tracks:
	129
130	- How many unique completions have been generated, to terminate
131	completion list generation early if the list has grown to a size
132	so large as to be useless. This helps avoid GDB seeming to lock
133	up in the event the user requests to complete on something vague
134	that necessitates the time consuming expansion of many symbol
135	tables.
136	*/
137	class completion_tracker
138	{
139	public:
140	completion_tracker ();
141	~completion_tracker ();
142
143	/* Disable copy. */
144	completion_tracker (const completion_tracker &rhs) = delete;
145	void operator= (const completion_tracker &rhs) = delete;
146
147	/* Add the completion NAME to the list of generated completions if
148	it is not there already. If too many completions were already
149	found, this throws an error. */
150	void add_completion (gdb::unique_xmalloc_ptr<char> name);
151
152	/* Add all completions matches in LIST. Elements are moved out of
153	LIST. */
154	void add_completions (completion_list &&list);
155
156	/* True if we have any completion match recorded. */
157	bool have_completions () const
158	{ return !m_entries_vec.empty (); }
159
160	/* Build a completion_result containing the list of completion
161	matches to hand over to readline. The parameters are as in
162	rl_attempted_completion_function. */
163	completion_result build_completion_result (const char *text,
164	int start, int end);
165
166	private:
167
168	/* Add the completion NAME to the list of generated completions if
169	it is not there already. If false is returned, too many
170	completions were found. */
171	bool maybe_add_completion (gdb::unique_xmalloc_ptr<char> name);
172
173	/* Given a new match, recompute the lowest common denominator (LCD)
174	to hand over to readline. */
175	void recompute_lowest_common_denominator (const char *new_match);
176
177	/* The completion matches found so far, in a vector. */
178	completion_list m_entries_vec;
179
180	/* The completion matches found so far, in a hash table, for
181	duplicate elimination as entries are added. Otherwise the user
182	is left scratching his/her head: readline and complete_command
183	will remove duplicates, and if removal of duplicates there brings
184	the total under max_completions the user may think gdb quit
185	searching too early. */
186	htab_t m_entries_hash;
187
188	/* Our idea of lowest common denominator to hand over to readline. */
189	char *m_lowest_common_denominator = NULL;
190
191	/* If true, the LCD is unique. I.e., all completion candidates had
192	the same string. */
193	bool m_lowest_common_denominator_unique = false;
194	};
195
82083d6d DE	196	extern void gdb_display_match_list (char **matches, int len, int max,
	197	const struct match_list_displayer *);
	198
ef0b411a GB	199	extern const char *get_max_completions_reached_message (void);
ef0b411a GB	200
eb3ff9a5 PA	201	extern void complete_line (completion_tracker &tracker,
	202	const char *text,
	203	const char *line_buffer,
	204	int point);
83d31a92	205
6a2c1b87 PA	206	/* Find the bounds of the word in TEXT for completion purposes, and
	207	return a pointer to the end of the word. Calls the completion
	208	machinery for a handle_brkchars phase (using TRACKER) to figure out
	209	the right work break characters for the command in TEXT.
	210	QUOTE_CHAR, if non-null, is set to the opening quote character if
	211	we found an unclosed quoted substring, '\0' otherwise. */
	212	extern const char *completion_find_completion_word (completion_tracker &tracker,
	213	const char *text,
	214	int *quote_char);
	215
eb3ff9a5 PA	216	extern char *gdb_rl_attempted_completion_function (const char text,
eb3ff9a5 PA	217	int start, int end);
d75b5104	218
eb3ff9a5 PA	219	extern void noop_completer (struct cmd_list_element *,
	220	completion_tracker &tracker,
	221	const char , const char );
d75b5104	222
eb3ff9a5 PA	223	extern void filename_completer (struct cmd_list_element *,
	224	completion_tracker &tracker,
	225	const char , const char );
c5f0f3d0	226
eb3ff9a5 PA	227	extern void expression_completer (struct cmd_list_element *,
	228	completion_tracker &tracker,
	229	const char , const char );
65d12d83	230
eb3ff9a5 PA	231	extern void location_completer (struct cmd_list_element *,
	232	completion_tracker &tracker,
	233	const char , const char );
c94fdfd0	234
eb3ff9a5 PA	235	extern void symbol_completer (struct cmd_list_element *,
	236	completion_tracker &tracker,
	237	const char , const char );
78b13106	238
eb3ff9a5 PA	239	extern void command_completer (struct cmd_list_element *,
	240	completion_tracker &tracker,
	241	const char , const char );
db60ec62	242
eb3ff9a5 PA	243	extern void signal_completer (struct cmd_list_element *,
	244	completion_tracker &tracker,
	245	const char , const char );
de0bea00	246
eb3ff9a5 PA	247	extern void reg_or_group_completer (struct cmd_list_element *,
	248	completion_tracker &tracker,
	249	const char , const char );
71c24708	250
eb3ff9a5 PA	251	extern void reggroup_completer (struct cmd_list_element *,
	252	completion_tracker &tracker,
	253	const char , const char );
51f0e40d	254
67cb5b2d	255	extern const char *get_gdb_completer_quote_characters (void);
c5f0f3d0	256
67c296a2 PM	257	extern char *gdb_completion_word_break_characters (void);
67c296a2 PM	258
67cb5b2d PA	259	/* Set the word break characters array to BREAK_CHARS. This function
	260	is useful as const-correct alternative to direct assignment to
	261	rl_completer_word_break_characters, which is "char *",
	262	not "const char ". /
	263	extern void set_rl_completer_word_break_characters (const char *break_chars);
	264
6e1dbf8c PA	265	/* Get the matching completer_handle_brkchars_ftype function for FN.
	266	FN is one of the core completer functions above (filename,
	267	location, symbol, etc.). This function is useful for cases when
	268	the completer doesn't know the type of the completion until some
7d793aa9 SDJ	269	calculation is done (e.g., for Python functions). */
7d793aa9 SDJ	270
6e1dbf8c PA	271	extern completer_handle_brkchars_ftype *
6e1dbf8c PA	272	completer_handle_brkchars_func_for_completer (completer_ftype *fn);
7d793aa9	273
c5f0f3d0 FN	274	/* Exported to linespec.c */
c5f0f3d0 FN	275
d7561cbb KS	276	extern const char skip_quoted_chars (const char , const char *,
d7561cbb KS	277	const char *);
4e87b832	278
d7561cbb	279	extern const char skip_quoted (const char );
c5f0f3d0	280
ef0b411a GB	281	/* Maximum number of candidates to consider before the completer
	282	bails by throwing MAX_COMPLETIONS_REACHED_ERROR. Negative values
	283	disable limiting. */
	284
	285	extern int max_completions;
	286
c5f0f3d0	287	#endif /* defined (COMPLETER_H) */