Skip to content

Commit

Permalink
Document feature flags in lib.rs (#947)
Browse files Browse the repository at this point in the history
* Autoformat Cargo.toml

Uses VSCode Even Better TOML plugin for opinionated formatting

* Document feature flags

Use the document-features crate to automatically add documentation about the features to the crate documentation at the crate level.
  • Loading branch information
joshka authored Nov 22, 2024
1 parent 56ee252 commit fc8f977
Show file tree
Hide file tree
Showing 5 changed files with 37 additions and 60 deletions.
89 changes: 32 additions & 57 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -17,91 +17,66 @@ categories = ["command-line-interface", "command-line-utilities"]
name = "crossterm"
path = "src/lib.rs"

#
# Build documentation with all features -> EventStream is available
#
[package.metadata.docs.rs]
all-features = true

#
# Features
#
[features]
default = ["bracketed-paste", "windows", "events"]
windows = [
"dep:winapi",
"dep:crossterm_winapi",
] # Disables winapi dependencies from being included into the binary (SHOULD NOT be disabled on windows).
bracketed-paste = [
] # Enables triggering a `Event::Paste` when pasting text into the terminal.
event-stream = ["dep:futures-core", "events"] # Enables async events
use-dev-tty = [
"filedescriptor",
"rustix/process",
] # Enables raw file descriptor polling / selecting instead of mio.
events = [
"dep:mio",
"dep:signal-hook",
"dep:signal-hook-mio",
] # Enables reading input/events from the system.
serde = ["dep:serde", "bitflags/serde"] # Enables 'serde' for various types.

#
# Shared dependencies
#
default = ["bracketed-paste", "events", "windows"]

#! ### Default features
## Enables triggering [`Event::Paste`](event::Event::Paste) when pasting text into the terminal.
bracketed-paste = []

## Enables reading input/events from the system using the [`event`] module.
events = ["dep:mio", "dep:signal-hook", "dep:signal-hook-mio"]

## Enables windows specific crates.
windows = ["dep:winapi", "dep:crossterm_winapi"]

#! ### Optional Features

## Enables the [EventStream](event::EventStream) struct for async event reading.
event-stream = ["dep:futures-core", "events"]

## Enables [`serde`] for various types.
serde = ["dep:serde", "bitflags/serde"]

## Enables raw file descriptor polling / selecting instead of mio.
use-dev-tty = ["filedescriptor", "rustix/process"]

[dependencies]
bitflags = { version = "2.3" }
parking_lot = "0.12"

# optional deps only added when requested
document-features = "0.2.10"
futures-core = { version = "0.3", optional = true, default-features = false }
parking_lot = "0.12"
serde = { version = "1.0", features = ["derive"], optional = true }

#
# Windows dependencies
#
[target.'cfg(windows)'.dependencies.winapi]
version = "0.3.9"
features = ["winuser", "winerror"]
optional = true

[target.'cfg(windows)'.dependencies]
crossterm_winapi = { version = "0.9.1", optional = true }
winapi = { version = "0.3.9", optional = true, features = ["winuser", "winerror"] }

#
# UNIX dependencies
#
[target.'cfg(unix)'.dependencies]
filedescriptor = { version = "0.8", optional = true }
# Default to using rustix for UNIX systems, but provide an option to use libc for backwards
# compatibility.
libc = { version = "0.2", default-features = false, optional = true }
rustix = { version = "0.38.34", default-features = false, features = [
"std",
"stdio",
"termios",
] }
signal-hook = { version = "0.3.17", optional = true }
filedescriptor = { version = "0.8", optional = true }
mio = { version = "1.0", features = ["os-poll"], optional = true }
signal-hook-mio = { version = "0.2.4", features = [
"support-v1_0",
], optional = true }
rustix = { version = "0.38.34", default-features = false, features = ["std", "stdio", "termios"] }
signal-hook = { version = "0.3.17", optional = true }
signal-hook-mio = { version = "0.2.4", features = ["support-v1_0"], optional = true }

#
# Dev dependencies (examples, ...)
#
[dev-dependencies]
tokio = { version = "1.25", features = ["full"] }
async-std = "1.12"
futures = "0.3"
futures-timer = "3.0"
async-std = "1.12"
serde_json = "1.0"
serial_test = "2.0.0"
temp-env = "0.3.6"
tokio = { version = "1.25", features = ["full"] }

#
# Examples
#
[[example]]
name = "event-read"
required-features = ["bracketed-paste", "events"]
Expand Down
2 changes: 2 additions & 0 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,8 @@
//! Ok(())
//! }
//!```
//! ## Feature Flags
#![doc = document_features::document_features!()]
//!
//! [write]: https://doc.rust-lang.org/std/io/trait.Write.html
//! [stdout]: https://doc.rust-lang.org/std/io/fn.stdout.html
Expand Down
2 changes: 1 addition & 1 deletion src/style.rs
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,7 @@ pub fn available_color_count() -> u16 {
///
/// # Notes
///
/// crossterm supports NO_COLOR (https://no-color.org/) to disabled colored output.
/// crossterm supports NO_COLOR (<https://no-color.org/>) to disabled colored output.
///
/// This API allows applications to override that behavior and force colorized output
/// even if NO_COLOR is set.
Expand Down
2 changes: 1 addition & 1 deletion src/style/types/colored.rs
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ impl Colored {
}

/// Checks whether ansi color sequences are disabled by setting of NO_COLOR
/// in environment as per https://no-color.org/
/// in environment as per <https://no-color.org/>
pub fn ansi_color_disabled() -> bool {
!std::env::var("NO_COLOR")
.unwrap_or("".to_string())
Expand Down
2 changes: 1 addition & 1 deletion src/terminal.rs
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ pub struct WindowSize {
/// Returns the terminal size `[WindowSize]`.
///
/// The width and height in pixels may not be reliably implemented or default to 0.
/// For unix, https://man7.org/linux/man-pages/man4/tty_ioctl.4.html documents them as "unused".
/// For unix, <https://man7.org/linux/man-pages/man4/tty_ioctl.4.html> documents them as "unused".
/// For windows it is not implemented.
pub fn window_size() -> io::Result<WindowSize> {
sys::window_size()
Expand Down

0 comments on commit fc8f977

Please sign in to comment.