ncdirect_init: add flags parameter #976

NEWS.md

@@ -3,6 +3,8 @@ rearrangements of Notcurses.
 
 * 1.7.0 (2020-08-30)
   * Added `notcurses_ucs32_to_utf8()` conversion helper.
+  * `ncdirect_init()` now takes a third `uint64_t flags` parameter. No flags
+    have been defined, and this parameter ought be set to 0.
 
 * 1.6.20 (2020-08-30)
   * Added convenience functions `ncplane_y()` and `ncplane_x()`, components

USAGE.md

@@ -283,9 +283,10 @@ struct ncdirect; // minimal state for a terminal
 // 'fp' must be a tty. You'll usually want stdout. Direct mode supportes a
 // limited subset of notcurses routines which directly affect 'fp', and neither
 // supports nor requires notcurses_render(). This can be used to add color and
-// styling to text in the standard output paradigm. Returns NULL on error,
-// including any failure initializing terminfo.
-struct ncdirect* ncdirect_init(const char* termtype, FILE* fp);
+// styling to text in the standard output paradigm. No flags are yet defined;
+// 'flags' should be set to 0.
+// Returns NULL on error, including any failure initializing terminfo.
+struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t flags);
 
 // Release 'nc' and any associated resources. 0 on success, non-0 on failure.
 int ncdirect_stop(struct ncdirect* nc);

doc/man/man3/notcurses_directmode.3.md

@@ -10,7 +10,7 @@ ncdirect_init - minimal notcurses instances for styling text
 
 **#include <notcurses/direct.h>**
 
-**struct ncdirect* ncdirect_init(const char* termtype, FILE* fp);**
+**struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t flags);**
 
 **unsigned ncdirect_palette_size(const struct ncdirect* nc);**
 
@@ -83,6 +83,9 @@ terminal and free up resources. **ncdirect_init** places the terminal into
 input. **ncdirect_stop** restores the terminal state as it was when the
 corresponding **ncdirect_init** call was made.
 
+The **flags** parameter to **ncdirect_init** does not yet have any flags
+defined, and should be passed as 0 for now.
+
 An appropriate **terminfo(5)** entry must exist for the terminal. This entry is
 usually selected using the value of the **TERM** environment variable (see
 **getenv(3)**), but a non-**NULL** value for **termtype** will override this. An

include/ncpp/Direct.hh

@@ -18,7 +18,7 @@ namespace ncpp
 		explicit Direct (const char *termtype = nullptr, FILE *fp = nullptr, NotCurses *ncinst = nullptr)
 			: Root (ncinst)
 		{
-			direct = ncdirect_init (termtype, fp == nullptr ? stdout : fp);
+			direct = ncdirect_init (termtype, fp == nullptr ? stdout : fp, 0);
 			if (direct == nullptr)
 				throw init_error ("Notcurses failed to initialize direct mode");
 		}

include/notcurses/direct.h

@@ -13,9 +13,10 @@ extern "C" {
 // 'fp' must be a tty. You'll usually want stdout. Direct mode supportes a
 // limited subset of notcurses routines which directly affect 'fp', and neither
 // supports nor requires notcurses_render(). This can be used to add color and
-// styling to text in the standard output paradigm. Returns NULL on error,
-// including any failure initializing terminfo.
-API struct ncdirect* ncdirect_init(const char* termtype, FILE* fp);
+// styling to text in the standard output paradigm. No flags are yet defined;
+// 'flags' should be set to 0.
+// Returns NULL on error, including any failure initializing terminfo.
+API struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t flags);
 
 // Direct mode. This API can be used to colorize and stylize output generated
 // outside of notcurses, without ever calling notcurses_render(). These should

python/src/notcurses/build_notcurses.py

@@ -405,7 +405,7 @@ int ncplane_puttext(struct ncplane* n, int y, ncalign_e align, const char* text,
 int ncplane_putnstr_yx(struct ncplane* n, int y, int x, size_t s, const char* gclusters);
 int ncplane_putnstr_aligned(struct ncplane* n, int y, ncalign_e align, size_t s, const char* gclustarr);
 int ncplane_qrcode(struct ncplane* n, ncblitter_e blitter, int* ymax, int* xmax, const void* data, size_t len);
-struct ncdirect* ncdirect_init(const char* termtype, FILE* fp);
+struct ncdirect* ncdirect_init(const char* termtype, FILE* fp, uint64_t flags);
 int ncdirect_bg_rgb(struct ncdirect* n, unsigned r, unsigned g, unsigned b);
 int ncdirect_fg_rgb(struct ncdirect* n, unsigned r, unsigned g, unsigned b);
 unsigned ncdirect_palette_size(const struct ncdirect* nc);

python/src/notcurses/notcurses.py

@@ -172,7 +172,7 @@ class Notcurses:
 
 class Ncdirect:
     def __init__(self):
-        self.nc = lib.ncdirect_init(ffi.NULL, sys.stdout)
+        self.nc = lib.ncdirect_init(ffi.NULL, sys.stdout, 0)
 
     def __del__(self):
         lib.ncdirect_stop(self.nc)

rust/src/direct.rs

@@ -53,7 +53,7 @@ extern "C" {
 /// This can be used to add color and styling to text in the standard output paradigm.
 /// Returns NULL on error, including any failure initializing terminfo.
 pub unsafe fn ncdirect_start() -> *mut DirectMode {
-    nc::ncdirect_init(core::ptr::null(), libc_stdout())
+    nc::ncdirect_init(core::ptr::null(), libc_stdout(), 0)
 }
 
 #[cfg(test)]

rust/src/lib.rs

@@ -84,7 +84,7 @@ mod tests {
     fn create_direct_context() {
         unsafe {
             let _ = libc::setlocale(libc::LC_ALL, CString::new("").unwrap().as_ptr());
-            let nc = nc::ncdirect_init(null_mut(), null_mut());
+            let nc = nc::ncdirect_init(null_mut(), null_mut(), 0);
             nc::ncdirect_stop(nc);
         }
     }

src/demo/demo.c

@@ -551,7 +551,7 @@ int main(int argc, char** argv){
       fprintf(stderr, "Warning: error closing renderfile\n");
     }
   }
-  struct ncdirect* ncd = ncdirect_init(NULL, stdout);
+  struct ncdirect* ncd = ncdirect_init(NULL, stdout, 0);
   if(!ncd){
     return EXIT_FAILURE;
   }

src/fetch/main.c

@@ -469,7 +469,7 @@ int main(void){
   if(setlocale(LC_ALL, "") == NULL){
     fprintf(stderr, "Warning: couldn't set locale based off LANG\n");
   }
-  struct ncdirect* nc = ncdirect_init(NULL, NULL);
+  struct ncdirect* nc = ncdirect_init(NULL, NULL, 0);
   if(nc == NULL){
     return EXIT_FAILURE;
   }

src/lib/direct.cpp

@@ -417,7 +417,10 @@ int get_controlling_tty(FILE* ttyfp){
   return open(cbuf, O_RDWR | O_CLOEXEC);
 }
 
-ncdirect* ncdirect_init(const char* termtype, FILE* outfp){
+ncdirect* ncdirect_init(const char* termtype, FILE* outfp, uint64_t flags){
+  if(flags){ // allow them through with warning
+    logwarn((struct notcurses*)NULL, "Passed non-zero flags 0x%016jx, but no flags are defined\n", (uintmax_t)flags);
+  }
   if(outfp == nullptr){
     outfp = stdout;
   }

src/poc/direct-input.c

@@ -4,7 +4,7 @@
 #include <notcurses/direct.h>
 
 int main(void){
-  struct ncdirect* n = ncdirect_init(NULL, NULL);
+  struct ncdirect* n = ncdirect_init(NULL, NULL, 0);
   if(n == NULL){
     return EXIT_FAILURE;
   }

src/poc/direct.c

@@ -14,7 +14,7 @@ int main(void){
     return EXIT_FAILURE;
   }
   struct ncdirect* n; // see bug #391
-  if((n = ncdirect_init(NULL, stdout)) == NULL){
+  if((n = ncdirect_init(NULL, stdout, 0)) == NULL){
     return EXIT_FAILURE;
   }
   int dimy = ncdirect_dim_y(n);

src/poc/dirgb.c

@@ -56,7 +56,7 @@ int main(void){
   if(!setlocale(LC_ALL, "")){
     return EXIT_FAILURE;
   }
-  struct ncdirect* nc = ncdirect_init(NULL, stdout);
+  struct ncdirect* nc = ncdirect_init(NULL, stdout, 0);
   if(!nc){
     return EXIT_FAILURE;
   }

src/poc/dirlines.c

@@ -6,7 +6,7 @@ int main(void){
   if(!setlocale(LC_ALL, "")){
     return EXIT_FAILURE;
   }
-  struct ncdirect* n = ncdirect_init(NULL, stdout);
+  struct ncdirect* n = ncdirect_init(NULL, stdout, 0);
   putchar('\n');
   for(int i = 0 ; i < 15 ; ++i){
     uint64_t c1 = 0, c2 = 0;

src/poc/sgr-direct.c

@@ -8,7 +8,7 @@ int main(void){
   if(!setlocale(LC_ALL, "")){
     return EXIT_FAILURE;
   }
-  struct ncdirect* nc = ncdirect_init(NULL, stdout);
+  struct ncdirect* nc = ncdirect_init(NULL, stdout, 0);
   if(!nc){
     return EXIT_FAILURE;
   }

src/poc/vizdirect.c

@@ -9,7 +9,7 @@ int main(void){
     return EXIT_FAILURE;
   }
   struct ncdirect* n; // see bug #391
-  if((n = ncdirect_init(NULL, stdout)) == NULL){
+  if((n = ncdirect_init(NULL, stdout, 0)) == NULL){
     return EXIT_FAILURE;
   }
   if(!ncdirect_canopen_images(n)){

tests/direct.cpp

@@ -2,7 +2,7 @@
 #include <notcurses/direct.h>
 
 TEST_CASE("DirectMode") {
-  struct ncdirect* nc_ = ncdirect_init(NULL, stderr);
+  struct ncdirect* nc_ = ncdirect_init(NULL, stdout, 0);
   if(!nc_){
     return;
   }
@@ -29,4 +29,12 @@ TEST_CASE("DirectMode") {
   }
 
   CHECK(0 == ncdirect_stop(nc_));
+
+  // make sure that we can pass undefined flags and still create the ncdirect
+  SUBCASE("FutureFlags") {
+    nc_ = ncdirect_init(NULL, stdout, ~0ULL);
+    REQUIRE(nullptr != nc_);
+    CHECK(0 == ncdirect_stop(nc_));
+  }
+
 }