console.lua: add this script

Merged from mpv-repl git repo commit 5ea2bf64f9c239f0326b02. Some
changes were made on top of it:

- Tabs were converted to 4 spaces indentation (plus some manual
  indentation fixes in some places).
- All user-visible mentions of "repl" were renamed to "console".
- The README was converted to a manpage (with heavy changes, some
  additions taken from stats.rst; rossy converted the key bindings
  table to RST).
- The method to change the default key binding was changed.
- Change minor detail about "font" default value setting (not a
  functional change).
- Integrate into the player as builtin script, including an option to
  prevent loading it.

Above changes and commit message done by wm4.

Signed-off-by: wm4 <wm4@nowhere>

3 files changed, 112 insertions, 0 deletions

diff --git a/DOCS/man/console.rst b/DOCS/man/console.rst
new file mode 100644
index 0000000000..89726b72a6
--- /dev/null
+++ b/DOCS/man/console.rst
@@ -0,0 +1,104 @@
+CONSOLE
+=======
+
+The console is a REPL for mpv input commands. It is displayed on the video
+window. It also shows log messages. It can be disabled entirely using the
+``--load-osd-console=no`` option.
+
+Keybindings
+-----------
+
+\`
+    Show the console.
+
+ESC
+    Hide the console.
+
+ENTER
+    Run the typed command.
+
+Shift+ENTER
+    Type a literal newline character.
+
+Ctrl+LEFT and Ctrl+RIGHT
+    Move cursor to previous/next word.
+
+UP and DOWN
+    Navigate command history.
+
+PGUP
+    Go to the first command in the history.
+
+PGDN
+    Stop navigating command history.
+
+INSERT
+    Toggle insert mode.
+
+Shift+INSERT
+    Paste text (uses the primary selection on X11.)
+
+TAB
+    Complete the command or property name at the cursor.
+
+Ctrl+C
+    Clear current line.
+
+Ctrl+K.
+    Delete text from the cursor to the end of the line.
+
+Ctrl+L
+    Clear all log messages from the console.
+
+Ctrl+U
+    Delete text from the cursor to the beginning of the line.
+
+Ctrl+V
+    Paste text (uses the clipboard on X11.)
+
+Ctrl+W
+    Delete text from the cursor to the beginning of the current word.
+
+Commands
+--------
+
+``script-message-to console type <text>``
+    Show the console and pre-fill it with the provided text.
+
+Known issues
+------------
+
+- Pasting text is slow on Windows
+- Non-ASCII keyboard input has restrictions
+- The cursor keys move between Unicode code-points, not grapheme clusters
+
+Configuration
+-------------
+
+This script can be customized through a config file ``script-opts/console.conf``
+placed in mpv's user directory and through the ``--script-opts`` command-line
+option. The configuration syntax is described in `ON SCREEN CONTROLLER`_.
+
+Key bindings can be changed in a standard way, see for example stats.lua
+documentation.
+
+Configurable Options
+~~~~~~~~~~~~~~~~~~~~
+
+``scale``
+    Default: 1
+
+    All drawing is scaled by this value, including the text borders and the
+    cursor. Change it if you have a high-DPI display.
+
+``font``
+    Default: unset (picks a hardcoded font depending on detected platform)
+
+    Set the font used for the REPL and the console. This probably doesn't
+    have to be a monospaced font.
+
+``font_size``
+    Default: 16
+
+    Set the font size used for the REPL and the console. This will be
+    multiplied by "scale."
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 3eb46ebdff..e41e992072 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -991,6 +991,8 @@ works like in older mpv releases. The profiles are currently defined as follows:
 
 .. include:: stats.rst
 
+.. include:: console.rst
+
 .. include:: lua.rst
 
 .. include:: javascript.rst
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 86a72f1ce0..9335d69b63 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -847,6 +847,12 @@ Program Behavior
     binding (default: yes). By default, the ``i`` key is used (``I`` to make
     the overlay permanent).
 
+``--load-osd-console=<yes|no>``
+    Enable the builtin script that shows a console on a key binding and lets
+    you enter commands (default: yes). By default,. The ``´`` key is used to
+    show the console, and ``ESC`` to hide it again. (This is based on  a user
+    script called ``repl.lua``.)
+
 ``--player-operation-mode=<cplayer|pseudo-gui>``
     For enabling "pseudo GUI mode", which means that the defaults for some
     options are changed. This option should not normally be used directly, but