contrib/llvm/tools/lldb/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
  31 // components needed to handle wide characters ( <codecvt>, codecvt_utf8, libedit built with '--enable-widec' )
  32 // are not consistenly available on non-OSX platforms.  The wchar_t versions of libedit functions will only be
  33 // used in cases where this is true.  This is a compile time dependecy, for now selected per target Platform
  34 #if defined (__APPLE__)
  35 #define LLDB_EDITLINE_USE_WCHAR 1
  36 #include <codecvt>
  37 #else
  38 #define LLDB_EDITLINE_USE_WCHAR 0
  39 #endif
  40
  41 #include "lldb/lldb-private.h"
  42 #include "lldb/Host/ConnectionFileDescriptor.h"
  43
  44 #if defined(_WIN32)
  45 #include "lldb/Host/windows/editlinewin.h"
  46 #else
  47 #if !defined(__ANDROID_NDK__)
  48 #include <histedit.h>
  49 #endif
  50 #endif
  51
  52 #include <string>
  53 #include <vector>
  54
  55 #include "lldb/Host/Condition.h"
  56 #include "lldb/Host/ConnectionFileDescriptor.h"
  57 #include "lldb/Host/FileSpec.h"
  58 #include "lldb/Host/Mutex.h"
  59 #include "lldb/Host/Predicate.h"
  60
  61 namespace lldb_private {
  62     namespace line_editor {
  63
  64         // type alias's to help manage 8 bit and wide character versions of libedit
  65 #if LLDB_EDITLINE_USE_WCHAR
  66         using EditLineStringType = std::wstring;
  67         using EditLineStringStreamType = std::wstringstream;
  68         using EditLineCharType = wchar_t;
  69 #else
  70         using EditLineStringType=std::string;
  71         using EditLineStringStreamType = std::stringstream;
  72         using EditLineCharType = char;
  73 #endif
  74
  75         typedef int (* EditlineGetCharCallbackType)(::EditLine * editline, EditLineCharType * c);
  76         typedef unsigned char (* EditlineCommandCallbackType)(::EditLine * editline, int ch);
  77         typedef const char * (* EditlinePromptCallbackType)(::EditLine * editline);
  78
  79         class EditlineHistory;
  80
  81         typedef std::shared_ptr<EditlineHistory> EditlineHistorySP;
  82
  83         typedef bool (* IsInputCompleteCallbackType) (
  84             Editline * editline,
  85             StringList & lines,
  86             void * baton);
  87
  88         typedef int (* FixIndentationCallbackType) (
  89             Editline * editline,
  90             const StringList & lines,
  91             int cursor_position,
  92             void * baton);
  93
  94         typedef int (* CompleteCallbackType) (
  95             const char * current_line,
  96             const char * cursor,
  97             const char * last_char,
  98             int skip_first_n_matches,
  99             int max_matches,
 100             StringList & matches,
 101             void * baton);
 102
 103         /// Status used to decide when and how to start editing another line in multi-line sessions
 104         enum class EditorStatus
 105         {
 106
 107             /// The default state proceeds to edit the current line
 108             Editing,
 109
 110             /// Editing complete, returns the complete set of edited lines
 111             Complete,
 112
 113             /// End of input reported
 114             EndOfInput,
 115
 116             /// Editing interrupted
 117             Interrupted
 118         };
 119
 120         /// Established locations that can be easily moved among with MoveCursor
 121         enum class CursorLocation
 122         {
 123             /// The start of the first line in a multi-line edit session
 124             BlockStart,
 125
 126             /// The start of the current line in a multi-line edit session
 127             EditingPrompt,
 128
 129             /// The location of the cursor on the current line in a multi-line edit session
 130             EditingCursor,
 131
 132             /// The location immediately after the last character in a multi-line edit session
 133             BlockEnd
 134         };
 135     }
 136
 137     using namespace line_editor;
 138
 139     /// Instances of Editline provide an abstraction over libedit's EditLine facility.  Both
 140     /// single- and multi-line editing are supported.
 141     class Editline
 142     {
 143     public:
 144         Editline (const char * editor_name, FILE * input_file, FILE * output_file, FILE * error_file, bool color_prompts);
 145
 146         ~Editline();
 147
 148         /// Uses the user data storage of EditLine to retrieve an associated instance of Editline.
 149         static Editline *
 150         InstanceFor (::EditLine * editline);
 151
 152         /// Sets a string to be used as a prompt, or combined with a line number to form a prompt.
 153         void
 154         SetPrompt (const char * prompt);
 155
 156         /// Sets an alternate string to be used as a prompt for the second line and beyond in multi-line
 157         /// editing scenarios.
 158         void
 159         SetContinuationPrompt (const char * continuation_prompt);
 160
 161         /// Required to update the width of the terminal registered for I/O.  It is critical that this
 162         /// be correct at all times.
 163         void
 164         TerminalSizeChanged();
 165
 166         /// Returns the prompt established by SetPrompt()
 167         const char *
 168         GetPrompt();
 169
 170         /// Returns the index of the line currently being edited
 171         uint32_t
 172         GetCurrentLine();
 173
 174         /// Hides the current input session in preparation for output
 175         void
 176         Hide();
 177
 178         /// Prepare to return to editing after a call to Hide()
 179         void
 180         Refresh();
 181
 182         /// Interrupt the current edit as if ^C was pressed
 183         bool
 184         Interrupt();
 185
 186         /// Register a callback for the tab key
 187         void
 188         SetAutoCompleteCallback (CompleteCallbackType callback, void * baton);
 189
 190         /// Register a callback for testing whether multi-line input is complete
 191         void
 192         SetIsInputCompleteCallback (IsInputCompleteCallbackType callback, void * baton);
 193
 194         /// Register a callback for determining the appropriate indentation for a line
 195         /// when creating a newline.  An optional set of insertable characters can also
 196         /// trigger the callback.
 197         bool
 198         SetFixIndentationCallback (FixIndentationCallbackType callback,
 199                                    void * baton,
 200                                    const char * indent_chars);
 201
 202         /// Prompts for and reads a single line of user input.
 203         bool
 204         GetLine (std::string &line, bool &interrupted);
 205
 206         /// Prompts for and reads a multi-line batch of user input.
 207         bool
 208         GetLines (int first_line_number, StringList &lines, bool &interrupted);
 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 return is pressed in multi-line mode.
 284         unsigned char
 285         BreakLineCommand (int ch);
 286
 287         /// Delete command used when delete is pressed in multi-line mode.
 288         unsigned char
 289         DeleteNextCharCommand (int ch);
 290
 291         /// Delete command used when backspace is pressed in multi-line mode.
 292         unsigned char
 293         DeletePreviousCharCommand (int ch);
 294
 295         /// Line navigation command used when ^P or up arrow are pressed in multi-line mode.
 296         unsigned char
 297         PreviousLineCommand (int ch);
 298
 299         /// Line navigation command used when ^N or down arrow are pressed in multi-line mode.
 300         unsigned char
 301         NextLineCommand (int ch);
 302
 303         /// Buffer start command used when Esc < is typed in multi-line emacs mode.
 304         unsigned char
 305         BufferStartCommand (int ch);
 306
 307         /// Buffer end command used when Esc > is typed in multi-line emacs mode.
 308         unsigned char
 309         BufferEndCommand (int ch);
 310
 311         /// Context-sensitive tab insertion or code completion command used when the tab key is typed.
 312         unsigned char
 313         TabCommand (int ch);
 314
 315         /// Respond to normal character insertion by fixing line indentation
 316         unsigned char
 317         FixIndentationCommand (int ch);
 318
 319         /// Revert line command used when moving between lines.
 320         unsigned char
 321         RevertLineCommand (int ch);
 322
 323         /// Ensures that the current EditLine instance is properly configured for single or multi-line editing.
 324         void
 325         ConfigureEditor (bool multiline);
 326
 327     private:
 328 #if LLDB_EDITLINE_USE_WCHAR
 329         std::wstring_convert<std::codecvt_utf8<wchar_t>> m_utf8conv;
 330 #endif
 331         ::EditLine * m_editline = nullptr;
 332         EditlineHistorySP m_history_sp;
 333         bool m_in_history = false;
 334         std::vector<EditLineStringType> m_live_history_lines;
 335         bool m_multiline_enabled = false;
 336         std::vector<EditLineStringType> m_input_lines;
 337         EditorStatus m_editor_status;
 338         bool m_editor_getting_char = false;
 339         bool m_color_prompts = true;
 340         int m_terminal_width = 0;
 341         int m_base_line_number = 0;
 342         unsigned m_current_line_index = 0;
 343         int m_current_line_rows = -1;
 344         int m_revert_cursor_index = 0;
 345         int m_line_number_digits = 3;
 346         std::string m_set_prompt;
 347         std::string m_set_continuation_prompt;
 348         std::string m_current_prompt;
 349         bool m_needs_prompt_repaint = false;
 350         std::string m_editor_name;
 351         FILE * m_input_file;
 352         FILE * m_output_file;
 353         FILE * m_error_file;
 354         ConnectionFileDescriptor m_input_connection;
 355         IsInputCompleteCallbackType m_is_input_complete_callback = nullptr;
 356         void * m_is_input_complete_callback_baton = nullptr;
 357         FixIndentationCallbackType m_fix_indentation_callback = nullptr;
 358         void * m_fix_indentation_callback_baton = nullptr;
 359         const char * m_fix_indentation_callback_chars = nullptr;
 360         CompleteCallbackType m_completion_callback = nullptr;
 361         void * m_completion_callback_baton = nullptr;
 362     };
 363 }
 364
 365 #endif  // #if defined(__cplusplus)
 366 #endif  // liblldb_Editline_h_