63 stable releases
new 2.1.5 | Jan 15, 2021 |
---|---|
2.1.3 | Dec 31, 2020 |
2.0.8 | Nov 27, 2020 |
1.7.6 | Oct 10, 2020 |
1.2.4 | Mar 24, 2020 |
#65 in Command-line interface
254 downloads per month
Used in 2 crates
380KB
5.5K
SLoC
libnotcurses-sys
lib.rs
:
libnotcurses-sys
is a Rust wrapper for the notcurses
C library
This is a work in progress.
This library is built with several layers of zero-overhead abstractions over the C functions and pointers accessed through FFI.
How to use this library
There are basically two ways: The Rust way, and the C way. (Or a mix of both).
1. The Rust way
Where you use the safely wrapped types, with its methods and constructors, and painless error handling, like this:
Example
use libnotcurses_sys::*;
fn main() -> NcResult<()> {
let mut nc = FullMode::with_flags(NCOPTION_NO_ALTERNATE_SCREEN)?;
let plane = nc.stdplane();
plane.putstr("hello world")?;
nc.render()?;
Ok(())
}
Specifically [FullMode
] and [DirectMode
] are safe wrappers
over [Notcurses
] and [NcDirect
], respectively.
FullMode
and DirectMode
both implement the [Drop], [AsRef], [AsMut],
[Deref][std::ops::Deref] and [DerefMut][std::ops::DerefMut] traits.
Their destructors are called automatically at the end of their scope.
Methods are directly implemented for Notcurses
and NcDirect
, and
are made automatically available to FullMode
& DirectMode
,
minus some function overrides, like their destructors,
plus the static methods that have to be recreated.
The rest of the types that allocate, like [NcPlane
], [NcMenu
], [NcReader
]…
have no higher level wrapping struct, they don't implement Drop,
so they have to be *.destroy()
ed manually.
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
(e.g.: [NcChannel
], [NcChannelPair
], [NcRgb
], [NcColor
]…), to
leverage type checking, and they implement methods through traits
(e.g. [NcChannelMethods
] must be in scope to use the NcChannel
methods.
2. The C way
You can always use the C API functions directly if you prefer, in a very similar way as the C library is used.
It requires the use of unsafe, since most functions are wrapped directly
by bindgen
marked as such.
Error handling is done this way by checking the returned [NcIntResult
],
or in case of receiving a pointer, by comparing it
to [null_mut()][core::ptr::null_mut].
Example
use core::ptr::{null, null_mut};
use std::process::exit;
use libnotcurses_sys::*;
fn main() {
let options = ffi::notcurses_options {
termtype: null(),
renderfp: null_mut(),
loglevel: 0,
margin_t: 0,
margin_r: 0,
margin_b: 0,
margin_l: 0,
flags: NCOPTION_NO_ALTERNATE_SCREEN,
};
unsafe {
let nc = notcurses_init(&options, null_mut());
if nc == null_mut() {
exit(1);
}
let plane = notcurses_stdplane(nc);
let cols = ncplane_putstr(&mut *plane, "hello world");
if cols < NCRESULT_OK {
notcurses_stop(nc);
exit(cols.abs());
}
if notcurses_stop(nc) < NCRESULT_OK {
exit(2);
}
}
}
The notcurses
C API docs
Dependencies
~0–1.4MB
~30K SLoC