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
The C API, including structs, constants, functions and type aliases.
widgets
The notcurses widgets.

Macros§

putstr
Wrapper around NcPlane.putstr, rendering and rasterizing the plane afterwards.
putstrln
Wrapper around NcPlane.putstrln. rendering and rasterizing the plane afterwards.

Structs§

NcBoxMask
A bitmask for drawing borders, gradients and corners.
NcChannel
32 bits of context-dependent info containing NcRgb + NcAlpha + extra
NcChannels
64 bits containing a foreground and background NcChannel
NcDirectFlag
A bitmask of NcDirect flags.
NcError
The error type for the Rust methods API.
NcFilestd
A wrapper struct around libc::FILE
NcFlag
A bitmask of NcOptions flags.
NcKey
A synthesized input event.
NcKeyMod
A bitmask of NcKey modifiers.
NcMiceEvents
A bitmask of mice input events.
NcOptionsBuilder
Builder object for NcOptions.
NcPixel
An ABGR pixel.
NcPixelGeometry
Contains the pixel geometry information as returned by the NcPlane.pixel_geom method.
NcPlaneFlag
A bitmask of flags for NcPlaneOptions.
NcPlaneOptionsBuilder
Builder object for NcPlaneOptions.
NcRgb
24 bits broken into 3x RGB components.
NcRgba
32 bits broken into 3x RGB components + alpha component.
NcString
A wrapped CString accepted by widgets.
NcStyle
A bitmask of styles.
NcVisualFlag
A bitmask of flags for NcVisualOptions.
NcVisualGeometry
Describes all the geometries of an NcVisual.
NcVisualOptionsBuilder
Builder object for NcVisualOptions.

Enums§

NcAlign
Alignment within a plane or terminal.
NcAlpha
Alpha information, part of an NcChannel, applies to NcCell’s foreground or background color.
NcBlitter
The blitter mode to use for rasterizing an NcVisual.
NcInputType
The type of the NcInput event.
NcLogLevel
Log level for NcOptions.
NcPixelImpl
Pixel blitting implementations, informative only.
NcReceived
A received character or event.
NcScale
Indicates how to scale an NcVisual during rendering.

Type Aliases§

Nc
Notcurses state for a given terminal, composed of NcPlanes.
NcCapabilities
Capabilities, derived from terminfo, environment variables, and queries.
NcCell
A coordinate on an NcPlane storing 128 bits of data.
NcDirect
Minimal notcurses instance for styling text.
NcFadeCb
Called for each fade iteration on a fading NcPlane.
NcFadeCtx
Context for a palette fade operation
NcFd
A raw file descriptor, as returned by Nc.inputready_fd and NcDirect.inputready_fd.
NcFdPlane
I/O wrapper to dump file descriptor to NcPlane.
NcFdPlaneOptions
Options struct for NcFdPlane.
NcInput
Reads and decodes input events.
NcOptions
Options struct for Nc.
NcPalette
An array of 256 NcChannels.
NcPaletteIndex
Used for indexing into a NcPalette (alias of u8).
NcPlane
A drawable Nc notcurses surface, composed of NcCells.
NcPlaneOptions
Options struct for NcPlane.
NcResizeCb
A callback function called when an NcPlane is resized.
NcResult
The result type for the Rust methods API.
NcStats
notcurses runtime statistics
NcStreamCb
Called for each frame rendered from an NcVisual
NcSubproc
NcFdPlane wrapper with subprocess management.
NcSubprocOptions
Options struct for NcSubproc
NcTime
A time in seconds and nanoseconds.
NcVisual
A visual bit of multimedia.
NcVisualOptions
Options struct for NcVisual.