From 797ef4b0ae2a347a609746e648ad9585ad336bd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?joseLu=C3=ADs?= Date: Sun, 3 Jan 2021 02:40:28 +0100 Subject: [PATCH] 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 | 2 +- rust/examples/full-basics.rs | 2 +- rust/examples/poc-cjkscroll.rs | 2 +- rust/examples/poc-menu.rs | 4 +- rust/src/direct/wrapper.rs | 2 +- rust/src/fade.rs | 4 +- rust/src/lib.rs | 39 ++++++----- rust/src/macros.rs | 8 +-- rust/src/notcurses/helpers.rs | 8 +-- rust/src/notcurses/methods.rs | 95 +++++++++++++-------------- rust/src/notcurses/mod.rs | 24 +++---- rust/src/notcurses/reimplemented.rs | 24 +++---- rust/src/notcurses/wrapper.rs | 56 ++++++++-------- rust/src/palette/methods.rs | 6 +- rust/src/plane/helpers.rs | 4 +- rust/src/plane/methods.rs | 26 ++++---- rust/src/stats.rs | 10 +-- rust/src/widgets/menu/methods/menu.rs | 2 +- rust/src/widgets/reel/mod.rs | 7 +- 19 files changed, 163 insertions(+), 162 deletions(-) diff --git a/rust/README.md b/rust/README.md index e48d86a8f..0302ce2b5 100644 --- a/rust/README.md +++ b/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) diff --git a/rust/examples/full-basics.rs b/rust/examples/full-basics.rs index baa1892e8..88faa03fb 100644 --- a/rust/examples/full-basics.rs +++ b/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); diff --git a/rust/examples/poc-cjkscroll.rs b/rust/examples/poc-cjkscroll.rs index 42b219e32..30c0a1c5c 100644 --- a/rust/examples/poc-cjkscroll.rs +++ b/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}'; // 一 diff --git a/rust/examples/poc-menu.rs b/rust/examples/poc-menu.rs index 140e6a450..fffb78e33 100644 --- a/rust/examples/poc-menu.rs +++ b/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); diff --git a/rust/src/direct/wrapper.rs b/rust/src/direct/wrapper.rs index c17029f03..baf3e90a5 100644 --- a/rust/src/direct/wrapper.rs +++ b/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 for DirectMode<'a> { diff --git a/rust/src/fade.rs b/rust/src/fade.rs index f6c739562..02e92be3c 100644 --- a/rust/src/fade.rs +++ b/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 diff --git a/rust/src/lib.rs b/rust/src/lib.rs index 7c787c21f..dd2354264 100644 --- a/rust/src/lib.rs +++ b/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`]``, 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 //! diff --git a/rust/src/macros.rs b/rust/src/macros.rs index 1c98116b0..b77d6946d 100644 --- a/rust/src/macros.rs +++ b/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),+ ,) => { diff --git a/rust/src/notcurses/helpers.rs b/rust/src/notcurses/helpers.rs index 9164c700c..2b93cf922 100644 --- a/rust/src/notcurses/helpers.rs +++ b/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(), ) } diff --git a/rust/src/notcurses/methods.rs b/rust/src/notcurses/methods.rs index 05c734f28..a7db95c40 100644 --- a/rust/src/notcurses/methods.rs +++ b/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].* diff --git a/rust/src/notcurses/mod.rs b/rust/src/notcurses/mod.rs index 15d60ab83..c751604d8 100644 --- a/rust/src/notcurses/mod.rs +++ b/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. diff --git a/rust/src/notcurses/reimplemented.rs b/rust/src/notcurses/reimplemented.rs index 6054a8a1d..79c547adc 100644 --- a/rust/src/notcurses/reimplemented.rs +++ b/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); diff --git a/rust/src/notcurses/wrapper.rs b/rust/src/notcurses/wrapper.rs index d6b4e5b3a..0244dd3cb 100644 --- a/rust/src/notcurses/wrapper.rs +++ b/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 for FullMode<'a> { - fn as_ref(&self) -> &NcNotcurses { +impl<'a> AsRef for FullMode<'a> { + fn as_ref(&self) -> &Notcurses { self.raw } } -impl<'a> AsMut for FullMode<'a> { - fn as_mut(&mut self) -> &mut NcNotcurses { +impl<'a> AsMut 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 { - raw_wrap![NcNotcurses::new()] + raw_wrap![Notcurses::new()] } /// New FullMode, without banners. pub fn with_banners() -> NcResult { - raw_wrap![NcNotcurses::with_banners()] + raw_wrap![Notcurses::with_banners()] } /// New FullMode, without an alternate screen (nor banners). pub fn without_altscreen() -> NcResult { - raw_wrap![NcNotcurses::without_altscreen()] + raw_wrap![Notcurses::without_altscreen()] } /// New FullMode, expects `NCOPTION_*` flags. pub fn with_flags(flags: u64) -> NcResult { - raw_wrap![NcNotcurses::with_flags(flags)] + raw_wrap![Notcurses::with_flags(flags)] } - /// New FullMode, expects [NcNotcursesOptions]. - pub fn with_options(options: NcNotcursesOptions) -> NcResult { - raw_wrap![NcNotcurses::with_options(options)] + /// New FullMode, expects [NotcursesOptions]. + pub fn with_options(options: NotcursesOptions) -> NcResult { + raw_wrap![Notcurses::with_options(options)] } /// New FullMode, expects [NcLogLevel] and flags. pub fn with_debug(loglevel: NcLogLevel, flags: u64) -> NcResult { - 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 { - 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 { - 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() } } diff --git a/rust/src/palette/methods.rs b/rust/src/palette/methods.rs index 40ffaf3b9..552cee743 100644 --- a/rust/src/palette/methods.rs +++ b/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) }] } diff --git a/rust/src/plane/helpers.rs b/rust/src/plane/helpers.rs index 7272a0716..9ff29fb46 100644 --- a/rust/src/plane/helpers.rs +++ b/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, diff --git a/rust/src/plane/methods.rs b/rust/src/plane/methods.rs index 47b287ceb..40f4d4679 100644 --- a/rust/src/plane/methods.rs +++ b/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()" diff --git a/rust/src/stats.rs b/rust/src/stats.rs index 9db2281a7..a91dd5e5a 100644 --- a/rust/src/stats.rs +++ b/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) } } } diff --git a/rust/src/widgets/menu/methods/menu.rs b/rust/src/widgets/menu/methods/menu.rs index ec34ad93a..8bb217e66 100644 --- a/rust/src/widgets/menu/methods/menu.rs +++ b/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. /// diff --git a/rust/src/widgets/reel/mod.rs b/rust/src/widgets/reel/mod.rs index 205c78c92..f5f5b3d08 100644 --- a/rust/src/widgets/reel/mod.rs +++ b/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.