From d89d8c52e9b80ca8114586e1b7915f2a33b4db51 Mon Sep 17 00:00:00 2001 From: nick black Date: Sat, 9 May 2020 04:45:51 -0400 Subject: [PATCH] notcurses_options: add flags field --- NEWS.md | 5 +++++ USAGE.md | 16 ++++++++++++++++ doc/man/man3/notcurses_init.3.md | 16 ++++++++++++++++ include/notcurses/notcurses.h | 16 ++++++++++++++++ 4 files changed, 53 insertions(+) diff --git a/NEWS.md b/NEWS.md index 41e183520..7d959a006 100644 --- a/NEWS.md +++ b/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 diff --git a/USAGE.md b/USAGE.md index 5326d4aa6..36055fe56 100644 --- a/USAGE.md +++ b/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 diff --git a/doc/man/man3/notcurses_init.3.md b/doc/man/man3/notcurses_init.3.md index b75a36609..d6cdb2aad 100644 --- a/doc/man/man3/notcurses_init.3.md +++ b/doc/man/man3/notcurses_init.3.md @@ -11,6 +11,8 @@ notcurses_init - initialize a notcurses instance **#include ** ```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)**, diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index 9af09a3db..f71316570 100644 --- a/include/notcurses/notcurses.h +++ b/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