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         /// Interrupt the current edit as if ^C was pressed
 175         bool
 176         Interrupt();
 177
 178         /// Cancel this edit and oblitarate all trace of it
 179         bool
 180         Cancel();
 181
 182         /// Register a callback for the tab key
 183         void
 184         SetAutoCompleteCallback (CompleteCallbackType callback, void * baton);
 185
 186         /// Register a callback for testing whether multi-line input is complete
 187         void
 188         SetIsInputCompleteCallback (IsInputCompleteCallbackType callback, void * baton);
 189
 190         /// Register a callback for determining the appropriate indentation for a line
 191         /// when creating a newline.  An optional set of insertable characters can also
 192         /// trigger the callback.
 193         bool
 194         SetFixIndentationCallback (FixIndentationCallbackType callback,
 195                                    void * baton,
 196                                    const char * indent_chars);
 197
 198         /// Prompts for and reads a single line of user input.
 199         bool
 200         GetLine (std::string &line, bool &interrupted);
 201
 202         /// Prompts for and reads a multi-line batch of user input.
 203         bool
 204         GetLines (int first_line_number, StringList &lines, bool &interrupted);
 205
 206         void
 207         PrintAsync (Stream *stream, const char *s, size_t len);
 208
 209     private:
 210
 211         /// Sets the lowest line number for multi-line editing sessions.  A value of zero suppresses
 212         /// line number printing in the prompt.
 213         void
 214         SetBaseLineNumber (int line_number);
 215
 216         /// Returns the complete prompt by combining the prompt or continuation prompt with line numbers
 217         /// as appropriate.  The line index is a zero-based index into the current multi-line session.
 218         std::string
 219         PromptForIndex (int line_index);
 220
 221         /// Sets the current line index between line edits to allow free movement between lines.  Updates
 222         /// the prompt to match.
 223         void
 224         SetCurrentLine (int line_index);
 225
 226         /// Determines the width of the prompt in characters.  The width is guaranteed to be the same for
 227         /// all lines of the current multi-line session.
 228         int
 229         GetPromptWidth();
 230
 231         /// Returns true if the underlying EditLine session's keybindings are Emacs-based, or false if
 232         /// they are VI-based.
 233         bool
 234         IsEmacs();
 235
 236         /// Returns true if the current EditLine buffer contains nothing but spaces, or is empty.
 237         bool
 238         IsOnlySpaces();
 239
 240         /// Helper method used by MoveCursor to determine relative line position.
 241         int
 242         GetLineIndexForLocation (CursorLocation location, int cursor_row);
 243
 244         /// Move the cursor from one well-established location to another using relative line positioning
 245         /// and absolute column positioning.
 246         void
 247         MoveCursor (CursorLocation from, CursorLocation to);
 248
 249         /// Clear from cursor position to bottom of screen and print input lines including prompts, optionally
 250         /// starting from a specific line.  Lines are drawn with an extra space at the end to reserve room for
 251         /// the rightmost cursor position.
 252         void
 253         DisplayInput (int firstIndex = 0);
 254
 255         /// Counts the number of rows a given line of content will end up occupying, taking into account both
 256         /// the preceding prompt and a single trailing space occupied by a cursor when at the end of the line.
 257         int
 258         CountRowsForLine (const EditLineStringType & content);
 259
 260         /// Save the line currently being edited
 261         void
 262         SaveEditedLine();
 263
 264         /// Convert the current input lines into a UTF8 StringList
 265         StringList
 266         GetInputAsStringList(int line_count = UINT32_MAX);
 267
 268         /// Replaces the current multi-line session with the next entry from history.  When the parameter is
 269         /// true it will take the next earlier entry from history, when it is false it takes the next most
 270         /// recent.
 271         unsigned char
 272         RecallHistory (bool earlier);
 273
 274         /// Character reading implementation for EditLine that supports our multi-line editing trickery.
 275         int
 276         GetCharacter (EditLineCharType * c);
 277
 278         /// Prompt implementation for EditLine.
 279         const char *
 280         Prompt();
 281
 282         /// Line break command used when return is pressed in multi-line mode.
 283         unsigned char
 284         BreakLineCommand (int ch);
 285
 286         /// Delete command used when delete is pressed in multi-line mode.
 287         unsigned char
 288         DeleteNextCharCommand (int ch);
 289
 290         /// Delete command used when backspace is pressed in multi-line mode.
 291         unsigned char
 292         DeletePreviousCharCommand (int ch);
 293
 294         /// Line navigation command used when ^P or up arrow are pressed in multi-line mode.
 295         unsigned char
 296         PreviousLineCommand (int ch);
 297
 298         /// Line navigation command used when ^N or down arrow are pressed in multi-line mode.
 299         unsigned char
 300         NextLineCommand (int ch);
 301
 302         /// Buffer start command used when Esc < is typed in multi-line emacs mode.
 303         unsigned char
 304         BufferStartCommand (int ch);
 305
 306         /// Buffer end command used when Esc > is typed in multi-line emacs mode.
 307         unsigned char
 308         BufferEndCommand (int ch);
 309
 310         /// Context-sensitive tab insertion or code completion command used when the tab key is typed.
 311         unsigned char
 312         TabCommand (int ch);
 313
 314         /// Respond to normal character insertion by fixing line indentation
 315         unsigned char
 316         FixIndentationCommand (int ch);
 317
 318         /// Revert line command used when moving between lines.
 319         unsigned char
 320         RevertLineCommand (int ch);
 321
 322         /// Ensures that the current EditLine instance is properly configured for single or multi-line editing.
 323         void
 324         ConfigureEditor (bool multiline);
 325
 326     private:
 327 #if LLDB_EDITLINE_USE_WCHAR
 328         std::wstring_convert<std::codecvt_utf8<wchar_t>> m_utf8conv;
 329 #endif
 330         ::EditLine * m_editline = nullptr;
 331         EditlineHistorySP m_history_sp;
 332         bool m_in_history = false;
 333         std::vector<EditLineStringType> m_live_history_lines;
 334         bool m_multiline_enabled = false;
 335         std::vector<EditLineStringType> m_input_lines;
 336         EditorStatus m_editor_status;
 337         bool m_color_prompts = true;
 338         int m_terminal_width = 0;
 339         int m_base_line_number = 0;
 340         unsigned m_current_line_index = 0;
 341         int m_current_line_rows = -1;
 342         int m_revert_cursor_index = 0;
 343         int m_line_number_digits = 3;
 344         std::string m_set_prompt;
 345         std::string m_set_continuation_prompt;
 346         std::string m_current_prompt;
 347         bool m_needs_prompt_repaint = false;
 348         std::string m_editor_name;
 349         FILE * m_input_file;
 350         FILE * m_output_file;
 351         FILE * m_error_file;
 352         ConnectionFileDescriptor m_input_connection;
 353         IsInputCompleteCallbackType m_is_input_complete_callback = nullptr;
 354         void * m_is_input_complete_callback_baton = nullptr;
 355         FixIndentationCallbackType m_fix_indentation_callback = nullptr;
 356         void * m_fix_indentation_callback_baton = nullptr;
 357         const char * m_fix_indentation_callback_chars = nullptr;
 358         CompleteCallbackType m_completion_callback = nullptr;
 359         void * m_completion_callback_baton = nullptr;
 360
 361         Mutex m_output_mutex;
 362     };
 363 }
 364
 365 #endif  // #if defined(__cplusplus)
 366 #endif  // liblldb_Editline_h_