libnotcurses_sys/lib.rs
1//! `libnotcurses-sys` is a low-level Rust wrapper for the
2//! [notcurses C library](https://www.github.com/dankamongmen/notcurses/)
3//!
4//! It is built with several layers of zero-overhead abstractions
5//! over the C functions and pointers accessed through FFI.
6//!
7//! It adds greater safety and type correctness over the underlying C library
8//! API, while trying to remain very close to it.
9//!
10//! It offers the choice of using it [*more like Rust*](#like-rust)
11//! and/or [*more like C*](#like-c).
12//!
13//! ## Like Rust
14//!
15//! Where you use the more safely wrapped types, with its methods and
16//! constructors, and error handling with the `NcResult` enum:
17//!
18//! ### Example
19#![doc = concat!["```\n", include_str!("../examples/hello-world-rust.rs"), "\n```" ]]
20//!
21//! ### Notes on the Rust API
22//!
23//! The `Drop` trait is not implemented for any wrapping type in this library
24//! over structures created by the underlying C library.
25//!
26//! This means you still have to manually call the `stop()` method for `Nc`
27//! and `NcDirect` objects, and the `destroy()` method for the rest of types that
28//! allocate, (like `NcPlane`, `NcMenu`…) at the end of their scope.
29//!
30//! But they do implement methods and use `NcResult` as the return type,
31//! for handling errors in the way we are used to in Rust.
32//!
33//! For the types that don't allocate, most are based on primitives like `i32`,
34//! `u32`, `u64`… without a name in the C library. In Rust they are type aliased
35//! for the C API (e.g.: `NcChannel_u32`, `NcLogLevel_i32`, `NcStyle_u16`…), to
36//! leverage type checking. And for the Rust API they are wrapped as unit structs
37//! or enums, with associated methods and constants (e.g. `NcChannel`,
38//! `NcLogLevel`, `NcStyle`…).
39//!
40//! Several methods are declared unsafe when they have addittional contracts to
41//! manually upheld in order to avoid *UB*.
42//!
43//! ### even more like Rust
44//!
45//! The *WIP* sister crate
46//! [`notcurses`](https://github.com/dankamongmen/notcurses-rs) will eventually
47//! offer a *closer to Rust*, higher-level, safer, and simpler API, and make it
48//! easier to interoperate with the rest of the Rust ecosystem.
49//!
50//! ## Like C
51//!
52//! You can access the imported, or reimplemented C API functions directly,
53//! and use it in a very similar way as the C library is used.
54//!
55//! It requires more use of unsafe, since it has less safer abstractions.
56//!
57//! Error handling is done this way by checking the returned `NcResult_i32`,
58//! or in case of receiving a pointer, by comparing it to `null_mut()`.
59//!
60//! ### Example
61#![doc = concat!["```\n", include_str!("../examples/hello-world-c.rs"), "\n```" ]]
62//!
63//! ### The `notcurses` C API docs
64//!
65//! - [API reference (man pages)](https://notcurses.com/)
66//! - [Wiki Page](https://nick-black.com/dankwiki/index.php/Notcurses)
67//! - [The Book Guide (pdf)](https://nick-black.com/htp-notcurses.pdf)
68//! - [USAGE.md](https://github.com/dankamongmen/notcurses/blob/master/USAGE.md)
69//! - [HACKING.md](https://github.com/dankamongmen/notcurses/blob/master/doc/HACKING.md)
70//! - [Doxygen Documentation](https://nick-black.com/notcurses/html/index.html)
71//! - [FOSDEM 2021 presentation](https://fosdem.org/2021/schedule/event/notcurses/)
72//!
73#![allow(non_upper_case_globals, non_camel_case_types, non_snake_case)]
74#![allow(clippy::too_many_arguments, clippy::needless_doctest_main)]
75#![cfg_attr(feature = "nightly", feature(doc_cfg))]
76#![cfg_attr(not(feature = "std"), no_std)]
77#[cfg(not(feature = "std"))]
78extern crate alloc;
79
80mod align;
81mod alpha;
82mod bindings;
83mod blitter;
84mod r#box;
85mod capabilities;
86mod cell;
87mod channel;
88mod direct;
89mod error;
90mod fade;
91mod fd;
92#[cfg(feature = "std")]
93mod file;
94mod input;
95mod key;
96mod log_level;
97mod macros;
98mod metric;
99mod notcurses;
100mod palette;
101mod pixel;
102mod plane;
103mod resizecb;
104mod rgb;
105mod scale;
106mod stats;
107mod string;
108mod style;
109mod time;
110mod visual;
111
112pub mod widgets;
113
114// wrapper types and traits
115//
116// Note that the names of the implemented traits can't coincide for type aliases
117// with the same underlying primitive, like in the case of `NcAlign` & `NcScale`
118// in which case are both aliases over `u32`.
119pub use align::NcAlign;
120pub use alpha::NcAlpha;
121pub use blitter::NcBlitter;
122pub use capabilities::NcCapabilities;
123pub use cell::NcCell;
124pub use channel::{NcChannel, NcChannels};
125pub use direct::{NcDirect, NcDirectFlag};
126pub use error::{NcError, NcResult};
127pub use fade::{NcFadeCb, NcFadeCtx};
128pub use fd::{NcFd, NcFdPlane, NcFdPlaneOptions, NcSubproc, NcSubprocOptions};
129#[cfg(feature = "std")]
130#[cfg_attr(feature = "nightly", doc(cfg(feature = "std")))]
131pub use file::NcFile;
132pub use input::{NcInput, NcInputType, NcMiceEvents, NcReceived};
133pub use key::{NcKey, NcKeyMod};
134pub use log_level::NcLogLevel;
135pub use notcurses::{Nc, NcFlag, NcOptions, NcOptionsBuilder};
136pub use palette::{NcPalette, NcPaletteIndex};
137pub use pixel::{NcPixel, NcPixelGeometry, NcPixelImpl};
138pub use plane::{NcPlane, NcPlaneFlag, NcPlaneOptions, NcPlaneOptionsBuilder};
139pub use r#box::NcBoxMask;
140pub use resizecb::NcResizeCb;
141pub use rgb::{NcRgb, NcRgba};
142pub use scale::NcScale;
143pub use stats::NcStats;
144pub use string::NcString;
145pub use style::NcStyle;
146pub use time::NcTime;
147pub use visual::{
148 NcStreamCb, NcVisual, NcVisualFlag, NcVisualGeometry, NcVisualOptions, NcVisualOptionsBuilder,
149};
150
151pub mod c_api {
152 //! The `C API`, including structs, constants, functions and type aliases.
153 //!
154 //! Includes also both automatically imported functions by bindgen, and
155 //! manually wrapped and reimplemented global functions.
156
157 // public re-export of external crates:
158 #[cfg(feature = "libc")]
159 #[cfg_attr(feature = "nightly", doc(cfg(feature = "libc")))]
160 pub use libc;
161
162 pub mod ffi {
163 //! Rust FFI bindings, automatically generated with bindgen.
164 pub use crate::bindings::ffi::*;
165 }
166
167 // public re-export of imported functions & structs:
168 #[doc(inline)]
169 pub use crate::bindings::*;
170
171 // public re-export of reimplemented functions:
172 // TODO: join these into the same c_api submodule
173 pub use crate::capabilities::reimplemented::*;
174 pub use crate::cell::reimplemented::*;
175 pub use crate::channel::reimplemented::*;
176 pub use crate::direct::reimplemented::*;
177 pub use crate::input::reimplemented::*;
178 pub use crate::key::reimplemented::*;
179 pub use crate::metric::reimplemented::*;
180 pub use crate::notcurses::reimplemented::*;
181 pub use crate::palette::reimplemented::*;
182 pub use crate::pixel::reimplemented::*;
183 pub use crate::plane::reimplemented::*;
184
185 // public re-export of c_api constants & types:
186 pub use crate::align::c_api::*;
187 pub use crate::alpha::c_api::*;
188 pub use crate::blitter::c_api::*;
189 pub use crate::channel::c_api::*;
190 pub use crate::direct::c_api::*;
191 pub use crate::error::c_api::*;
192 pub use crate::input::c_api::*;
193 pub use crate::key::c_api::*;
194 pub use crate::log_level::c_api::*;
195 pub use crate::metric::c_api::*;
196 pub use crate::notcurses::options::flags::c_api::*;
197 pub use crate::palette::c_api::*;
198 pub use crate::pixel::c_api::*;
199 pub use crate::plane::options::flags::c_api::*;
200 pub use crate::r#box::c_api::*;
201 pub use crate::resizecb::c_api::*;
202 pub use crate::rgb::c_api::*;
203 pub use crate::scale::c_api::*;
204 pub use crate::style::c_api::*;
205 pub use crate::visual::c_api::*;
206
207 pub use crate::widgets::{
208 menu::c_api::*, plot::c_api::*, progbar::c_api::*, reader::c_api::*, reel::c_api::*,
209 tabbed::c_api::*,
210 };
211
212 // private re-export of helper functions for testing:
213 mod helpers {
214 #![allow(unused_imports)]
215 pub use crate::notcurses::helpers::*;
216 pub use crate::plane::helpers::*;
217 }
218 #[allow(unused_imports)]
219 pub(crate) use helpers::*;
220}