[elpa] externals/drepl aeba86f820 10/10: Add readme and commentary

[ELPA Syncer]

branch: externals/drepl
commit aeba86f820437026b9835cd3e2527ffb85506682
Author: Augusto Stoffel <arstoffel@gmail.com>
Commit: Augusto Stoffel <arstoffel@gmail.com>

    Add readme and commentary
---
 README.org       | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 drepl-ipython.el |   4 +-
 drepl-lua.el     |   3 +-
 drepl.el         |  11 ++++-
 4 files changed, 143 insertions(+), 3 deletions(-)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..ad234140ad
--- /dev/null
+++ b/README.org
@@ -0,0 +1,128 @@
+#+title: dREPL
+
+dREPL is a collection of fully featured language shells for Emacs.  At
+the moment it supports the following interpreters:
+
+- *Python:* requires [[https://pypi.org/project/ipython/][IPython]].
+- *Lua:* requires [[https://luarocks.org/modules/hoelzro/luarepl][luarepl]] 
and [[https://luarocks.org/modules/dhkolf/dkjson][dkjson]].
+
+The following features are available, subject to variations across
+different REPLs (IPython supports all of them):
+
+- [X] Completion, including annotations and also on continuation lines
+- [X] Multi-line input editing
+- [X] Eldoc integration
+- [X] Normal pty interaction during code evaluation (e.g. debuggers)
+- [X] Graphics support via 
[[https://github.com/astoff/comint-mime][comint-mime]]
+- [ ] Remote interpreters via Tramp
+- [ ] Persistent history
+
+In fancier terms, dREPL can be described as a REPL protocol for the
+dumb terminal.  One Elisp library defines the user interface and the
+client code; support for a new programming language requires only
+writing some backend code in the target language, plus a tiny bit of
+glue code in Elisp.  If the target language provides a good embeddable
+REPL library, then the backend implementation is also reasonably
+straightforward.
+
+** Usage
+
+To start a REPL, use one of the =M-x drepl-run-*= commands (making
+sure first that you have the target language dependencies installed,
+as described above).  The rest should look familiar.
+
+It is also possible to interact with a REPL from another buffer, say
+to evaluate a region of text.  The relevant commands are the
+following:
+
+- =drepl-associate=: By default, dREPL tries to guess which REPL is
+  the right one for any given buffer; an error is raised if there is
+  no good guess.  In this case, you can manually create an association
+  with this command.
+- =drepl-pop-to-repl=: Go to the REPL associated (implicitly or
+  explicitly) to the current buffer.
+- =drepl-eval=: Evaluate a string read from the minibuffer.
+- =drepl-eval-region= and =drepl-eval-buffer=: Evaluate text of the
+  current buffer.
+- =drepl-restart=: Restart the interpreter.  In IPython this is a soft
+  reset; use a prefix argument to kill and start again the
+  interpreter.
+
+Documentation on a symbol in the REPL buffer, if available, can be
+accessed with =eldoc-doc-buffer=.
+
+** Protocol
+
+This package extends Comint and so the communication between Emacs and
+the interpreter happens through a pseudoterminal.  The conundrum is
+how to multiplex control messages and regular IO.
+
+- From the subprocess to Emacs, control messages travel in JSON
+  objects inside an OSC escape sequence (code 5161).
+- From Emacs to the subprocess, control messages are passed as lines
+  of the form =ESC % <JSON object> LF=.
+
+At any given point in time, the subprocess expects either a framed
+messages like this or regular IO.  Emacs keeps track of the state of
+the subprocess through status notifications as described below.
+
+There are three types of message: /requests/, to which a /response/ is
+expected, and /notifications/, to which no response is expected.  A
+message contains the following fields:
+
+- =op=: The operation name.  It must be present in every notification
+  and request but is absent in response messages.
+- =id=: A unique number which should be present in every request and
+  repeated in the response message.  It is absent in notification
+  messages.
+- Further fields are parameters specific to each type of request,
+  notification or response.
+
+The following operations are defined:
+
+- =status=: Interpreter notification with one parameter, =status=.
+  The value can be =ready= (subprocess is expecting a framed
+  message) or =busy= (IO, if it occurs, should not be framed).
+
+- =eval=: Editor request with one argument, the string =code=.  The
+  REPL should evaluate the code, print the result, and send an empty
+  response.
+
+- =complete=: Editor request with arguments =code= and =offset=.  The
+  interpreter returns possible completions of the code at the given
+  position.  The response has one item, =candidates=, which is a list
+  of objects containing:
+  - =text=: The completed text, including existing prefix.
+  - =annot=: Annotation text to be displayed next to the candidate in
+    the completion UI.
+
+- =checkinput=: Editor request with one argument, the string =code=.
+  The interpreter returns:
+  - =status=: One of =complete= (the code is valid), =incomplete=
+    (the code is syntactically invalid, but may become so by adding
+    more text) or =invalid= (there is a syntax error in the existing
+    portion of code).
+  - =indent=: If present, this is the expected indentation of a
+    continuation line, as a string.
+  - =prompt=: The prompt of a continuation line.
+
+- =describe=: Editor request to obtain information on the symbol at
+  point.  The parameters are =code= and =offset=.  The response can
+  include any of the following:
+  - =name=: The symbol name.
+  - =type=: The symbol type or function signature.
+  - =text=: Free-form documentation on the symbol.
+
+- =setoptions=: Editor request to set configuration options.  The
+  parameters are arbitrary and interpreter-specific.  The interpreter
+  must send an empty response.
+
+- =getoptions=: Interpreter notification to request a =setoptions=
+  notification.
+
+** Why
+
+This package is intended to do what the good old Comint does, but
+polishing some rough edges.  For example, completion in Comint is
+spotty and one is able to edit only the last line of a multi-line
+input.
diff --git a/drepl-ipython.el b/drepl-ipython.el
index 7faabcdd52..4ec2f9e997 100644
--- a/drepl-ipython.el
+++ b/drepl-ipython.el
@@ -20,7 +20,9 @@
 
 ;;; Commentary:
 
-;; 
+;; This file defines a REPL based on the IPython interpreter.  It
+;; depends on Python and the ipython package, which can be installed
+;; with `pip install ipython'.
 
 ;;; Code:
 
diff --git a/drepl-lua.el b/drepl-lua.el
index 855db81c1e..42c8ec9c0b 100644
--- a/drepl-lua.el
+++ b/drepl-lua.el
@@ -20,7 +20,8 @@
 
 ;;; Commentary:
 
-;; 
+;; This file defines a REPL for Lua.  The required Lua packages can be
+;; installed with `luarocks install dkjson luarepl'.
 
 ;;; Code:
 
diff --git a/drepl.el b/drepl.el
index c02f8dfc91..1c6bd71f88 100644
--- a/drepl.el
+++ b/drepl.el
@@ -20,7 +20,16 @@
 
 ;;; Commentary:
 
-;; 
+;; dREPL is a collection of fully featured language shells for Emacs
+;; built on top of Comint.  It can be described as a REPL protocol for
+;; the dumb terminal.  This file defines the user interface and a base
+;; EIEIO class for client code.  The other files in this package
+;; define REPLs for specific interpreters.  Each of them is comprised
+;; of one Elisp file defining a REPL subclass and one file in the
+;; target programming language implementing the server side of the
+;; protocol.
+
+;; See the README for a description of the communication protocol.
 
 ;;; Code: