rust: more changes and improvements

- raw field of new wrapping structs is now public just to the crate.
- NcNotcurses.stdplane method now doesn't return an NcResult since it can't fail.
- rename NcNotcurses to Notcurses and NcNotcursesOptions to NotcursesOptions.
- rename NcPlane::new_termsize constructor to with_termsize.
- bump MSV to 1.48 for the doc links.
- improve lib documentation.
- minor fixes.

rust/README.md

@@ -3,4 +3,4 @@
 [![Crate](https://img.shields.io/crates/v/libnotcurses-sys.svg)](https://crates.io/crates/libnotcurses-sys)
 [![API](https://docs.rs/libnotcurses-sys/badge.svg)](https://dankamongmen.github.io/notcurses/rustdoc/libnotcurses_sys/)
 [![dependency status](https://deps.rs/crate/libnotcurses-sys/2.1.2/status.svg)](https://deps.rs/crate/libnotcurses-sys/2.1.2)
-[![MSRV: 1.47.0](https://flat.badgen.net/badge/MSRV/1.47.0/purple)](https://blog.rust-lang.org/2020/10/08/Rust-1.47.html)
+[![MSRV: 1.48.0](https://flat.badgen.net/badge/MSRV/1.48.0/purple)](https://blog.rust-lang.org/2020/11/19/Rust-1.48.html)

rust/examples/full-basics.rs

@@ -2,7 +2,7 @@ use libnotcurses_sys::*;
 
 fn main() -> NcResult<()> {
     let mut nc = FullMode::new()?;
-    let stdplane = nc.stdplane()?;
+    let stdplane = nc.stdplane();
 
     for ch in "Initializing cells...".chars() {
         let cell = NcCell::with_char7b(ch);

rust/examples/poc-cjkscroll.rs

@@ -4,7 +4,7 @@ use libnotcurses_sys::*;
 
 fn main() -> NcResult<()> {
     let mut nc = FullMode::new()?;
-    let plane = nc.stdplane()?;
+    let plane = nc.stdplane();
     plane.set_scrolling(true);
 
     let mut wc = '\u{4e00}'; // 一

rust/examples/poc-menu.rs

@@ -34,7 +34,7 @@ fn main() -> NcResult<()> {
     mopts.section_channels_mut().set_fg_rgb(0xb0d700);
     mopts.section_channels_mut().set_bg_rgb(0x002000);
 
-    let stdplane = nc.stdplane()?;
+    let stdplane = nc.stdplane();
     let (dim_y, _dim_x) = stdplane.dim_yx();
 
     let menu_top = NcMenu::new(stdplane, mopts)?;
@@ -75,7 +75,7 @@ fn main() -> NcResult<()> {
 fn run_menu(nc: &mut FullMode, menu: &mut NcMenu) -> NcResult<()> {
     // yellow rectangle
     let planeopts = NcPlaneOptions::new_aligned(10, NCALIGN_CENTER, 3, 40);
-    let stdplane = nc.stdplane()?;
+    let stdplane = nc.stdplane();
     let selplane = NcPlane::with_options_bound(stdplane, planeopts)?;
     selplane.set_fg_rgb(0);
     selplane.set_bg_rgb(0xdddddd);

rust/src/direct/wrapper.rs

@@ -11,7 +11,7 @@ use crate::{
 /// Safely wraps an [NcDirect],
 /// and implements Drop, AsRef, AsMut, Deref & DerefMut around it.
 pub struct DirectMode<'a> {
-    raw: &'a mut NcDirect,
+    pub(crate) raw: &'a mut NcDirect,
 }
 
 impl<'a> AsRef<NcDirect> for DirectMode<'a> {

rust/src/fade.rs

@@ -11,7 +11,7 @@
 
 use std::ffi::c_void;
 
-use crate::{NcIntResult, NcNotcurses, NcPlane, NcTime};
+use crate::{NcIntResult, Notcurses, NcPlane, NcTime};
 
 /// Called for each fade iteration on the NcPlane.
 ///
@@ -20,7 +20,7 @@ use crate::{NcIntResult, NcNotcurses, NcPlane, NcTime};
 ///
 /// The recommended absolute display time target is passed in 'tspec'.
 pub type NcFadeCb = Option<
-    unsafe extern "C" fn(*mut NcNotcurses, *mut NcPlane, *const NcTime, *mut c_void) -> NcIntResult,
+    unsafe extern "C" fn(*mut Notcurses, *mut NcPlane, *const NcTime, *mut c_void) -> NcIntResult,
 >;
 
 /// Context for a palette fade operation

rust/src/lib.rs

@@ -5,42 +5,45 @@
 //!
 //! # How to use this library
 //!
-//! Since this library is built with several layers of zero-overhead
-//! abstractions over the FFI functions, there are multiple ways to use it.
+//! This library is built with several layers of zero-overhead abstractions
+//! over the FFI functions and pointers.
 //!
-//! But basically there are two ways:
+//! There are basically two ways:
 //!
 //! ## 1. The Rust way
 //!
-//! Use the safely wrapped types, their methods and constructors:
+//! Is preferible to use the safely wrapped types, with methods and constructors:
 //!
 //! ```rust
 //! use libnotcurses_sys::*;
 //!
 //! fn main() -> NcResult<()> {
 //!     let mut nc = FullMode::with_flags(NCOPTION_NO_ALTERNATE_SCREEN)?;
-//!     let plane = nc.stdplane()?;
+//!     let plane = nc.stdplane();
 //!     plane.putstr("hello world")?;
 //!     nc.render()?;
 //!     Ok(())
 //! }
 //! ```
-//! Specifically, and for example:
+//! Specifically:
 //!
-//! [`FullMode`] is the safe wrapper over [`NcNotcurses`], which is the
-//! `&mut` reference over the raw `*mut` pointer received from FFI.
+//! [`FullMode`] and [`DirectMode`] are safe wrappers over [`Notcurses`]
+//! and [`NcDirectMode`][NcDirectMode], respectively.
 //!
-//! FullMode implements the [Drop], [AsRef], [AsMut], [Deref][std::ops::Deref]
-//! & [DerefMut][std::ops::DerefMut] traits.
+//! FullMode and DirectMode both implement the [Drop], [AsRef], [AsMut],
+//! [Deref][std::ops::Deref] and [DerefMut][std::ops::DerefMut] traits.
 //!
-//! Most methods are directly implemented for NcNotcurses,
-//! and automatically available also from FullMode.
+//! Most methods are directly implemented for Notcurses and NcDirect,
+//! are also automatically made available to FullMode & DirectMode,
+//! minus some function overrides, like their destructors,
+//! plus the associated functions that had to be recreated.
 //!
-//! The destructor ([notcurses_stop()]) is called automatically at the end
-//! of its scope, so you don't ever have to call it by hand.
+//! Their destructors are called automatically at the end of their scope.
 //!
-//! The Rust style methods manage errors by means of returning an
-//! [`NcResult`]`<T, `[`NcError`]`>`, for painless handling.
+//! Error handling is painless using [`NcResult`] as the return type.
+//!
+//! The rest of the objects allocated by notcurses, like NcPlane, NcMenu…
+//! don't implement Drop, and have to be `*_destroy()`ed manually.
 //!
 //! ## 2. The C way
 //!
@@ -74,8 +77,8 @@
 //! ```
 //! It requires the use of unsafe.
 //!
-//! The C style functions handle errors by the means of returning an i32 value
-//! aliased to [NcIntResult].
+//! Error handling requires to check the returned [NcIntResult],
+//! or in case of a pointer, comparing it to [null_mut()][core::ptr::null_mut].
 //!
 //! ## The `notcurses` C API docs
 //!

rust/src/macros.rs

@@ -5,7 +5,7 @@
 
 #[allow(unused_imports)]
 // enjoy briefer doc comments
-use crate::{NcDirect, NcError, NcNotcurses, NcResult, NCRESULT_ERR, NCRESULT_OK};
+use crate::{NcDirect, NcError, Notcurses, NcResult, NCRESULT_ERR, NCRESULT_OK};
 
 // Sleep, Render & Flush Macros ------------------------------------------------
 
@@ -32,9 +32,9 @@ macro_rules! sleep {
     };
 }
 
-/// NcNotcurses.[render][NcNotcurses#method.render]\(`nc`\)? plus [sleep]!(`sleep_args`).
+/// Notcurses.[render][Notcurses#method.render]\(`nc`\)? plus [sleep]!(`sleep_args`).
 ///
-/// Renders the `$nc` [NcNotcurses] object and, if there's no error,
+/// Renders the `$nc` [Notcurses] object and, if there's no error,
 /// calls the sleep macro with the rest of the arguments.
 ///
 /// Returns [NcResult].
@@ -42,7 +42,7 @@ macro_rules! sleep {
 macro_rules! rsleep {
     ($nc:expr, $( $sleep_args:expr),+ ) => {
         // Rust style, with methods & NcResult
-        NcNotcurses::render($nc)?;
+        Notcurses::render($nc)?;
         sleep![$( $sleep_args ),+];
     };
     ($nc:expr, $( $sleep_args:expr),+ ,) => {

rust/src/notcurses/helpers.rs

@@ -1,10 +1,10 @@
-use crate::{notcurses_init, NcNotcurses, NcNotcursesOptions, NCOPTION_SUPPRESS_BANNERS};
+use crate::{notcurses_init, Notcurses, NotcursesOptions, NCOPTION_SUPPRESS_BANNERS};
 
-/// Helper function for initializing NcNotcurses on C style tests.
+/// Helper function for initializing Notcurses on C style tests.
 #[allow(dead_code)]
-pub(crate) unsafe fn notcurses_init_test<'a>() -> &'a mut NcNotcurses {
+pub(crate) unsafe fn notcurses_init_test<'a>() -> &'a mut Notcurses {
     &mut *notcurses_init(
-        &NcNotcursesOptions::with_flags(NCOPTION_SUPPRESS_BANNERS),
+        &NotcursesOptions::with_flags(NCOPTION_SUPPRESS_BANNERS),
         core::ptr::null_mut(),
     )
 }

rust/src/notcurses/methods.rs

@@ -1,22 +1,22 @@
-//! `NcNotcurses*` methods and associated functions.
+//! `Notcurses*` methods and associated functions.
 
 use core::ptr::{null, null_mut};
 
 use crate::{
     cstring, error, error_ref_mut, notcurses_init, rstring, NcAlign, NcBlitter, NcChannelPair,
-    NcDimension, NcEgc, NcError, NcFile, NcInput, NcLogLevel, NcNotcurses, NcNotcursesOptions,
+    NcDimension, NcEgc, NcError, NcFile, NcInput, NcLogLevel, Notcurses, NotcursesOptions,
     NcPlane, NcResult, NcScale, NcSignalSet, NcStats, NcStyleMask, NcTime,
     NCOPTION_NO_ALTERNATE_SCREEN, NCOPTION_SUPPRESS_BANNERS, NCRESULT_ERR,
 };
 
-/// # `NcNotcursesOptions` Constructors
-impl NcNotcursesOptions {
-    /// New NcNotcursesOptions.
+/// # `NotcursesOptions` Constructors
+impl NotcursesOptions {
+    /// New NotcursesOptions.
     pub const fn new() -> Self {
         Self::with_all_options(0, 0, 0, 0, 0, 0)
     }
 
-    /// New NcNotcursesOptions, with margins.
+    /// New NotcursesOptions, with margins.
     pub const fn with_margins(
         top: NcDimension,
         right: NcDimension,
@@ -26,12 +26,12 @@ impl NcNotcursesOptions {
         Self::with_all_options(0, top, right, bottom, left, 0)
     }
 
-    /// New NcNotcursesOptions, with flags.
+    /// New NotcursesOptions, with flags.
     pub const fn with_flags(flags: u64) -> Self {
         Self::with_all_options(0, 0, 0, 0, 0, flags)
     }
 
-    /// New NcNotcursesOptions, with all the options.
+    /// New NotcursesOptions, with all the options.
     ///
     /// ## Arguments
     ///
@@ -83,46 +83,46 @@ impl NcNotcursesOptions {
     }
 }
 
-/// # `NcNotcurses` Constructors
-impl NcNotcurses {
-    /// New NcNotcurses (without banners).
-    pub fn new<'a>() -> NcResult<&'a mut NcNotcurses> {
+/// # `Notcurses` Constructors
+impl Notcurses {
+    /// New Notcurses (without banners).
+    pub fn new<'a>() -> NcResult<&'a mut Notcurses> {
         Self::with_flags(NCOPTION_SUPPRESS_BANNERS)
     }
 
-    /// New NcNotcurses, with banners.
+    /// New Notcurses, with banners.
     ///
     /// This is the default in the C library.
-    pub fn with_banners<'a>() -> NcResult<&'a mut NcNotcurses> {
+    pub fn with_banners<'a>() -> NcResult<&'a mut Notcurses> {
         Self::with_flags(0)
     }
 
-    /// New NcNotcurses, without an alternate screen (nor banners).
-    pub fn without_altscreen<'a>() -> NcResult<&'a mut NcNotcurses> {
+    /// New Notcurses, without an alternate screen (nor banners).
+    pub fn without_altscreen<'a>() -> NcResult<&'a mut Notcurses> {
         Self::with_flags(NCOPTION_NO_ALTERNATE_SCREEN | NCOPTION_SUPPRESS_BANNERS)
     }
 
-    /// New NcNotcurses, expects `NCOPTION_*` flags.
-    pub fn with_flags<'a>(flags: u64) -> NcResult<&'a mut NcNotcurses> {
-        Self::with_options(NcNotcursesOptions::with_flags(flags))
+    /// New Notcurses, expects `NCOPTION_*` flags.
+    pub fn with_flags<'a>(flags: u64) -> NcResult<&'a mut Notcurses> {
+        Self::with_options(NotcursesOptions::with_flags(flags))
     }
 
-    /// New NcNotcurses, expects [NcNotcursesOptions].
-    pub fn with_options<'a>(options: NcNotcursesOptions) -> NcResult<&'a mut NcNotcurses> {
+    /// New Notcurses, expects [NotcursesOptions].
+    pub fn with_options<'a>(options: NotcursesOptions) -> NcResult<&'a mut Notcurses> {
         let res = unsafe { notcurses_init(&options, null_mut()) };
-        error_ref_mut![res, "NcNotcurses.with_options()"]
+        error_ref_mut![res, "Notcurses.with_options()"]
     }
 
-    /// New NcNotcurses, expects [NcLogLevel] and flags.
-    pub fn with_debug<'a>(loglevel: NcLogLevel, flags: u64) -> NcResult<&'a mut NcNotcurses> {
-        Self::with_options(NcNotcursesOptions::with_all_options(
+    /// New Notcurses, expects [NcLogLevel] and flags.
+    pub fn with_debug<'a>(loglevel: NcLogLevel, flags: u64) -> NcResult<&'a mut Notcurses> {
+        Self::with_options(NotcursesOptions::with_all_options(
             loglevel, 0, 0, 0, 0, flags,
         ))
     }
 }
 
-/// # `NcNotcurses` methods
-impl NcNotcurses {
+/// # `Notcurses` methods
+impl Notcurses {
     /// Returns the offset into `availcols` at which `cols` ought be output given
     /// the requirements of `align`.
     ///
@@ -253,7 +253,7 @@ impl NcNotcurses {
         error![unsafe { crate::notcurses_cursor_enable(self, y as i32, x as i32) }]
     }
 
-    /// Dumps NcNotcurses state to the supplied `debugfp`.
+    /// Dumps Notcurses state to the supplied `debugfp`.
     ///
     /// Output is freeform, and subject to change. It includes geometry of all
     /// planes, from all piles.
@@ -353,7 +353,7 @@ impl NcNotcurses {
         } else {
             error![
                 -1,
-                &format!("NcNotcurses.getc_blocking({:?})", input_txt),
+                &format!("Notcurses.getc_blocking({:?})", input_txt),
                 res
             ]
         }
@@ -362,7 +362,7 @@ impl NcNotcurses {
     /// Gets a file descriptor suitable for input event poll()ing.
     ///
     /// When this descriptor becomes available, you can call
-    /// [getc_nblock()][NcNotcurses#method.getc_nblock], and input ought be ready.
+    /// [getc_nblock()][Notcurses#method.getc_nblock], and input ought be ready.
     ///
     /// This file descriptor is not necessarily the file descriptor associated
     /// with stdin (but it might be!).
@@ -383,13 +383,13 @@ impl NcNotcurses {
         ]
     }
 
-    /// Lexes a margin argument according to the standard NcNotcurses definition.
+    /// Lexes a margin argument according to the standard Notcurses definition.
     ///
     /// There can be either a single number, which will define all margins equally,
     /// or there can be four numbers separated by commas.
     ///
     /// *C style function: [notcurses_lex_margins()][crate::notcurses_lex_margins].*
-    pub fn lex_margins(op: &str, options: &mut NcNotcursesOptions) -> NcResult<()> {
+    pub fn lex_margins(op: &str, options: &mut NotcursesOptions) -> NcResult<()> {
         error![unsafe { crate::notcurses_lex_margins(cstring![op], options) }]
     }
 
@@ -432,13 +432,13 @@ impl NcNotcurses {
     /// Enable the mouse in "button-event tracking" mode with focus detection
     /// and UTF8-style extended coordinates.
     ///
-    /// On success, mouse events will be published to [getc()][NcNotcurses#method.getc].
+    /// On success, mouse events will be published to [getc()][Notcurses#method.getc].
     ///
     /// *C style function: [notcurses_mouse_enable()][crate::notcurses_mouse_enable].*
     pub fn mouse_enable(&mut self) -> NcResult<()> {
         error![
             unsafe { crate::notcurses_mouse_enable(self) },
-            "NcNotcurses.mouse_enable()"
+            "Notcurses.mouse_enable()"
         ]
     }
 
@@ -455,7 +455,7 @@ impl NcNotcurses {
 
     /// Refreshes the physical screen to match what was last rendered (i.e.,
     /// without reflecting any changes since the last call to
-    /// [render][crate::NcNotcurses#method.render]).
+    /// [render][crate::Notcurses#method.render]).
     ///
     /// This is primarily useful if the screen is externally corrupted, or if an
     /// [NCKEY_RESIZE][crate::NCKEY_RESIZE] event has been read and you're not
@@ -478,12 +478,12 @@ impl NcNotcurses {
     pub fn render(&mut self) -> NcResult<()> {
         error![
             unsafe { crate::notcurses_render(self) },
-            "NcNotcurses.render()"
+            "Notcurses.render()"
         ]
     }
 
     /// Performs the rendering and rasterization portion of
-    /// [render][NcNotcurses#method.render] but do not write the resulting buffer
+    /// [render][Notcurses#method.render] but do not write the resulting buffer
     /// out to the terminal.
     ///
     /// Using this function, the user can control the writeout process,
@@ -502,7 +502,7 @@ impl NcNotcurses {
 
     /// Writes the last rendered frame, in its entirety, to 'fp'.
     ///
-    /// If [render()][NcNotcurses#method.render] has not yet been called,
+    /// If [render()][Notcurses#method.render] has not yet been called,
     /// nothing will be written.
     ///
     /// *C style function: [notcurses_render_to_file()][crate::notcurses_render_to_file].*
@@ -510,7 +510,7 @@ impl NcNotcurses {
         error![unsafe { crate::notcurses_render_to_file(self, fp.as_nc_ptr()) }]
     }
 
-    /// Acquires an atomic snapshot of the NcNotcurses object's stats.
+    /// Acquires an atomic snapshot of the Notcurses object's stats.
     ///
     /// *C style function: [notcurses_stats()][crate::notcurses_stats].*
     pub fn stats(&mut self, stats: &mut NcStats) {
@@ -522,7 +522,7 @@ impl NcNotcurses {
     /// Allocates an ncstats object.
     ///
     /// Use this rather than allocating your own, since future versions of
-    /// NcNotcurses might enlarge this structure.
+    /// Notcurses might enlarge this structure.
     ///
     /// *C style function: [notcurses_stats_alloc()][crate::notcurses_stats_alloc].*
     pub fn stats_alloc<'a>(&'a mut self) -> &'a mut NcStats {
@@ -538,6 +538,8 @@ impl NcNotcurses {
         }
     }
 
+    // TODO: decide what to do with these two:
+    //
     // /// [notcurses_stdplane()][crate::notcurses_stdplane], plus free bonus
     // /// dimensions written to non-NULL y/x!
     // ///
@@ -551,7 +553,7 @@ impl NcNotcurses {
     //     crate::notcurses_stddim_yx(self, y, x)
     // }
 
-    // /// [stdplane_const()][NcNotcurses#method.stdplane_const], plus free
+    // /// [stdplane_const()][Notcurses#method.stdplane_const], plus free
     // /// bonus dimensions written to non-NULL y/x!
     // ///
     // /// *C style function: [notcurses_stddim_yx()][crate::notcurses_stddim_yx].*
@@ -570,11 +572,8 @@ impl NcNotcurses {
     /// uppermost, leftmost cell.
     ///
     /// *C style function: [notcurses_stdplane()][crate::notcurses_stdplane].*
-    pub fn stdplane<'a>(&mut self) -> NcResult<&'a mut NcPlane> {
-        error_ref_mut![
-            unsafe { crate::notcurses_stdplane(self) },
-            "NcNotcurses.stdplane()"
-        ]
+    pub fn stdplane<'a>(&mut self) -> &'a mut NcPlane {
+            unsafe { &mut *crate::notcurses_stdplane(self) }
     }
 
     /// Returns a reference to the standard [NcPlane] for this terminal.
@@ -587,7 +586,7 @@ impl NcNotcurses {
         unsafe { &*crate::notcurses_stdplane_const(self) }
     }
 
-    /// Destroys the NcNotcurses context.
+    /// Destroys the Notcurses context.
     ///
     /// *C style function: [notcurses_stop()][crate::notcurses_stop].*
     pub fn stop(&mut self) -> NcResult<()> {
@@ -641,7 +640,7 @@ impl NcNotcurses {
         rstring![crate::notcurses_version()].to_string()
     }
 
-    /// Returns the running NcNotcurses version components
+    /// Returns the running Notcurses version components
     /// (major, minor, patch, tweak).
     ///
     /// *C style function: [notcurses_version_components()][crate::notcurses_version_components].*

rust/src/notcurses/mod.rs

@@ -1,4 +1,4 @@
-//! `NcNotcurses`
+//! `Notcurses`
 
 // functions already exported by bindgen : 42
 // ------------------------------------------
@@ -74,14 +74,14 @@ pub(crate) use helpers::*;
 pub use reimplemented::*;
 pub use wrapper::*;
 
-/// NcNotcurses builds atop the terminfo abstraction layer to
+/// Notcurses builds atop the terminfo abstraction layer to
 /// provide reasonably portable vivid character displays.
 ///
 /// This is the internal type safely wrapped by [FullMode].
-pub type NcNotcurses = crate::bindings::ffi::notcurses;
+pub type Notcurses = crate::bindings::ffi::notcurses;
 
-/// Options struct for [`NcNotcurses`]
-pub type NcNotcursesOptions = crate::bindings::ffi::notcurses_options;
+/// Options struct for [`Notcurses`]
+pub type NotcursesOptions = crate::bindings::ffi::notcurses_options;
 
 /// Do not call setlocale()
 ///
@@ -97,17 +97,17 @@ pub const NCOPTION_INHIBIT_SETLOCALE: u64 = crate::bindings::ffi::NCOPTION_INHIB
 
 /// Do not enter alternate mode.
 ///
-/// If smcup/rmcup capabilities are indicated, NcNotcurses defaults to making use
+/// If smcup/rmcup capabilities are indicated, Notcurses defaults to making use
 /// of the "alternate screen". This flag inhibits use of smcup/rmcup.
 pub const NCOPTION_NO_ALTERNATE_SCREEN: u64 =
     crate::bindings::ffi::NCOPTION_NO_ALTERNATE_SCREEN as u64;
 
 /// Do not modify the font.
 ///
-/// NcNotcurses might attempt to change the font slightly, to support certain
+/// Notcurses might attempt to change the font slightly, to support certain
 /// glyphs (especially on the Linux console). If this is set, no such
 /// modifications will be made. Note that font changes will not affect anything
-/// but the virtual console/terminal in which NcNotcurses is running.
+/// but the virtual console/terminal in which Notcurses is running.
 pub const NCOPTION_NO_FONT_CHANGES: u64 = crate::bindings::ffi::NCOPTION_NO_FONT_CHANGES as u64;
 
 /// Do not handle SIG{ING, SEGV, ABRT, QUIT}
@@ -128,7 +128,7 @@ pub const NCOPTION_NO_WINCH_SIGHANDLER: u64 =
 
 /// Do not print banners
 ///
-/// NcNotcurses typically prints version info in notcurses_init() and performance
+/// Notcurses typically prints version info in notcurses_init() and performance
 /// info in notcurses_stop(). This inhibits that output.
 pub const NCOPTION_SUPPRESS_BANNERS: u64 = crate::bindings::ffi::NCOPTION_SUPPRESS_BANNERS as u64;
 
@@ -142,11 +142,11 @@ pub const NCOPTION_VERIFY_SIXEL: u64 = crate::bindings::ffi::NCOPTION_VERIFY_SIX
 
 // NcLogLevel ------------------------------------------------------------------
 
-/// Log level for [`NcNotcursesOptions`]
+/// Log level for [`NotcursesOptions`]
 ///
-/// These log levels consciously map cleanly to those of libav; NcNotcurses itself
+/// These log levels consciously map cleanly to those of libav; Notcurses itself
 /// does not use this full granularity. The log level does not affect the opening
-/// and closing banners, which can be disabled via the `NcNotcursesOptions`
+/// and closing banners, which can be disabled via the `NotcursesOptions`
 /// `NCOPTION_SUPPRESS_BANNERS`.
 /// Note that if stderr is connected to the same terminal on which we're
 /// rendering, any kind of logging will disrupt the output.

rust/src/notcurses/reimplemented.rs

@@ -3,7 +3,7 @@
 use core::ptr::{null, null_mut};
 
 use crate::{
-    NcAlign, NcDimension, NcError, NcInput, NcNotcurses, NcOffset, NcPlane, NcResult, NcSignalSet,
+    NcAlign, NcDimension, NcError, NcInput, Notcurses, NcOffset, NcPlane, NcResult, NcSignalSet,
     NcTime, NCALIGN_CENTER, NCALIGN_LEFT, NCALIGN_RIGHT, NCRESULT_ERR, NCRESULT_MAX,
 };
 
@@ -13,7 +13,7 @@ use crate::{
 /// Returns `-`[`NCRESULT_MAX`] if [NCALIGN_UNALIGNED][crate::NCALIGN_UNALIGNED]
 /// or invalid [NcAlign].
 ///
-/// *Method: NcNotcurses.[align()][NcNotcurses#method.align].*
+/// *Method: Notcurses.[align()][Notcurses#method.align].*
 #[inline]
 pub fn notcurses_align(availcols: NcDimension, align: NcAlign, cols: NcDimension) -> NcOffset {
     if align == NCALIGN_LEFT {
@@ -34,11 +34,11 @@ pub fn notcurses_align(availcols: NcDimension, align: NcAlign, cols: NcDimension
 ///
 /// If no event is ready, returns 0.
 ///
-/// *Method: NcNotcurses.[getc_nblock()][NcNotcurses#method.getc_nblock].*
+/// *Method: Notcurses.[getc_nblock()][Notcurses#method.getc_nblock].*
 //
 // TODO: use from_u32 & return Option.
 #[inline]
-pub fn notcurses_getc_nblock(nc: &mut NcNotcurses, input: &mut NcInput) -> char {
+pub fn notcurses_getc_nblock(nc: &mut Notcurses, input: &mut NcInput) -> char {
     unsafe {
         let mut sigmask = NcSignalSet::new();
         sigmask.fillset();
@@ -56,9 +56,9 @@ pub fn notcurses_getc_nblock(nc: &mut NcNotcurses, input: &mut NcInput) -> char
 ///
 /// In case of an invalid read (including on EOF) *-1 as char* is returned.
 ///
-/// *Method: NcNotcurses.[getc_blocking()][NcNotcurses#method.getc_blocking].*
+/// *Method: Notcurses.[getc_blocking()][Notcurses#method.getc_blocking].*
 #[inline]
-pub fn notcurses_getc_blocking(nc: &mut NcNotcurses, input: Option<&mut NcInput>) -> char {
+pub fn notcurses_getc_blocking(nc: &mut Notcurses, input: Option<&mut NcInput>) -> char {
     let input_ptr;
     if let Some(i) = input {
         input_ptr = i as *mut _;
@@ -75,10 +75,10 @@ pub fn notcurses_getc_blocking(nc: &mut NcNotcurses, input: Option<&mut NcInput>
 /// [notcurses_stdplane()][crate::notcurses_stdplane], plus free bonus
 /// dimensions written to non-NULL y/x!
 ///
-/// *Method: NcNotcurses.[getc_stddim_yx()][NcNotcurses#method.stddim_yx].*
+/// *Method: Notcurses.[getc_stddim_yx()][Notcurses#method.stddim_yx].*
 #[inline]
 pub fn notcurses_stddim_yx<'a>(
-    nc: &'a mut NcNotcurses,
+    nc: &'a mut Notcurses,
     y: &mut NcDimension,
     x: &mut NcDimension,
 ) -> NcResult<&'a mut NcPlane> {
@@ -95,10 +95,10 @@ pub fn notcurses_stddim_yx<'a>(
 /// [notcurses_stdplane_const()][crate::notcurses_stdplane_const], plus free
 /// bonus dimensions written to non-NULL y/x!
 ///
-/// *Method: NcNotcurses.[getc_stddim_yx_const()][NcNotcurses#method.stddim_yx_const].*
+/// *Method: Notcurses.[getc_stddim_yx_const()][Notcurses#method.stddim_yx_const].*
 #[inline]
 pub fn notcurses_stddim_yx_const<'a>(
-    nc: &'a NcNotcurses,
+    nc: &'a Notcurses,
     y: &mut NcDimension,
     x: &mut NcDimension,
 ) -> NcResult<&'a NcPlane> {
@@ -114,9 +114,9 @@ pub fn notcurses_stddim_yx_const<'a>(
 
 /// Returns our current idea of the terminal dimensions in rows and cols.
 ///
-/// *Method: NcNotcurses.[getc_term_yx()][NcNotcurses#method.term_yx].*
+/// *Method: Notcurses.[getc_term_yx()][Notcurses#method.term_yx].*
 #[inline]
-pub fn notcurses_term_dim_yx(nc: &NcNotcurses) -> (NcDimension, NcDimension) {
+pub fn notcurses_term_dim_yx(nc: &Notcurses) -> (NcDimension, NcDimension) {
     let (mut y, mut x) = (0, 0);
     unsafe {
         crate::ncplane_dim_yx(crate::notcurses_stdplane_const(nc), &mut y, &mut x);

rust/src/notcurses/wrapper.rs

@@ -3,32 +3,32 @@
 use std::ops::{Deref, DerefMut};
 
 use crate::{
-    raw_wrap, NcAlign, NcBlitter, NcDimension, NcLogLevel, NcNotcurses, NcNotcursesOptions,
+    raw_wrap, NcAlign, NcBlitter, NcDimension, NcLogLevel, Notcurses, NotcursesOptions,
     NcResult, NcScale,
 };
 
 /// The main struct of the TUI library (full mode).
 ///
-/// Safely wraps an [NcNotcurses],
+/// Safely wraps an [Notcurses],
 /// and implements Drop, AsRef, AsMut, Deref & DerefMut around it.
 pub struct FullMode<'a> {
-    raw: &'a mut NcNotcurses,
+    pub(crate) raw: &'a mut Notcurses,
 }
 
-impl<'a> AsRef<NcNotcurses> for FullMode<'a> {
-    fn as_ref(&self) -> &NcNotcurses {
+impl<'a> AsRef<Notcurses> for FullMode<'a> {
+    fn as_ref(&self) -> &Notcurses {
         self.raw
     }
 }
 
-impl<'a> AsMut<NcNotcurses> for FullMode<'a> {
-    fn as_mut(&mut self) -> &mut NcNotcurses {
+impl<'a> AsMut<Notcurses> for FullMode<'a> {
+    fn as_mut(&mut self) -> &mut Notcurses {
         self.raw
     }
 }
 
 impl<'a> Deref for FullMode<'a> {
-    type Target = NcNotcurses;
+    type Target = Notcurses;
 
     fn deref(&self) -> &Self::Target {
         self.as_ref()
@@ -48,38 +48,38 @@ impl<'a> Drop for FullMode<'a> {
     }
 }
 
-/// # Constructors and methods overriden from NcNotcurses
+/// # Constructors and methods overriden from Notcurses
 impl<'a> FullMode<'a> {
     // wrap constructors
 
     /// New FullMode (without banners).
     pub fn new() -> NcResult<Self> {
-        raw_wrap![NcNotcurses::new()]
+        raw_wrap![Notcurses::new()]
     }
 
     /// New FullMode, without banners.
     pub fn with_banners() -> NcResult<Self> {
-        raw_wrap![NcNotcurses::with_banners()]
+        raw_wrap![Notcurses::with_banners()]
     }
 
     /// New FullMode, without an alternate screen (nor banners).
     pub fn without_altscreen() -> NcResult<Self> {
-        raw_wrap![NcNotcurses::without_altscreen()]
+        raw_wrap![Notcurses::without_altscreen()]
     }
 
     /// New FullMode, expects `NCOPTION_*` flags.
     pub fn with_flags(flags: u64) -> NcResult<Self> {
-        raw_wrap![NcNotcurses::with_flags(flags)]
+        raw_wrap![Notcurses::with_flags(flags)]
     }
 
-    /// New FullMode, expects [NcNotcursesOptions].
-    pub fn with_options(options: NcNotcursesOptions) -> NcResult<Self> {
-        raw_wrap![NcNotcurses::with_options(options)]
+    /// New FullMode, expects [NotcursesOptions].
+    pub fn with_options(options: NotcursesOptions) -> NcResult<Self> {
+        raw_wrap![Notcurses::with_options(options)]
     }
 
     /// New FullMode, expects [NcLogLevel] and flags.
     pub fn with_debug(loglevel: NcLogLevel, flags: u64) -> NcResult<Self> {
-        raw_wrap![NcNotcurses::with_debug(loglevel, flags)]
+        raw_wrap![Notcurses::with_debug(loglevel, flags)]
     }
 
     // disable destructor
@@ -95,46 +95,46 @@ impl<'a> FullMode<'a> {
     /// Returns the offset into `availcols` at which `cols` ought be output given
     /// the requirements of `align`.
     pub fn align(availcols: NcDimension, align: NcAlign, cols: NcDimension) -> NcResult<()> {
-        NcNotcurses::align(availcols, align, cols)
+        Notcurses::align(availcols, align, cols)
     }
 
     /// Gets the name of an [NcBlitter] blitter.
     pub fn str_blitter(blitter: NcBlitter) -> String {
-        NcNotcurses::str_blitter(blitter)
+        Notcurses::str_blitter(blitter)
     }
 
     /// Gets the name of an [NcScale] scaling mode.
     pub fn str_scalemode(scalemode: NcScale) -> String {
-        NcNotcurses::str_scalemode(scalemode)
+        Notcurses::str_scalemode(scalemode)
     }
 
     /// Returns an [NcBlitter] from a string representation.
     pub fn lex_blitter(op: &str) -> NcResult<NcBlitter> {
-        NcNotcurses::lex_blitter(op)
+        Notcurses::lex_blitter(op)
     }
 
-    /// Lexes a margin argument according to the standard NcNotcurses definition.
+    /// Lexes a margin argument according to the standard Notcurses definition.
     ///
     /// There can be either a single number, which will define all margins equally,
     /// or there can be four numbers separated by commas.
     ///
-    pub fn lex_margins(op: &str, options: &mut NcNotcursesOptions) -> NcResult<()> {
-        NcNotcurses::lex_margins(op, options)
+    pub fn lex_margins(op: &str, options: &mut NotcursesOptions) -> NcResult<()> {
+        Notcurses::lex_margins(op, options)
     }
 
     /// Returns an [NcScale] from a string representation.
     pub fn lex_scalemode(op: &str) -> NcResult<NcScale> {
-        NcNotcurses::lex_scalemode(op)
+        Notcurses::lex_scalemode(op)
     }
 
     /// Returns a human-readable string describing the running FullMode version.
     pub fn version() -> String {
-        NcNotcurses::version()
+        Notcurses::version()
     }
 
-    /// Returns the running NcNotcurses version components
+    /// Returns the running Notcurses version components
     /// (major, minor, patch, tweak).
     pub fn version_components() -> (u32, u32, u32, u32) {
-        NcNotcurses::version_components()
+        Notcurses::version_components()
     }
 }

rust/src/palette/methods.rs

@@ -1,12 +1,12 @@
 //! `NcPalette` methods and associated functions.
 
-use crate::{error, NcChannel, NcColor, NcNotcurses, NcPalette, NcPaletteIndex, NcResult, NcRgb};
+use crate::{error, NcChannel, NcColor, Notcurses, NcPalette, NcPaletteIndex, NcResult, NcRgb};
 
 impl NcPalette {
     /// New NcPalette.
     ///
     /// *C style function: [palette256_new()][crate::palette256_new].*
-    pub fn new<'a>(nc: &mut NcNotcurses) -> &'a mut Self {
+    pub fn new<'a>(nc: &mut Notcurses) -> &'a mut Self {
         unsafe { &mut *crate::palette256_new(nc) }
     }
 
@@ -22,7 +22,7 @@ impl NcPalette {
     /// Attempts to configure the terminal with this NcPalette.
     ///
     /// *C style function: [palette256_use()][crate::palette256_use].*
-    pub fn r#use(&self, nc: &mut NcNotcurses) -> NcResult<()> {
+    pub fn r#use(&self, nc: &mut Notcurses) -> NcResult<()> {
         error![unsafe { crate::palette256_use(nc, self) }]
     }
 

rust/src/plane/helpers.rs

@@ -1,9 +1,9 @@
-use crate::{NcDimension, NcNotcurses, NcOffset, NcPlane, NcPlaneOptions};
+use crate::{NcDimension, Notcurses, NcOffset, NcPlane, NcPlaneOptions};
 
 /// Helper function for a new NcPlane on C style tests.
 #[allow(dead_code)]
 pub(crate) unsafe fn ncplane_new_test<'a>(
-    nc: &mut NcNotcurses,
+    nc: &mut Notcurses,
     y: NcOffset,
     x: NcOffset,
     rows: NcDimension,

rust/src/plane/methods.rs

@@ -4,7 +4,7 @@ use core::ptr::{null, null_mut};
 
 use crate::{
     cstring, error, error_ref, error_ref_mut, rstring, NcAlign, NcAlphaBits, NcBoxMask, NcCell,
-    NcChannel, NcChannelPair, NcColor, NcDimension, NcEgc, NcError, NcFadeCb, NcNotcurses,
+    NcChannel, NcChannelPair, NcColor, NcDimension, NcEgc, NcError, NcFadeCb, Notcurses,
     NcOffset, NcPaletteIndex, NcPlane, NcPlaneOptions, NcResizeCb, NcResult, NcRgb, NcStyleMask,
     NcTime, NCRESULT_ERR,
 };
@@ -76,7 +76,7 @@ impl NcPlane {
     ///
     /// *C style function: [ncpile_create()][crate::ncpile_create].*
     pub fn new<'a>(
-        nc: &mut NcNotcurses,
+        nc: &mut Notcurses,
         y: NcOffset,
         x: NcOffset,
         rows: NcDimension,
@@ -91,12 +91,12 @@ impl NcPlane {
     ///
     /// *C style function: [ncpile_create()][crate::ncpile_create].*
     pub fn with_options<'a>(
-        nc: &mut NcNotcurses,
+        nc: &mut Notcurses,
         options: NcPlaneOptions,
     ) -> NcResult<&'a mut NcPlane> {
         error_ref_mut![
             unsafe { crate::ncpile_create(nc, &options) },
-            &format!["NcPlane::with_options(NcNotcurses, {:?})", options]
+            &format!["NcPlane::with_options(Notcurses, {:?})", options]
         ]
     }
 
@@ -115,8 +115,6 @@ impl NcPlane {
 
     /// New NcPlane, bound to another plane, expects an [NcPlaneOptions] struct.
     ///
-    /// The returned plane will be the top, bottom, and root of this new pile.
-    ///
     /// *C style function: [ncplane_create()][crate::ncplane_create].*
     pub fn with_options_bound<'a>(
         bound_to: &mut NcPlane,
@@ -133,7 +131,7 @@ impl NcPlane {
     /// The returned plane will be the top, bottom, and root of this new pile.
     ///
     /// *(No equivalent C style function)*
-    pub fn new_termsize<'a>(nc: &mut NcNotcurses) -> NcResult<&'a mut NcPlane> {
+    pub fn with_termsize<'a>(nc: &mut Notcurses) -> NcResult<&'a mut NcPlane> {
         let (trows, tcols) = crate::notcurses_term_dim_yx(nc);
         assert![(trows > 0) & (tcols > 0)];
         Self::with_options(
@@ -310,7 +308,7 @@ impl NcPlane {
     /// the provided values will be interpreted in some lossy fashion.
     ///
     /// "HP-like" terminals require setting foreground and background at the same
-    /// time using "color pairs"; NcNotcurses will manage color pairs transparently.
+    /// time using "color pairs"; Notcurses will manage color pairs transparently.
     ///
     /// *C style function: [ncplane_set_fg_rgb8()][crate::ncplane_set_fg_rgb8].*
     pub fn set_fg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) {
@@ -327,7 +325,7 @@ impl NcPlane {
     /// the provided values will be interpreted in some lossy fashion.
     ///
     /// "HP-like" terminals require setting foreground and background at the same
-    /// time using "color pairs"; NcNotcurses will manage color pairs transparently.
+    /// time using "color pairs"; Notcurses will manage color pairs transparently.
     ///
     /// *C style function: [ncplane_set_bg_rgb8()][crate::ncplane_set_bg_rgb8].*
     pub fn set_bg_rgb8(&mut self, red: NcColor, green: NcColor, blue: NcColor) {
@@ -871,7 +869,7 @@ impl NcPlane {
 }
 
 // -----------------------------------------------------------------------------
-/// ## NcPlane methods: `NcPlane` & `NcNotcurses`
+/// ## NcPlane methods: `NcPlane` & `Notcurses`
 impl NcPlane {
     /// Duplicates this NcPlane.
     ///
@@ -1116,20 +1114,20 @@ impl NcPlane {
         error![unsafe { crate::ncpile_render(self) }, "NcPlane.render()"]
     }
 
-    /// Gets a mutable reference to the [NcNotcurses] context of this NcPlane.
+    /// Gets a mutable reference to the [Notcurses] context of this NcPlane.
     ///
     /// *C style function: [ncplane_notcurses()][crate::ncplane_notcurses].*
-    pub fn notcurses<'a>(&mut self) -> NcResult<&'a mut NcNotcurses> {
+    pub fn notcurses<'a>(&mut self) -> NcResult<&'a mut Notcurses> {
         error_ref_mut![
             unsafe { crate::ncplane_notcurses(self) },
             "NcPlane.notcurses()"
         ]
     }
 
-    /// Gets an immutable reference to the [NcNotcurses] context of this NcPlane.
+    /// Gets an immutable reference to the [Notcurses] context of this NcPlane.
     ///
     /// *C style function: [ncplane_notcurses_const()][crate::ncplane_notcurses_const].*
-    pub fn notcurses_const<'a>(&self) -> NcResult<&'a NcNotcurses> {
+    pub fn notcurses_const<'a>(&self) -> NcResult<&'a Notcurses> {
         error_ref![
             unsafe { crate::ncplane_notcurses_const(self) },
             "NcPlane.notcurses()"

rust/src/stats.rs

@@ -1,6 +1,6 @@
 //! `NcStats`
 
-use crate::NcNotcurses;
+use crate::Notcurses;
 
 /// notcurses runtime statistics
 pub type NcStats = crate::bindings::ffi::ncstats;
@@ -8,17 +8,17 @@ pub type NcStats = crate::bindings::ffi::ncstats;
 /// # `NcStats` Methods.
 impl NcStats {
     /// Allocates an NcStats object.
-    pub fn new<'a>(nc: &'a NcNotcurses) -> &'a mut Self {
+    pub fn new<'a>(nc: &'a Notcurses) -> &'a mut Self {
         unsafe { &mut *crate::notcurses_stats_alloc(nc) }
     }
 
-    /// Acquires an atomic snapshot of the NcNotcurses object's stats.
-    pub fn stats(&mut self, nc: &NcNotcurses) {
+    /// Acquires an atomic snapshot of the Notcurses object's stats.
+    pub fn stats(&mut self, nc: &Notcurses) {
         unsafe { crate::notcurses_stats(nc, self) }
     }
 
     /// Resets all cumulative stats (immediate ones are not reset).
-    pub fn reset(&mut self, nc: &mut NcNotcurses) {
+    pub fn reset(&mut self, nc: &mut Notcurses) {
         unsafe { crate::notcurses_stats_reset(nc, self) }
     }
 }

rust/src/widgets/menu/methods/menu.rs

@@ -9,7 +9,7 @@ use crate::{
 impl NcMenu {
     /// Creates an [NcMenu] with the specified options.
     ///
-    /// Menus are currently bound to an overall [Notcurses][crate::Notcurses]
+    /// Menus are currently bound to an overall [FullMode][crate::FullMode]
     /// object (as opposed to a particular plane), and are implemented as
     /// [NcPlane]s kept atop other NcPlanes.
     ///

rust/src/widgets/reel/mod.rs

@@ -1,12 +1,13 @@
 //! `NcReel` widget.
 
-/// A wheel with `NcTablet`s on the outside
+/// A wheel with [`NcTablet`]s on the outside.
 ///
 /// An `NcReel` is projected onto the 2d rendering area, showing some portion of
 /// the `NcReel`, and zero or more `NcTablet`s.
 ///
-/// An `NcReel` is a `Notcurses` region devoted to displaying zero or more
-/// line-oriented, contained `NcTablet`s between which the user may navigate.
+/// An `NcReel` is a [`FullMode`][crate::FullMode] region devoted to displaying
+/// zero or more line-oriented, contained [`NcTablet`]s
+/// between which the user may navigate.
 ///
 /// If at least one `NcTablet`s exists, there is a "focused tablet".
 /// As much of the focused tablet as is possible is always displayed.