src/lib/line_input/line_input.h

// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef SRC_LIB_LINE_INPUT_LINE_INPUT_H_
#define SRC_LIB_LINE_INPUT_LINE_INPUT_H_

#include <deque>
#include <map>
#include <string>
#include <vector>

#include "lib/fit/function.h"

#if !defined(__Fuchsia__)
struct termios;
#endif

namespace line_input {

struct SpecialCharacters {
  static constexpr char kKeyControlA = 1;
  static constexpr char kKeyControlB = 2;
  static constexpr char kKeyControlC = 3;
  static constexpr char kKeyControlD = 4;
  static constexpr char kKeyControlE = 5;
  static constexpr char kKeyControlF = 6;
  static constexpr char kKeyControlH = 8;
  static constexpr char kKeyTab = 9;
  static constexpr char kKeyNewline = 10;
  static constexpr char kKeyControlK = 11;
  static constexpr char kKeyFormFeed = 12;
  static constexpr char kKeyEnter = 13;
  static constexpr char kKeyControlN = 14;  // Down
  static constexpr char kKeyControlP = 16;  // Up
  static constexpr char kKeyControlR = 18;
  static constexpr char kKeyControlT = 20;
  static constexpr char kKeyControlU = 21;
  static constexpr char kKeyControlW = 23;
  static constexpr char kKeyEsc = 27;
  static constexpr char kKeyBackspace = 127;

  // Escape sequences for terminal output.
  static const char* kTermBeginningOfLine;
  static const char* kTermClearToEnd;
  static const char* kTermCursorToColFormat;  // printf format.
};

// Abtract base class for line input.
//
// This class implements a push model for input of characters, allowing it to be used in
// asynchronous contexts.
//
// The model is you create a LineInput class outside of the input loop. It encapsulates the history
// state and remembers the prompt. When you want to read a line:
//
//  1. Call Show().
//  2. Push data to it via OnInput().
//  3. On an accept callback:
//     3a. Handle the input.
//     3b. Add line to history if desired.
//  4. Repeat until done.
//  5. Call Hide() to put the terminal back.
//
// If your application has data that it needs to print asynchronously, just:
//  1. Call Hide().
//  2. Print the stuff you want.
//  3. Call Show().
class LineInput {
 public:
  virtual ~LineInput() = default;

  // Called with the user input when the user acceps a line. This takes a copy because the accept
  // callback can often modify the command history which in turn owns the string being edited and
  // accepted.
  using AcceptCallback = fit::function<void(std::string)>;

  // Called when the current line changes. This is not called for <Enter> which doesn't change
  // anything but will call the AcceptCallback. As in AcceptCallback, this takes a copy.
  using ChangeCallback = fit::function<void(std::string)>;

  // Given some typing, returns a prioritized list of completions.
  using AutocompleteCallback = fit::function<std::vector<std::string>(const std::string&)>;

  // Callback that indicates Control-C or EOF (Control-D) was typed.
  using CancelCallback = fit::function<void()>;
  using EofCallback = fit::function<void()>;

  // Setup -----------------------------------------------------------------------------------------

  // Provides the callback for tab completion.
  virtual void SetAutocompleteCallback(AutocompleteCallback cb) = 0;

  // Provides the callback for when the current line changes.
  virtual void SetChangeCallback(ChangeCallback cb) = 0;

  // Provides the callback for handling Control-C. If unset, "^C" will be echoed and the line
  // will be cleared.
  virtual void SetCancelCallback(CancelCallback cb) = 0;

  // Provides the callback for handling EOF. If unset EOF will be ignored.
  virtual void SetEofCallback(EofCallback cb) = 0;

  // Sets the maximum width of a line. Beyond this the input will scroll. Setitng to 0 will disable
  // horizontal scrolling.
  virtual void SetMaxCols(size_t max) = 0;

  // Querying --------------------------------------------------------------------------------------

  // Returns the current input text.
  virtual const std::string& GetLine() const = 0;

  // Returns the current history. The most resent input is at the begin().
  virtual const std::deque<std::string>& GetHistory() const = 0;

  // State -----------------------------------------------------------------------------------------

  // Provides one character of input to the editor. Callbacks for autocomplete or line done will be
  // issued from within this function.
  virtual void OnInput(char c) = 0;

  // Adds the given line to history. If the history is longer than max_history_, the oldest thing
  // will be deleted.
  //
  // AddToHistory should be called on startup before the initial Show() call, or from within the
  // accept callback (typically you would add the current line at this point).
  virtual void AddToHistory(const std::string& line) = 0;

  // Whether the input should handle interruptions (e.g., handle Ctrl-C by calling the cancel
  // callback and handle Ctrl-D by calling EOF callbacks) while hidden.
  enum class InterruptHandlingBehavior {
    // Handle input interuptions in-band, such as Ctrl-C and Ctrl-D.
    kHandleInterrupts,

    // Ignore input interruptions, for example letting the pty route Ctrl-C to the shell.
    kIgnoreInterrupts,
  };

  // The input can be hidden and re-shown. Hiding it will erase the current line and put the cursor
  // at the beginning of the line, but not change any internal state. Showing it again will repaint
  // the line at the new cursor position. This allows other output to be printed to the screen
  // without interfering with the input.
  //
  // Hiding or showing when it's already in that state will do nothing. There is not a reference
  // count on the hide calls.
  //
  // OnInput() should not be called while hidden.
  //
  // Tip: When the application is done (the user types "quit" or whatever), call Hide() from within
  // the AcceptCallback or EofCallback. This will ensure the prompt isn't repainted when the
  // callback is complete only to be rehidden on exit (which will cause flickering).
  virtual void Hide(
      InterruptHandlingBehavior behavior = InterruptHandlingBehavior::kHandleInterrupts) = 0;
  virtual void Show() = 0;

  // Replaces the contents of the current line with the given contents. The cursor will be placed
  // at the end of the text. Any changes in editing history will be reset.
  //
  // This bypasses handling of any special characters and input and any such
  // characters will be included as literals on the line. This will issue any changed callbacks.
  virtual void SetCurrentInput(const std::string& input) = 0;
};

// Implementation of LineInput that implements the editing state. Output is still abstract to
// allow for output to different places.
class LineInputEditor : public LineInput {
 public:
  explicit LineInputEditor(AcceptCallback accept_cb, const std::string& prompt);
  virtual ~LineInputEditor();

  // LineInput implementation.
  void SetAutocompleteCallback(AutocompleteCallback cb) override;
  void SetChangeCallback(ChangeCallback cb) override;
  void SetCancelCallback(CancelCallback cb) override;
  void SetEofCallback(EofCallback cb) override;
  void SetMaxCols(size_t max) override;
  const std::string& GetLine() const override;
  const std::deque<std::string>& GetHistory() const override;
  void OnInput(char c) override;
  void AddToHistory(const std::string& line) override;
  void Hide(
      InterruptHandlingBehavior behavior = InterruptHandlingBehavior::kHandleInterrupts) override;
  void Show() override;
  void SetCurrentInput(const std::string& input) override;

  size_t pos() const { return pos_; }

  bool in_reverse_history_mode() const { return reverse_history_mode_; }
  size_t reverse_history_index() const { return reverse_history_index_; }

  // Exposed for testing purposes.
  std::string GetReverseHistoryPrompt() const;
  std::string GetReverseHistorySuggestion() const;

 protected:
  enum TerminalMode {
    // The original mode of the terminal when we started. Used for putting it back when we exit.
    kOriginalMode,

    // Raw input and output. Used for active line input.
    kRawInOutMode,

    // Raw input only. Output will be formatted as normal in a terminal. Used when the input is
    // hidden so the app may print with normal behavior but input is still raw. This prevents
    // echoing input to the terminal when we're not processing it, and Control-C from exiting the
    // app out from under us.
    kRawInMode,
  };

  // Sets the terminal mode to the given value if necessary.
  virtual void EnsureTerminalMode(TerminalMode mode) {}

  // Abstract output function, overridden by a derived class to output to screen.
  virtual void Write(const std::string& data) = 0;

  // Helper to return the current line of text as an editable string. This uses the overlay provided
  // by editing_history and falls back to promoting the value from persistent_history_.
  //
  // Use the const GetLine() on the base class to avoid the promotion if the returned value will
  // not be modified.
  std::string& mutable_cur_line() {
    if (auto found = editing_history_.find(history_index_); found != editing_history_.end())
      return found->second;

    // Make the permanent history line mutable by copying to the editing history.
    return editing_history_[history_index_] = persistent_history_[history_index_];
  }

  // Useful for testing.
  void set_pos(size_t pos) { pos_ = pos; }

  const std::string& prompt() const { return prompt_; }
  void set_prompt(std::string prompt) { prompt_ = std::move(prompt); }

 private:
  void HandleEscapedInput(char c);

  void HandleBackspace();
  void HandleDelete();
  // FormFeed is the name of Ctrl-L in ASCII world.
  void HandleFormFeed();
  void HandleEnter();
  void HandleTab();
  // NegAck is the name of Ctrl-U in ASCII world.
  void HandleNegAck();
  // EndOfTransimission is the name for Ctrl-W in ASCII world.
  void HandleEndOfTransimission();
  // EndOfFile means Ctrl-D with an empty input line.
  void HandleEndOfFile();

  // ReverseHistory means Ctrl-R.
  void HandleReverseHistory(char c);
  void StartReverseHistoryMode();
  void EndReverseHistoryMode(bool accept_suggestion);
  void SearchNextReverseHistory(bool restart);

  void Insert(char c);
  void MoveLeft();
  void MoveRight();
  void MoveUp();
  void MoveDown();
  void MoveHome();
  void MoveEnd();

  void TransposeLastTwoCharacters();
  void CancelCommand();
  void DeleteToEnd();

  void CancelCompletion();
  void AcceptCompletion();

  // Issues a line change notification and repaints the current line.
  void LineChanged();

  // Repaints the current line without issuing a line change notification.
  void RepaintLine();

  void ResetLineState();

  AcceptCallback accept_callback_;
  ChangeCallback change_callback_;  // Possibly null.
  std::string prompt_;

  size_t max_cols_ = 0;
  AutocompleteCallback autocomplete_callback_;  // Possibly null.
  CancelCallback cancel_callback_;              // Possibly null;.
  EofCallback eof_callback_;                    // Possibly null;.

  // Indicates whether the line is currently visible (as controlled by Show()/Hide()).
  bool visible_ = false;

  // The history is basically the line stack going back in time as indices increase. There are two
  // versions of history: the permanent history of stuff the user has typed, and the editing history
  // which is where temporary modifications are made until something is accepted.
  //
  // The editing history shadows the permanent history so the user can move up and down and edit
  // different items in history, seeing those edits as they move up and down. But when a new history
  // item is added, those edits are all cleared and the history represents what was actually input
  // at each point. Only the line that was input is kept, and that's saved only by adding it to the
  // front of history. This temporary shadow copy of history where edits occur matches the behavior
  // of other popular line input libraries.
  //
  // Use GetLine() to get a const view of the current line.  Use mutable_cur_line() to get a mutable
  // version of the current line (promotes to editable). Avoid changing the strings in these
  // structures outside of mutable_cur_line().
  std::deque<std::string> persistent_history_;  // front() is newest.
  size_t history_index_ = 0;                    // Offset from persistent_history_.front().
  const size_t max_history_ = 256;
  std::map<size_t, std::string> editing_history_;  // Indices override items in persistent_history_.

  bool completion_mode_ = false;
  std::vector<std::string> completions_;
  size_t completion_index_ = 0;

  // Tracks the current line's state before suggesting completions so we can
  // put them back if necessary. Only valid when completion_mode_ = true.
  std::string line_before_completion_;
  size_t pos_before_completion_ = 0;

  // When an escape is read, we enter "escaped input" mode which interprets the
  // next few characters input as an escape sequence.
  bool reading_escaped_input_ = false;
  std::string escape_sequence_;

  bool reverse_history_mode_ = false;
  std::string reverse_history_input_;

  // Index within history the reverse search suggestion current is. 0 means not found, as that is
  // pointing to the current line, which we don't want to do a history search in.
  size_t reverse_history_index_ = 0;

  size_t pos_ = 0;  // Current editing position.
};

// Implementation of LineInput that prints to stdout. The caller is still responsible for providing
// input asynchronously. The initial width of the output will be automatically derived from the
// terminal associated wit, as that is pointing to the current line, which we don't want to do a
// history search in. stdout (if any).
class LineInputStdout : public LineInputEditor {
 public:
  LineInputStdout(AcceptCallback accept_cb, const std::string& prompt);
  ~LineInputStdout() override;

 protected:
  // LineInputEditor implementation.
  void EnsureTerminalMode(TerminalMode mode) override;
  void Write(const std::string& str) override;

 private:
#if !defined(__Fuchsia__)
  // The terminal is converted into raw mode when the prompt is visible and accepting input. Then
  // it's switched back. This block tracks that information. Use unique_ptr to avoid bringing all
  // terminal headers into this header.
  TerminalMode terminal_mode_ = kOriginalMode;
  std::unique_ptr<termios> original_termios_;
  std::unique_ptr<termios> raw_inout_termios_;
  std::unique_ptr<termios> raw_in_termios_;
#endif
};

}  // namespace line_input

#endif  // SRC_LIB_LINE_INPUT_LINE_INPUT_H_