rust: more fixes and improvements

- fix notcurses_init unit test
- fix fn call name: `nplane_at_cursor_cell` → `ncplane_at_cursor_cell`.
- make LIBC_FILE & NC_FILE type aliases with doc comment.
- add lib module comment.
- improve direct-cursor example.
- fix full-text example and rename it to full-basics.

rust/examples/direct-cursor.rs

@@ -3,21 +3,17 @@
 //! Explore cursor functions in direct mode
 //!
 
-use std::thread::sleep;
-use std::time::Duration;
-use std::ffi::CString;
-
-/// utility macro: sleep for $s seconds
+// utility macro: sleep for $ms milliseconds
 macro_rules! sleep {
-    ($s:expr) => {
-        sleep(Duration::new($s, 0));
+    ($ms:expr) => {
+        std::thread::sleep(std::time::Duration::from_millis($ms));
     };
 }
 
-/// utility macro: convert the String $s to *mut CString
+// utility macro: convert the String $s to *mut CString
 macro_rules! cstring {
     ($s:expr) => {
-        CString::new($s).unwrap().as_ptr();
+        std::ffi::CString::new($s).unwrap().as_ptr();
     }
 }
 
@@ -31,30 +27,34 @@ fn main() {
         let rows = ncdirect_dim_y(ncd);
         println!("terminal size (rows, cols): {}, {}", rows, cols);
 
-        // show current coordinates
-        let (mut cy, mut cx) = (0, 0);
-        ncdirect_cursor_yx(ncd, &mut cy, &mut cx);
-        ncdirect_putstr(ncd, 0, cstring![format!(" ({},{})\n", cy, cx)],
-        );
-
-        sleep![1];
-
-        ncdirect_putstr(ncd, 0, cstring!["HELLO"]);
+        ncdirect_putstr(ncd, 0, cstring![format!("The current coordinates are")]);
         ncdirect_flush(ncd);
 
-        sleep![1];
+        for _n in 0..20 {
+            ncdirect_putstr(ncd, 0, cstring!("."));
+            ncdirect_flush(ncd);
+            sleep![50];
+        }
 
-        ncdirect_putstr(ncd, 0, cstring!["HELLO"]);
+        let (mut cy, mut cx) = (0, 0);
+        ncdirect_cursor_yx(ncd, &mut cy, &mut cx);
+        ncdirect_putstr(ncd, 0, cstring![format!(" ({},{})\n", cy, cx)]);
+        sleep![1000];
+
+        let sentence = vec!["And", "now", "I", "will", "clear", "the", "screen", ".", ".", "."];
+        for word in sentence {
+            ncdirect_putstr(ncd, 0, cstring!(format!["{} ", word]));
+            ncdirect_flush(ncd);
+            sleep![200];
+        }
+        sleep![300];
+        ncdirect_putstr(ncd, 0, cstring!("\nbye!\n\n"));
         ncdirect_flush(ncd);
+        sleep![600];
 
-        sleep![2];
-
-        // show current coordinates
-        ncdirect_cursor_yx(ncd, &mut cy, &mut cx);
-        ncdirect_putstr( ncd, 0, cstring![format!(" ({},{})\n", cy, cx)],
-        );
+        ncdirect_clear(ncd);
+        sleep![1000];
 
-        sleep![1];
         ncdirect_stop(ncd);
     }
 }

rust/examples/full-basics.rs

@@ -0,0 +1,30 @@
+// utility macro: sleep for $ms milliseconds
+macro_rules! sleep {
+    ($ms:expr) => {
+        std::thread::sleep(std::time::Duration::from_millis($ms));
+    };
+}
+
+// utility macro: convert the String $s to *mut CString
+// macro_rules! cstring {
+//     ($s:expr) => {
+//         std::ffi::CString::new($s).unwrap().as_ptr();
+//     }
+// }
+
+use libnotcurses_sys::*;
+
+fn main() {
+    unsafe {
+        let nc = Notcurses::new();
+        let stdplane = notcurses_stdplane(nc);
+
+        let c1 = cell_char_initializer!('A');
+        ncplane_putc(&mut *stdplane, &c1);
+
+        let _ = notcurses_render(nc);
+
+        sleep![1200];
+        notcurses_stop(nc);
+    }
+}

rust/examples/full-text.rs

@@ -1,31 +0,0 @@
-use std::thread::sleep;
-use std::time::Duration;
-use std::ffi::CString;
-
-/// utility macro: sleep for $s seconds
-macro_rules! sleep {
-    ($s:expr) => {
-        sleep(Duration::new($s, 0));
-    };
-}
-
-/// utility macro: convert the String $s to *mut CString
-macro_rules! cstring {
-    ($s:expr) => {
-        CString::new($s).unwrap().as_ptr();
-    }
-}
-
-use libnotcurses_sys::*;
-
-fn main() {
-    unsafe {
-        let nc = Notcurses::new();
-
-        println!("WIP");
-        sleep![2];
-
-        notcurses_stop(nc);
-    }
-}
-

rust/src/lib.rs

@@ -1,6 +1,19 @@
-#![allow(non_upper_case_globals)]
-#![allow(non_camel_case_types)]
-#![allow(non_snake_case)]
+//! `libnotcurses-sys` is an unsafe Rust wrapper for the notcurses C library
+//!
+//! It follows very closely the original C API while following the Rust API Guidelines
+//!
+//! For a higher lever API, safer and more idiomatic, take a look at
+//! [notcurses-rs](https://github.com/dankamongmen/notcurses-rs)
+//!
+//! ### notcurses C API docs:
+//!
+//! - [Doxygen Documentation](https://nick-black.com/notcurses/html/index.html)
+//! - [API reference (man pages)](https://nick-black.com/notcurses/)
+//! - [Wiki](https://nick-black.com/dankwiki/index.php/Notcurses)
+//! - [The Book Guide (pdf)](https://nick-black.com/htp-notcurses.pdf)
+//! - [USAGE.md](https://github.com/dankamongmen/notcurses/blob/master/USAGE.md)
+//!
+#![allow(non_upper_case_globals, non_camel_case_types, non_snake_case)]
 #![allow(clippy::too_many_arguments)]
 
 pub mod bindings;

rust/src/notcurses.rs

@@ -250,9 +250,8 @@ mod test {
     fn notcurses_init() {
         unsafe {
             let nc = Notcurses::new();
-            let res = crate::notcurses_canchangecolor(nc);
+            assert![nc as *mut _ != core::ptr::null_mut()];
             notcurses_stop(nc);
-            print!("[{}] ", res);
         }
     }
 

rust/src/plane.rs

@@ -232,7 +232,7 @@ pub fn ncplane_align(plane: &NcPlane, align: NcAlign, cols: i32) -> i32 {
 /// Retrieve the current contents of the cell under the cursor into 'cell'.
 /// This cell is invalidated if the associated plane is destroyed.
 #[inline]
-pub fn nplane_at_cursor_cell(plane: &mut NcPlane, cell: &mut Cell) -> IntResult {
+pub fn ncplane_at_cursor_cell(plane: &mut NcPlane, cell: &mut Cell) -> IntResult {
     let mut egc = unsafe { ncplane_at_cursor(plane, &mut cell.stylemask, &mut cell.channels) };
     if egc.is_null() {
         return -1;

rust/src/types/file.rs

@@ -8,11 +8,15 @@ use core::ptr::{null_mut, NonNull};
 use std::io::{Error, ErrorKind, Read, Seek, SeekFrom};
 
 pub use libc::{
-    c_long, c_void, fclose, feof, fread, fseek, ftell, FILE as LIBC_FILE, SEEK_CUR, SEEK_END,
+    c_long, c_void, fclose, feof, fread, fseek, ftell, SEEK_CUR, SEEK_END,
     SEEK_SET,
 };
 
-pub use crate::bindgen::_IO_FILE as NC_FILE;
+/// notcurses functions expects this type of *FILE (struct)
+pub type NC_FILE = crate::bindgen::_IO_FILE;
+
+/// the libc crate expects this type of *FILE (opaque enum)
+pub type LIBC_FILE = libc::FILE;
 
 /// Intended to be passed into the CFile::open method.
 /// It will open the file in a way that will allow reading and writing,