include/lldb/Host/Editline.h

   1 //===-- Editline.h ----------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 //TODO: wire up window size changes
  11
  12 // If we ever get a private copy of libedit, there are a number of defects that would be nice to fix;
  13 // a) Sometimes text just disappears while editing.  In an 80-column editor paste the following text, without
  14 //    the quotes:
  15 //    "This is a test of the input system missing Hello, World!  Do you disappear when it gets to a particular length?"
  16 //    Now press ^A to move to the start and type 3 characters, and you'll see a good amount of the text will
  17 //    disappear.  It's still in the buffer, just invisible.
  18 // b) The prompt printing logic for dealing with ANSI formatting characters is broken, which is why we're
  19 //    working around it here.
  20 // c) When resizing the terminal window, if the cursor moves between rows libedit will get confused.
  21 // d) The incremental search uses escape to cancel input, so it's confused by ANSI sequences starting with escape.
  22 // e) Emoji support is fairly terrible, presumably it doesn't understand composed characters?
  23
  24 #ifndef liblldb_Editline_h_
  25 #define liblldb_Editline_h_
  26 #if defined(__cplusplus)
  27
  28 #include <sstream>
  29 #include <vector>
  30 #include <locale>
  31
  32 // components needed to handle wide characters ( <codecvt>, codecvt_utf8, libedit built with '--enable-widec' )
  33 // are available on some platforms. The wchar_t versions of libedit functions will only be
  34 // used in cases where this is true.  This is a compile time dependecy, for now selected per target Platform
  35 #if defined (__APPLE__) || defined(__NetBSD__)
  36 #define LLDB_EDITLINE_USE_WCHAR 1
  37 #include <codecvt>
  38 #else
  39 #define LLDB_EDITLINE_USE_WCHAR 0
  40 #endif
  41
  42 #include "lldb/lldb-private.h"
  43 #include "lldb/Host/ConnectionFileDescriptor.h"
  44
  45 #if defined(_WIN32)
  46 #include "lldb/Host/windows/editlinewin.h"
  47 #else
  48 #if !defined(__ANDROID_NDK__)
  49 #include <histedit.h>
  50 #endif
  51 #endif
  52
  53 #include <mutex>
  54 #include <string>
  55 #include <vector>
  56
  57 #include "lldb/Host/Condition.h"
  58 #include "lldb/Host/ConnectionFileDescriptor.h"
  59 #include "lldb/Host/FileSpec.h"
  60 #include "lldb/Host/Predicate.h"
  61
  62 namespace lldb_private {
  63     namespace line_editor {
  64
  65         // type alias's to help manage 8 bit and wide character versions of libedit
  66 #if LLDB_EDITLINE_USE_WCHAR
  67         using EditLineStringType = std::wstring;
  68         using EditLineStringStreamType = std::wstringstream;
  69         using EditLineCharType = wchar_t;
  70 #else
  71         using EditLineStringType=std::string;
  72         using EditLineStringStreamType = std::stringstream;
  73         using EditLineCharType = char;
  74 #endif
  75
  76         typedef int (* EditlineGetCharCallbackType)(::EditLine * editline, EditLineCharType * c);
  77         typedef unsigned char (* EditlineCommandCallbackType)(::EditLine * editline, int ch);
  78         typedef const char * (* EditlinePromptCallbackType)(::EditLine * editline);
  79
  80         class EditlineHistory;
  81
  82         typedef std::shared_ptr<EditlineHistory> EditlineHistorySP;
  83
  84         typedef bool (* IsInputCompleteCallbackType) (
  85             Editline * editline,
  86             StringList & lines,
  87             void * baton);
  88
  89         typedef int (* FixIndentationCallbackType) (
  90             Editline * editline,
  91             const StringList & lines,
  92             int cursor_position,
  93             void * baton);
  94
  95         typedef int (* CompleteCallbackType) (
  96             const char * current_line,
  97             const char * cursor,
  98             const char * last_char,
  99             int skip_first_n_matches,
 100             int max_matches,
 101             StringList & matches,
 102             void * baton);
 103
 104         /// Status used to decide when and how to start editing another line in multi-line sessions
 105         enum class EditorStatus
 106         {
 107
 108             /// The default state proceeds to edit the current line
 109             Editing,
 110
 111             /// Editing complete, returns the complete set of edited lines
 112             Complete,
 113
 114             /// End of input reported
 115             EndOfInput,
 116
 117             /// Editing interrupted
 118             Interrupted
 119         };
 120
 121         /// Established locations that can be easily moved among with MoveCursor
 122         enum class CursorLocation
 123         {
 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 session
 131             EditingCursor,
 132
 133             /// The location immediately after the last character in a multi-line edit session
 134             BlockEnd
 135         };
 136     }
 137
 138     using namespace line_editor;
 139
 140     /// Instances of Editline provide an abstraction over libedit's EditLine facility.  Both
 141     /// single- and multi-line editing are supported.
 142     class Editline
 143     {
 144     public:
 145         Editline (const char * editor_name, FILE * input_file, FILE * output_file, FILE * error_file, bool color_prompts);
 146
 147         ~Editline();
 148
 149         /// Uses the user data storage of EditLine to retrieve an associated instance of Editline.
 150         static Editline *
 151         InstanceFor (::EditLine * editline);
 152
 153         /// Sets a string to be used as a prompt, or combined with a line number to form a prompt.
 154         void
 155         SetPrompt (const char * prompt);
 156
 157         /// Sets an alternate string to be used as a prompt for the second line and beyond in multi-line
 158         /// editing scenarios.
 159         void
 160         SetContinuationPrompt (const char * continuation_prompt);
 161
 162         /// Required to update the width of the terminal registered for I/O.  It is critical that this
 163         /// be correct at all times.
 164         void
 165         TerminalSizeChanged();
 166
 167         /// Returns the prompt established by SetPrompt()
 168         const char *
 169         GetPrompt();
 170
 171         /// Returns the index of the line currently being edited
 172         uint32_t
 173         GetCurrentLine();
 174
 175         /// Interrupt the current edit as if ^C was pressed
 176         bool
 177         Interrupt();
 178
 179         /// Cancel this edit and oblitarate all trace of it
 180         bool
 181         Cancel();
 182
 183         /// Register a callback for the tab key
 184         void
 185         SetAutoCompleteCallback (CompleteCallbackType callback, void * baton);
 186
 187         /// Register a callback for testing whether multi-line input is complete
 188         void
 189         SetIsInputCompleteCallback (IsInputCompleteCallbackType callback, void * baton);
 190
 191         /// Register a callback for determining the appropriate indentation for a line
 192         /// when creating a newline.  An optional set of insertable characters can also
 193         /// trigger the callback.
 194         bool
 195         SetFixIndentationCallback (FixIndentationCallbackType callback,
 196                                    void * baton,
 197                                    const char * indent_chars);
 198
 199         /// Prompts for and reads a single line of user input.
 200         bool
 201         GetLine (std::string &line, bool &interrupted);
 202
 203         /// Prompts for and reads a multi-line batch of user input.
 204         bool
 205         GetLines (int first_line_number, StringList &lines, bool &interrupted);
 206
 207         void
 208         PrintAsync (Stream *stream, const char *s, size_t len);
 209
 210     private:
 211
 212         /// Sets the lowest line number for multi-line editing sessions.  A value of zero suppresses
 213         /// line number printing in the prompt.
 214         void
 215         SetBaseLineNumber (int line_number);
 216
 217         /// Returns the complete prompt by combining the prompt or continuation prompt with line numbers
 218         /// as appropriate.  The line index is a zero-based index into the current multi-line session.
 219         std::string
 220         PromptForIndex (int line_index);
 221
 222         /// Sets the current line index between line edits to allow free movement between lines.  Updates
 223         /// the prompt to match.
 224         void
 225         SetCurrentLine (int line_index);
 226
 227         /// Determines the width of the prompt in characters.  The width is guaranteed to be the same for
 228         /// all lines of the current multi-line session.
 229         int
 230         GetPromptWidth();
 231
 232         /// Returns true if the underlying EditLine session's keybindings are Emacs-based, or false if
 233         /// they are VI-based.
 234         bool
 235         IsEmacs();
 236
 237         /// Returns true if the current EditLine buffer contains nothing but spaces, or is empty.
 238         bool
 239         IsOnlySpaces();
 240
 241         /// Helper method used by MoveCursor to determine relative line position.
 242         int
 243         GetLineIndexForLocation (CursorLocation location, int cursor_row);
 244
 245         /// Move the cursor from one well-established location to another using relative line positioning
 246         /// and absolute column positioning.
 247         void
 248         MoveCursor (CursorLocation from, CursorLocation to);
 249
 250         /// Clear from cursor position to bottom of screen and print input lines including prompts, optionally
 251         /// starting from a specific line.  Lines are drawn with an extra space at the end to reserve room for
 252         /// the rightmost cursor position.
 253         void
 254         DisplayInput (int firstIndex = 0);
 255
 256         /// Counts the number of rows a given line of content will end up occupying, taking into account both
 257         /// the preceding prompt and a single trailing space occupied by a cursor when at the end of the line.
 258         int
 259         CountRowsForLine (const EditLineStringType & content);
 260
 261         /// Save the line currently being edited
 262         void
 263         SaveEditedLine();
 264
 265         /// Convert the current input lines into a UTF8 StringList
 266         StringList
 267         GetInputAsStringList(int line_count = UINT32_MAX);
 268
 269         /// Replaces the current multi-line session with the next entry from history.  When the parameter is
 270         /// true it will take the next earlier entry from history, when it is false it takes the next most
 271         /// recent.
 272         unsigned char
 273         RecallHistory (bool earlier);
 274
 275         /// Character reading implementation for EditLine that supports our multi-line editing trickery.
 276         int
 277         GetCharacter (EditLineCharType * c);
 278
 279         /// Prompt implementation for EditLine.
 280         const char *
 281         Prompt();
 282
 283         /// Line break command used when meta+return is pressed in multi-line mode.
 284         unsigned char
 285         BreakLineCommand (int ch);
 286
 287         /// Command used when return is pressed in multi-line mode.
 288         unsigned char
 289         EndOrAddLineCommand(int ch);
 290
 291         /// Delete command used when delete is pressed in multi-line mode.
 292         unsigned char
 293         DeleteNextCharCommand (int ch);
 294
 295         /// Delete command used when backspace is pressed in multi-line mode.
 296         unsigned char
 297         DeletePreviousCharCommand (int ch);
 298
 299         /// Line navigation command used when ^P or up arrow are pressed in multi-line mode.
 300         unsigned char
 301         PreviousLineCommand (int ch);
 302
 303         /// Line navigation command used when ^N or down arrow are pressed in multi-line mode.
 304         unsigned char
 305         NextLineCommand (int ch);
 306
 307         /// History navigation command used when Alt + up arrow is pressed in multi-line mode.
 308         unsigned char
 309         PreviousHistoryCommand(int ch);
 310
 311         /// History navigation command used when Alt + down arrow is pressed in multi-line mode.
 312         unsigned char
 313         NextHistoryCommand(int ch);
 314
 315         /// Buffer start command used when Esc < is typed in multi-line emacs mode.
 316         unsigned char
 317         BufferStartCommand (int ch);
 318
 319         /// Buffer end command used when Esc > is typed in multi-line emacs mode.
 320         unsigned char
 321         BufferEndCommand (int ch);
 322
 323         /// Context-sensitive tab insertion or code completion command used when the tab key is typed.
 324         unsigned char
 325         TabCommand (int ch);
 326
 327         /// Respond to normal character insertion by fixing line indentation
 328         unsigned char
 329         FixIndentationCommand (int ch);
 330
 331         /// Revert line command used when moving between lines.
 332         unsigned char
 333         RevertLineCommand (int ch);
 334
 335         /// Ensures that the current EditLine instance is properly configured for single or multi-line editing.
 336         void
 337         ConfigureEditor (bool multiline);
 338
 339     private:
 340 #if LLDB_EDITLINE_USE_WCHAR
 341         std::wstring_convert<std::codecvt_utf8<wchar_t>> m_utf8conv;
 342 #endif
 343         ::EditLine * m_editline = nullptr;
 344         EditlineHistorySP m_history_sp;
 345         bool m_in_history = false;
 346         std::vector<EditLineStringType> m_live_history_lines;
 347         bool m_multiline_enabled = false;
 348         std::vector<EditLineStringType> m_input_lines;
 349         EditorStatus m_editor_status;
 350         bool m_color_prompts = true;
 351         int m_terminal_width = 0;
 352         int m_base_line_number = 0;
 353         unsigned m_current_line_index = 0;
 354         int m_current_line_rows = -1;
 355         int m_revert_cursor_index = 0;
 356         int m_line_number_digits = 3;
 357         std::string m_set_prompt;
 358         std::string m_set_continuation_prompt;
 359         std::string m_current_prompt;
 360         bool m_needs_prompt_repaint = false;
 361         std::string m_editor_name;
 362         FILE * m_input_file;
 363         FILE * m_output_file;
 364         FILE * m_error_file;
 365         ConnectionFileDescriptor m_input_connection;
 366         IsInputCompleteCallbackType m_is_input_complete_callback = nullptr;
 367         void * m_is_input_complete_callback_baton = nullptr;
 368         FixIndentationCallbackType m_fix_indentation_callback = nullptr;
 369         void * m_fix_indentation_callback_baton = nullptr;
 370         const char * m_fix_indentation_callback_chars = nullptr;
 371         CompleteCallbackType m_completion_callback = nullptr;
 372         void * m_completion_callback_baton = nullptr;
 373
 374         std::mutex m_output_mutex;
 375     };
 376 }
 377
 378 #endif  // #if defined(__cplusplus)
 379 #endif  // liblldb_Editline_h_