eat-emacs/README.org

#+title: Eat: Emulate A Terminal

Eat's name self-explainary, it stands for "Emulate A Terminal".  Eat
is a terminal emulator.  It can run most (if not all) full-screen
terminal programs, including Emacs.

It is pretty fast, more than three times faster than Term, despite
being implemented entirely in Emacs Lisp.  So fast that you can
comfortably run Emacs inside Eat, or even use your Emacs as a terminal
multiplexer.

It has many features that other Emacs terminal emulator still don't
have, for example complete mouse support, shell integration, etc.

It flickers less than other Emacs terminal emulator, so you get more
performance and a smooth experience.

To get the most out of Eat, you should also setup shell integration.

* Usage

To start Eat, run =M-x eat=.  Eat has three keybinding modes:

- "emacs" mode: No special keybinding, except the following:

  - =C-c C-j=: Switch to semi-char mode.
  - =C-c M-d=: Switch to char mode.
  - =C-c C-k=: Kill process.

- "semi-char" mode: Most keys are bound to send the key to the
  terminal, except the following keys: =C-\=, =C-c=, =C-x=, =C-g=,
  =C-h=, =C-M-c=, =C-u=, =C-q=, =M-x=, =M-:=, =M-!=, =M-&=.  The
  following special keybinding are available:

  - =C-q=: Send next key to the terminal.
  - =C-y=: Like `yank', but send the text to the terminal.
  - =M-y=: Like `yank-pop', but send the text to the terminal.
  - =C-c C-k=: Kill process.

- "char" mode: All supported keys are bound to send the key to the
  terminal, except =C-M-m= or =M-RET=, which is bound to switch to
  semi-char mode.

If you like Eshell, then there is a good news for you.  Eat integrates
with Eshell.  Eat has two global minor modes for Eshell:

- ~eat-eshell-visual-command-mode~: Run visual commands with Eat
  instead of Term.

- ~eat-eshell-mode~: Run Eat inside Eshell.  After enabling this, you
  can run full-screen terminal programs directly in Eshell.  You have
  the above three keybinding modes here too, except that =C-c C-k= is
  not special (i.e. not bound by Eat) in "emacs" mode and "line" mode.

You can add any of these to ~eshell-load-hook~ like the following:

#+begin_src emacs-lisp
;; For `eat-eshell-mode'.
(add-hook 'eshell-load-hook #'eat-eshell-mode)

;; For `eat-eshell-visual-command-mode'.
(add-hook 'eshell-load-hook #'eat-eshell-visual-command-mode)
#+end_src

To setup shell integration for GNU Bash, put the following at the end
of your ~.bashrc~:

#+begin_src sh
[ -n "$EAT_SHELL_INTEGRATION_DIR" ] && \
  source "$EAT_SHELL_INTEGRATION_DIR/bash"
#+end_src sh

* Installation

Eat requires at least Emacs 28.1 or above.

** NonGNU ELPA

Eat is available on NonGNU ELPA.  If you don't have the archive setup,
put something like the following in your init file:

#+begin_src emacs-lisp
(add-to-list 'package-archives
             '("nongnu" . "https://elpa.nongnu.org/nongnu/"))
#+end_src

** Quelpa

#+begin_src emacs-lisp
(quelpa '(eat :fetcher git
              :url "/home/akib/projects/emacs-eat"
              :files ("*.el" ("term" "term/*.el") "*.texi"
                      "*.ti" ("terminfo/e" "terminfo/e/*")
                      ("terminfo/65" "terminfo/65/*")
                      ("integration" "integration/*")
                      (:exclude ".dir-locals.el" "*-tests.el"))))
#+end_src

** Manual

Clone the repository and put it in your ~load-path~.

* Comparison With Other Terminal Emulators

** Term

Term is the Emacs built-in terminal emulator.  Its terminal emulation
is pretty good too.  But it's slow.  It is so slow that Eat can beat
native-compiled Term even without byte-compilation, and when Eat is
byte-compiled, Eat is more than three times fast.  Also, Term
flickers, just try to run =emacs -nw= in it.  It doesn't support
remote connections, for example over Tramp.  However, it has "line"
mode, which Eat still doesn't have.  If you want line mode in a
terminal, or use an old version of Emacs, you can use Term, but
Coterm + Shell is probably a better choice in case your Emacs version
is 26.1 or above.

** Vterm

Vterm is powered by a C library, libvterm.  For this reason, it can
process huge amount of text quickly.  It is about 1.5 times faster
than Eat (byte-compiled or native-compiled) (and about 2.75 faster
then Eat without byte-compilation).  But it doesn't have a char mode
(however you can make a char mode spending some effort).  And it too
flickers like Term, so despite being much faster that Eat, it seems to
be slow.  If you need your terminal to handle huge bursts (megabytes)
of data, you should Vterm.

** Coterm + Shell

Coterm adds terminal emulation to Shell mode.  Although the terminal
Coterm emulates is same as Term, it is much faster, about three times,
just a bit slow than Eat.  However, it too flickers like other
terminals.  Since it's an upgrade to Shell, you get all the features
of Shell like "line" mode, completion using your favorite completion
UI (Company, Corfu, etc), etc.  Most of these features are available
in Eat-Eshell-Mode as Eshell is similar to Shell, however it's not
Shell mode.  Recommended if you like Shell.

* Acknowledgements

This wouldn't have been possible if the following awesome softwares
didn't exist:

- [[https://gnu.org][GNU Operating System]]
- [[https://st.suckless.org/][St]]
- [[https://sw.kovidgoyal.net/kitty/][Kitty]]
- [[https://invisible-island.net/xterm/][XTerm]]
- [[https://www.gnu.org/software/linux-libre/][Linux-libre]]
- [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Terminal-emulator.html][Term]]
- [[https://repo.or.cz/emacs-coterm.git][Coterm]]
- [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Interactive-Shell.html][Shell]]
- [[https://github.com/akermu/emacs-libvterm][Vterm]]
- [[https://www.gnu.org/software/emacs/manual/html_node/eshell/index.html][Eshell]]
- Numerous terminal programs
- And obviously, [[https://www.gnu.org/software/emacs/][GNU Emacs]]