ncdirect: prep readline for use #1120

CMakeLists.txt

@@ -77,6 +77,9 @@ set_package_properties(Threads PROPERTIES TYPE REQUIRED)
 pkg_search_module(TERMINFO REQUIRED tinfo>=6.1 ncursesw>=6.1)
 set_property(GLOBAL APPEND PROPERTY PACKAGES_FOUND terminfo)
 set_package_properties(terminfo PROPERTIES TYPE REQUIRED)
+pkg_search_module(READLINE REQUIRED readline>=8.0)
+set_property(GLOBAL APPEND PROPERTY PACKAGES_FOUND readline)
+set_package_properties(readline PROPERTIES TYPE REQUIRED)
 if(${USE_FFMPEG})
 pkg_check_modules(AVCODEC REQUIRED libavcodec>=57.0)
 pkg_check_modules(AVFORMAT REQUIRED libavformat>=57.0)
@@ -139,16 +142,19 @@ target_include_directories(notcurses
     include
     "${PROJECT_BINARY_DIR}/include"
     "${TERMINFO_INCLUDE_DIRS}"
+    "${READLINE_INCLUDE_DIRS}"
 )
 target_include_directories(notcurses-static
   PRIVATE
     include
     "${PROJECT_BINARY_DIR}/include"
     "${TERMINFO_STATIC_INCLUDE_DIRS}"
+    "${READLINE_STATIC_INCLUDE_DIRS}"
 )
 target_link_libraries(notcurses
   PRIVATE
     "${TERMINFO_LIBRARIES}"
+    "${READLINE_LIBRARIES}"
     "${LIBRT}"
     unistring
   PUBLIC
@@ -157,6 +163,7 @@ target_link_libraries(notcurses
 target_link_libraries(notcurses-static
   PRIVATE
     "${TERMINFO_STATIC_LIBRARIES}"
+    "${READLINE_STATIC_LIBRARIES}"
     "${LIBRT}"
     unistring
   PUBLIC
@@ -165,10 +172,12 @@ target_link_libraries(notcurses-static
 target_link_directories(notcurses
   PRIVATE
     "${TERMINFO_LIBRARY_DIRS}"
+    "${READLINE_LIBRARY_DIRS}"
 )
 target_link_directories(notcurses-static
   PRIVATE
     "${TERMINFO_STATIC_LIBRARY_DIRS}"
+    "${READLINE_STATIC_LIBRARY_DIRS}"
 )
 
 if(${USE_QRCODEGEN})

NEWS.md

@@ -5,6 +5,9 @@ rearrangements of Notcurses.
   * `ncplane_putstr_yx()`, `ncplane_putstr_stained()`, and
     `ncplane_putnstr_yx()` now return the number of columns output, as
     long documented (they were mistakenly returning the number of bytes).
+  * Notcurses now depends on GNU Readline at build and runtime, entirely
+    for the benefit of direct mode, which now prepares GNU Readline for safe
+    use (unless the new `NCDIRECT_OPTIONS_NO_READLINE` is used).
 
 * 2.1.4 (2021-01-03):
   * Direct mode now supports `NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS`, and by

README.md

@@ -102,10 +102,14 @@ portability, you should by all means use that fine library.
 
 ## Requirements
 
+Minimum versions generally indicate the oldest version I've tested with; it
+may well be possible to use still older versions. Let me know of any successes!
+
 * (build) A C11 and a C++17 compiler
 * (build) CMake 3.14.0+
 * (build+runtime) From [NCURSES](https://invisible-island.net/ncurses/announce.html): terminfo 6.1+
 * (build+runtime) GNU [libunistring](https://www.gnu.org/software/libunistring/) 0.9.10+
+* (build+runtime) GNU [Readline](https://www.gnu.org/software/libunistring/) 8.0+
 * (OPTIONAL) (build+runtime) From QR-Code-generator: [libqrcodegen](https://github.com/nayuki/QR-Code-generator) 1.5.0+
 * (OPTIONAL) (build+runtime) From [FFmpeg](https://www.ffmpeg.org/): libswscale 5.0+, libavformat 57.0+, libavutil 56.0+
 * (OPTIONAL) (build+runtime) [OpenImageIO](https://github.com/OpenImageIO/oiio) 2.15.0+
@@ -375,7 +379,7 @@ to breaking under incorrect `TERM` values. If you're not using `xterm`, your
 
 * **Q:** When my program exits, I don't have a cursor, or text is invisible, or colors are weird, <i>ad nauseam</i>. **A:** Ensure you're calling `notcurses_stop()`/`ncdirect_stop()` on all exit paths, including fatal signals.
 
-* **Q:** How can I use Direct Mode in conjunction with libreadline? **A:** Pass `NCDIRECT_OPTION_CBREAK` to `ncdirect_init()`, call `ncdirect_init()` prior to calling `rl_prep_terminal()`, and call `rl_deprep_terminal()` before calling `ncdirect_stop()`. But you should probably just use a Notcurses `ncreader`, if possible.
+* **Q:** How can I use Direct Mode in conjunction with libreadline? **A:** Pass `NCDIRECT_OPTION_CBREAK` to `ncdirect_init()`, and ensure you do not pass `NCDIRECT_OPTION_NO_READLINE`. If you'd like, set `rl_readline_name` and `rl_attempted_completion_function` prior to calling `ncdirect_init()`. With that said, consider using a Notcurses `ncreader`.
 
 * **Q:** Will there ever be Java wrappers? **A:** I should hope not.
 

doc/man/man3/notcurses_directmode.3.md

@@ -13,6 +13,7 @@ ncdirect_init - minimal notcurses instances for styling text
 
 #define NCDIRECT_OPTION_INHIBIT_SETLOCALE   0x0001ull
 #define NCDIRECT_OPTION_INHIBIT_CBREAK      0x0002ull
+#define NCDIRECT_OPTION_NO_READLINE         0x0004ull
 #define NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS 0x0008ull
 ```
 
@@ -107,6 +108,10 @@ The following flags are defined:
     will place the terminal into cbreak mode (i.e. disabling echo and line
     buffering; see **tcgetattr(3)**).
 
+* **NCDIRECT_OPTION_NO_READLINE**: Unless this flag is set, **ncdirect_init**
+    will initialize GNU Readline so that it can be safely used together with
+    direct mode. With this flag, no calls are made to GNU Readline.
+
 * **NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS**: A signal handler will usually be
     installed for **SIGINT**, **SIGQUIT**, **SIGSEGV**, **SIGTERM**, and
     **SIGABRT**, cleaning up the terminal on such exceptions. With this flag,
@@ -150,7 +155,8 @@ All other functions return 0 on success, and non-zero on error.
 # SEE ALSO
 
 **getenv(3)**,
-**termios(3)**,
+**readline(3)**
 **notcurses(3)**,
 **notcurses_plane(3)**,
-**terminfo(5)**
+**terminfo(5)**,
+**termios(3)**

include/notcurses/direct.h

@@ -25,6 +25,11 @@ typedef struct ncplane ncdirectv;
 // echo and input's line buffering are turned off.
 #define NCDIRECT_OPTION_INHIBIT_CBREAK      0x0002ull
 
+// We typically initialize the GNU Readline library in a way that works with
+// ncdirect. If you intend no use of GNU Readline, this flag will inhibit any
+// such setup/teardown.
+#define NCDIRECT_OPTION_NO_READLINE         0x0004ull
+
 // We typically install a signal handler for SIG{INT, SEGV, ABRT, QUIT} that
 // restores the screen, and then calls the old signal handler. Set to inhibit
 // registration of these signal handlers. Chosen to match fullscreen mode.

src/lib/direct.cpp

@@ -4,6 +4,7 @@
 #include <cstring>
 #include <unistd.h>
 #include <termios.h>
+#include <readline/readline.h>
 #include "version.h"
 #include "visual-details.h"
 #include "notcurses/direct.h"
@@ -614,6 +615,9 @@ ncdirect_stop_minimal(void* vnc){
     }
     ret |= close(nc->ctermfd);
   }
+  if(!(nc->flags & NCDIRECT_OPTION_NO_READLINE)){
+    rl_deprep_terminal();
+  }
   return ret;
 }
 
@@ -673,6 +677,11 @@ ncdirect* ncdirect_init(const char* termtype, FILE* outfp, uint64_t flags){
   }
   ret->channels = 0;
   ncdirect_set_styles(ret, 0);
+  if(!(flags & NCDIRECT_OPTION_NO_READLINE)){
+    rl_outstream = outfp;
+    rl_instream = stdin;
+    rl_prep_terminal(1); // 1 == read 8-bit input
+  }
   return ret;
 
 err: