notcurses_options: add flags field

NEWS.md

@@ -16,6 +16,11 @@ rearrangements of Notcurses.
   * `NULL` can now be passed as the `FILE*` argument to `notcurses_init()` and
     `ncdirect_init()`. In this case, a new `FILE*` will be created using
     `/dev/tty`. If the `FILE*` cannot be created, an error will be returned.
+  * A `flags` field has been added to `notcurses_options`. This will allow new
+    boolean options to be added in the future without resizing the structure.
+    Define `NCOPTION_INHIBIT_SETLOCALE` bit. If it's not set, and the "C" or
+    "POSIX" locale is in use, `notcurses_init()` will invoke
+    `setlocale(LC_ALL, "")`.
 
 * 1.3.4 (2020-05-07)
   * `notcurses_lex_margins()` has been added to lex margins expressed in either

USAGE.md

@@ -67,6 +67,18 @@ typedef enum {
   NCLOGLEVEL_TRACE,   // there's probably a better way to do what you want
 } ncloglevel_e;
 
+// Bits for notcurses_options->flags
+
+// notcurses_init() will call setlocale() to inspect the current locale. If
+// that locale is "C" or "POSIX", it will call setlocale(LC_ALL, "") to set
+// the locale according to the LANG environment variable. Ideally, this will
+// result in UTF8 being enabled, even if the client app didn't call
+// setlocale() itself. Unless you're certain that you're invoking setlocale() 
+// prior to notcurses_init(), you should not set this bit. Even if you are
+// invoking setlocale(), this behavior shouldn't be an issue unless you're
+// doing something weird (setting a locale not based on LANG).
+#define NCOPTION_INHIBIT_SETLOCALE 0x0001
+
 // Configuration for notcurses_init().
 typedef struct notcurses_options {
   // The name of the terminfo database entry describing this terminal. If NULL,
@@ -100,6 +112,10 @@ typedef struct notcurses_options {
   // strictly best-effort. Absolute coordinates are relative to the rendering
   // area ((0, 0) is always the origin of the rendering area).
   int margin_t, margin_r, margin_b, margin_l;
+  // General flags; see NCOPTION_*. This is expressed as a bitfield so that
+  // future options can be added without reshaping the struct. Undefined bits
+  // must be set to 0.
+  unsigned flags;
 } notcurses_options;
 
 // Lex a margin argument according to the standard notcurses definition. There

doc/man/man3/notcurses_init.3.md

@@ -11,6 +11,8 @@ notcurses_init - initialize a notcurses instance
 **#include <notcurses/notcurses.h>**
 
 ```c
+#define NCOPTION_INHIBIT_SETLOCALE 0x0001
+
 typedef struct notcurses_options {
   const char* termtype;
   bool inhibit_alternate_screen;
@@ -20,6 +22,7 @@ typedef struct notcurses_options {
   bool no_winch_sighandler;
   FILE* renderfp;
   int margin_t, margin_r, margin_b, margin_l;
+  unsigned flags; // from NCOPTION_* bits
 } notcurses_options;
 ```
 
@@ -77,6 +80,18 @@ margin argument expression in one of two forms:
 * a single number, which will be applied to all sides, or
 * four comma-delimited numbers, applied to top, right, bottom, and left.
 
+To allow future options without requiring redefinition of the structure, the
+**flags** field is only a partially-defined bitfield. Undefined bits must be
+zero. The following flags are defined:
+
+* **NCOPTION_INHIBIT_SETLOCALE**: Unless this flag is set, **notcurses_init**
+    will call **setlocale(LC_ALL, NULL)**. If the result is either "**C**" or
+    "**POSIX**", it will print a diagnostic to **stder**, and then call
+    **setlocale(LC_ALL, "").** This will attempt to set the locale based off
+    the **LANG** environment variable. Your program should call **setlocale(3)**
+    itself, usually as one of the first lines.
+
+
 ## Fatal signals
 
 It is important to reset the terminal before exiting, whether terminating due
@@ -131,6 +146,7 @@ across the new screen geometry.
 # SEE ALSO
 
 **getenv(3)**,
+**setlocale(3)**,
 **termios(3)**,
 **notcurses(3)**,
 **notcurses_input(3)**,

include/notcurses/notcurses.h

@@ -752,6 +752,18 @@ typedef enum {
   NCLOGLEVEL_TRACE,   // there's probably a better way to do what you want
 } ncloglevel_e;
 
+// Bits for notcurses_options->flags.
+
+// notcurses_init() will call setlocale() to inspect the current locale. If
+// that locale is "C" or "POSIX", it will call setlocale(LC_ALL, "") to set
+// the locale according to the LANG environment variable. Ideally, this will
+// result in UTF8 being enabled, even if the client app didn't call
+// setlocale() itself. Unless you're certain that you're invoking setlocale() 
+// prior to notcurses_init(), you should not set this bit. Even if you are
+// invoking setlocale(), this behavior shouldn't be an issue unless you're
+// doing something weird (setting a locale not based on LANG).
+#define NCOPTION_INHIBIT_SETLOCALE 0x0001
+
 // Configuration for notcurses_init().
 typedef struct notcurses_options {
   // The name of the terminfo database entry describing this terminal. If NULL,
@@ -785,6 +797,10 @@ typedef struct notcurses_options {
   // strictly best-effort. Absolute coordinates are relative to the rendering
   // area ((0, 0) is always the origin of the rendering area).
   int margin_t, margin_r, margin_b, margin_l;
+  // General flags; see NCOPTION_*. This is expressed as a bitfield so that
+  // future options can be added without reshaping the struct. Undefined bits
+  // must be set to 0.
+  unsigned flags;
 } notcurses_options;
 
 // Lex a margin argument according to the standard notcurses definition. There