[rust] rename macros & update docs

- rename psleep to prs
- rename rsleep to nrs
- deprecate and hide docs for fsleep, psleep, prsleep, rsleep.
- update examples

rust/examples/direct-cursor.rs

@@ -10,18 +10,19 @@ use libnotcurses_sys::*;
 fn main() -> NcResult<()> {
     let mut rng = thread_rng();
 
-    let mut dm = NcDirect::new()?;
+    let ncd = NcDirect::new()?;
 
-    let cols = dm.dim_x();
-    let rows = dm.dim_y();
+    let cols = ncd.dim_x();
+    let rows = ncd.dim_y();
     println!("terminal size (rows, cols): {}, {}", rows, cols);
 
     let mut channels =
         NcChannels::combine(NcChannel::from_rgb(0xAA2244), NcChannel::from_rgb(0x112233));
-    dm.putstr(channels, "The current coordinates are")?;
+    ncd.putstr(channels, "The current coordinates are")?;
 
     for _n in 0..40 {
-        fsleep![&mut dm, 0, 30];
+        ncd.flush()?;
+        sleep![0, 30];
         channels.set_fg_rgb8(
             rng.gen_range(0x66..=0xEE),
             rng.gen_range(0x66..=0xEE),
@@ -32,11 +33,11 @@ fn main() -> NcResult<()> {
             rng.gen_range(0..=0x9),
             rng.gen_range(0..=0x9),
         );
-        dm.putstr(channels, ".")?;
+        ncd.putstr(channels, ".")?;
     }
 
-    let (cy, cx) = dm.cursor_yx()?;
-    dm.putstr(channels, &format!(" ({},{})\n", cy, cx))?;
+    let (cy, cx) = ncd.cursor_yx()?;
+    ncd.putstr(channels, &format!(" ({},{})\n", cy, cx))?;
     sleep![1];
 
     let sentence = vec![
@@ -45,14 +46,16 @@ fn main() -> NcResult<()> {
     for word in sentence {
         channels.set_fg_rgb(channels.fg_rgb().wrapping_sub(0x050505));
         channels.set_bg_rgb(channels.bg_rgb().wrapping_add(0x090909));
-        dm.putstr(channels, &format!["{} ", word])?;
-        fsleep![&mut dm, 0, 150];
+        ncd.putstr(channels, &format!["{} ", word])?;
+        ncd.flush()?;
+        sleep![0, 150];
     }
     sleep![0, 300];
     channels.set_fg_rgb(0xFFFFFF);
     channels.set_bg_default();
-    dm.putstr(channels, "\nbye!\n\n")?;
-    fsleep![&mut dm, 0, 600];
-    dm.clear()?;
+    ncd.putstr(channels, "\nbye!\n\n")?;
+    ncd.flush()?;
+    sleep![0, 600];
+    ncd.clear()?;
     Ok(())
 }

rust/examples/full-input.rs

@@ -21,7 +21,7 @@ fn main() -> NcResult<()> {
             println!("'{0}' ({1:x})\n{2:?}", key, key as u32, input);
         }
 
-        rsleep![&mut nc, 0, 10];
+        nrs![&mut nc, 0, 10];
 
         match key {
             NCKEY_F01 => break,
@@ -31,7 +31,7 @@ fn main() -> NcResult<()> {
 
     println!("\nExiting...");
 
-    rsleep![&mut nc, 1];
+    nrs![&mut nc, 1];
     nc.stop()?;
     Ok(())
 }

rust/examples/full-planes.rs

@@ -13,51 +13,51 @@ fn main() -> NcResult<()> {
     // set the standard plane's base cell's foreground and background colors
     let channels = NcChannels::from_rgb(0x88aa00, 0x222288);
     stdplane.set_base("x", 0, channels)?;
-    rsleep![&mut nc, 0, 500];
+    nrs![&mut nc, 0, 500];
 
     // add a green plane to the stdplane's pile
     let plane_green = NcPlane::new_bound(&mut stdplane, 0, 0, 16, 30)?;
     plane_green.set_base("·", 0, NcChannels::from_rgb(0x224411, 0x229922))?;
-    rsleep![&mut nc, 0, 800];
+    nrs![&mut nc, 0, 800];
 
     // add a smaller red plane, a bit displaced to the bottom right
     let plane_red = NcPlane::new_bound(&mut stdplane, 8, 12, 10, 20)?;
     plane_red.set_base("~", 0, NcChannels::from_rgb(0xaadd2b, 0x882222))?;
-    rsleep![&mut nc, 0, 800];
+    nrs![&mut nc, 0, 800];
 
     // write something
     plane_green.putstr("PLANE 11111")?;
     plane_red.putstr("PLANE 22222")?;
-    rsleep![&mut nc, 0, 800];
+    nrs![&mut nc, 0, 800];
 
     // move the green plane down
     for _ in 0..16 {
         plane_green.move_rel(1, 1)?;
-        rsleep![&mut nc, 0, 30];
+        nrs![&mut nc, 0, 30];
     }
     // and up
     for _ in 0..20 {
         plane_green.move_rel(-1, -1)?;
-        rsleep![&mut nc, 0, 35];
+        nrs![&mut nc, 0, 35];
     }
 
     // move the red plane right
     for _ in 0..26 {
         plane_red.move_rel(0, 1)?;
-        rsleep![&mut nc, 0, 40];
+        nrs![&mut nc, 0, 40];
     }
     sleep![1];
 
     // resize the red plane
     plane_red.resize_simple(14, 24)?;
-    rsleep![&mut nc, 0, 300];
+    nrs![&mut nc, 0, 300];
     plane_red.move_rel(-2, -2)?;
-    rsleep![&mut nc, 0, 300];
+    nrs![&mut nc, 0, 300];
     plane_red.resize_simple(8, 16)?;
 
     // TODO…
 
-    rsleep![&mut nc, 3];
+    nrs![&mut nc, 3];
 
     nc.stop()?;
     Ok(())

rust/examples/pixel-cell.rs

@@ -44,7 +44,7 @@ fn main() -> NcResult<()> {
     let voptions =
         NcVisualOptions::without_plane(1, 2, 0, 0, pg.cell_y, pg.cell_x, NCBLIT_PIXEL, 0, 0);
     v1.render(&mut nc, &voptions)?;
-    rsleep![&mut nc, 1];
+    nrs![&mut nc, 1];
 
     // show the ncvisual, scaled with interpolated values
     let mut vplane2 = NcPlane::new_bound(&mut stdplane, 7, 4, 5, 4)?;
@@ -62,7 +62,7 @@ fn main() -> NcResult<()> {
         0,
     );
     v1.render(&mut nc, &voptions2)?;
-    rsleep![&mut nc, 0, 250];
+    nrs![&mut nc, 0, 250];
 
     // show the ncvisual, scaled without using interpolation
     let mut vplane3 = NcPlane::new_bound(&mut stdplane, 7, 19, 5, 4)?;
@@ -80,14 +80,14 @@ fn main() -> NcResult<()> {
         0,
     );
     v1.render(&mut nc, &voptions3)?;
-    rsleep![&mut nc, 0, 250];
+    nrs![&mut nc, 0, 250];
 
     // resize the ncvisual (doesn't use interpolation)
     let voptions4 =
         NcVisualOptions::without_plane(7, 39, 0, 0, pg.cell_y, pg.cell_x, NCBLIT_PIXEL, 0, 0);
     v1.resize_noninterpolative(pg.cell_y * 4, pg.cell_x * 4)?;
     v1.render(&mut nc, &voptions4)?;
-    rsleep![&mut nc, 0, 250];
+    nrs![&mut nc, 0, 250];
 
     // resize the ncvisual (uses interpolation)
     let v5 = NcVisual::from_rgba(buffer.as_slice(), pg.cell_y, pg.cell_x * 4, pg.cell_x)?;
@@ -95,7 +95,7 @@ fn main() -> NcResult<()> {
         NcVisualOptions::without_plane(7, 56, 0, 0, pg.cell_y, pg.cell_x, NCBLIT_PIXEL, 0, 0);
     v5.resize(pg.cell_y * 4, pg.cell_x * 4)?;
     v5.render(&mut nc, &voptions5)?;
-    rsleep![&mut nc, 0, 250];
+    nrs![&mut nc, 0, 250];
 
     sleep![2];
 

rust/examples/poc-cjkscroll.rs

@@ -18,7 +18,7 @@ fn main() -> NcResult<()> {
         if wc == '\u{9fa5}' {
             wc = '\u{4e00}';
         }
-        rsleep![&mut nc, 0, 0, 30];
+        nrs![&mut nc, 0, 0, 30];
     }
 
     // nc.stop()?;

rust/examples/poc-direct.rs

@@ -1,7 +1,7 @@
 //! based on the proof of concept at ../../src/poc/direct.c
 
-use libnotcurses_sys::*;
 use core::convert::TryInto;
+use libnotcurses_sys::*;
 
 fn main() -> NcResult<()> {
     let dm = NcDirect::new()?;

rust/src/macros.rs

@@ -32,6 +32,7 @@ macro_rules! sleep {
     };
 }
 
+/// notcurses render sleep:
 /// [`Nc::render`][Nc#method.render]\(`$nc`\)? + [`sleep!`]`[$sleep_args]`.
 ///
 /// Renders the `$nc` [`Nc`] object's standard plane pile and then,
@@ -39,7 +40,7 @@ macro_rules! sleep {
 ///
 /// Returns [NcResult].
 #[macro_export]
-macro_rules! rsleep {
+macro_rules! nrs {
     ($nc:expr, $( $sleep_args:expr),+ ) => {
         crate::Nc::render($nc)?;
         sleep![$( $sleep_args ),+];
@@ -49,6 +50,7 @@ macro_rules! rsleep {
     };
 }
 
+/// plane render sleep:
 /// [`NcPlane::render`][NcPlane#method.render]\(`$p`\)? +
 /// [`NcPlane::rasterize`][NcPlane#method.rasterize]\(`$p`\)? +
 /// [`sleep!`]`[$sleep_args]`.
@@ -58,7 +60,7 @@ macro_rules! rsleep {
 ///
 /// Returns [NcResult].
 #[macro_export]
-macro_rules! psleep {
+macro_rules! prs {
     ($p:expr, $( $sleep_args:expr),+ ) => {
         crate::NcPlane::render($p)?;
         crate::NcPlane::rasterize($p)?;
@@ -76,6 +78,8 @@ macro_rules! psleep {
 ///
 /// Returns [NcResult].
 #[macro_export]
+#[deprecated]
+#[doc(hidden)]
 macro_rules! fsleep {
     ($ncd:expr, $( $sleep_args:expr),+ ) => {
         // Rust style, with methods & NcResult
@@ -87,6 +91,33 @@ macro_rules! fsleep {
     };
 }
 
+#[deprecated]
+#[doc(hidden)]
+#[allow(unused_macros)]
+macro_rules! prsleep {
+    ($p:expr, $( $sleep_args:expr),+ ) => {
+        prs![$p, $( $sleep_args ),+];
+    };
+}
+
+#[deprecated]
+#[doc(hidden)]
+#[allow(unused_macros)]
+macro_rules! psleep {
+    ($p:expr, $( $sleep_args:expr),+ ) => {
+        prs![$p, $( $sleep_args ),+];
+    };
+}
+
+#[deprecated]
+#[doc(hidden)]
+#[allow(unused_macros)]
+macro_rules! rsleep {
+    ($nc:expr, $( $sleep_args:expr),+ ) => {
+        nrs![$nc, $( $sleep_args ),+];
+    };
+}
+
 // String & Print Macros -------------------------------------------------------
 
 /// Converts an `&str` into `*const c_char`.