LLDB mainline
Editline.h
Go to the documentation of this file.
1//===-- Editline.h ----------------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9// TODO: wire up window size changes
10
11// If we ever get a private copy of libedit, there are a number of defects that
12// would be nice to fix;
13// a) Sometimes text just disappears while editing. In an 80-column editor
14// paste the following text, without
15// the quotes:
16// "This is a test of the input system missing Hello, World! Do you
17// disappear when it gets to a particular length?"
18// Now press ^A to move to the start and type 3 characters, and you'll see a
19// good amount of the text will
20// disappear. It's still in the buffer, just invisible.
21// b) The prompt printing logic for dealing with ANSI formatting characters is
22// broken, which is why we're working around it here.
23// c) The incremental search uses escape to cancel input, so it's confused by
24// ANSI sequences starting with escape.
25// d) Emoji support is fairly terrible, presumably it doesn't understand
26// composed characters?
27
28#ifndef LLDB_HOST_EDITLINE_H
29#define LLDB_HOST_EDITLINE_H
30#if defined(__cplusplus)
31
32#include "lldb/Host/Config.h"
33
34#if LLDB_EDITLINE_USE_WCHAR
35#include <codecvt>
36#endif
37#include <locale>
38#include <sstream>
39#include <vector>
40
41#include "lldb/lldb-private.h"
42
43#if !defined(_WIN32) && !defined(__ANDROID__)
44#include <histedit.h>
45#endif
46
47#include <csignal>
48#include <mutex>
49#include <optional>
50#include <string>
51#include <vector>
52
58
59#include "llvm/ADT/FunctionExtras.h"
60
61namespace lldb_private {
62namespace line_editor {
63
64// type alias's to help manage 8 bit and wide character versions of libedit
65#if LLDB_EDITLINE_USE_WCHAR
66using EditLineStringType = std::wstring;
67using EditLineStringStreamType = std::wstringstream;
68using EditLineCharType = wchar_t;
69#else
70using EditLineStringType = std::string;
71using EditLineStringStreamType = std::stringstream;
72using EditLineCharType = char;
73#endif
74
75// At one point the callback type of el_set getchar callback changed from char
76// to wchar_t. It is not possible to detect differentiate between the two
77// versions exactly, but this is a pretty good approximation and allows us to
78// build against almost any editline version out there.
79#if LLDB_EDITLINE_USE_WCHAR || defined(EL_CLIENTDATA) || LLDB_HAVE_EL_RFUNC_T
80using EditLineGetCharType = wchar_t;
81#else
82using EditLineGetCharType = char;
83#endif
84
85using EditlineGetCharCallbackType = int (*)(::EditLine *editline,
86 EditLineGetCharType *c);
87using EditlineCommandCallbackType = unsigned char (*)(::EditLine *editline,
88 int ch);
89using EditlinePromptCallbackType = const char *(*)(::EditLine *editline);
90
91class EditlineHistory;
92
93using EditlineHistorySP = std::shared_ptr<EditlineHistory>;
94
95using IsInputCompleteCallbackType =
96 llvm::unique_function<bool(Editline *, StringList &)>;
97
98using FixIndentationCallbackType =
99 llvm::unique_function<int(Editline *, StringList &, int)>;
100
101using SuggestionCallbackType =
102 llvm::unique_function<std::optional<std::string>(llvm::StringRef)>;
103
104using CompleteCallbackType = llvm::unique_function<void(CompletionRequest &)>;
105
106/// Status used to decide when and how to start editing another line in
107/// multi-line sessions
108enum class EditorStatus {
109
110 /// The default state proceeds to edit the current line
111 Editing,
112
113 /// Editing complete, returns the complete set of edited lines
114 Complete,
115
116 /// End of input reported
117 EndOfInput,
118
119 /// Editing interrupted
120 Interrupted
121};
122
123/// Established locations that can be easily moved among with MoveCursor
124enum class CursorLocation {
125 /// The start of the first line in a multi-line edit session
126 BlockStart,
127
128 /// The start of the current line in a multi-line edit session
129 EditingPrompt,
130
131 /// The location of the cursor on the current line in a multi-line edit
132 /// session
133 EditingCursor,
134
135 /// The location immediately after the last character in a multi-line edit
136 /// session
137 BlockEnd
138};
139
140/// Operation for the history.
141enum class HistoryOperation {
142 Oldest,
143 Older,
144 Current,
145 Newer,
146 Newest
147};
148}
149
150using namespace line_editor;
151
152/// Instances of Editline provide an abstraction over libedit's EditLine
153/// facility. Both
154/// single- and multi-line editing are supported.
155class Editline {
156public:
157 Editline(const char *editor_name, FILE *input_file, FILE *output_file,
158 FILE *error_file, std::recursive_mutex &output_mutex,
159 bool color_prompts);
160
161 ~Editline();
162
163 /// Uses the user data storage of EditLine to retrieve an associated instance
164 /// of Editline.
165 static Editline *InstanceFor(::EditLine *editline);
166
167 /// Sets a string to be used as a prompt, or combined with a line number to
168 /// form a prompt.
169 void SetPrompt(const char *prompt);
170
171 /// Sets an alternate string to be used as a prompt for the second line and
172 /// beyond in multi-line
173 /// editing scenarios.
174 void SetContinuationPrompt(const char *continuation_prompt);
175
176 /// Call when the terminal size changes
177 void TerminalSizeChanged();
178
179 /// Returns the prompt established by SetPrompt()
180 const char *GetPrompt();
181
182 /// Returns the index of the line currently being edited
183 uint32_t GetCurrentLine();
184
185 /// Interrupt the current edit as if ^C was pressed
186 bool Interrupt();
187
188 /// Cancel this edit and oblitarate all trace of it
189 bool Cancel();
190
191 /// Register a callback for autosuggestion.
192 void SetSuggestionCallback(SuggestionCallbackType callback) {
193 m_suggestion_callback = std::move(callback);
194 }
195
196 /// Register a callback for the tab key
197 void SetAutoCompleteCallback(CompleteCallbackType callback) {
198 m_completion_callback = std::move(callback);
199 }
200
201 /// Register a callback for testing whether multi-line input is complete
202 void SetIsInputCompleteCallback(IsInputCompleteCallbackType callback) {
203 m_is_input_complete_callback = std::move(callback);
204 }
205
206 /// Register a callback for determining the appropriate indentation for a line
207 /// when creating a newline. An optional set of insertable characters can
208 /// also trigger the callback.
209 void SetFixIndentationCallback(FixIndentationCallbackType callback,
210 const char *indent_chars) {
211 m_fix_indentation_callback = std::move(callback);
212 m_fix_indentation_callback_chars = indent_chars;
213 }
214
215 void SetSuggestionAnsiPrefix(std::string prefix) {
216 m_suggestion_ansi_prefix = std::move(prefix);
217 }
218
219 void SetSuggestionAnsiSuffix(std::string suffix) {
220 m_suggestion_ansi_suffix = std::move(suffix);
221 }
222
223 /// Prompts for and reads a single line of user input.
224 bool GetLine(std::string &line, bool &interrupted);
225
226 /// Prompts for and reads a multi-line batch of user input.
227 bool GetLines(int first_line_number, StringList &lines, bool &interrupted);
228
229 void PrintAsync(Stream *stream, const char *s, size_t len);
230
231private:
232 /// Sets the lowest line number for multi-line editing sessions. A value of
233 /// zero suppresses
234 /// line number printing in the prompt.
235 void SetBaseLineNumber(int line_number);
236
237 /// Returns the complete prompt by combining the prompt or continuation prompt
238 /// with line numbers
239 /// as appropriate. The line index is a zero-based index into the current
240 /// multi-line session.
241 std::string PromptForIndex(int line_index);
242
243 /// Sets the current line index between line edits to allow free movement
244 /// between lines. Updates
245 /// the prompt to match.
246 void SetCurrentLine(int line_index);
247
248 /// Determines the width of the prompt in characters. The width is guaranteed
249 /// to be the same for
250 /// all lines of the current multi-line session.
251 int GetPromptWidth();
252
253 /// Returns true if the underlying EditLine session's keybindings are
254 /// Emacs-based, or false if
255 /// they are VI-based.
256 bool IsEmacs();
257
258 /// Returns true if the current EditLine buffer contains nothing but spaces,
259 /// or is empty.
260 bool IsOnlySpaces();
261
262 /// Helper method used by MoveCursor to determine relative line position.
263 int GetLineIndexForLocation(CursorLocation location, int cursor_row);
264
265 /// Move the cursor from one well-established location to another using
266 /// relative line positioning
267 /// and absolute column positioning.
268 void MoveCursor(CursorLocation from, CursorLocation to);
269
270 /// Clear from cursor position to bottom of screen and print input lines
271 /// including prompts, optionally
272 /// starting from a specific line. Lines are drawn with an extra space at the
273 /// end to reserve room for
274 /// the rightmost cursor position.
275 void DisplayInput(int firstIndex = 0);
276
277 /// Counts the number of rows a given line of content will end up occupying,
278 /// taking into account both
279 /// the preceding prompt and a single trailing space occupied by a cursor when
280 /// at the end of the line.
281 int CountRowsForLine(const EditLineStringType &content);
282
283 /// Save the line currently being edited
284 void SaveEditedLine();
285
286 /// Convert the current input lines into a UTF8 StringList
287 StringList GetInputAsStringList(int line_count = UINT32_MAX);
288
289 /// Replaces the current multi-line session with the next entry from history.
290 unsigned char RecallHistory(HistoryOperation op);
291
292 /// Character reading implementation for EditLine that supports our multi-line
293 /// editing trickery.
294 int GetCharacter(EditLineGetCharType *c);
295
296 /// Prompt implementation for EditLine.
297 const char *Prompt();
298
299 /// Line break command used when meta+return is pressed in multi-line mode.
300 unsigned char BreakLineCommand(int ch);
301
302 /// Command used when return is pressed in multi-line mode.
303 unsigned char EndOrAddLineCommand(int ch);
304
305 /// Delete command used when delete is pressed in multi-line mode.
306 unsigned char DeleteNextCharCommand(int ch);
307
308 /// Delete command used when backspace is pressed in multi-line mode.
309 unsigned char DeletePreviousCharCommand(int ch);
310
311 /// Line navigation command used when ^P or up arrow are pressed in multi-line
312 /// mode.
313 unsigned char PreviousLineCommand(int ch);
314
315 /// Line navigation command used when ^N or down arrow are pressed in
316 /// multi-line mode.
317 unsigned char NextLineCommand(int ch);
318
319 /// History navigation command used when Alt + up arrow is pressed in
320 /// multi-line mode.
321 unsigned char PreviousHistoryCommand(int ch);
322
323 /// History navigation command used when Alt + down arrow is pressed in
324 /// multi-line mode.
325 unsigned char NextHistoryCommand(int ch);
326
327 /// Buffer start command used when Esc < is typed in multi-line emacs mode.
328 unsigned char BufferStartCommand(int ch);
329
330 /// Buffer end command used when Esc > is typed in multi-line emacs mode.
331 unsigned char BufferEndCommand(int ch);
332
333 /// Context-sensitive tab insertion or code completion command used when the
334 /// tab key is typed.
335 unsigned char TabCommand(int ch);
336
337 /// Apply autosuggestion part in gray as editline.
338 unsigned char ApplyAutosuggestCommand(int ch);
339
340 /// Command used when a character is typed.
341 unsigned char TypedCharacter(int ch);
342
343 /// Respond to normal character insertion by fixing line indentation
344 unsigned char FixIndentationCommand(int ch);
345
346 /// Revert line command used when moving between lines.
347 unsigned char RevertLineCommand(int ch);
348
349 /// Ensures that the current EditLine instance is properly configured for
350 /// single or multi-line editing.
351 void ConfigureEditor(bool multiline);
352
353 bool CompleteCharacter(char ch, EditLineGetCharType &out);
354
355 void ApplyTerminalSizeChange();
356
357 // The following set various editline parameters. It's not any less
358 // verbose to put the editline calls into a function, but it
359 // provides type safety, since the editline functions take varargs
360 // parameters.
361 void AddFunctionToEditLine(const EditLineCharType *command,
362 const EditLineCharType *helptext,
363 EditlineCommandCallbackType callbackFn);
364 void SetEditLinePromptCallback(EditlinePromptCallbackType callbackFn);
365 void SetGetCharacterFunction(EditlineGetCharCallbackType callbackFn);
366
367#if LLDB_EDITLINE_USE_WCHAR
368 std::wstring_convert<std::codecvt_utf8<wchar_t>> m_utf8conv;
369#endif
370 ::EditLine *m_editline = nullptr;
371 EditlineHistorySP m_history_sp;
372 bool m_in_history = false;
373 std::vector<EditLineStringType> m_live_history_lines;
374 bool m_multiline_enabled = false;
375 std::vector<EditLineStringType> m_input_lines;
376 EditorStatus m_editor_status;
377 bool m_color_prompts = true;
378 int m_terminal_width = 0;
379 int m_base_line_number = 0;
380 unsigned m_current_line_index = 0;
381 int m_current_line_rows = -1;
382 int m_revert_cursor_index = 0;
383 int m_line_number_digits = 3;
384 std::string m_set_prompt;
385 std::string m_set_continuation_prompt;
386 std::string m_current_prompt;
387 bool m_needs_prompt_repaint = false;
388 volatile std::sig_atomic_t m_terminal_size_has_changed = 0;
389 std::string m_editor_name;
390 FILE *m_input_file;
391 FILE *m_output_file;
392 FILE *m_error_file;
393 ConnectionFileDescriptor m_input_connection;
394
395 IsInputCompleteCallbackType m_is_input_complete_callback;
396
397 FixIndentationCallbackType m_fix_indentation_callback;
398 const char *m_fix_indentation_callback_chars = nullptr;
399
400 CompleteCallbackType m_completion_callback;
401 SuggestionCallbackType m_suggestion_callback;
402
403 std::string m_suggestion_ansi_prefix;
404 std::string m_suggestion_ansi_suffix;
405
406 std::size_t m_previous_autosuggestion_size = 0;
407 std::recursive_mutex &m_output_mutex;
408};
409}
410
411#endif // #if defined(__cplusplus)
412#endif // LLDB_HOST_EDITLINE_H
bool IsOnlySpaces(const EditLineStringType &content)
Definition: Editline.cpp:96
#define UINT32_MAX
Definition: lldb-defines.h:19
A class that represents a running process on the host machine.
Definition: SBAttachInfo.h:14