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