Crate libnotcurses_sys
source ·Expand description
libnotcurses-sys is a low-level Rust wrapper for the
notcurses C library
It is built with several layers of zero-overhead abstractions over the C functions and pointers accessed through FFI.
It adds greater safety and type correctness over the underlying C library API, while trying to remain very close to it.
It offers the choice of using it more like Rust and/or more like C.
Like Rust
Where you use the more safely wrapped types, with its methods and
constructors, and error handling with the NcResult enum:
Example
use libnotcurses_sys::*;
fn main() -> NcResult<()> {
let nc = unsafe { Nc::new_cli()? };
let stdplane = unsafe { nc.stdplane() };
stdplane.putstr("\nhello world!\n")?;
nc.render()?;
unsafe { nc.stop()? }; // always stop before exiting
Ok(())
}
Notes on the Rust API
The Drop trait is not implemented for any wrapping type in this library
over structures created by the underlying C library.
This means you still have to manually call the stop() method for Nc
and NcDirect objects, and the destroy() method for the rest of types that
allocate, (like NcPlane, NcMenu…) at the end of their scope.
But they do implement methods and use NcResult as the return type,
for handling errors in the way we are used to in Rust.
For the types that don’t allocate, most are based on primitives like i32,
u32, u64… without a name in the C library. In Rust they are type aliased
for the C API (e.g.: NcChannel_u32, NcLogLevel_i32, NcStyle_u16…), to
leverage type checking. And for the Rust API they are wrapped as unit structs
or enums, with associated methods and constants (e.g. NcChannel,
NcLogLevel, NcStyle…).
Several methods are declared unsafe when they have addittional contracts to manually upheld in order to avoid UB.
even more like Rust
The WIP sister crate
notcurses will eventually
offer a closer to Rust, higher-level, safer, and simpler API, and make it
easier to interoperate with the rest of the Rust ecosystem.
Like C
You can access the imported, or reimplemented C API functions directly, and use it in a very similar way as the C library is used.
It requires more use of unsafe, since it has less safer abstractions.
Error handling is done this way by checking the returned NcResult_i32,
or in case of receiving a pointer, by comparing it to null_mut().
Example
use core::ptr::{null, null_mut};
use std::process::exit;
use libnotcurses_sys::c_api::*;
fn main() {
let options = ffi::notcurses_options {
termtype: null(),
loglevel: 0,
margin_t: 0,
margin_r: 0,
margin_b: 0,
margin_l: 0,
flags: NCOPTION_CLI_MODE,
};
unsafe {
let nc = notcurses_init(&options, null_mut());
if nc.is_null() {
exit(1);
}
let plane = notcurses_stdplane(nc);
let cols = ncplane_putstr(&mut *plane, "\nhello world!\n");
if cols < NCRESULT_OK {
notcurses_stop(nc);
exit(cols.abs());
}
if notcurses_render(&mut *nc) < NCRESULT_OK {
exit(2);
}
if notcurses_stop(nc) < NCRESULT_OK {
exit(3);
}
}
}
The notcurses C API docs
Modules
C API, including structs, constants, functions and type aliases.Macros
NcPlane.putstr,
rendering and rasterizing the plane afterwards.NcPlane.putstrln.
rendering and rasterizing the plane afterwards.Structs
NcChannelNcDirect flags.libc::FILENcOptions.NcPlane.pixel_geom method.NcPlaneOptions.NcPlaneOptions.NcVisualOptions.NcVisual.NcVisualOptions.Enums
NcInput event.NcOptions.Type Definitions
Nc.inputready_fd and
NcDirect.inputready_fd.NcFdPlane.NcPalette (alias of u8).NcPlane.NcPlane is resized.NcVisualNcSubprocNcVisual.